feat(ra): bundled signed agent attestation — GET /v2/ans/agents/{agentId}/attestation

[nicknacnic]

Summary

Adds GET /v2/ans/agents/{agentId}/attestation — an anonymous-read RA endpoint that returns a single COSE_Sign1 (RFC 9052, CBOR tag 18) bundling an agent's current registration state with its transparency-log inclusion proof. A third-party verifier fetches one document, validates two signatures (RA producer key + TL checkpoint key), and has cryptographic certainty of both the agent's identity and its TL inclusion — with no second key-distribution channel.

Use case: an external verifier (a marketplace, an API gateway, a DNS-AID-aware client resolving a flat-FQDN agent) wants to confirm an agent is genuinely registered with this RA and that the registration is sealed in the TL. Today they need to compose three reads: agent metadata from the RA, a producer key from the TL's /internal/v1/producer-keys, and the receipt from the TL. This endpoint collapses that to one fetch with the binding baked in.

What ships

The envelope. A new AttestationPayload value type with byte-pinned CBOR tags:

iss, sub, did, iat, exp,
identity_cert_spki_sha256, server_cert_spki_sha256,
dns { verified_at, tlsa_records, dnssec_validated },
tl  { log_url, leaf_hash, tree_size, receipt },
trust_scheme (optional, TRAIN)

• sub is the agent's flat-FQDN — drops directly onto an x.509 SAN dNSName and onto a draft-mozleywilliams-dnsop-dnsaid-02 flat owner record without translation.
• did is the lossless did:web: alias of sub; derived server-side so callers can't ship an inconsistent (sub, did) pair.
• dns.tlsa_records is the TLSA bundle the RA's DNS verifier captured at registration / latest renewal, so a verifier can compare against what it independently resolves.
• tl.receipt is the existing TL-signed SCITT COSE_Sign1 receipt, embedded verbatim.

Two-key verification topology. The outer COSE_Sign1 is signed by the RA's producer key — the same ECDSA P-256 key that signs every event going to the TL via the outbox, already listed in the TL's producerKeys[] trust store. The embedded tl.receipt is signed by the TL's checkpoint key advertised at /root-keys. The shared producer key is load-bearing: a verifier holding it can validate the outer envelope without an extra key fetch.

This mirrors the OmniOne Open DID TAS pattern — a Trust Agent Service issues membership credentials, anchored in a Trust Repository — with ANS playing the TAS role and the TL playing the Trust Repository role.

Wire-format consolidation. Extracts the COSE_Sign1 assembly into a new internal/crypto/cose package so the byte-layout invariant lives in exactly one place across the three call sites (SCITT receipts, status tokens, agent attestations). Deterministic CBOR per RFC 8949 §4.2; ECDSA P-256 in IEEE P1363 form; CBOR tag 18.

Error model. RFC 7807 problem+json on every non-success path, distinct codes for the two 503 cases (TL_LEAF_UNCOMMITTED retries fast, TL_NOT_REACHABLE retries slow) so operators can tell a transient TL race from infrastructure trouble.

CLI. New ans-verify attest subcommand encapsulates the verification flow: outer-signature against an RA pubkey PEM, embedded receipt against TL /root-keys, and a leaf_hash == RFC 6962 SHA-256(0x00 || receipt-attached-payload) cross-check that catches a TL handing out a valid receipt for the wrong leaf. Existing single-agent verify form unchanged.

End-to-end test. scripts/demo/test-attestation.sh registers a fresh V2 agent, waits for the TL receipt to materialize, fetches the bundled attestation, asserts the HTTP shape (200, application/cose, Cache-Control: public, max-age=3600, CBOR tag-18 marker), then runs ans-verify attest offline. Every successful run cryptographically proves both signatures.

Commits

Eight commits, landing in dependency order:

1. OpenAPI spec for the route (contract first; downstream code encodes against this)
2. Extract COSE_Sign1 envelope assembly into internal/crypto/cose
3. domain/AttestationPayload value type with strict validation
4. tlclient.GetReceipt for pulling the SCITT proof
5. service/AttestationService (composes domain + crypto + tlclient)
6. HTTP handler with the full error model
7. Wire the route into ans-ra (anonymous read, shared producer key)
8. ans-verify attest subcommand + end-to-end integration script

Why anonymous read

The attestation IS the document a third-party verifier fetches. Putting it behind bearerAuth would mean every verifier needs a credential issued by the RA's identity provider — exactly the trust relationship the COSE envelope is supposed to make unnecessary. The sibling GET /ans/agents/{agentId} remains owner-scoped for operator management. Auth adapter gains WithAnonymousPathSuffix so parameterized routes can opt out of auth without prefix-matching onto owner-scoped siblings; a regression test confirms the sibling still requires auth.

Configuration

