COSE envelope adoption: consumers and the v0.1 issuance end date (#243 phases 4-5)

[imran-siddique]

Split out of #243, which closes with phases 1-3 complete: the envelope is specified (#248), implemented behind the version gate (#274), and has a portable negative-vector contract (#302, AM-VEC-COSE-002..015).

The two remaining phases are adoption rather than design, they move on a different clock, and neither was what the CoSAI WS4 review (ws4 #149, review track 3) was asking about. Keeping them inside the migration issue made it look open on the design question when the design question is settled.

Phase 4 — consumers

• cmcp and ca2a both now have explicit Agent Manifest consumer paths. cmcp#530 is green and awaiting maintainer review. ca2a#121 merged and shipped in cA2A v0.2.0.
• cA2A verifies v0.1 JSON and v0.2 COSE through its startup identity-binding path, rejects untrusted and tampered envelopes, and does not fall back from a v0.2 envelope to the v0.1 detached block. Remaining consumer work is to merge cmcp#530 and make the v0.1-under-v0.2 negotiation rejection explicit wherever it is not already asserted at the consumer boundary; AM-VEC-COSE-012 and 014 remain the portable vector contract.
• A TypeScript SDK is on the roadmap and not started. When it exists it is written against COSE from the start rather than ported to v0.1 and migrated twice, which is what phase 4 recorded and is still the right call.

Phase 5 — deprecation

Announce an end date for issuing v0.1 manifests. Verification of v0.1 records stays supported through the retention window: these are audit records with regulated retention well beyond their 90-day life, and a verifier that stops reading them destroys evidence rather than tidying a codebase.

The date is a maintainer decision, not a technical one, and it should not be set before phase 4 shows a consumer verifying v0.2 in anger.

Out of scope, still

Reconciling ADR-0005 with the implemented CryptoProfile values, carried over from #243's own out-of-scope list.

[imran-siddique]

Phase 4, cmcp half: the consumer could not verify v0.2 at all

Landing in cmcp#530. This turned out to be a real defect rather than a missing test.

cmcp pinned agent-manifest>=0.11, so the COSE verifier was available, and nothing there had ever presented a v0.2 manifest to it. It could not have worked: load_agent_manifest read JSON and _verify_with_sdk passed a dict, and from v0.2 the COSE_Sign1 structure is the signature. A v0.2 document handed over as a dict has no signature to appraise, so the SDK correctly returned SIGNATURE_MISSING, which cmcp surfaced as "signature block is missing" — an error that reads as a malformed manifest rather than a manifest supplied in the wrong form, and the first one an operator following the v0.2 spec would have hit.

Fixed by carrying the envelope bytes alongside the decoded document and handing the envelope to the verifier. test_cose_envelope_binds_end_to_end is the evidence this issue was asking for: a genuinely signed envelope through cmcp's own binding path to a bound session identity, plus untrusted-key and tampered-payload rejection, and the v0.1 path unchanged.

Worth recording for the ca2a half: the "available through the published package" claim was doing no work. Depending on a version that contains a verifier is not the same as reaching it, and the pin was satisfied for weeks while the path was unreachable. ca2a pins >=0.10 and should be assumed to have the same defect until a test says otherwise, rather than checked by reading its dependency line.

Remaining on this issue:

• ca2a — same check, and probably the same fix.
• Version negotiation in both directions at the consumer level. AM-VEC-COSE-012 and 014 pin it at the vector level: a v0.1 payload must not be verified under v0.2 rules, and a v0.2 manifest must not fall back to the v0.1 detached block. cmcp#530 covers the second direction implicitly by rejecting a bare v0.2 payload; neither consumer asserts the first.
• TypeScript SDK — still not started, and still the right call to write it against COSE from the start.
• Phase 5 — the v0.1 issuance end date. One consumer now verifies v0.2 end to end, which was the precondition; ca2a is the other half before a date is worth setting.

[imran-siddique]

ca2a half: there is nothing to migrate, and the phase 4 wording was wrong

Checked rather than assumed, and the answer changes this issue's scope.

ca2a does not verify Agent Manifests. It imports agent_manifest for TEE parsing primitives only: parse_snp_report, SNP_OFFSETS, SNP_REPORT_LEN, parse_tpmt_signature, verify_tpm_quote, verify_cert_chain. There is no call to verify_manifest, no VerificationContext, and no manifest loader anywhere in src/ or tests/. Its >=0.10 pin buys shared attestation parsers, not the verifier.

So phase 4's original wording — "cmcp and ca2a consume the verifier through the published package and move when v0.2 verification ships" — was accurate for cmcp and wrong about ca2a. Nothing in ca2a is affected by the envelope change, and there is no v0.2 migration for it to do. What it does depend on is the parser surface staying stable, which is what #255 is about (absorbing the TPMT_SIGNATURE parse so cmcp and ca2a can drop their copies) rather than anything envelope-related.

Where the credential work touches this is narrower and worth stating so it is not confused with verification: ca2a_runtime.delegation.credential documents its signatures as cross-verifiable with agent-manifest through the shared canonical form. That is an RFC 8785 dependency, not an envelope dependency, and RFC 8785 is unchanged in v0.2. It is also the thing that would break silently if the canonical form ever moved, so it is worth a cross-repo vector at some point — not part of this issue.

Revised remaining scope:

• ca2a — same check, and probably the same fix Not applicable. No manifest verification.
• Version negotiation in both directions at the consumer level. Still open. AM-VEC-COSE-012 and 014 pin it at the vector level; cmcp#530 covers one direction by rejecting a bare v0.2 payload, and neither consumer asserts that a v0.1 payload is not verified under v0.2 rules.
• TypeScript SDK. Not started.
• Phase 5, the v0.1 issuance end date. The precondition was a consumer verifying v0.2 end to end, and cmcp#530 is that. ca2a was never the second half of it, so the date is now gated on the negotiation assertion above and on a maintainer decision rather than on another consumer.

[imran-siddique]

Phase 4 status from a direct consumer-path audit (2026-08-18):

• cMCP now has the v0.2 end-to-end path in feat(manifest): verify a v0.2 COSE manifest, not just a v0.1 document (#315) cmcp#530: a signed COSE envelope reaches cMCP's own binding path, v0.1 still verifies, and v0.2 bare-JSON fallback is rejected. The PR is green, ready, reviewer-assigned, and auto-merge enabled.
• ca2a pins agent-manifest for shared hardware-attestation primitives only. Current main has no Agent Manifest loader, verifier adapter, identity binding, configuration surface, documentation contract, or prior issue/PR defining one. There is therefore no ca2a "own verification path" through which to run the proposed COSE case.

Adding a verifier solely to make the test exist would invent a new identity/manifest architecture without a consumer contract. The ca2a half of Phase 4 needs a maintainer decision first: either (a) declare ca2a not an Agent Manifest consumer and remove it from this adoption criterion, or (b) open/design the ca2a Agent Manifest integration surface, then land the v0.1/v0.2 negotiation tests with that feature.

Phase 5 remains gated as the issue says: do not set the v0.1 issuance end date until consumer adoption is demonstrated and maintainers choose the date.

[imran-siddique]

Phase 4 correction: cA2A is now a consumer

This supersedes my earlier comments that found no cA2A Agent Manifest surface. That finding was correct for the code at the time; ca2a#121 then deliberately added the missing contract rather than treating the dependency pin as adoption.

The PR merged after maintainer approval and shipped in cA2A v0.2.0. Its startup path loads v0.1 JSON or v0.2 COSE, verifies the manifest against a pinned trust anchor, binds agent_id to the configured node identity, rejects tampered/untrusted material, and refuses v0.2 bare-JSON fallback. The release passed the Linux/Windows Python matrix, conformance, artifact smoke tests, PyPI trusted publishing, signed container build, SBOM, and governance evidence upload.

Remaining on #315:

• merge cmcp#530, which is green and review-gated;
• make the v0.1-under-v0.2 negotiation rejection explicit at each consumer boundary where it is not already asserted;
• choose and announce the v0.1 issuance end date after that assertion lands, while retaining v0.1 verification for the evidence-retention window;
• keep the TypeScript SDK as its own roadmap item rather than pretending the Python consumers constitute a second implementation.

[imran-siddique]

Bidirectional negotiation assertion now present in both consumers

• cmcp#530 now exercises a correctly signed v0.2 COSE envelope whose payload declares v0.1 and asserts rejection at cMCP's loader boundary. Focused COSE suite: 11 passed. The PR remains ready, maintainer-assigned, and auto-merge enabled.
• ca2a#122 adds the same AM-VEC-COSE-012 case through cA2A's startup loader. Focused Agent Manifest suite: 9 passed. The PR is ready, assigned to all repository maintainers, and auto-merge enabled.

Once those review-gated PRs merge, Phase 4's Python-consumer criterion is complete. Phase 5 then has one decision left: choose and announce the v0.1 issuance end date while retaining v0.1 verification for the evidence-retention window. The TypeScript SDK remains separately tracked roadmap work.

[imran-siddique]

Phase 4 is complete, and Phase 5 has a date

Phase 4. Both outstanding items landed on 2026-08-19. cmcp#530 merged, so cMCP verifies a correctly signed v0.2 COSE envelope and rejects one whose payload declares v0.1 at its loader boundary. ca2a#122 merged the same AM-VEC-COSE-012 case through cA2A's startup loader. That was the "make the v0.1-under-v0.2 negotiation rejection explicit wherever it is not already asserted at the consumer boundary" item, and it is now asserted in both consumers rather than one.

The TypeScript SDK stays as recorded: not started, and when it exists it is written against COSE from the start rather than ported and migrated twice.

Phase 5. Issuing v0.1 manifests ends 2026-11-30.

That is roughly one v0.1 record lifetime of notice, which is the shortest period that cannot strand anything already in flight. From that date the reference implementation issues v0.2 COSE only.

Verification of v0.1 records is not deprecated and has no end date. These are audit records under retention obligations that outlast their 90-day validity by years, and a verifier that stops reading them destroys evidence rather than tidying a codebase. If that ever changes it will be its own decision with its own notice, not a consequence of this one.

The condition this issue set for picking a date was that Phase 4 show a consumer verifying v0.2 through a real path rather than a test harness. Two do, through their startup and loader boundaries, including the negative case. I am treating that as met.

Still out of scope, carried from #243: reconciling ADR-0005 with the implemented CryptoProfile values.

Closing once the date is recorded in CHANGELOG.md and the spec's deprecation note.

[imran-siddique]

Both phases are complete. Closing.

Phase 4, consumers. cmcp#530 and ca2a#122 merged 2026-08-19. cMCP verifies a correctly signed v0.2 COSE envelope and rejects one whose payload declares v0.1 at its loader boundary; cA2A asserts the same AM-VEC-COSE-012 case through its startup identity-binding path. That was the last outstanding consumer item, and it is now asserted in both rather than one.

Phase 5, deprecation. Issuing v0.1 manifests ends 2026-11-30, recorded in spec/agent-manifest-spec-v0.2.md §2.4 and CHANGELOG.md by #336. Roughly one v0.1 record lifetime of notice.

Verifying v0.1 manifests is not deprecated and has no end date, which the spec now says explicitly rather than leaving to inference. INCOMPATIBLE_VERSION stays reserved for versions a verifier genuinely cannot interpret and never for v0.1. Manifests are audit records under retention obligations that outlast their validity by years, so a verifier that stopped reading them would destroy evidence rather than remove code.

Two things stay open elsewhere rather than here, both correctly:

• The TypeScript SDK, not started. When it exists it is written against COSE from the start rather than ported to v0.1 and migrated twice, which is what phase 4 recorded and is still the right call.
• Reconciling ADR-0005 with the implemented CryptoProfile values, carried over from Migrate the manifest signature envelope to COSE_Sign1 (ADR-0011, spec v0.2) #243's out-of-scope list and still out of scope.

Reopening if 2026-11-30 arrives and the reference implementation is still issuing v0.1.