Skip to content

Commit 414b40d

Browse files
committed
Tranche 2: producer/verifier source surfaces for D137-D141, integrated e2e
Five parallel implementation agents built the protocol-package layer; edits applied serially and validated together (1657 tests green: @atrib/mcp 695, @atrib/verify 605, @atrib/agent 195, @atrib/emit 107, @atrib/mcp-wrap 55; all five packages tsc-clean): - D137: packages/verify evidence-envelope module (validateEnvelope, frozen legacy-protocol mapping, profile registry, opaque render), opt-in verifyRecord({evidenceEnvelopes}) projection, and the eight docs/evidence-profiles/ documents the §5.5.7 registration rule requires. - D138: packages/mcp anchors module (§2.11.12 posture resolution, §2.11.10 anchoring-claim builder with fresh Ed25519 signatures, non-blocking fan-out with atrib-log/rekor/rfc3161/ots transports — non-log transports stubbed behind AnchorTransport), middleware queue-wrapper hook (identical queue when anchors unset), and the packages/verify anchor_plurality annotation with §2.11.4 hard conditions unchanged and malformed-wins precedence pinned. - D139: session-checkpoint modules in packages/mcp (roots, record assembly under the extension URI, inclusion/consistency proofs, equivocation detection), packages/verify (structural validation, freshness tiering, full verification), and @atrib/emit (emitSessionCheckpoint over the existing pipeline, §5.8-silent). - D140: packages/mcp delegation issuance (issueDelegationCertificate, withDelegationCertHash composing with the existing signRecord flow, run-key revocation builder) and packages/verify evaluateDelegation promoted to source with depth-limit and ambiguity rules; opt-in verifyRecord delegation block (signal-not-block). - D141: dev.atrib/attribution implemented across packages/mcp (negotiation incl. legacy-initialize, receipt building/application, middleware extensionAttribution flag), packages/agent (declare + parse), mcp-wrap (config flag), and the proxy capability advert — all opt-in, byte-identical behavior when unconfigured. - Conformance suites for all five corpora now exercise the shipped library exports instead of in-test reference implementations. - CLAUDE.md registers docs/evidence-profiles/; the upgrade-path punch list is refreshed to remaining-only items. The D139 agent was lost to a connection error at reporting time; its on-disk work validated green and its index exports were derived from the modules directly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014qR9gMu4FMmTsaXbUEF2qD
1 parent 47eeb52 commit 414b40d

44 files changed

Lines changed: 11189 additions & 1597 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

CLAUDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ atrib/
5656
docs/redesign-upgrade-path.md # Proposed (pre-ADR) ordered promotion plan from the 2026-07 clean-room redesign analysis: universal evidence envelope, anchor plurality, session checkpoints, delegation certificates, daemon consolidation, attest/recall verb rename, payments profile spin-out. No signed byte changes.
5757
docs/atrib-sdk-session-brief.md # Handoff brief for a future dedicated session building the Python and consolidated JS/TS client SDKs against the redesign target surface (conformance corpora as fixtures, byte-identical records, degradation contract).
5858
docs/adr-draft-p042-*.md ... p049-*.md # Candidate ADR drafts for the P042-P049 redesign upgrade-path set, one file per pending decision, generated by the 2026-07-06 redesign-overhaul workflow (research -> draft -> adversarial judge -> revise). Compact entries live in the DECISIONS.md Pending decisions section.
59+
docs/evidence-profiles/ # §5.5.7 (D137) profile documents for the eight atrib-maintained evidence-envelope profiles (oauth2, mcp-oauth, aauth, x401, ap2-vi, human-approval, counterparty-attestation, delegation-certificate).
5960
docs/extensions/dev.atrib-attribution/ # dev.atrib/attribution MCP extension specification (P049): v0.1 extension document (identifier, capability settings, prefixed _meta carriage, attestation receipts, negotiation, degradation, versioning per SEP-2133).
6061
docs/website-redesign-relay.md # Relay brief for the website-overhaul session: approved P042-P050 facts that change public language, vocabulary table, embargoes/timeline, and the governance rules copy changes are bound by.
6162
docs/attest-recall-rename-impact.md # Blast-radius catalog for the tentative attest/recall verb rename: npm packages, MCP tool names, persisted producer labels, signed-bytes analysis, operator machine state, and doc/skill surfaces.