Three new config keys under attestation:

Key	Purpose	Default
`attestation.issuer_url`	Externally-reachable RA base URL, written into `iss` + CWT issuer claim	falls back to `http://server.host:server.port\` for local dev
`attestation.ttl`	Payload `exp` lifetime; matches `Cache-Control: max-age` so HTTP cache and crypto expiry decay together	`1h`
`attestation.trust_scheme`	Optional TRAIN trust-scheme DNS name	unset → field omitted from wire

Companion work

PR #32 (`feat/ans-verify-list-provider`) adds the by-provider enumeration mode on `ans-verify`. The two compose: enumerate every agent under a provider host, fetch each one's attestation, verify offline. Independent diffs; either order is fine.

The DNS-AID draft-02 reference implementation (dns-aid-core 0.24.0, shipped 2026-06-04) now publishes flat-FQDN owner records that this `sub` field aligns with byte-for-byte. A consumer that resolves a DNS-AID record can fetch the matching attestation here and verify with no naming translation.

Local verification

```
go build ./... # clean
go test ./... # 25 packages, all pass
scripts/demo/start.sh # bring up demo stack
scripts/demo/test-attestation.sh # e2e flow (registers, polls TL, verifies)
```

All commits are DCO-signed.

[nicknacnic]

Some related design context — last week I wrote up the layering question this PR sits inside of: how DNS + ANS + W3C VCs / OID4VC compose into an agent-identity substrate without standing up a new authority. The piece argues, with worked examples, that the substrate-agnostic DNS path (DNS-AID flat owner + TLSA + cap-sha256) plus an audit-log-anchored attestation (this PR) plus the wallet ecosystem's existing OID4VP/OID4VCI flows is enough to ship verifiable agent identity end-to-end.

Agent Identity Without a New Authority (2026-06-03)

Why it's relevant to this PR specifically:

• The post sketches a credential-issuance event type for the audit log (VC_ISSUED) that fits directly on top of the COSE_Sign1 envelope this PR introduces — same wire-format primitive, just a new eventType discriminant. Logging the credential hash (not the credential body) keeps the holder's claim data out of the log while still letting verifiers check inclusion.

• The sub field landing in this PR is the same flat-FQDN that appears in an OID4VP x509_san_dns chain — when a wallet validates a verifier's request object against the SAN, the attestation here is the corroborating substrate-layer document. One name across DNS, x.509 SAN, ANS attestation, and the OID4VP trust flow.

• The two-key verification topology (RA producer key + TL checkpoint key) is what lets a wallet check the substrate layer without trusting either the RA's HTTP endpoint or the TL's HTTP endpoint unilaterally — which is the property OpenDID-style deployments get from their TAS + Trust Repository split.

Not asking for any of this to be in scope for the present PR — the attestation route is the right unit to ship first. Flagging it because the design context informed the envelope shape and might inform a future-work section in the spec.

Happy to walk through any of it during review.

[aeoess]

Cache-Control: public, max-age=3600 seems to weaken the 410 revocation path. A shared cache can keep serving the earlier 200 for up to an hour after the RA begins returning 410, so even a client calling the endpoint may never reach the origin.

The payload has no lifecycle state, and the embedded TL receipt establishes inclusion of the registration leaf. It cannot exclude a later revocation event. That window matters most for key compromise, which /revoke names explicitly.

Was the one-hour revocation delay intentional? If the COSE document should stay valid for an hour while shared caches refresh more often, a shorter s-maxage would separate those two lifetimes. I would also state in the route description that the attestation records the RA's view at iat and does not establish current lifecycle state at verification time.

One related question: the attestation route defines 410 for REVOKED, while the lifecycle enum also includes EXPIRED and DEPRECATED. What should this endpoint return for those states? The status-token route treats EXPIRED and REVOKED as terminal, so an explicit mapping here would make verifier behavior clear.

[csnitker-godaddy]

Thanks for this, and sorry for the slow reply.

My main concern is the anonymous read on the RA. The RA is the management interface, so every agent route is owner-scoped on purpose, and the public read side is the TL. This route would be the first exception to that and I don't think we want to open it up for that purpose.

On the three reads in your description, I don't think that's the path today. Agent metadata from the RA is owner-scoped, so an external verifier can't read it. And the producer key isn't something an external verifier needs at all: the TL verifies the producer signature at ingest and rejects anything it can't attribute to a key in its trust store, so its signature already stands behind that check. /internal/v1/producer-keys is the admin route for managing that store, not a distribution point.

So it's already a single read on the TL side, and the only key involved is the TL's. ans-verify covers that today:

ans-verify -url https://tl.example.com -agent <agentId>

Is there something in the marketplace or gateway cases that this doesn't cover? If there is, I'd rather fix it there than on the RA.