docs(adr): ADR-0011, the manifest is a signed document not a JWT/JOSE profile

[imran-siddique]

Settles the "why not just a JWT extension?" question before the next standards conversation, and fixes what writing it turned up.

The ADR

docs/adr/0011-signature-envelope.md, status Proposed because part 2 needs your sign-off.

It argues from precedent rather than from capability. EAT (RFC 9711, Standards Track, April 2025) is steelmanned rather than waved away: the IETF genuinely did pick the JWT/CWT route for attestation tokens, and EAT supports nested tokens (§4.2.18.3) and Detached EAT Bundles (§5). Any rebuttal resting on "JWT cannot do this" loses to anyone who knows EAT.

What decides it is that every comparable object went the other way:

Standard	Object	Envelope
EAT (RFC 9711)	Attestation token about a caller	JWT / CWT profile
SCITT (RFC 9943, June 2026)	Signed statement + transparency receipt	COSE_Sign1, mandated
in-toto / SLSA	Multi-subject build attestation	DSSE, which rejected JWS in writing
C2PA	Multi-assertion content provenance	JUMBF + COSE_Sign1_Tagged

Part 1 (settled): the manifest is a signed document, not a bearer token. An EAT is a valid input to the attestation block. The layers compose; we are not a competitor to the token layer.

Part 2 (needs your call): the envelope encoding. The ADR records something this project never actually decided. We are neither JOSE nor COSE. signing_pre_image() produces RFC 8785 canonical bytes and the signature is a bespoke detached JSON object, so the spec's two "JWS" references were simply wrong. That third position carries both properties DSSE cites as reasons to avoid JWS (canonicalize-before-verify, no authenticated payload-type or algorithm binding) while lacking a specification anyone else implements. Recommendation is Option A, migrate to COSE_Sign1; Option B, harden what we have and write the rules down normatively, is legitimate if the churn is not worth it. Section 3.6 is unchanged until you pick.

The argument is not hypothetical for us: the crypto-profile downgrade fixed in 0.6.0 is exactly the algorithm-agility bug DSSE warns about, and COSE_Sign1 excludes that class structurally by putting alg in the protected header.

Also in this PR

A second fail-open on the same field. signature.algorithm is REQUIRED by spec 3.6 but sits outside the pre-image, and the verifier defaulted an absent identifier to Ed25519. 0.6.0 only caught a present-but-weaker one. A missing algorithm is now a mismatch, with a test.

Three factual errors in the spec. Sections 2.2 and 5 called the signature "JWS" (never true, there is no JOSE dependency). Section 10.4 cited EAT as RFC 9528, which is EDHOC; EAT is RFC 9711.

Section 3.6 gains a normative algorithm-binding rule so the verifier's behaviour is specified rather than merely implemented, and Section 10.4 gains RFC 9711 and RFC 9943 rows positioning Agent Manifest as the agent-layer profile of the SCITT model.

FAQ + nav. docs/index.md answers "why not specify it as a JWT or JOSE profile?" in short form. The mkdocs nav was missing ADR-0010 as well as 0011; both added.

Verification

Every RFC citation was fetched from rfc-editor.org rather than recalled, including the two that anchor the argument. That check earned its keep: it caught the RFC 9528 error, and the DSSE and C2PA quotes were pulled from source too.

• pytest: 618 passed, 18 skipped
• mypy, ruff: clean

Note, not addressed here

ADR-0005 describes CryptoProfile values as standard / post_quantum / hybrid, but the spec and the code use standard / post-quantum with hybrid expressed as a signature algorithm. ADR-0005 also says a verifier lacking ML-DSA support must reject a hybrid manifest with INCOMPATIBLE_VERSION, which is not what the verifier does. Worth reconciling, but it is a separate decision from this one.