docs/evidence-profiles/aauth.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Evidence profile: `aauth`
2+
3+
- **Type URI:** `https://atrib.dev/v1/evidence/aauth`
4+
- **Profile version:** `1.0.0` (semver of this document)
5+
- **Status:** atrib-maintained. Mapped 1:1 from the legacy [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks) `aauth` protocol string (frozen legacy set).
6+
7+
Carries AAuth agent-authorization results: agent tokens, resource tokens, auth tokens, mission claims, HTTP message signatures, and R3 (resource-request-restriction) evidence for a signed agent action. Verifier-side only; never alters `verifyRecord().valid` ([§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope)).
8+
9+
## Payload media types and hash rule
10+
11+
| Media type | Payload | Hash rule |
12+
| ------------------ | ------------------------------------------- | --------------------------- |
13+
| `application/jwt` | Compact AAuth token (`aa-agent+jwt`, UTF-8) | raw bytes (`rawSha256`) |
14+
| `application/json` | Claims / mission / R3 / signature evidence | JCS (RFC 8785, `jcsSha256`) |
15+
16+
`payload.hash` = `"sha256:" + hex(SHA-256(bytes))`. Raw tokens and HTTP-signature material stay local-only.
17+
18+
## Facts schema
19+
20+
| Fact | JSON type | Provenance class |
21+
| ---------------- | ---------------- | ---------------- |
22+
| `issuer` | string \| null | verifier-derived |
23+
| `subject` | string \| null | verifier-derived |
24+
| `scope` | string[] | verifier-derived |
25+
| `attenuation_ok` | boolean \| null | verifier-derived |
26+
| `delegation_ok` | boolean \| null | verifier-derived |
27+
| `details_hash` | string (sha256:) | verifier-derived |
28+
29+
`delegation_ok` reflects the AAuth `act` chain; `details_hash` commits the token kind, `typ`, mission, R3, HTTP-signature covered components, and access mode.
30+
31+
## Tier semantics
32+
33+
- `declared` / `shape` — asserted / offline-parsed AAuth token.
34+
- `attested` — a caller-owned AAuth path accepted the token; legacy-mapping default.
35+
- `verified` — token signature, HTTP message signature, and R3 document hash verified against declared keys, reproducible from the envelope.
36+
37+
## Verifier behavior
38+
39+
`verifyAAuthAuthorizationEvidence` in `@atrib/verify` produces `result.constraints` for scope, `aauth.typ`, mission, R3 grants/`s256`/document-hash, and HTTP-signature coverage. Failures set `result.valid: false` only.
40+
41+
## Sanitization contract
42+
43+
Hashes and sanitized facts only; raw AAuth tokens, HTTP-signature inputs, and R3 documents MUST NOT appear in public projections.
44+
45+
## Sources
46+
47+
- [§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope), [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks)
48+
- [D119](../../DECISIONS.md#d119-aauth-evidence-stays-verifier-side), [D137](../../DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model)
49+
- Profile-internal corpus: [`spec/conformance/5.5.6/aauth/`](../../spec/conformance/5.5.6/aauth/); envelope corpus: [`spec/conformance/evidence-envelope/`](../../spec/conformance/evidence-envelope/)

docs/evidence-profiles/ap2-vi.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Evidence profile: `ap2-vi`
2+
3+
- **Type URI:** `https://atrib.dev/v1/evidence/ap2-vi`
4+
- **Profile version:** `1.0.0` (semver of this document)
5+
- **Status:** atrib-maintained. Mapped 1:1 from the legacy [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks) `ap2_vi` protocol string (frozen legacy set).
6+
7+
Carries AP2 (Agent Payments Protocol) receipt evidence plus Verifiable Intent (VI) credential and mandate-constraint evidence for a signed transaction record. Verifier-side evidence off the settlement critical path; never alters `verifyRecord().valid` and never substitutes for the [§1.7.6](../../atrib-spec.md#176-cross-attestation-requirement-for-transaction-records) `signers[]` cross-attestation rule ([§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope)).
8+
9+
## Payload media types and hash rule
10+
11+
| Media type | Payload | Hash rule |
12+
| ------------------ | ---------------------------------------------- | --------------------------- |
13+
| `application/jwt` | AP2 receipt JWT / SD-JWT VC (UTF-8) | raw bytes (`rawSha256`) |
14+
| `application/json` | Mandate / constraint / VI evidence bundle | JCS (RFC 8785, `jcsSha256`) |
15+
16+
`payload.hash` = `"sha256:" + hex(SHA-256(bytes))`. Raw receipt JWTs and SD-JWT disclosures stay local-only.
17+
18+
## Facts schema
19+
20+
| Fact | JSON type | Provenance class |
21+
| ---------------- | ---------------- | ---------------- |
22+
| `issuer` | string \| null | verifier-derived |
23+
| `subject` | string \| null | verifier-derived |
24+
| `scope` | string[] | verifier-derived |
25+
| `attenuation_ok` | boolean \| null | verifier-derived |
26+
| `delegation_ok` | boolean \| null | verifier-derived |
27+
| `details_hash` | string (sha256:) | verifier-derived |
28+
29+
`delegation_ok` reflects the VI delegation chain; `details_hash` commits the AP2 receipt checks, VI credential layers, checkout/payment binding, and mandate-constraint evaluation.
30+
31+
## Tier semantics
32+
33+
- `declared` / `shape` — asserted / offline-parsed receipt.
34+
- `attested` — a caller-owned AP2 path accepted the receipt; legacy-mapping default.
35+
- `verified` — receipt JWT, JWKS, and SD-JWT VC conformance verified against the pinned offline corpus ([D096](../../DECISIONS.md#d096-ap2--vi-crypto-conformance-uses-a-pinned-offline-corpus)), reproducible from the envelope.
36+
37+
## Verifier behavior
38+
39+
`verifyAp2ViEvidenceAsync` / `evaluateAp2ViConstraints` in `@atrib/verify` produce the AP2 receipt checks, VI credential checks, and typed mandate-constraint evaluation. A verifier that sees only a `counterparty-attestation` envelope still reports `cross_attestation_missing: true` — the AP2 receipt signature is external evidence ([D098](../../DECISIONS.md#d098-ap2-receipts-stay-external-evidence-for-cross-attestation)).
40+
41+
## Sanitization contract
42+
43+
Hashes and sanitized facts only; raw receipt JWTs, SD-JWT disclosures, and mandate bodies MUST NOT appear in public projections.
44+
45+
## Sources
46+
47+
- [§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope), [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks), [§1.7.6](../../atrib-spec.md#176-cross-attestation-requirement-for-transaction-records)
48+
- [D098](../../DECISIONS.md#d098-ap2-receipts-stay-external-evidence-for-cross-attestation), [D107](../../DECISIONS.md#d107-ap2-counterparty-attestation-signs-atrib-transaction-bytes), [D137](../../DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model)
49+
- Profile-internal corpus: [`spec/conformance/ap2-vi-crypto/`](../../spec/conformance/ap2-vi-crypto/); envelope corpus: [`spec/conformance/evidence-envelope/`](../../spec/conformance/evidence-envelope/)
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Evidence profile: `counterparty-attestation`
2+
3+
- **Type URI:** `https://atrib.dev/v1/evidence/counterparty-attestation`
4+
- **Profile version:** `1.0.0` (semver of this document)
5+
- **Status:** atrib-maintained. Envelope-native (no legacy [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks) protocol string; frozen set).
6+
7+
Carries an out-of-band co-signature receipt from a counterparty about an agent action or transaction — for example an AP2 receipt signature that arrives outside the record's `signers[]` array. This is external evidence about attestation, never a substitute for the [§1.7.6](../../atrib-spec.md#176-cross-attestation-requirement-for-transaction-records) cross-attestation rule ([D098](../../DECISIONS.md#d098-ap2-receipts-stay-external-evidence-for-cross-attestation) / [D107](../../DECISIONS.md#d107-ap2-counterparty-attestation-signs-atrib-transaction-bytes)). It never alters `verifyRecord().valid` ([§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope)).
8+
9+
## Payload media types and hash rule
10+
11+
| Media type | Payload | Hash rule |
12+
| ------------------ | ------------------------------------------ | --------------------------- |
13+
| `application/jwt` | Signed receipt / attestation JWT (UTF-8) | raw bytes (`rawSha256`) |
14+
| `application/json` | Attestation object / co-signature receipt | JCS (RFC 8785, `jcsSha256`) |
15+
16+
`payload.hash` = `"sha256:" + hex(SHA-256(bytes))`. When the attestation signs the atrib transaction bytes ([D107](../../DECISIONS.md#d107-ap2-counterparty-attestation-signs-atrib-transaction-bytes)), `ref.record_hash` MAY name the attested transaction record. Raw receipts stay local-only.
17+
18+
## Facts schema
19+
20+
| Fact | JSON type | Provenance class |
21+
| ------------------- | --------------- | ---------------- |
22+
| `attester_key` | string \| null | verifier-derived |
23+
| `attested_subject` | string \| null | caller-attested |
24+
| `signature_valid` | boolean \| null | verifier-derived |
25+
| `attested_at_ms` | number \| null | caller-attested |
26+
27+
`attester_key` is the counterparty key; `signature_valid` reflects verification of the receipt signature over the attested bytes.
28+
29+
## Tier semantics
30+
31+
- `declared` — receipt hash and facts asserted.
32+
- `shape` — receipt parsed and structurally validated.
33+
- `attested` — a caller-owned path accepted the counterparty signature.
34+
- `verified` — the counterparty signature verified against `attester_key` over the attested bytes, reproducible from the envelope.
35+
36+
## Verifier behavior
37+
38+
The verifier checks the receipt signature and surfaces `signature_valid`. Critically, a verifier that sees only a `counterparty-attestation` envelope for a transaction record still reports `cross_attestation_missing: true` ([D052](../../DECISIONS.md#d052-cross-attestation-requirement-for-transaction-records)): only distinct verified `signers[]` entries over the canonical transaction bytes satisfy the ≥2-distinct-keys minimum. The envelope is corroborating evidence, not a signer.
39+
40+
## Sanitization contract
41+
42+
`attester_key`, `attested_subject`, `signature_valid`, `attested_at_ms`, and `payload.hash` MAY appear in public projections. Raw receipt tokens and any counterparty PII in the receipt body MUST NOT appear.
43+
44+
## Sources
45+
46+
- [§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope), [§1.7.6](../../atrib-spec.md#176-cross-attestation-requirement-for-transaction-records)
47+
- [D098](../../DECISIONS.md#d098-ap2-receipts-stay-external-evidence-for-cross-attestation), [D107](../../DECISIONS.md#d107-ap2-counterparty-attestation-signs-atrib-transaction-bytes), [D137](../../DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model)
48+
- Envelope corpus: [`spec/conformance/evidence-envelope/`](../../spec/conformance/evidence-envelope/)
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Evidence profile: `delegation-certificate`
2+
3+
- **Type URI:** `https://atrib.dev/v1/evidence/delegation-certificate`
4+
- **Profile version:** `1.0.0` (semver of this document)
5+
- **Status:** atrib-maintained. Envelope-native. No legacy [§5.5.6](../../atrib-spec.md#556-generic-authorization-evidence-blocks) protocol string exists or may be introduced for delegation; the legacy set is frozen ([§1.11.8](../../atrib-spec.md#1118-carriage)).
6+
7+
The verifier-facing carrier for a delegation certificate: a principal key's signed statement `{run_pubkey, scope, not_after, context_id?}` certifying an ephemeral run key that occupies the `creator_key` slot of run records ([D140](../../DECISIONS.md#d140-delegation-certificates-principal-keys-certify-ephemeral-run-keys)). It is the third carrier alongside the `_local.delegation_cert` sidecar and the archive evidence surface ([§1.11.8](../../atrib-spec.md#1118-carriage)). It never alters `verifyRecord().valid` ([§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope)); depth-0 (uncertified) records verify exactly as today.
8+
9+
## Payload media type and hash rule
10+
11+
| Media type | Payload | Hash rule |
12+
| ------------------ | -------------------------------- | --------------------------- |
13+
| `application/json` | The certificate object | JCS (RFC 8785, `jcsSha256`) |
14+
15+
`payload.hash` = `"sha256:" + hex(SHA-256(JCS(certificate)))`, i.e. the certificate's `cert_hash`; the payload MAY instead be carried by reference as that `cert_hash`. **`ref.record_hash` never applies — a certificate is not a signed atrib record** ([§1.11.8](../../atrib-spec.md#1118-carriage)). `ref.kind` is `inline` (with the certificate body local-only), `mirror`, `archive`, or `withheld`.
16+
17+
## Facts schema
18+
19+
The profile's verifier facts are the [§1.11.4](../../atrib-spec.md#1114-verifier-walk) walk outputs (the `delegation` block), all verifier-derived:
20+
21+
| Fact | JSON type | Notes |
22+
| ---------------- | --------------- | -------------------------------------------- |
23+
| `depth` | number (0 \| 1) | 0 = identity case, no certificate |
24+
| `principal_key` | string \| null | null at depth 0 |
25+
| `cert_hash` | string \| null | matches `payload.hash` |
26+
| `cert_valid` | boolean \| null | certificate signature/format validity |
27+
| `in_window` | boolean \| null | `not_before <= R.timestamp <= not_after` |
28+
| `context_bound` | boolean \| null | null when the cert has no `context_id` |
29+
| `cert_bound` | boolean \| null | null when no genesis `delegation_cert_hash` |
30+
| `scope_check` | object \| null | `{ in_scope, attenuation_ok, mismatches[] }` |
31+
| `revoked` | boolean \| null | run-key or principal revocation ([§1.11.5](../../atrib-spec.md#1115-run-key-revocation)) |
32+
33+
## Tier semantics
34+
35+
- `declared` — certificate hash and facts asserted.
36+
- `shape` — certificate parsed and structurally validated.
37+
- `attested` — a caller-owned path accepted the certificate.
38+
- `verified` — principal signature over `{run_pubkey, scope, not_after, context_id?}` verified and the [§1.11.4](../../atrib-spec.md#1114-verifier-walk) walk reproduced offline against declared trust roots.
39+
40+
## Verifier behavior
41+
42+
The verifier runs the [§1.11.4](../../atrib-spec.md#1114-verifier-walk) offline walk: it never alters `R.signature` validity; run keys are resolved through the principal, not the directory (`run_key_in_directory: true` is a structural anomaly); scope is signal-not-block per [§6.7.3](../../atrib-spec.md#673-out-of-envelope-is-a-signal-not-invalidation); and two valid certificates from different principals covering one run key set `delegation_ambiguous: true` rather than choosing. All facts are signals; none invalidate the record.
43+
44+
## Sanitization contract
45+
46+
Certificates contain only public keys, a scope, and timestamps — no salted-commitment or PII concern ([§1.11.8](../../atrib-spec.md#1118-carriage)). `cert_hash`, `principal_key`, and every walk fact MAY appear in public projections; the certificate body MAY be surfaced (public-key/scope/timestamp only), unlike raw tokens in other profiles.
47+
48+
## Sources
49+
50+
- [§5.5.7](../../atrib-spec.md#557-universal-evidence-envelope), [§1.11.4](../../atrib-spec.md#1114-verifier-walk), [§1.11.8](../../atrib-spec.md#1118-carriage)
51+
- [D140](../../DECISIONS.md#d140-delegation-certificates-principal-keys-certify-ephemeral-run-keys), [D137](../../DECISIONS.md#d137-universal-evidence-envelope-as-the-single-protocol-level-attachment-model)
52+
- Certificate corpus: [`spec/conformance/delegation-certificates/`](../../spec/conformance/delegation-certificates/); envelope corpus: [`spec/conformance/evidence-envelope/`](../../spec/conformance/evidence-envelope/)

0 commit comments

Comments
 (0)