Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ad701ac
docs(specs): add 101-tpa-db — versioned signed offline TPA signature …
Dumbris Aug 23, 2026
91d3bec
docs(specs): close trust-model and eval-gate gaps in 101-tpa-db
Dumbris Aug 23, 2026
bbc1b79
docs(specs): fix watermark lockout + embedded-default regression in 1…
Dumbris Aug 23, 2026
f2ce0fe
docs(specs): bind the trust epoch into signed bundle bytes in 101-tpa-db
Dumbris Aug 23, 2026
0527bfe
docs(specs): seed the anti-downgrade watermark from a trusted baselin…
Dumbris Aug 23, 2026
c178144
docs(specs): make the operator-authority baseline explicit and durabl…
Dumbris Aug 23, 2026
49c4e7e
docs(specs): close the authority-swap hole and de-vacuate the gate co…
Dumbris Aug 24, 2026
eea76d3
docs(specs): bind rollback to a fingerprint and narrow the degraded f…
Dumbris Aug 24, 2026
9feda6e
docs(specs): cap the sidecar, scope the rollback floor, pin the gate …
Dumbris Aug 24, 2026
c2fbc7f
docs(specs): refuse non-regular candidates and scope the freshness me…
Dumbris Aug 24, 2026
3979f29
docs(specs): name the baseline-less exemption and bucket operator seq…
Dumbris Aug 24, 2026
544d713
docs(specs): correct the SC-002a fixture count after adding (b2) (101…
Dumbris Aug 24, 2026
82d544d
docs(specs): align FR-007 and FR-009a with the two-exemption rule (10…
Dumbris Aug 24, 2026
afff3cb
docs(specs): scope pins per epoch, gate telemetry on provenance, fix …
Dumbris Aug 24, 2026
10ae3cf
docs(specs): define authority-switch serving semantics + operator epo…
Dumbris Aug 24, 2026
2e0ceee
docs(specs): close cross-model review gaps in 101-tpa-db
Dumbris Aug 26, 2026
a6f0d58
docs(specs): put numbers on the 101-tpa-db load ceilings
Dumbris Aug 26, 2026
cb619fd
docs(specs): 101-tpa-db implementation plan
Dumbris Aug 26, 2026
78c683c
docs(specs): close cross-model review findings in the 101-tpa-db plan
Dumbris Aug 26, 2026
735bde1
Merge origin/main into 101-tpa-db
Dumbris Aug 26, 2026
55497c0
docs(specs): lock D2 — require_signed_bundle stays default-off
Dumbris Aug 27, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,6 @@ tail -f ~/Library/Logs/mcpproxy/main.log # main log (macOS; Linux: ~/.mcpproxy/
- **Windows installer**: [docs/github-actions-windows-wix-research.md](docs/github-actions-windows-wix-research.md). **Prerelease** (`next` branch + `v*-rc.*` tags, opt-in, off stable channels): [docs/prerelease-builds.md](docs/prerelease-builds.md).

## Recent Changes
- 101-tpa-db: Go 1.25.5 module toolchain (`go.mod`), backend-only + stdlib only for the new work — `crypto/ed25519`, `crypto/sha256`, `syscall` (no ed25519 usage in the tree before this); existing bbolt (state), zap, Cobra. **No new dependencies.**
- 098-tools-preflight: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — chi (httpapi), bbolt (storage), Bleve (index), zap (logging), Cobra (CLI), swaggo/swag v2 (contract regen). **No new dependencies.**
- 097-stored-scripts: Added Go 1.25 (os.Root/Root.ReadFile available — R1) + stdlib only (os.Root). **No new dependencies.**
- 096-batched-call-tools: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — goja (sandbox), mark3labs/mcp-go (tool surface), zap. **No new dependencies.**
1 change: 1 addition & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -881,4 +881,5 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
| [098-tools-preflight](./specs/098-tools-preflight/) | `in-flight` | 26/33 (79%) |
| [099-describe-check-mode](./specs/099-describe-check-mode/) | `in-flight` | 9/10 (90%) |
| [100-prompt-rugpull-baseline](./specs/100-prompt-rugpull-baseline/) | — | — |
| [101-tpa-db](./specs/101-tpa-db/) | — | — |
| [102-schema-deferred](./specs/102-schema-deferred/) | — | — |
90 changes: 90 additions & 0 deletions specs/101-tpa-db/contracts/bundle-signatures-section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Contract: Bundle `signatures[]` Section

**Feature**: `101-tpa-db` · Resolves FR-001a.

## 1. Why this exists

FR-001 says the publishable artifact is "the existing compiled bundle". FR-012 says "each signature MUST carry provenance … and a redistributable license". **Both cannot hold today**, because the shipped `scanner-bundle.json` has nowhere to put either:

```text
top level : bundle_version, generated_from, rules, schema_version, signature_count, skipped
rules[] : category, confidence, detector, engine, flags, id, indicators,
level, pattern, severity, target, type
```

No provenance. No licence. No campaign identity — `signature_count` counts *rules*, so SC-004's "at least 25 signatures spanning at least 8 distinct classes" is not even expressible.

## 2. Shape

A new **additive** top-level array. A v0.1 loader ignores unknown top-level keys, so contract §4 forward-compat is preserved (FR-001a).

```json
{
"signatures": [
{
"id": "TPA-2026-0001",
"category": "instruction_injection",
"gating": true,
"provenance": {
"source": "https://invariantlabs.ai/blog/mcp-github-vulnerability",
"published": "2026-01-14",
"note": "hidden <IMPORTANT> block coaxing ~/.ssh/id_rsa"
},
"license": "CC-BY-4.0",
"rule_ids": ["r-hidden-important-block", "r-hidden-html-comment"]
}
]
}
```

| Field | Type | Rules |
|---|---|---|
| `id` | string | `^TPA-[0-9]{4}-[0-9]{4}$`, unique across the bundle |
| `category` | string | the campaign/technique class; must have a `categoryCheck` entry in the gate (FR-016a) |
| `gating` | bool | `true` ⇒ must emit hard-tier signals and must ship eval evidence (FR-013/FR-014) |
| `provenance.source` | URL | the public disclosure that motivated the signature |
| `provenance.published` | `YYYY-MM-DD` | |
| `provenance.note` | string | optional, human context |
| `license` | SPDX id | from the redistributable allowlist below |
| `rule_ids` | array | ≥1, each naming an existing `rules[]` entry |

**Licence allowlist** (redistributable, FR-012): `CC0-1.0`, `CC-BY-4.0`, `CC-BY-SA-4.0`, `MIT`, `Apache-2.0`. Anything else is refused at corpus build — including "no licence stated", which is the common case for a pattern lifted from a blog post and is precisely what FR-012 exists to stop shipping.

## 3. Relationship to `rules[]`

**Many-to-one, explicitly.** Several rules may implement one signature — a hidden-instruction class already needs distinct patterns for `<IMPORTANT>` blocks, HTML comments and zero-width runs. One rule belongs to at most one signature.

```text
signatures[] ──1─────*── rules[]
TPA id pattern
```

## 4. Referential integrity — enforced at build, in both directions

A bundle failing any of these is **rejected whole**, exactly like any other contract violation:

1. every `signatures[]` entry names ≥1 rule id that exists in `rules[]`;
2. every **hard-tier** rule is named by exactly one `gating: true` signature entry — not zero (an ungoverned gating rule has no provenance and no eval evidence) and not two (ambiguous campaign attribution).

**"Gating" must be mechanical, because `rules[]` has no such field.** Its keys are `category, confidence, detector, engine, flags, id, indicators, level, pattern, severity, target, type` — nothing that says "this rule gates approvals". Left as prose about intent, the check is unenforceable and a hard-tier rule can evade attribution entirely, or be attached to a `gating: false` signature and thereby dodge the FR-013 eval-evidence requirement while still driving the approval gate at runtime. The build MUST therefore derive it from `level` — a rule is gating **iff** it emits at the hard tier, which is exactly what FR-014 says gating means and exactly what the eval gate and the `scan`-mode approval gates score — and MUST reject any bundle where a hard-tier rule's owning signature has `gating: false`. `signatures[].gating` is then a declaration that is *checked* against the rules it names, not an independent switch;
3. `id` values are unique;
4. `license` is in the allowlist;
5. every `gating: true` signature has its FR-013 eval pair in the frozen dataset — ≥1 labeled gated-malicious sample and ≥1 category-matched hard negative following the `hn_<attack_category>_*` naming the dataset validator enforces;
6. every `gating: true` signature's `category` resolves to a **registered** `categoryCheck` entry in the gate. §5 below explains why an unmapped category is scored vacuously; that explanation is not enforcement, so this rule is what actually stops one shipping. A bundle naming a category the gate cannot enforce is rejected at build, not merely noted.

Direction 2 is the one a naive implementation drops, and it is the one that matters: checking only "signatures point at real rules" lets a gating rule ship with no campaign record at all, which is the state the corpus is in today. Rule 6 is the same failure one level up — a campaign record that exists but that the gate silently declines to score.

## 5. Interaction with the eval gate

`gating: true` is not self-certifying. FR-016a's `categoryCheck` map decides whether a category is *enforced*: `gatedCategory()` enforces a category only when its mapped check id is registered, so **a new class whose category is missing from that map is tallied and reported but excluded from `gatedMalicious`/`OverallRecall`** — its misses can never fail the gate. Adding a signature class therefore means adding its `categoryCheck` entry in the same change, or the coverage is decorative.

(Its false positives still count either way, since `FPRate` is computed over the whole hard-negative set regardless of category mapping. So an unmapped class can only ever hurt — never help — the gate outcome. That asymmetry is the tell.)

## 6. Counting for SC-004

- **signatures** = `len(signatures)` — must be ≥ 25
- **classes** = distinct `category` — must be ≥ 8
- every signature carries provenance + licence (rule 4 above)
- every `gating: true` signature has its eval pair (rule 5)

Note `signature_count` (existing, top-level) counts **rules** and keeps that meaning. Renaming it would break the v0.1 line for no gain; SC-004 counts `signatures[]`.
80 changes: 80 additions & 0 deletions specs/101-tpa-db/contracts/bundle-status-surface.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Contract: Bundle Status Surface

**Feature**: `101-tpa-db` · Resolves FR-020.

The operator question this surface must answer is not "what version am I on" but **"am I current and verified, or stuck on last-known-good — and why?"** Today's `BundleInfo` cannot answer the second half at all.

## 1. Fields

Existing fields keep their meaning and their names. `Fingerprint` stays the 12-hex short form (it is load-bearing in current operator output and in `logBundle`); the full digest is **added beside it**, not substituted.

| Field | Existing | Purpose |
|---|---|---|
| `bundle_version`, `schema_version`, `source`, `generated_at`, `load_error` | ✅ | unchanged |
| `runnable_rules`, `skipped_rules`, `declared_skipped` | ✅ | unchanged — un-evaluated coverage, never clean coverage |
| `fingerprint` | ✅ | 12-hex short form, human-comparable |
| `full_digest` | **new** | complete SHA-256; the **only** value rollback accepts (FR-010) |
| `sequence` | **new** | decimal string, as published |
| `authority` | **new** | `publisher` \| `operator` — which authority is serving |
| `trust_epoch` | **new** | the epoch it was published under |
| `signature_verified` | **new** | bool |
| `staleness_days` | **new** | derived from `generated_at` |
| `coverage_degraded` | **new** | bool |
| `degraded_reason` | **new** | enum, §3 |
| `last_rejection` | **new** | `{reason, detail, at}`, §2 — retained across a successful load so "what did it refuse, and when" survives. `detail` is a short human string carrying the part the enum cannot (which ceiling was exceeded and by how much, which key id was untrusted, which epoch was expected); it is never parsed, and `reason` is the only field anything branches on |

## 2. Rejection reasons

The vocabulary an operator reads to tell a tamper attempt from a stale epoch from their own misconfiguration:

| Reason | Means |
|---|---|
| `tamper` | signature did not verify over the raw bytes |
| `downgrade` | sequence below this authority's watermark for this epoch, or equal sequence with a different fingerprint |
| `stale_epoch_replay` | manifest epoch below the binary-trusted epoch — a validly-signed but superseded artifact |
| `unsigned_refused_by_ratchet` | this install has activated a signed bundle before; unsigned drops are refused thereafter |
| `authority_not_active` | verified against a real key of the **non-active** authority (FR-004b) |
| `rollback_target_mismatch` | the loaded artifact's full digest ≠ the digest the operator named |
| `gate_failure` | activation self-check (Spec 087 FR-008) rejected the candidate |
| `ceiling_exceeded` | over one of FR-011's four limits — which limit, and the observed value, in `detail` |
| `not_regular_file` | candidate was a FIFO/device/socket, or a symlink to one |
| `read_timeout` | the 5 s read budget expired; the single-flight slot was released |
| `sidecar_*`, `key_*`, `signature_invalid`, `sequence_mismatch` | the sidecar grammar — see [sidecar-format.md](sidecar-format.md) §3 |

**Every one of these keeps last-known-good serving.** There is no rejection path that leaves the scanner with an empty or partial rule set.

## 3. Degraded-coverage reasons

`coverage_degraded` suspends `scan`-mode auto-approval, routing changes to human review. It **must** be visible: a silently suspended auto-approval is indistinguishable from a quiet install, which is the failure this field exists to prevent.

| `degraded_reason` | Condition |
|---|---|
| `unsigned_external_active` | an unsigned file-dropped/fetched bundle is active (FR-007) |
| `embedded_below_watermark` | the embedded default is serving and its sequence is below the **publisher** watermark (FR-009a a) |
| `operator_bundle_missing` | the operator authority is active and its previously-activated external bundle is gone or invalid (FR-009a b) |
| `operator_authority_unbaselined` | an operator-signed bundle is active under an authority configured without a baseline (FR-009b) |

**Not degraded** — the two cases a careless implementation gets wrong:

- an ordinary fresh install serving the embedded default with no retained watermark and no missing external bundle. The embedded default is binary-trusted; degrading here would ship every fresh install with `scan` mode silently disabled.
- an embedded default **at or above** the publisher watermark after an external file was removed. It is demonstrably no older than what went missing — the ordinary "external file removed after a binary upgrade shipped a newer corpus" case.

## 4. Surfaces

Same field set everywhere; three renderings.

| Surface | Rendering |
|---|---|
| **CLI** (`mcpproxy security …`) | human table + `-o json`/`yaml`; the full digest shown in full (it is the rollback input) |
| **REST** (security overview) | the JSON object above; `make swagger` regenerated |
| **Web UI** (Security page) | short fingerprint with the full digest on demand; degraded state as a banner with its reason, never a silent flag |

The Web UI rule follows the house preference already established for status surfaces: **mark only the states that need action**, and always say *why* rather than showing a bare badge.

## 5. Activation history

`(authority, trust_epoch, sequence, full digest, generated_at, activated_at, source)` per activation, append-only, retained across restarts.

Exposed read-only. It exists because rollback is authorized by full digest and there is otherwise **no trustworthy way to learn the digest of the known-good artifact you want to revert to** — reading it from the candidate file would defeat the purpose, since the file is what the attacker controls.

Data-dir resident, so it carries the same caveat as the ratchet: it makes a legitimate rollback *possible*; it does not *authorize* one.
Loading
Loading