Glossary

Short definitions for the vocabulary used across these docs. Each links to the page where the concept is developed in full.

​

Identity & keys

• did:key — A W3C DID that encodes an Ed25519 public key directly in the identifier (multicodec 0xed01 + the 32-byte key), so the identifier is the key and signatures verify offline — no registry, no DNS. The only agent-account method in v0.1. → Identity and keys
• agent_did — An agent’s did:key, used as the signing keyid on every request and the sub of its attestations. It changes when the key rotates. → Identity and keys
• account_id — A service-local, opaque account identifier, distinct from any key and stable across key rotation, so one account can hold several agent credentials. → How it works
• service_did — The service’s own DID, declared in its discovery document (typically did:web, since services have stable hosts) and used as the aud an attestation is bound to. → Identity and keys
• did:web — A DNS-anchored DID method. Not an agent identity in AFAuth (agents have no stable web origin); used only for a service’s service_did and for did-type owner recipients. → Identity and keys

​

Signing & verification

• RFC 9421 — HTTP Message Signatures, the standard AFAuth signs requests with, so existing tooling interoperates. → Signing requests
• content-digest — A covered component carrying the SHA-256 of the request body (RFC 9530); included whenever there’s a body, so tampering breaks verification. → Signing requests
• nonce — A unique per-request signature parameter; the verifier keeps a seen-set of (keyid, nonce) tuples and rejects reuse with replayed_nonce. → Signing requests
• created / expires — Signature timestamps; expires − created is capped at 300 seconds, verified with ±60 s of skew tolerance. → Signing requests
• Freshness window — The interval a signature is valid and its nonce must be remembered (expires − created + skew). → Signing requests

​

Attestation & trust

• Attestation — A JWT, presented in the AFAuth-Attestation header, in which an attestor vouches for the agent’s runtime — by default, that a verified human stands behind it. → Attestation
• Attestor — The party that signs attestations. AFAuth recognizes four classes: trust, platform, commerce, and service-operator HMAC. → Attestation
• Trust attestor — The canonical afauth-trust issuer at trust.afauth.org, which mints short-lived, audience-bound JWTs that an agent is bound to a human — verifiable offline against its JWKS. → The trust attestor
• sub_h — A per-service, pairwise human pseudonym (HMAC-SHA256, ≥ 128 bits, opaque, no PII), stable per (human, service) and unlinkable across services — the handle services bucket per-human quotas and bans on. It is also the OIDC sub when the human signs in, so attestation and Sign in with AFAuth converge on one account. → The trust attestor
• Binding (trust link) — The link between an agent DID and a human account at the trust attestor (afauth trust link). Transfers no ownership, creates no account, lasts ~90 days, and lets the agent mint attestations. → The trust attestor
• unclaimed_mode — The discovery field declaring how a service treats pre-claim signups: attested_only, free, or denied. → Attestation
• attested_only — The defineService default: implicit signup is refused unless a valid attestation is present (401 attestation_required, no account created). → Attestation
• free (mode) — A service that doesn’t require attestation; a bare signed request suffices. → Attestation
• verification (claim) — The trust-attestation claim naming the strongest method the human has on file: email, oauth, or payment. Services rank it by their own policy; unknown values MUST be ignored, not rejected. → The trust attestor
• Attested session — Keeping a fresh attestation on file and re-challenging when it lapses (§10.7), so an attestor-side revoke reaches signature-gated services within the window. → Keep attested access live
• JWKS / JWT — The JSON Web Key Set a service verifies attestation JWTs against (the trust attestor publishes its keys at trust.afauth.org/.well-known/jwks.json), and the JSON Web Token an attestation takes. → Attestation
• Sign in with AFAuth — Human social-login: a person signs in via the trust attestor (an OpenID Provider) and lands in the (iss, sub_h) account their agent already created. Authentication, not ownership. → Sign in with AFAuth
• id_token — The OIDC token the trust attestor mints at sign-in: sub is the same pairwise sub_h as the agent’s attestation, iss is the URL https://trust.afauth.org, aud is the service’s service_did; it carries no PII. → Sign in with AFAuth

​

Ownership & lifecycle

• Ceremony — The owner invitation + claim flow that hands an account from agent to human, gated by the invariant that the agent’s signature alone can’t bind ownership. The security boundary of AFAuth. → The ceremony
• Claim — A human authenticating as the invited recipient at the service’s claim page, which (after the match relation) moves the account to CLAIMED. → The ceremony
• Two-step verify — The ceremony’s two independent authentications — the agent’s signature and the human’s authentication — that together enforce the invariant. → The ceremony
• Match relation — The rule a service applies at claim time to confirm the human’s authenticated identity equals the staged recipient before transitioning to CLAIMED. → The ceremony
• Recipient — The identity an agent stages in an invitation. The spec defines email, phone, oidc, and did; the v0.1 reference SDK ships only the email handler. → Invite and claim
• Account states — UNCLAIMED (created, no owner) → INVITED (invitation pending) → CLAIMED (owned); plus EXPIRED (only on services that opt into an unclaimed_ttl_seconds; absent by default) and ARCHIVED (owner-deleted). → The ceremony
• Owner-binding operation — A change to which credentials can authenticate as the owner; requires a freshly authenticated owner session (60–300 s), never the agent key alone. → Invite and claim

​

Operations

• Revocation — Cutting an agent off via two independent levers: global (revoke the binding at the attestor — stops new attestations everywhere) and local (revoke or re-key at one service). → Revocation
• Error envelope — The single shape every conformant error takes: { error: { code, message, details? } }, where code is a stable identifier clients program against. → Error envelope
• Service directory — The opt-in, non-normative registry of AFAuth services at registry.afauth.org; a listing proves control of the discovery host, not endorsement. → Service directory

​

Where to next