skip to content
agentregistrar_

Conformance

The v1.2 relying-party conformance checklist, the separate attestation verdict, validator commands and exit codes, fixtures, and registry entry.

awaiting reviewupdated view markdown ->

A relying party is agent-identity-v1 conformant when the discovery document it serves at GET /.well-known/agent-signup.json passes the conformance validator with zero errors. Conformance is about the discovery document, not the vendor's product.

Conformance is not verification. A malformed rp_attestation field is a conformance error. An expired, invalid, untrusted, or unavailable attestation is a separate verification result. Conformance never calls Broker B; only explicit attestation verification does.

The normative checklist is spec section 21. The validator reference is the generated Conformance validator page.

Relying-party checklist

  • GET /.well-known/agent-signup.json returns 200 with Content-Type: application/json.
  • GET returns 404 or 410, never 401 or 403, when the service does not support the protocol.
  • protocol is exactly agent-identity-v1.
  • audience, provider_name, a non-empty issuer_allowlist, and unique required_scopes including tos:accept are present.
  • terms.text is the complete ToS text; terms.sha256 is sha256: plus 64 lowercase hex characters over its exact UTF-8 bytes; terms.url and terms.version are present and consistent.
  • endpoints.agent_signup is the only endpoint and is an absolute URL.
  • rp_attestation is omitted or is a compact JWS string of at most 16384 characters. Omission means unverified, not invalid.
  • No forbidden vendor field appears anywhere, including under extensions.
  • CORS and cache headers follow spec section 4; the body is within the 1 MiB cap.
  • Assertions are verified against issuer JWKS with every check in spec section 7.1.
  • Stable section 7.2 error codes are returned.
  • If a context pointer is used, it is on the vendor's registrable domain, uses HTTPS, and is hash-pinned. It is returned in the signup response and receipt, not in discovery.
  • A v1.2 signup_token is RP-signed, names service.origin, service.attestation_jti, and service.key_id, has no exp, and carries no instance_sku or endpoint_url.
  • If the provider claims verification, it publishes a valid credential and the registry entry carries all five verification fields from a live check.
  • A repeated signup for an existing account, keyed as recommended in spec section 9.1, resolves idempotently: it returns resolution: "resolved", does not re-issue provider credentials and sends no duplicate welcome or legal mail. This is a SHOULD.
  • The vendor guide documents a credential recovery or rotation path reached after signup, and that path is not advertised in discovery or the receipt. This is a SHOULD.

Two independent results

Result What it covers What it does not do
Document conformance Schema, ToS hash, scope boundary, field rules, and the rp_attestation field format. It never requires Broker B to be up.
Attestation verification Optional JWS parse, trusted issuer before fetch, signature, typ/alg/kid, time, origin/audience binding. It does not make the provider safe or change the conformance verdict.

A malformed field (not three base64url segments, over 16384 characters, or not a string) makes the run exit 1 and reports attestation.status: "not_checked", never invalid. An expired credential is a verification warning by default. A bad signature, origin mismatch, or audience mismatch is a verification failure. An absent field is unverified plus a warning.

Validate a document

Run the validator from a clone of agentregistrar/spec at the pinned tag. The package is source-first; install its dependencies first.

pnpm install
pnpm validate:discovery fixtures/valid-minimal.json
pnpm validate:discovery https://example.com/.well-known/agent-signup.json

For machine-readable output, pass --silent so stdout is pure JSON:

pnpm --silent validate:discovery https://example.com/.well-known/agent-signup.json --json | jq .

Verify the optional credential:

pnpm validate:discovery https://example.com/.well-known/agent-signup.json \
  --verify-attestation \
  --trusted-rp-broker https://agentregistrar.dev

Turn it into a gate with --require-attestation. Use --jwks to pin one issuer's JWKS for an offline run and --at to freeze the clock for fixtures.

Opt-in probes are non-destructive and off by default:

pnpm validate:discovery https://example.com/.well-known/agent-signup.json --probe-jwks
pnpm validate:discovery https://example.com/.well-known/agent-signup.json --probe-endpoints

Probes never POST, never trigger signup or provisioning, and are limited to the issuers in issuer_allowlist and the advertised endpoints.agent_signup.

Exit codes

Code Meaning
0 Valid conformant document, and no required verification failed. Warnings are allowed and do not change the code.
1 A document was obtained and parsed, but it failed conformance (including a malformed rp_attestation field or unparseable JSON), or a required attestation check failed.
2 Could not obtain what was needed: unreadable file, network or timeout failure, redirect limit or cross-origin redirect, non-200 status, wrong content type, over the size cap, or JWKS unavailable under --require-attestation. The conformance verdict is not evaluated.

Exit 2 is "no usable run" and exit 1 is "bad document or failed gate". Both are non-zero, so a gate that checks only the exit status still fails correctly.

Fixtures

The spec repository ships conformance and attestation fixtures:

  • fixtures/valid-* documents pass with exit 0.
  • fixtures/invalid-* documents fail with exit 1 and a field-level message.
  • Attestation fixtures cover valid domain/entity, expired, invalid, untrusted, unavailable, malformed, and unknown-additive-claim cases.
  • A fixture's __fixture_note field is an unknown top-level field and produces a warning only. __fixture_origin declares the fetch origin for offline binding.

Run pnpm validate:fixtures for the full matrix. See the generated Conformance validator page for the --json field reference.

Registry entry

A validator-passing discovery document is the objective entry criterion. The registry is adoption infrastructure, not an enforcement mechanism.

Entry criteria:

  1. The identity-only validator passes: valid: true with exitCode: 0. Warnings are permitted; errors are not.
  2. The discovery document is public and stable: an HTTPS /.well-known/agent-signup.json on the implementation's canonical origin, not a throwaway or per-deploy URL.
  3. The contact is reachable: a security, abuse or legal contact that someone monitors.
  4. A post-signup context guide is published if the vendor has capabilities to document.
  5. Optionally, a five-field verification snapshot if the entry claims verification.

Submission path: open a pull request against agentregistrar/spec that adds one object to the implementations array in registry/implementations.json and updates the table in registry/README.md. Include name, url, discovery_url, audience, protocol, capabilities (protocol capabilities only), contact, validated_at, validator_version, and the exact command and counts in validator_evidence. If claiming verification, include broker, level, attestation_jti, checked_at, and status.

Registry capabilities are protocol capabilities only: agent_signup and post_signup_context. Vendor features such as provisioning, catalogs, SKUs, pricing and OTP endpoints are never registry capabilities.

Conformance is not verification. An entry with no verification object is conformant and unverified. Only verification.status: "active" at checked_at renders the verified badge; the conformance badge is separate, and neither is an endorsement. The registry is a snapshot, not a live status feed.

Known limits

  • The registry lists discovery documents that pass the validator. It is not a broker endorsement of the implementation's product, security posture, uptime or pricing.
  • A document can be conformant and still be a poor or malicious service. Conformance is a schema and scope check, not a trust decision.
  • Verification is identity, not safety. A valid credential says a broker checked an origin and, at entity level, legal-entity evidence; it does not rate conduct.
  • Warnings do not fail conformance. Review them, but do not treat a warning-free run as a security review.
edit page -> githubreport issue
sections

type to search.

up/down navigateenter selectesc close