specs: publish the layered ANS specification#24
Open
scourtney-godaddy wants to merge 4 commits into
Open
Conversation
Adds spec/ans-{0-5}-*.md plus spec/examples/ans-1-examples.md.
Updates README.md to point at the layered specs. Replaces DESIGN.md
with a thin pointer to spec/ and to the IETF draft.
TRUST_INDEX_SPEC.md, MAESTRO.md, SENDER_VERIFICATION_SPEC.md,
CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE, and pki/
are unchanged.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR publishes the layered ANS specification under spec/ (ANS-0 through ANS-5), adds a worked examples document for ANS-1, and replaces the previous long-form DESIGN.md with a short pointer to the new layered specs (plus the related IETF draft).
Changes:
- Add six new spec documents under
spec/covering identity anchors, registration/lifecycle, versioned naming, DNS publication, transparency, and integrity monitoring. - Add non-normative worked examples for ANS-1 under
spec/examples/. - Update
README.mdand replaceDESIGN.mdwith links into the layered spec set.
Reviewed changes
Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/ans-0-identity-anchor.md | Adds the ANS-0 identity anchor spec (IdentityClaim, AnchorResolver, profiles). |
| spec/ans-1-registration.md | Adds the ANS-1 registration & lifecycle spec (aggregate, state machine, events, Trust Card). |
| spec/ans-2-versioned-naming.md | Adds the ANS-2 versioned naming spec (ANSName, identity cert, PriCC, mTLS, aliases). |
| spec/ans-3-dns-publication.md | Adds the ANS-3 DNS publication spec (SVCB/TXT styles, TLSA, emission rules). |
| spec/ans-4-transparency.md | Adds the ANS-4 transparency spec (SCITT statements/receipts, witness profiles, API). |
| spec/ans-5-integrity-monitoring.md | Adds the ANS-5 integrity monitoring spec (verification worker, check set, reporting). |
| spec/examples/ans-1-examples.md | Provides non-normative JSON payload examples for ANS-1. |
| README.md | Updates docs entrypoint to point at layered specs under spec/. |
| DESIGN.md | Replaces prior long-form design doc with a pointer to spec/ and the IETF draft. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Author
|
/copilot review |
- ans-1 §7.3 anchor link fixed (ANS-3 §6.2 now Status: Active). - ans-5 §8 dropped reference to non-existent operating-cadence section. - ans-4 and ans-5 Worked Examples appendices added with relative-path pointers; ans-4-examples.md and ans-5-examples.md added under spec/examples/. - ans-1-examples §A.1, §A.2 realigned to the flat ANS-1 §6.1 event shape with claim sub-block (anchorType, resolvedId, publicKey, issuedAt). Replaces the prior nested 'agent' wrapper. - ans-4-examples §A.3 revocation event realigned to the same flat shape. - Vectors-planned conformance lines dropped from ans-0 §5, ans-3 §9, ans-4 §9, ans-5 §8. - Worked-examples pointer in ans-1-registration §B uses relative path.
… lint
Field/format alignment of the layered specs (spec/ans-0..5 + examples) to the
authoritative API contracts, ahead of the reference implementation:
- RA request & Trust Card fields use the V1 RA names: agentDisplayName,
agentDescription, version, identityCsrPEM, serverCsrPEM, metaDataUrl, and the
new metaDataHash (SHA256:-prefixed).
- TL event / badge / envelope examples use the V2 TL response format: ansId
(distinct from the RA agentId by design), nested agent{host,name,version,
providerId}, identityCerts[]/serverCerts[] arrays, dnsRecordsProvisioned[]
objects, merkleProof, schemaVersion "V2", status {ACTIVE,REVOKED,DEPRECATED}.
- SHA256: hash prefixes throughout; PENDING -> PENDING_VALIDATION lifecycle;
ansId identifier row added.
- ANS-5 schema-integrity check keyed off metaDataUrl + the TL metadataHashes map.
- Add .github/linters/.markdown-lint.yml and clear markdownlint issues repo-wide
(table-delimiter padding, fence languages, heading levels, bare URL/email
wrapping, list indentation).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jdamick
reviewed
Jun 10, 2026
|
|
||
| The AHP submits a registration request. The payload structure mirrors `RegisterInput` defined above plus a few fields the RA derives or fills in: | ||
|
|
||
| | Group | Field | Required | Description | |
There was a problem hiding this comment.
Instead of giving these in a table, is there a json schema or CDDL that shows describes the input? ideally linking to the actual schema file so that someone can just import it and run with it.
|
|
||
| ## 3. The `RegistrationService` interface | ||
|
|
||
| The `RegistrationService` interface is the protocol contract for ANS-1; conformant implementations expose `register`, `verifyACME`, `getRegistration`, and the lifecycle event surface. ANS-1 carries the `LifecycleStatus` enum (`PENDING`, `PENDING_DNS`, `ACTIVE`, `DEPRECATED`, `REVOKED`, `EXPIRED`) and the registration fields `description`, `serverCsr`, `serverCertificatePEM`, and `echConfigList` on `RegisterInput`. |
There was a problem hiding this comment.
instead of giving this in words, i think it would be clearly to just reference the json schema or openapi spec that describes what the interface needs to adhere to to be compliant.
| | **On-chain (optional cross-anchor signal)** | `onChainId`, `ensName` | No | Persistent ledger identifiers, verified post-activation by ANS-5 | | ||
| | **Discovery (optional)** | `ansUrn` | No | URN alias for Agent Finder catalog entries (e.g., `urn:acme:agent:support`); not an identity anchor | | ||
|
|
||
| When `trustCardContent` is provided, the RA hashes it (SHA-256 over JCS-canonical bytes per ANS-4 §canonicalization) and seals the hash into the TL at activation. When omitted and the AHP hosts a Trust Card, ANS-5 computes the baseline hash on first successful fetch. |
There was a problem hiding this comment.
Are there steps somewhere that spells this out this process?
| - The skill registration sub-profile, where artifacts register as catalog entries under a parent agent. | ||
| - Capability token discipline for ANS-registered agents issuing verifiable credentials to verifiers. | ||
|
|
||
| ANS-1 is **anchor-agnostic**: it reads identity through `IdentityClaim` only and never branches on the anchor type. A `RegistrationService` composes with any ANS-0 profile by configuration alone. |
There was a problem hiding this comment.
is this relevant to mention for implementors?
Comment on lines
+13
to
+20
| - The `RegistrationService` code-interface contract: register, verify-acme, verify-dns, deprecate, revoke. | ||
| - The registration aggregate's data shape and identifier set. | ||
| - The lifecycle state machine (PENDING → PENDING_DNS → ACTIVE → DEPRECATED → REVOKED, plus EXPIRED). | ||
| - The event set the RA emits to the Transparency Log (ANS-4) and event stream consumers. | ||
| - The cross-anchor `EquivalenceLink` event shape. | ||
| - Base-only registration handling, including the special-case rules around verification and uniqueness. | ||
| - The skill registration sub-profile, where artifacts register as catalog entries under a parent agent. | ||
| - Capability token discipline for ANS-registered agents issuing verifiable credentials to verifiers. |
There was a problem hiding this comment.
i'm not sure if these points really add clarity, can it be just a 1-liner scope? Starting with all of these just confuses the reader before they really understand the purpose of the RA and it references other material, the cognitive load here is high..
|
|
||
| ### 12.2 Unstable payload fields | ||
|
|
||
| Some payload fields (`onChainId`, `ensName`, `ansUrn`) are advisory metadata at registration and verified post-activation by ANS-5. ANS-1 stores them but does not gate registration on their validity; an attacker who lies about an unrelated `onChainId` cannot prevent registration but produces a verification failure once ANS-5 catches up. |
There was a problem hiding this comment.
this sounds like i can store whatever i want in a onChainId? i the the api schema would take care of this clarity and the words aren't really needed..
| | Anchor expires (FQDN domain expires; LEI lapses to inactive; DID document removed) | Endpoint unreachable; subsequent re-validation fails | RA treats the anchor-proof failure as a security event and MUST emit `AGENT_REVOKED` | | ||
| | TL unavailable | New registrations queue; in-flight registrations retain `PENDING` status | RA MUST NOT activate without a sealed event (step (d) is the point of no return) | | ||
|
|
||
| ## Appendix A: Trust Card and metadata (normative) |
There was a problem hiding this comment.
i would carefully consider what is relevant in the appendix and what is superfluous and can be removed.
|
|
||
| Conformant ANS-1 implementations MUST gate identity-cert issuance on the presence of an Identity CSR, not unconditionally on lifecycle entry. An implementation that requires a pending Identity CSR for every `verifyACME` call rejects all base-only DID and LEI registrations and is non-conformant. | ||
|
|
||
| ### 4.4 The state machine |
|
|
||
| ### 4.2 Stage 2 — activation | ||
|
|
||
| Activation requires four validations (all MUST pass): |
There was a problem hiding this comment.
probably a sequence or activity diagram would clarify this
| | (a) Certificate issuance | RA obtains the Server Certificate from a Public CA (if CSR) or validates the BYOC certificate. **Conditional on `versionSelector` being present**, the RA also obtains the Identity Certificate from the Private CA per [ANS-2 §3](ans-2-versioned-naming.md). For base-only registrations, the Identity Certificate branch does not run | | ||
| | (b) DNS record generation | RA generates record set content per [ANS-3 §3](ans-3-dns-publication.md) | | ||
| | (c) Event payload | RA hashes Trust Card content (if submitted) and assembles the event payload | | ||
| | (d) Log sealing | RA submits signed event to ANS-4 TL. Point of no return | |
There was a problem hiding this comment.
i'm not sure what "log sealing" means in this context.
specs: align layered ANS specs with RA v1 / TL V2 contracts; markdown…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Publishes the layered ANS specification under
spec/and replaces DESIGN.md with a thin pointer.What lands
spec/ans-0-identity-anchor.md: Identity anchor,IdentityClaim,AnchorResolver, FQDN/DID/LEI profiles.spec/ans-1-registration.md: Registration aggregate, lifecycle, event set, Trust Card.spec/ans-2-versioned-naming.md: ANSName URI form, Identity Certificate URI SAN binding, PriCC, Stable Aliases, mTLS.spec/ans-3-dns-publication.md: DNS publication, record styles, DANE, anchor-conditional emission.spec/ans-4-transparency.md: SCITT statements and receipts, Transparency Log, witness profiles.spec/ans-5-integrity-monitoring.md: Verification worker, integrity reporting.spec/examples/ans-1-examples.md: Worked registration request and event-payload examples.README.md: points at the layered specs.DESIGN.md: replaced with a pointer tospec/and todraft-narajala-courtney-ansv2.Companion documents unchanged
TRUST_INDEX_SPEC.md, MAESTRO.md, SENDER_VERIFICATION_SPEC.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE, and
pki/remain as-is.Authoritative source
The layered specs are maintained in the upstream registry repository and mirrored to this public repository. Future spec changes land upstream first, then mirror here.