# The mandate authority: HTTP contract (v0.15, 2026-09-29)

What a buyer, a seller and a verifier can expect from the authority that issues mandates
(architecture v0.5 §5.5, §5.9, §6 step 5), so that the authority can be built by anyone and
replaced by anyone. The seller's side of this contract (checks 4 to 10, `authority.mjs`) and
the buyer's side (`authority.py`, `AuthorityTransport`) already exist; this document is the
authority's side, written before the authority, from what the two of them already read.

Status (2026-09-11): implemented by agent-authority and live at https://sealedby.dev; the
buyer's `HttpAuthorityTransport` (`authority_http.py`) speaks it, and the seller accepted the
first cart mandate issued there the same day.

Changed in v0.2 (2026-09-19): "Who may ask", the signed envelope on `POST /mandate-requests`
and the agents a person linked. Behind a mode that is `off` unless the authority says otherwise
on `/health` (`requester`), so a v0.1 buyer keeps working against an authority that has not
turned it on.

Changed in v0.3 (2026-09-19): "Who approves", a passkey on the approval, with what it signs
bound to the one purchase, the evidence kept and its digest in the ledger. Behind a mode of its
own, `off` unless the authority says otherwise on `/health` (`approver`); nothing changes for
the buyer, the seller or the mandates in any mode.

Changed in v0.4 (2026-09-19): "Standing rules", the person's approval given once, ahead of the
purchase, within limits their passkey signs; a request that fits is issued without asking.
Behind a mode of its own, `off` unless `/health` says `rules: on`. The manual mode stays the
default in every sense: with no rule that fits, a purchase waits for the person as it always
did. The request, the mandates and the seller do not change. Added the same day with no change
of version, since nothing in this API moved: the paragraph "In the buyer's ledger", for a
buyer that proposes rules on the person's behalf (`rule.proposed`).

Changed in v0.5 (2026-09-19): "Signing in for the person's assistant", the authority as the
OAuth 2.1 authorization server of the buyer's entrance for the person's assistant (an MCP
server), as the Model Context Protocol's authorization specification asks (revision
2026-07-28). Behind a mode of its own, `off` unless `/health` says `oauth: on`: off, none of
its routes exists. Nothing changes in a mandate request, in a mandate or for the seller.

Changed in v0.6 (2026-09-20): "Stopping", the person freezing their own agent in one gesture:
while stopped nothing is issued for them, by approval or under a rule, and the mandates still
out are revoked; resuming takes their passkey. Behind a mode of its own, `off` unless `/health`
says `stopping: on`: off, none of its routes exists. A buyer learns one new refusal,
`person_paused`; a mandate, the seller and the status document do not change.

Changed in v0.7 (2026-09-20): "Signing in to enroll", the person signing in at an identity
provider this authority accepts (OpenID Connect) before enrolling a passkey, so that who holds
a passkey is no longer the operator's word alone. Asked once, at enrollment and when a passkey
has to be replaced; never at a purchase, which is still approved with the passkey. Behind a mode
of its own, `off` unless `/health` says `login: on`: off, none of its routes exists and no
enrollment writes an entry, as before. With it on every enrollment writes `passkey.enrolled`,
which names the issuer that vouched and never the person. Nothing changes for the buyer, the
seller or a mandate. Added the same day with no change of version, since nothing in this API
moved: a sign-in bound to nobody reads as a request to be let in, which the operator answers in
one step ("Whose identity it is"), and the enrollment page says that the ledgers are public. Also added
that day, with nothing moving for a buyer, a seller or a verifier: the person's own pages,
`/account` ("Stopping", "The person's own pages"), behind the session the stop panel uses.

Changed in v0.8 (2026-09-20): "Which assistant asked", a mandate request naming the assistant
it came through, with the access token that assistant presented at the buyer's entrance: a token
this authority issued, so what it checks is its own signature. The request remembers the grant,
the entries of that purchase name it, and the person reads on their own pages which assistant
asked for what. Optional in every mode: a request without it is taken as before; one that
carries it is refused when it does not hold (`assistant_unknown`). Nothing changes in a
mandate or for the seller.

Changed in v0.9 (2026-09-20): "The person's own limits", guardrails the person sets for their
agent on their own pages, with their passkey, and which the authority holds every purchase to by
arithmetic: the most per purchase, a budget and a number of purchases in a rolling period, no
second purchase of the same trip too soon, sellers the person blocks, and tighter ones per
assistant. Behind a mode of its own, `off` unless `/health` says `limits: on`. They only
restrict, within the ceiling the registry holds. A buyer learns one new reason,
`limit_exceeded`; a mandate and the seller do not change.

Changed in v0.10 (2026-09-20): "Letting a person in, from the web". A sign-in bound to nobody
can make the person at once, waiting (`signup: enroll` on `/health`; `request`, the default, is
the v0.7 behaviour): they enroll their passkey in that same visit and are nobody at every door
until whoever runs the authority lets them in. And that operator, a person of the registry the
host's configuration names, does it from their own pages, with their passkey, with an entry
that names nobody (`person.admitted`, `person.removed`). Nothing changes for a buyer, a seller or
a mandate.

Changed in v0.11 (2026-09-21): "Rules the person makes". Until now a standing rule was born from
a proposal, by the buyer agent or by the operator, and the person could only confirm it or revoke
it. The person now makes a rule themselves, on their own pages, with their passkey, and the rule
they make is wider: a budget for one seller (a most per purchase, a total, a number of purchases,
up to thirty days), any route. Changing a rule is making another that replaces it, in one signed
act. Behind a mode of its own, `off` unless `/health` says `own_rules: on`. `rule.confirmed` gains
`form`, `total` and `replaces`; `rule.revoked` gains `replaced_by`. Nothing changes for a buyer, a
seller or a mandate: the buyer asks as it always did, and an issuance under such a rule reads as
any issuance under a rule.

Changed in v0.12 (2026-09-21): "What a seller is trusted with", a number this authority quotes
and never invents. A verifier publishes a scorecard it signs; that scorecard carries the trust
index a registry gives a seller, one whole number from 0 to 100. The authority keeps it with
the moment it was measured and the digest of the document it was read from, shows it on the
person's Sellers page beside each seller, and, when the person's own limits ask for a least
(`seller_trust_at_least`), refuses a purchase from a seller it is told is under it. A seller
with no reading goes through, and the entry of its purchase says it had none. Behind a mode of
its own, `off` unless `/health` says `trust: on`. The sellers a person blocks move to the same
page. No new entry type and no new reason code: a refusal is `limit_exceeded` with
`limit: "seller_trust"`. Nothing changes in a mandate, for a buyer or for a seller.

Changed in v0.13 (2026-09-21): "A sign-in to the buyer's own page". The buyer keeps what the
person likes (airlines, times, stops) and shows it on a page of its own, where the person signs
in here with their passkey. A third scope, `preferences`, asked for by name; a request that
names no scope still gets `search purchase`. A grant of `preferences` alone is that sign-in:
one access token, no refresh token, and the grant ends as its code is redeemed, so it is never
one of the person's assistants and nothing renews it. The consent page says it in those words.
The overview links to the buyer's page when the deployment names it (`agent_pages`, for the
operator). No new entry type (`access.granted` carries the scope) and no new reason code.
Nothing changes in a mandate, for a buyer's purchases or for a seller.

Changed in v0.14 (2026-09-26): "The day's allowance". Beside the ceiling per purchase, whoever
runs the authority may give a person an allowance per calendar day: what their approved
purchases may add up to in one day, in the ceiling's currency. Set when a person is let in
(the People page, `allowance` in the admit draft and in `person.admitted`) or from the host
(`allowance.set`, a new entry type), and held to at step 6a of the request and again at the
moment of issuing: a purchase that would pass it is denied with a new reason,
`allowance_exceeded`. The day is the calendar day of the zone the host names (`/health` says
`allowance_zone`). The person's own limits (v0.9) stay theirs and only go below it. Nothing
changes in a mandate or for a seller; a buyer learns one new reason.

Changed in v0.15 (2026-09-29): "A seller known by its UCP profile". A request may name, in a
new optional field `seller_profile`, the UCP profile of a seller that publishes no SPIFFE
identity and signs its quotes with a key the profile names (`https://<host>/.well-known/ucp`,
nothing after it). The quote is then read as that seller signs it (section below), and the
same two mandates are issued from what it signed alone; the approval page shows the offer and
says that no route or date was signed. No new reason code and no new entry type; a buyer that
never names a profile sees nothing new.

The authority is a service, not an agent: it runs no model, it decides by fixed policy, and
the only judgement in it is the person's, on the approval page. The interfaces are shaped so
a bank or a wallet provider can stand in the same place.

## Names

| Term | Meaning |
|---|---|
| issuer | The authority's public base URL, `https://<authority domain>`, no path, no trailing slash. It is the `iss` of every mandate and the base of every URL below |
| person, `sub` | An opaque id the authority holds for a human (`mandate.schema.json`): never a phone number, never a name. The buyer learns it from its own allow-list; the authority holds it in its registry with the person's ceiling and the number it notifies |
| buyer instance, `act_sub` | The SPIFFE ID of the buyer acting for the person |
| buyer key, `cnf_jkt` | RFC 7638 thumbprint of the buyer's stable signing key; the mandate is bound to it |
| ceiling | The standing amount, in minor units of one currency, the person allows the buyer to spend per purchase. Set in the registry, never sent by the buyer |
| request | One ask for a mandate: one quote, one person, one buyer key. It has a `request_id`, a status, and at most one decision |

## Keys and signatures

- `GET /.well-known/jwks.json` publishes the issuing keys: `{keys: [{kty: EC, crv: P-256, x, y, kid, alg: ES256, use: sig}]}`, `kid` equal to the RFC 7638 thumbprint. v0.1 publishes one issuing key and does not rotate it; a rotation would keep the previous key published until its last mandate expired (architecture §3.1), and is not built. The seller caches the set for five minutes and refreshes once on an unknown `kid`.
- Every mandate is a compact JWS under `jws-policy.md`: `alg: ES256`, `typ: mandate+jwt`, `kid` mandatory, no `jku`, `x5u`, `jwk`, `x5c`, `crit`. Payload: `mandate.schema.json`.
- The authority's ledger entries are signed by the issuing key too, in v0.1 (one key per authority). The signer is `spiffe://<authority domain>/authority/<kid>`.

## Endpoints

| Method and path | Who calls | What |
|---|---|---|
| `GET /.well-known/jwks.json` | seller, buyer, verifier | The issuing key set |
| `POST /mandate-requests` | buyer | Ask for a mandate: the quote JWS, the person, the buyer instance and key; since v0.2 in a signed envelope ("Who may ask"); since v0.8 it may name the assistant it came through ("Which assistant asked") |
| `GET /mandate-requests/{request_id}` | buyer | The request document; `?wait=<seconds>` (at most 25) holds the answer until a decision or the wait passes |
| `GET /approve/{approval_token}` | the person, from the link | The approval page |
| `POST /approve/{approval_token}` | the person | `decision=approve`, `deny`, or (after an approval) `revoke`, as the page's form; since v0.3, where the approval takes a passkey, approve is `{decision: approve, credential}` as JSON ("Who approves") |
| `POST /rules` | buyer | Propose a standing rule for the person to confirm (since v0.4, "Standing rules"); signed envelope |
| `GET /rules/{rule_id}` | buyer | The rule document |
| `GET /rules/approve/{approval_token}` | the person, from the link | The rule's page: the limits, Confirm (passkey) and Deny; after a confirmation, what was used and Revoke |
| `POST /rules/approve/{approval_token}` | the person | `{decision: approve, credential}` as JSON (the passkey's answer), or `decision=deny` or `revoke` as the page's form |
| `GET /enroll/{invitation_token}` | the person, from the operator's invitation | The page where a passkey is enrolled (since v0.3) |
| `POST /enroll/{invitation_token}` | the person | The new credential, as JSON; answers JSON |
| `GET /mandates/{jti}` | seller (check 10), buyer, verifier, monitor | `authority-status.schema.json`; 404 for a `jti` the authority never issued |
| `POST /mandates/{jti}/revoke` | operator | Revokes one mandate; `Authorization: Bearer <operator token>` |
| `GET /revocations` | verifier | `{as_of, revoked: [{jti, revoked_at, revoked_by}]}`, every revocation the authority holds |
| `GET /ledger` | verifier, monitor | The authority's signed chain, same document shape as the buyer's (`ledger-entry.schema.json`) |
| `GET /checkpoints` | verifier | The chain's checkpoints beside their witness receipts (`checkpoints-document.schema.json`), since 2026-09-12; see "Checkpoints" |
| `GET /.well-known/oauth-authorization-server` | the person's assistant (an MCP client) | Since v0.5, only with `oauth: on`: the authorization server's metadata (RFC 8414); see "Signing in for the person's assistant" |
| `GET /oauth/jwks.json` | the buyer's entrance (a resource server) | The key access tokens are signed with; never the issuing key of mandates |
| `POST /oauth/register` | an MCP client | Dynamic client registration (RFC 7591), public clients only |
| `GET /oauth/authorize` | the person's browser, sent by the client | The authorization request: 303 to its consent page, or back to the client with an error |
| `GET`, `POST /oauth/authorize/{id}` | the person | The consent page; `{decision: approve, credential}` as JSON (the passkey's answer) answers `{redirect}`; `decision=deny` as the page's form |
| `POST /oauth/token` | an MCP client | `authorization_code` (with PKCE) and `refresh_token`, as a form; the token response, or `{error, error_description}` (RFC 6749, 5.2) |
| `GET /stop` | the person | Since v0.6, only with `stopping: on`: opens a session and shows one button that asks the device for a passkey, no credential named; see "Stopping" |
| `GET`, `POST /stop/session/{session_id}` | the person | The person's panel once the passkey has said who they are: what is running, Stop, Revoke beside each rule and each assistant's access, Resume. `{decision: signin, credential}` and `{decision: resume, credential}` as JSON; `decision=stop`, `revoke-rule`, `revoke-access` as the page's form |
| `GET`, `POST /stop/link/{stop_token}` | whoever holds the person's stop link | Whether the person's agent is stopped, and one button, Stop (`decision=stop`). Nothing else is shown and nothing else can be done here |
| `GET /account` | the person | Since 2026-09-20, only with `stopping: on`: opens a session of the same kind as `/stop` does and shows the same one button; see "The person's own pages" |
| `GET`, `POST /account/{session_id}[/{section}]` | the person | The person's own pages once the passkey has said who they are: the overview, and `purchases`, `assistants`, `sellers`, `records`; since v0.9, with `limits: on`, also `limits`; since v0.10, for an operator, also `people` (`{decision: admit, person, ceiling}`, `{decision: remove, person}` and `{decision: people-confirm, credential}` as JSON, "Letting a person in, from the web"). `{decision: signin, credential}` as JSON; `decision=revoke-rule`, `revoke-access`, `label-access` as the page's form; on `limits`, `{decision: limits, limits}` and `{decision: limits-confirm, credential}` as JSON ("The person's own limits"); since v0.11, with `own_rules: on`, also `rules` (`{decision: rule, rule}` and `{decision: rule-confirm, credential}` as JSON, "Rules the person makes") |
| `GET /login` | the person | Since v0.7, only with `login: on`: what the sign-in is for and one button per identity provider this authority accepts; see "Signing in to enroll" |
| `POST /login` | the person | `provider=<label>` as the page's form: 303 to that provider's authorization endpoint |
| `GET /login/callback` | the person's browser, sent back by the provider | The provider's answer: 303 to the enrollment page of an invitation drawn for the person that identity is bound to, or a page that says why not |
| `GET /health` | anyone | `{status, role: "authority", issuer, policy_version, notifier, requester, approver, rules, oauth, stopping, login, limits, trust, own_rules, signup, build, pending, issued}`: `build` names the deployed code (on the POC host, 12 hex of the tarball's sha256), `pending` counts requests awaiting a decision, `issued` counts approvals |

`GET` answers on `/.well-known/jwks.json`, `/mandates/{jti}`, `/revocations`, `/ledger`,
`/checkpoints` and `/health` carry `Access-Control-Allow-Origin: *`: the flow monitor reads
the status of a mandate from the audience's browser.

Every non-2xx answer on a JSON route is `{"error": "<code>", "message": "<sentence>"}` with
the code from `reason-codes.json` (`authority_side`), including 405 `method_not_allowed` for a
method a route does not take and 500 `internal_error` for a fault; the approval page answers its
errors (400, 404, 410) as HTML, with the code in the page. Every timestamp in a document (`created_at`, `expires_at`, `decided_at`, `revoked_at`,
`as_of`, `logged_at`) is RFC 3339 in UTC with a `Z` suffix and millisecond precision at most,
as the ledgers' `at` already is.

## Who may ask (since v0.2)

Until v0.2 anyone who knew a `sub` could ask for a mandate in that person's name, and with the
`relay` notifier the asker also received the approval link. Since v0.2 the request can, and
under `require` must, travel in the envelope the buyer already signs for the seller
(`schemas/request-envelope.schema.json`): `Authorization: Bearer <request+jwt>`, signed by the
buyer's stable instance key, with `aud` the authority's issuer, `method: POST`, `path:
/mandate-requests`, `body_sha256` over the exact bytes sent and the transaction's
`correlation_id`. Nothing is registered at the authority beforehand but the person's word
that this agent may ask: the key is resolved from the buyer's own domain, as the seller does at
its check 3 (`/.well-known/agent-keys.json`, either attestation form, under
`/.well-known/spiffe-bundle.json`; a key the domain withdrew is refused).

The mode is the authority's, shown on `/health` as `requester`:

| `requester` | An unsigned request | An envelope that is present |
|---|---|---|
| `off` | Taken, as in v0.1 | Not read |
| `verify` | Taken, unless the person has linked agents | Must verify |
| `require` | `signature_required` | Must verify |

A credential that is presented is verified whatever the mode says about requiring one: a bad
envelope is refused, never treated as absent (except under `off`, where nothing is read).

The checks, in the seller's order, cheap first; each failure answers the HTTP status and the
code below as `{"error", "message"}`, **creates no request and writes no entry**:

1. The envelope: `typ`, `iat` within 60 s either way (`timestamp_out_of_window`), a nonce of 16
   characters or more, `aud` equal to the issuer (`audience_mismatch`), method, path and body
   hash equal to the call's (`signature_invalid`). Nothing is fetched before these hold.
2. The signer: `iss` a SPIFFE ID whose trust domain is a public DNS name; the `kid` named by a
   valid attestation of that domain, for that instance (`signer_unknown`,
   `attestation_invalid`); the signature (`signature_invalid`); the key not withdrawn by its
   domain (`identity_revoked`, HTTP 403); the nonce not seen from this key in the last 120 s
   (`nonce_replayed`). The documents are cached a minute per trust domain. An authority may
   keep an allow-list of buyer trust domains.
3. The agent asks for itself: the body's `act_sub` is the envelope's `iss`, its `cnf_jkt` the
   envelope's `kid` (`requester_mismatch`, HTTP 403), and the two name one `correlation_id`
   (`request_invalid`).
4. The link: a person's registry entry may name `agents`, each a SPIFFE ID (that instance) or
   a bare trust domain, `spiffe://<domain>` (any instance of it). A person with linked agents
   takes requests only from them: an unsigned one is `signature_required` (HTTP 401), one
   signed by another agent is `agent_not_linked` (HTTP 403). A person with none is as in
   v0.1. In this version the operator links (`agent-authority persons link`); the person doing
   it on the authority's page, signed in, is the next step.

A request that a verified envelope asked for is remembered as such, and its `mandate.issued`
entry carries `requester: {verified: true, form, linked}` (`form` is `x509-svid` or
`jwt-svid`, the signer that vouched for the key); an entry for a request taken the v0.1 way
is what it always was. A buyer reads a 401 or 403 with a code as the authority's refusal, its
reason and its sentence, never as an outage.

The poll (`GET /mandate-requests/{request_id}`) stays as it was: the `request_id` is 16 random
bytes that only the asker holds.

## Who approves (since v0.3)

Until v0.3 the approval page proved that someone holding the link decided, not who; and with
the `relay` notifier the link passes through the buyer that asked. A sign-in and a button would
not close that, because the person's assistant may drive the person's own signed-in browser.
What an assistant cannot do is answer the device's own prompt. So since v0.3 an approval can,
and under `require` must, be signed by a passkey of the person: W3C Web Authentication Level 3,
user verification required (fingerprint, face or PIN on the device), verified as its §7.2 says.

The mode is the authority's, shown on `/health` as `approver`:

| `approver` | Approve | Deny, revoke |
|---|---|---|
| `off` | The page's form, as in v0.1: whoever holds the link | The page's form |
| `verify` | A person with an enrolled passkey: only with one. A person with none: the form | The page's form |
| `require` | Only with a passkey; a person with none cannot approve, and the page says so | The page's form |

Deny and revoke take only the link in every mode: they grant nothing, and stopping must stay
easy.

**What the passkey signs.** Not a login: this purchase and no other (what PSD2 calls dynamic
linking, done here with the WebAuthn challenge). The challenge is the SHA-256 of the approval
statement, the JCS (`canonicalization.md`) of

```json
{"purpose": "mandate-approval", "iss": "<issuer>", "request_id": "…", "correlation_id": "…", "actor": "<sha256 hex of sub>",
 "quote_hash": "…", "amount": 32000, "currency": "EUR", "merchant_id": "…", "aud": "<quote.iss>",
 "act_sub": "spiffe://…", "cnf_jkt": "…", "ceiling": {"value": 50000, "currency": "EUR"}, "format": "poc-v1", "nonce": "<base64url>"}
```

where `nonce` is 32 random bytes the authority drew when the request was created. The
authority rebuilds the statement from its own record when it verifies, never from the
browser; a request is decided once; so an answer cannot be moved to another purchase, another
amount or another buyer key, nor used twice. The options the page hands
`navigator.credentials.get()` are `{challenge, rpId: <issuer host>, userVerification: required,
allowCredentials: <the person's credential ids>, timeout: 300000}`.

**The approval.** The page's script posts to the same path, as `application/json`:

```json
{"decision": "approve", "credential": {"id": "…", "rawId": "<base64url>", "type": "public-key",
  "response": {"clientDataJSON": "<base64url>", "authenticatorData": "<base64url>", "signature": "<base64url>", "userHandle": "<base64url or null>"}}}
```

The authority checks, and refuses at the first failure with `{"error", "message"}`, **deciding
nothing and writing no entry** (the person can try again until the link expires): the
credential is one enrolled for this request's person (`passkey_unknown`, HTTP 403, the same
answer for another person's passkey and for one never seen); a `userHandle`, when present, is
this person's; then, as `passkey_invalid` (HTTP 403) with the failed check in the sentence, the
client data (`type` `webauthn.get`, the challenge above, `origin` equal to the issuer, not
framed by another origin), the authenticator data (the RP ID hash of the issuer's host, user
present, **user verified**, a backed-up credential one eligible for backup, the eligibility
unchanged since enrollment), the signature over `authenticatorData || SHA-256(clientDataJSON)`
under the enrolled public key (ES256 as ASN.1 DER, RS256, or EdDSA), and the signature counter
(when either side is non-zero it must have grown; passkeys that sync report zero, which is
allowed). A form `approve` where a passkey is needed is `passkey_required` (HTTP 403, as HTML).
Success answers `{"status": "issued"}` and issues exactly as the form did.

**The evidence.** The authority keeps, per approved request, the statement, the client data,
the authenticator data, the signature, and the public key as it was enrolled, and writes the
digest of that record into the entry: `mandate.issued` carries `approval: {method: "passkey",
user_verified: true, credential, backup_eligible, backed_up, evidence_sha256}`, where
`credential` is the SHA-256 (hex) of the credential id's bytes and `evidence_sha256` is over the
JCS of `{statement, credential_id, client_data_json, authenticator_data, signature}` (binary
members base64url). So the approval can be checked again by someone who was not there, from
what is kept alone (`agent-authority passkeys evidence <request_id>`), and the signed,
checkpointed chain fixes what was kept. An entry for an approval taken by the form carries no
`approval`, and is what it always was. The mandates do not change in any mode: how the person
approved is the authority's word in its ledger, not a claim the seller reads. The request
document the buyer polls does not carry it either.

**Enrollment.** By invitation: the operator draws a single-use link for a person in the
registry (`agent-authority passkeys invite <sub>`; 15 minutes by default; the store keeps the
token's digest, never the token), and `GET /enroll/{token}` is a page with one button. The
options handed to `navigator.credentials.create()`: `rp.id` the issuer's host; `user.id` the
SHA-256 of `<issuer>\n<sub>` (stable per person, and not the person's id); `pubKeyCredParams`
ES256, EdDSA, RS256; `authenticatorSelection: {residentKey: preferred, userVerification:
required}`; `attestation: none`; `excludeCredentials` the person's own. `POST /enroll/{token}`
takes `{id, rawId, type, response: {clientDataJSON, attestationObject, transports}}` and
verifies it as §7.1 says (the challenge is the invitation's own 32 random bytes; user
verified; an algorithm that was asked for; a credential id of at most 1023 bytes that is the
`rawId` sent and is not enrolled already, for anyone), then answers `{status: "enrolled",
credential, backup_eligible, backed_up, passkeys}`. A used invitation is `link_used` (HTTP
410), an expired one `invite_expired` (HTTP 410), an unknown one `not_found`; a refused
enrollment keeps nothing and leaves the invitation unspent. Enrolling works in every mode, so a
passkey can be enrolled before the mode is turned; it writes no ledger entry, except under
`login: on` (since v0.7, "Signing in to enroll"), where every enrollment writes one.
The operator lists and removes passkeys on the host (`passkeys list`, `passkeys remove`); under
`verify`, a person whose last passkey is removed approves by the form again.

What this leaves unproven is said in "What this contract does not promise".

## Standing rules (since v0.4)

Approving every purchase is the default and stays the default. A standing rule is the second
mode beside it: the person confirms once, with their passkey, limits that can be checked, and
a mandate request that fits them is issued at once, **the same two exact mandates as ever**,
so the seller reads nothing new. A request that does not fit waits for the person as it always
did. The agent never chooses: it asks for a mandate exactly as before (the request has no new
field), and the authority decides whether the person has to be asked, the way a card issuer
decides between a frictionless and a challenged payment.

This version is narrow on purpose, and the caps are the authority's, not the person's: **one
purchase per rule, 48 hours at most, the most per purchase within the person's standing
ceiling**, at most five rules proposed or active per person. With an active rule the buyer's own
entrance becomes a way to spend without a tap, so what a rule can grant stays small until that
entrance is itself authenticated.

**A rule's limits:** one buyer agent (`agent`, the SPIFFE ID of one instance), one seller
(`seller`, its issuer) and `merchant_id`, one `route` (`origin`, `destination`, one
`departure_date`, `adults`), `max_amount` (`{value, currency}`, minor units), `purchases` (1)
and until when (`valid_until`, fixed when the rule is proposed: then plus `ttl_seconds`, 600 to
172800, default 172800).

**Proposing.** `POST /rules`, `application/json`, in the signed envelope of "Who may ask" (`path:
/rules`): `{sub, act_sub, correlation_id, seller, merchant_id, route, max_amount, purchases?,
ttl_seconds?}`, nothing else. Refused before anything exists, as `{"error", "message"}`:
`rules_off` (HTTP 403) when the mode is off; `request_invalid` (400) for the shape and the caps;
`signature_required` (401) without a verified envelope, whatever the requester mode (under
`requester: off` no envelope is read, so no agent can propose), and the envelope's own codes; `requester_mismatch` (403) when `act_sub` is not the signer; `agent_not_linked` (403) when
the person has not linked that agent (an unknown person answers the same);
`passkey_required` (403) when the person has no passkey enrolled; `rule_invalid` (400) when the
most is above the person's ceiling or in another currency, the date is past, or the seller is
not one the authority issues for; `rule_limit` (403) at five open rules;
`approval_undeliverable` (502). Otherwise HTTP 202 and the rule document, and the link to the
rule's page goes to the person by the notifier, as an approval link does (`relay`: also
`approval_url` in the document while it is `proposed`). The operator can draw the same proposal
on the host (`agent-authority rules propose`), held to the same caps and confirmed the same way.
An agent can propose a rule and cannot confirm, widen or renew one: any change is a new rule and
a new tap.

```json
{"rule_id": "<opaque>", "status": "proposed", "correlation_id": "<uuid>", "created_at": "<iso>", "valid_until": "<iso>",
 "limits": {"agent": "spiffe://…", "seller": "https://…", "merchant_id": "…", "route": {"origin": "MAD", "destination": "LHR", "departure_date": "2026-10-14", "adults": 1},
            "max_amount": {"value": 15000, "currency": "EUR"}, "purchases": 1},
 "used": 0, "poll": "/rules/<rule_id>", "expires_at": "<iso, of the proposal>"}
```

`status` is what the rule is at the moment it is read: `proposed` (the link is out, ten
minutes), `lapsed` (nobody decided), `denied`, `active`, `exhausted` (every purchase it allowed
was issued), `expired` (past `valid_until`), `revoked` (with `revoked_at`, `revoked_by`). Once
confirmed it carries `decided_at` and `rule_sha256`. Never the person.

**Confirming.** Only with a passkey of the person, whatever `approver` says about purchases; a
form `approve` is `passkey_required` (HTTP 403). What the passkey signs is the rule and no
other: the challenge is the SHA-256 of the JCS of

```json
{"purpose": "rule-approval", "iss": "<issuer>", "rule_id": "…", "correlation_id": "…", "actor": "<sha256 hex of sub>", "agent": "spiffe://…",
 "seller": "https://…", "merchant_id": "…", "route": {"origin": "…", "destination": "…", "departure_date": "…", "adults": 1},
 "max_amount": {"value": 15000, "currency": "EUR"}, "purchases": 1, "valid_until": 1789999999, "nonce": "<base64url>"}
```

checked exactly as a purchase's approval is ("Who approves"), with the evidence kept the same
way (`agent-authority rules evidence <rule_id>`). That digest is the rule's name from then on,
`rule_sha256`. Success answers `{"status": "active"}` and writes `rule.confirmed`. Deny (from
`proposed`) and Revoke (from `active`) are the page's form and take only the link: they grant
nothing. A denied or lapsed proposal writes no entry.

**Issuing under a rule.** On `POST /mandate-requests`, after the seven steps have passed (so the
quote is verified and the person's ceiling still holds), and only when rules are on, the
envelope verified and the person has this agent linked at that moment: the authority takes the
person's active rules for this agent, oldest first, and the first whose every limit the quote is
within (`agent`, `seller`, `merchant_id`, `route.origin` and `destination`, `departure_date`,
`adults`, currency, `total` at most `max_amount`) gives one purchase, reserved in one conditional
update of the authority's store (not revoked, not past `valid_until` on the authority's clock,
`used` below `purchases`), so of two requests at the same instant exactly one is issued under
the rule and the other waits for the person. The answer is HTTP 200 with the `issued` document,
which also carries `approval: {method: "rule", rule_id}` so the person's own channel can say
that nobody was asked and why; no approval link exists for such a request. A reservation is not
given back when a mandate goes unused: a rule counts mandates issued, not purchases completed.

**Revoking.** By the person from the rule's page, or by the operator (`agent-authority rules
revoke`): it stops the next reservation and writes `rule.revoked`; a mandate already issued has
its own window and its own revocation. A rule that ran out or was used up has nothing to revoke.

**In the ledger.** `rule.confirmed` and `rule.revoked` (below), and every `mandate.issued` under
a rule says `approval: {method: "rule", rule_id, rule_sha256, use, of}` with `requester`
verified and linked. A stranger can hold an issuance to its rule from the chain alone: the rule
was confirmed before, not revoked before, the agent, the seller, the merchant and the currency
are the rule's, the amount is at most its most, the time is before its `valid_until`, and no
more than `purchases` entries name it. The route is inside `rule_sha256` and not spelled out.

**In the buyer's ledger** (its own contract is `ledger-entry.schema.json`; said here so the two
can be joined). A buyer that proposes a rule writes `rule.proposed` under the rule's
`correlation_id`, the one `rule.confirmed` carries here, with the `rule_id` this authority
answered, or with its refusal; like this ledger, it leaves the route out. A purchase issued
under a rule is, in the buyer's ledger, the same entries as any other, and its
`mandate.received` repeats the `approval: {method, rule_id}` of the issued document as this
authority's word. Whether a rule was confirmed, and what was issued under it, is said only here.

AP2 draws this case with an open mandate that carries `amount_range` or `budget` and that the
agent closes per purchase. This profile keeps the count in one place instead, the authority,
and issues the exact mandate of each purchase, because a budget has to be counted somewhere and
a seller sees only its own sales.

## Signing in for the person's assistant (since v0.5)

The person reaches their buyer agent through an assistant, and the buyer's entrance for it is an
MCP server. The Model Context Protocol's authorization (specification 2026-07-28,
`basic/authorization`) makes that entrance an OAuth 2.1 resource server which names its
authorization server in its Protected Resource Metadata (RFC 9728), and lets that server be "a
separate entity". This authority is that entity: it is where the person already acts, with a
passkey, and where the agents they linked are known. A deployment turns it on with `oauth: on`
and a list of the resources it issues tokens for (the URLs of MCP servers, as their metadata
give them).

**What it is, in the words of the standards it follows.** An OAuth 2.1 authorization server for
public clients: the authorization code grant with PKCE (`S256`, required) and the `resource`
parameter (RFC 8707, required); refresh tokens, rotated at every use. Metadata per RFC 8414 at
`/.well-known/oauth-authorization-server`, with `code_challenge_methods_supported`,
`authorization_response_iss_parameter_supported: true` (RFC 9207: `iss` comes back with the code
and with every error) and `client_id_metadata_document_supported: true`. No OpenID Connect: no
`id_token`, no userinfo; a client does not learn here who the person is.

**Clients.** A client is named either by a Client ID Metadata Document (the `client_id` is an
https URL with a path, which the authority fetches: a public host, no redirect followed, 16 KB
at most, kept five minutes; the document's `client_id` has to be that URL), which the protocol
prefers, or by Dynamic Client Registration (`POST /oauth/register`), kept for clients that have
not moved. `token_endpoint_auth_method` is `none`, nothing else. A redirect URI is https, or
http on the loopback interface; it is matched exactly, the port of a loopback one set aside
(RFC 8252, 7.3). An unknown client, or a redirect URI that is not the client's, is answered on
a page of the authority and never by a redirect.

**The person.** The consent page says who asks, as far as the authority knows it (the client's
name is its own word, escaped and stripped of control characters; a dynamic registration is
said to be one), where the answer goes (the host in full, and plainly when it is the same
computer), which MCP server it asks to reach and what each scope allows. Allowing takes the
person's passkey and nothing else, in every mode of `approver`. Nobody is signed in before: the
page names no credential, the passkey the person picks is a discoverable one, and its id says
who they are. What it signs is this grant: the challenge is the SHA-256 of the JCS of

```json
{"purpose": "oauth-authorization", "iss": "<issuer>", "authorization_id": "…", "client_id": "…", "redirect_uri": "…",
 "resource": "https://<buyer>/mcp", "scope": "search purchase", "code_challenge": "<the request's PKCE challenge>", "nonce": "<base64url>"}
```

so the code that follows is of use only to whoever holds the verifier. The evidence is kept as
an approval's is (`agent-authority oauth evidence <grant_id>`). A token is issued only for a
resource on a domain where the person has linked a buyer agent (`agent_not_linked`, HTTP 403,
otherwise): a token says "this assistant may speak to this person's buyer", and whose buyer it
is was already the authority's to know. Denying is the page's form and takes nothing: the
client gets `access_denied`. A consent page waits ten minutes and is decided once.

**Tokens.** The access token is a JWT (RFC 9068): `typ: at+jwt`, ES256, signed by a key of its
own, published at `/oauth/jwks.json` and absent from `/.well-known/jwks.json`, so nothing that
verifies a mandate accepts an access token, and the reverse. Claims: `iss`, `sub` (the person's
opaque id, the one a mandate request carries), `aud` (the resource, as asked), `client_id`,
`scope`, `iat`, `exp` (ten minutes), `jti`, `grant_id`. The refresh token is opaque, thirty days,
used once: a refresh answers a new one. A refresh token presented again more than thirty seconds
after its first use revokes the grant (inside that window it is taken as one client asking
twice, which a client with two sessions open does), and so does an authorization code used
twice; so does a refresh after the person unlinked their buyer at that
resource. Scopes: `search` (find the seller, quotes, follow a purchase) and `purchase` (ask for a
mandate, propose a rule, cancel); a request that names none gets these two. Since v0.13,
`preferences` (see and change what the buyer keeps about what the person likes), asked for by
name. A grant of `preferences` alone is a sign-in to the buyer's own page: its code is redeemed
for one access token and no refresh token, and the grant ends there (`status: ended`), so it is
never one of the person's assistants and nothing renews it; its consent page asks the person to
sign in to that page, for this visit. An access token widens nothing else: a purchase still
takes the person's approval, or a rule of theirs.

**For the resource server.** Name this issuer in `authorization_servers`; take a token only when
it verifies under `/oauth/jwks.json` (read `jwks_uri` from the metadata, whose `issuer` has to be
this one), its `typ` is `at+jwt`, its `aud` is your own resource URI and its `exp` holds; read
the person from `sub`. Revocation reaches you when the token in flight runs out: ten minutes.

**Revocation.** By the operator (`agent-authority oauth revoke <grant_id>`). The person cannot
revoke a grant on their own yet, and there is no revocation endpoint for clients.

**In the ledger.** `access.granted`: `grant_id`, `actor` (hashed), `client_id`, `registration`
(`metadata-document` or `dynamic`), `redirect_host`, `resource`, `scope`, and `approval` as on a
purchase (the passkey's facts and the digest of the kept evidence); never the client's name,
a code or a token. `access.revoked`: `grant_id`, `revoked_by` (`operator`, `code-reuse`,
`refresh-reuse`, `agent-unlinked`). Their `correlation_id` is the grant's own. A refresh writes
nothing.

**Not promised.** CORS on the token and registration endpoints (a client in a browser tab cannot
use this server yet); confidential clients; consent remembered across sign-ins (every sign-in
asks the passkey).

## Stopping (since v0.6)

A person who approves ahead, and whose assistant holds an access that renews itself, has more
than one thing to withdraw, and until v0.6 no single gesture withdrew them: a mandate and a rule
were revoked from their own pages, an assistant's access only by the operator. Stopping is that
gesture. It is the third switch beside the two the verifier already measures (the agent's key
withdrawn at its domain, a mandate revoked here), and the first one that is in the person's hand.

**A freeze, not a cancellation.** Stopping does two things: it marks the person as stopped, and
it revokes every mandate of theirs that is issued and not yet expired, so the seller refuses it
at check 10. Requests still waiting for the person are denied (`person_paused`). Standing rules
and assistants' accesses are left as they are, inert: nothing is issued under a rule while the
person is stopped, and an assistant that still reaches the buyer can ask for nothing that is
granted. Resuming brings them back, and the person can revoke each one first, from the same
panel. A button that destroys nothing is one a person presses without thinking twice, which is
what it is for.

**While a person is stopped,** the authority grants nothing in their name:

| Where | Answer |
|---|---|
| `POST /mandate-requests` | HTTP 403 `person_paused`, after "Who may ask" has passed, so under `requester: require` only an agent the person linked learns it. No request exists and no entry is written |
| `POST /rules` | HTTP 403 `person_paused`; no rule, no entry |
| Approve, on an approval page or a rule's page | `person_paused` (HTTP 403), by the form or with a passkey; nothing is decided. Deny and Revoke work as ever |
| The consent page of "Signing in for the person's assistant" | `person_paused` (HTTP 403) once the passkey has said who is asking; nothing is granted |
| `POST /oauth/token` | Unchanged. Refusing a refresh would end the assistant's access for good (a client drops a grant whose refresh fails), and stopping is not that. The token lets an assistant ask the buyer; what it asks for is refused above. Ending an access is Revoke, on the panel |

**Stopping is easy, resuming is strong.** Stopping grants nothing, so it takes little; resuming
grants again, so it takes the person's passkey. Two doors lead to Stop:

- `GET /stop` opens a session (its id in the address, no cookie; it waits ten minutes for its
  sign-in and, signed in, lasts while it is used: each page opened gives it ten more minutes, an
  hour from the sign-in at most) and shows one
  button. The button asks the device for a passkey with no credential named, as the consent page
  does, so the passkey the person picks says who they are. What it signs is this session and no
  other, the SHA-256 of the JCS of `{"purpose": "stop-session", "iss", "session_id", "nonce"}`,
  sent as `{decision: signin, credential}` to `POST /stop/session/{session_id}` and checked as an
  approval is ("Who approves"). From then on `GET /stop/session/{session_id}` is the person's
  panel: whether they are stopped and since when, their active rules with the limits of each,
  the assistants that hold an access (client, resource, since when), the mandates still out, and
  the buttons: Stop, Revoke beside each rule and each access, and, when stopped, Resume. Every
  page the person opens at this authority (an approval, a rule, a consent) ends with the address
  of `/stop`, and of `/account`, which are no secrets. Every page of a person is served with
  `Referrer-Policy: no-referrer`, since the address of a session or of a link is one.
- `GET /stop/link/{stop_token}` is the person's stop link, a bearer address the authority draws
  for each person (the operator reads it with `agent-authority stop link SUB`; the panel and the
  page a passkey is enrolled on show it, to be kept where the person will find it without their
  device). It says whether the person is stopped and offers Stop. It lists nothing and revokes
  nothing else. Whoever holds it can stop the person's agent and do nothing more: a nuisance at
  worst, never a purchase.

**The person's own pages** (added 2026-09-20 with no change of version: nothing moved for a
buyer, a seller or a verifier). `GET /account` opens a session of the same kind and shows the
same button; what the passkey signs there is `{"purpose": "account-session", "iss", "session_id",
"nonce"}`, sent as `{decision: signin, credential}` to `POST /account/{session_id}`. One session
serves both doors: signed in at either, the person moves between the stop panel and these pages
with no second prompt. The pages are read from this authority's own store, for that person
alone, and grant nothing, so the session is enough:

- the overview: what was approved in the last thirty days (the sum per currency and how many),
  what waits for the person now, the assistants connected, and who talks to whom (the assistant
  to the buyer agent, the buyer agent to this authority, the person's approval, the seller);
- `purchases`: their requests, newest first, each with what it was for, the seller, how it was
  decided (with their passkey, ahead under a rule, waiting, denied by them, ended by their stop,
  expired, refused at the door and why, revoked and by whom) and a link to that request's own
  page; `?show=approved|waiting|denied|expired` narrows the list. Approved is not paid: whether
  a checkout followed is read in the person's browser from the seller's public ledger, by the
  presented `jti`, as the approval page does;
- `assistants`: each access held (what the client calls itself, the resource, the scopes, since
  when), with Revoke and a name of the person's own (`label-access`: 40 characters, printable,
  kept at the authority, shown nowhere else, no entry); how to connect another one: the address
  of the MCP server of the person's own buyer (a resource this authority issues tokens for, on
  a domain where the person has an agent linked) and the command that adds it to the
  assistants the page knows; and the buyer agents linked to the person;
- `sellers`: where their approved purchases went, how many and how much was approved;
- `records`: `actor`, the value that stands for them in the public ledgers, the addresses of
  those ledgers, and their passkeys (the first characters of each credential's id, when it was
  created and last used).

Stop is one click away on every page, and is pressed on the stop panel, which says what it does.
The forms answer 303 to a `GET` of the same page.

**Resuming** is `{decision: resume, credential}` to the session, a fresh passkey answer over the
SHA-256 of the JCS of

```json
{"purpose": "person-resume", "iss": "<issuer>", "session_id": "…", "actor": "<sha256 hex of sub>", "paused_at": 1789999999, "nonce": "<base64url>"}
```

with the evidence kept as an approval's is. Every form of the panel and of the stop link answers
303 to a `GET` of the same page, so reloading it repeats nothing. The panel shows, above the button, what comes back
with it: the rules still active and the accesses still held, each with its Revoke. That is where
a stolen token is cut. `not_paused` (HTTP 409) when there is nothing to resume.

**The operator** can do both on the host, `agent-authority stop person SUB` and `agent-authority
resume SUB`, recorded as `by: operator`. A person with no passkey at hand is resumed this way.

**In the ledger.** `person.paused` and `person.resumed` (below), sharing one `correlation_id`,
the pause's own. The denials and revocations a stop causes are the entries they always were,
under their own purchases' ids; each `mandate.revoked` of a stop also carries `pause`, that
`correlation_id`. A stranger can hold the authority to a stop from the chain alone: between a
`person.paused` and the `person.resumed` that follows it for the same `actor`, no
`mandate.issued`, `rule.confirmed` or `access.granted` names that `actor`.

**What stopping does not do:** undo a checkout the seller already captured (a purchase that
ended before the stop stands, and the dispute is elsewhere); reach another authority where the
person keeps another agent; or end an assistant's access, which is Revoke. How long a seller
takes to refuse a mandate revoked by a stop is the seller's check 10 and its caches, measured by
the verifier as any revocation is.

## Signing in to enroll (since v0.7)

A passkey proves that the credential enrolled for a person answered and that the device
verified its user. It does not say which human that is: until v0.7 a passkey was enrolled
through an invitation the operator drew, so who holds it was the operator's word. Since v0.7
the person can sign in at an identity provider first, and the invitation is drawn for the
person of the registry that identity is bound to.

**Once, not per purchase.** The sign-in happens where a passkey comes to exist: the first
enrollment, and a new passkey when a device was changed or lost. A purchase, a rule, an
assistant's access and a resume are approved with the passkey, as before: a sign-in at each
approval would add a round trip to every purchase and prove less than the passkey already does
there. Nothing in a mandate changes.

The mode is the authority's, shown on `/health` as `login`: `off` (none of these routes exists,
no provider is read, and an enrollment writes no entry, as before) or `on`. The operator's
invitation keeps working in both.

**Accepted issuers.** A list, never one provider: one entry per issuer, each with the client
this authority registered there (`redirect_uri` = `<issuer of this authority>/login/callback`).
The list is the operator's file, never served. Each entry is read through OpenID Connect
Discovery (`<issuer>/.well-known/openid-configuration`, https only, the document has to name
the issuer configured; a multi-tenant issuer that declares `{tenantid}` in its own name is
matched with the token's `tid`).

**The round trip.** `GET /login` is a page with one button per accepted issuer. `POST /login`
(`provider=<label>`) answers 303 to the provider's authorization endpoint: the authorization
code flow with PKCE (`S256`), scope `openid email`, a `state` and a `nonce` of 32 random bytes
each, kept hashed, good for ten minutes and for one use; the same answer sets a cookie
(`HttpOnly`, `SameSite=Lax`, path `/login`, ten minutes) whose digest is kept with the `state`,
so a callback only finishes in the browser that started it. `GET /login/callback` spends the
`state` whatever happens next, redeems the code at the token endpoint and reads the `id_token`:
RS256 under a key of the provider's published set (this verifier is for a token someone else
signed and is never used on a token of this authority, whose own policy stays `jws-policy.md`,
ES256); `iss` the accepted issuer; `aud` this client, and `azp` when present; the `nonce` of
this attempt; `exp` and `iat` within two minutes of this clock; a `sub`.

**Whose identity it is.** The registry binds a person to `(issuer, subject)`. The operator may
also bind `(issuer, e-mail)` ahead of the first sign-in: the first `id_token` of that issuer
with that address and `email_verified: true` pins the subject, and from then on only the pair
counts (an address can change hands; a provider that does not say `email_verified` can only be
bound by subject). An identity bound to nobody is `identity_unbound`: nothing is drawn, nothing
is written, and the person reads that their request is in. Nobody becomes a person of this
authority by signing in: ceiling, notifier and linked agents stay the operator's. The attempt
(issuer, subject, the address when the provider verified it) is kept on the host for seven days,
where the operator sees it and answers: by binding the identity to a person already in the
registry, or by letting a new one in, in one step and all or nothing: an opaque id drawn by the
authority, the ceiling the operator gives, the identity bound by subject, the buyer agents
linked. Letting a person in draws no invitation and writes no entry; the person signs in again
and enrolls, which does. The enrollment page tells them what is public: what their agent
searches and buys is listed on the ledgers of this proof of concept under `actor`, the SHA-256
of their `sub`, the same value in every entry about them.

**What a finished sign-in gives.** One single-use invitation, fifteen minutes, exactly the one
"Who approves" describes, and 303 to its page, which says which provider vouched. No session
and no cookie outlive the round trip.

**The entry.** Under `login: on` every enrollment, by either door, writes `passkey.enrolled`:
`by` says `login` or `operator`, and for a sign-in `login` carries `iss` (the accepted issuer as
configured, never a tenant), `subject_hmac_sha256` (HMAC-SHA-256 of `<iss>\n<sub>` under a key
only this authority holds: the same identity gives the same value here, and nobody outside can
test a guess against it, which a plain hash of a provider-wide account id would allow),
`evidence_sha256` (SHA-256 of the `id_token` as received, which the authority keeps beside the
key that verified it, so the provider's own signed word can be shown to whoever has the right
to ask) and, when the provider gave them, `auth_time` and `amr`. Never an address, never a name.

**What it does not prove** is said in "What this contract does not promise".

## Which assistant asked (since v0.8)

A person may reach one buyer agent through more than one assistant, each holding an access of
its own ("Signing in for the person's assistant": one grant per sign-in, which the person can
name and revoke). Until v0.8 the authority could not tell them apart in a purchase: a mandate
request named the person and the buyer, never the assistant. A name chosen by the buyer would
be the buyer's word. The access token is not: this authority signed it, it names the grant
(`grant_id`), and the buyer holds it because the assistant presented it.

**The member.** `assistant_token`, optional: the access token (`at+jwt`) the assistant presented
at the buyer's entrance for the call that led to this request, exactly as received. It travels
in the body, so the envelope of "Who may ask" covers it.

**The checks,** when it is present, after "Who may ask" and before anything else: the token
verifies under `/oauth/jwks.json` with `typ: at+jwt`; its `iss` is this issuer; its `sub` is the
request's `sub`; its `aud` is a resource this authority issues tokens for, on the trust domain of
the request's `act_sub` (the buyer that asks is the one the token was presented to); its scope
carries `purchase`; its `exp` passed at most ten minutes ago (a request may wait its turn at the
buyer behind another of the same person, and a token lives ten minutes); and its grant is
active. Any failure, or a token presented while `oauth` is off, is HTTP 403
`assistant_unknown` with a sentence that says which: no request is created and no entry is
written. A request without the member is taken as before, in every mode.

**What is remembered.** The request keeps the `grant_id`. The entries of that purchase
(`mandate.issued`, `mandate.denied`) carry `assistant: {grant_id, client_id}`, both already
public in that grant's `access.granted`; never the client's name, the person's name for it, or
the token. The person's own pages show which assistant asked for each purchase, by the name the
person gave it, and narrow the list by assistant.

**What a stranger can check,** from the chain alone: every entry that names an assistant names
a grant whose `access.granted` comes earlier, for the same `actor`, with `purchase` in its
scope, and with no `access.revoked` before it.

**What it does not prove.** The token is a bearer token, and the buyer holds it: a buyer that
misbehaves can, within the token's life, name another assistant of the same person, or none.
It cannot name a grant that does not exist, one of another person, or a revoked one. Which
assistant asked is an attribution, for the person's reading and for limits of the person's own;
what a purchase takes is unchanged: the person's approval, or a rule of theirs.

## The person's own limits (since v0.9)

The ceiling in the registry is the operator's word about a person. Limits are the person's word
about their own agent. They cannot live in the buyer, which would then hold its own leash: they
live here, where the person already approves, and the agent never sees them and never chooses.
It asks for a mandate as it always did.

**The document.** One per person, replaced as a whole; every member optional, and a limit the
person did not set does not exist:

```json
{"currency": "EUR", "per_purchase": 30000, "budget": 60000, "purchases": 4, "period_days": 7,
 "repeat_hours": 24, "blocked_sellers": ["shop.example"], "seller_trust_at_least": 70,
 "assistants": {"<grant_id>": {"purchase": false}, "<grant_id>": {"per_purchase": 10000}}}
```

Amounts are minor units of the ceiling's currency, and `per_purchase` (the person's and an
assistant's) is within the ceiling: limits only restrict. `budget` is the most the approved
purchases of any rolling `period_days` (1, 7 or 30) may sum to, `purchases` how many there may
be. `repeat_hours` refuses the same trip (the quote's seller, origin, destination and date)
approved again within that many hours. `blocked_sellers` are host names, at most 500 of them. `seller_trust_at_least` is a whole
number from 1 to 100, the least a seller may be scored ("What a seller is trusted with"), and
is read only with `trust: on`. `assistants` is keyed
by `grant_id` ("Which assistant asked"): `purchase: false` lets that assistant search only, and
its `per_purchase` is tighter than the person's. A request that names no assistant is held to
the general limits alone. What counts is what was approved, not what was paid (the authority
knows what it issued, not what the seller charged), and an approval later revoked still counts.

**Setting them** is the person's, on the `limits` page of their own pages, and takes their
passkey every time, to tighten and to loosen alike, in two steps. `{decision: limits, limits}`
is shaped (HTTP 400 `limits_invalid` for a document that does not fit, one that would pass the
ceiling, or an assistant that is not the person's), kept as that session's draft, and answered
with `{limits_sha256, options}`: the prompt whose challenge is the SHA-256 of the JCS of

```json
{"purpose": "person-limits", "iss": "<issuer>", "actor": "<sha256 hex of sub>", "limits_sha256": "<sha256 hex of the JCS of the document>",
 "previous_sha256": "<the digest it replaces, or null>", "session_id": "…", "nonce": "<base64url>"}
```

`{decision: limits-confirm, credential}` is the passkey's answer, checked as an approval is,
with the evidence kept; only then do the limits change (HTTP 409 `limits_invalid` when nothing
was drafted, or when the limits changed meanwhile).

**Holding a purchase to them** is step 6b of "The request", after the ceiling, and again at the
moment of issuing, under the same lock: of two requests that each fit when they were asked, the
second to be approved may not. A purchase that would pass a limit is denied `limit_exceeded`,
by the form, with a passkey or under a standing rule alike: approved ahead is approved within
the limits. The detail is a sentence with no number; the entry names which limit.

**In the ledger.** `limits.set`: `actor`, `limits_sha256`, `previous_sha256`, `approval` (the
passkey's facts, as on a purchase), `policy_version`; never the document, which stays at the
authority and is shown to the person alone, who can hash what their page shows and find that
digest in the chain. From the first `limits.set` on, every `mandate.issued` for that `actor`
carries `limits_sha256`, the limits it was issued under, and a `mandate.denied` they caused
carries `reason: limit_exceeded`, `limit` (`per_purchase`, `budget`, `purchases`, `repeat`,
`blocked_seller`, `seller_trust`, `assistant.purchase` or `assistant.per_purchase`) and
`limits_sha256`.

**What a stranger can check,** from the chain alone: every `limits.set` was confirmed with a
passkey and names the digest it replaces, so the limits of an `actor` form one line with no
gap; every issuance and every `limit_exceeded` after it names the digest in force at that
point. **What it cannot:** that the arithmetic was done right, since the document is not
public. The person can: their page shows the document and what was counted.

**The mode** is the authority's, shown on `/health` as `limits`. Off, no limit is read, no
entry changes and the pages have no `limits`; the limits kept outlive the mode and come back
with it.

## What a seller is trusted with (since v0.12)

A person who says "buy from sellers others vouch for" needs a number, and a number needs an
author. This authority is the wrong author: it decides the purchases, so a score of its own
would be it marking its own homework, and the person could never tell the two apart. So it
quotes one.

**Where it comes from.** A verifier publishes a scorecard it signs (`scorecard+jwt`), and that
scorecard carries, under `third_party_scores`, the opinions of third parties about the parties
it ran over. The one taken here is the registry's trust index, `source: "ans-trust-index"`,
whose `value.trust_score` is one whole number from 0 to 100. The subject is the entry's
`value.subject` when it names one, and the scorecard's `run.domains.seller` when it does not.
The host is told two addresses: the scorecard, and the keys it is signed with
(`/.well-known/jwks.json` of the verifier). A scorecard whose signature fails under those keys
is no reading at all.

**What is kept,** per host: the source, the number, `run.ended_at` as the moment it was
measured, the SHA-256 of the compact JWS as served, and when it was read. A reading older than
thirty days is no reading. Nothing else from the scorecard is kept, and the second opinion
without a single number (the trust-index engine's vector) is passed over.

**When it is read.** When a person opens their Sellers page and what is kept is over an hour
old, at most once a minute however many pages are open, and whenever the host asks. Never in
the path of a purchase: issuing reads what is kept, so a verifier that is down or slow costs no
purchase. A fetch that fails leaves what was kept as it was.

**What it does.** With `trust: on`, the person's Sellers page shows the number beside each
seller they bought from, with the source and when it was measured, and a seller with no reading
says so in the same place. The person may set `seller_trust_at_least` there, with their passkey,
as any limit is set. A purchase from a seller the authority is told is under that number is
denied `limit_exceeded` with `limit: "seller_trust"`, by the form, with a passkey or under a
standing rule alike; the detail is a sentence with no number. **A seller with no reading goes
through:** a limit refuses what it is told is under, not what it has not been told about.

**In the ledger.** For a person who set a least, every `mandate.issued` and every
`mandate.denied` of theirs carries `seller_trust`: `{source, score, measured_at,
scorecard_sha256}`, or `{source, score: null}` for a seller with no reading, which is why it
went through. A person who set no least has none of this in their entries.

**What a stranger can check,** from the chain alone: a refusal for `seller_trust` names a score
and the scorecard it was read from, and that document is public at its address, so the same
digest can be fetched and the same number found under the verifier's signature. **What it
cannot:** whether the number deserves to be believed. It is the registry's opinion, quoted;
this authority neither computes nor endorses it, and says whose it is wherever it shows it.

**The mode** is the authority's, shown on `/health` as `trust`. Off, no scorecard is fetched,
no score is shown, and a `seller_trust_at_least` already in a person's limits is inert and kept,
like the limits themselves.

## Letting a person in, from the web (since v0.10)

Until v0.10 a newcomer came twice: a sign-in bound to nobody was a request ("Whose identity it
is"), the operator answered it on the host, and the person signed in again to enroll. And the
operator's answer was a command on the host.

**Signing up in one visit** (`signup: enroll`). A sign-in that held and is bound to nobody makes
the person at once, WAITING: an opaque id drawn by the authority, a ceiling of nothing, no buyer
agent, the account bound by subject (never by the address alone), the verified address kept as
the label the operator will tell them by and shown to nobody else. The invitation is drawn in
that same answer, so the person enrolls their passkey now (`passkey.enrolled`, `by: login`, as
any enrollment), and their own pages say that the account waits for approval. Until let in, a
waiting person is nobody at every door that grants: a mandate request for them is
`subject_unknown`, and no assistant can be given access, since no buyer agent is linked. The
places are few (25 at a time) and free themselves: a person who waited a week is taken out,
with the passkeys they created; with every place taken the sign-in answers HTTP 403
`signups_full`. With `signup: request` nothing of this happens, as in v0.7.

**The operator's page.** The host's configuration names the operators (persons of the
registry), the buyer agents a person let in is linked to, the ceiling the page offers and the
most it takes. An operator's own pages carry `people`: who waits (label, since when, passkeys
created), and who is in (label, id, ceiling, agents, passkeys, whether stopped). Letting a
waiting person in, or taking them out, takes the operator's passkey, in two steps as setting
limits does: `{decision: admit, person, ceiling}` or `{decision: remove, person}` is kept as
that session's draft and answered with `{options}`, whose challenge is the SHA-256 of the JCS of

```json
{"purpose": "operator-admit", "iss": "<issuer>", "operator": "<sha256 hex of the operator's sub>", "person": "<sha256 hex of the person's sub>",
 "ceiling": {"value": 150000, "currency": "EUR"}, "agents": ["spiffe://…"], "session_id": "…", "nonce": "<base64url>"}
```

(`operator-remove` carries no ceiling and no agents); `{decision: people-confirm, credential}`
is the passkey's answer, and only then does anything change. A ceiling above the most the host
gives, a person who is not waiting, or a page with no buyer agent configured changes nothing.
For whoever is not an operator the page does not exist (HTTP 404).

**In the ledger.** `person.admitted`: `actor` (the person let in), `by: operator`, `operator`
(the operator's `actor`), `ceiling`, `agents`, `approval` (the passkey's facts),
`policy_version`. `person.removed`: the same without ceiling and agents. Never an address, a
name or a `sub`. A person let in from the host's command line has no entry, as before.

**What a stranger can check,** from the chain alone: each `person.admitted` was confirmed with a
passkey, names an operator other than the person, and from it on no `mandate.issued` for that
`actor` is above that ceiling or in another currency. **What it cannot:** who the operator is,
that the address the operator saw belongs to the human they meant, or anything about persons
let in from the host.

## Rules the person makes (since v0.11)

A standing rule of v0.4 is proposed by the buyer agent, or by the operator, and the person
confirms it. That left the person with half of the control: what refuses a purchase (their
limits, v0.9) was theirs to set, and what spares them the question was somebody else's to
propose. Since v0.11 the person makes a rule themselves, on their own pages (`/account`, the
section `rules`), and the agent is not part of the act. Behind a mode of its own: `/health`
says `own_rules: on`, which takes `rules: on` and `stopping: on` (the person's pages); `off`,
the default, the section does not exist (HTTP 404), no such rule is made, and the ones made
earlier are inert until the mode is on again, as the person's limits are under `limits: off`.

**The page** lists the person's rules, newest first, each in the person's terms with what it
is now (active, used up, expired, revoked) and what it has spent, Revoke beside an active one
(`decision=revoke-rule`, the page's form, as on the stop panel: it grants nothing, so the
session is enough), Change beside an active one, and the form that makes a rule. A rule an agent
proposed is listed and revoked here too.

**The rule the person makes is a budget**, `form: budget` (a rule of v0.4 is `form: route`, and
an entry with no `form` is one): one buyer agent the person has linked, one seller and
`merchant_id` among those the person has already approved a purchase at (nobody pre-approves a
seller they never approved), `max_amount` (`{value, currency}`, the most per purchase), `total`
(`{value, currency}`, the most the rule gives in its whole life), `purchases` and until when
(`valid_until`). No route: any route, date and number of travellers that seller quotes. The
caps are the authority's, not the person's: `max_amount` within the person's standing ceiling
and in its currency; `total` from `max_amount` up to five times that ceiling; `purchases` from
1 to 10; from one to thirty days; five rules proposed or active per person, as before.

**Making one takes the passkey, in two steps**, as setting limits does; the session that the
passkey opened is not enough, because the signature over the rule is what the ledger names
(`rule_sha256`) and what the kept evidence proves. `{decision: rule, rule: {seller, merchant_id,
agent?, max_amount, total, purchases, days, replaces?}}` is shaped, held to the caps and kept as
the session's draft, with a `rule_id`, a `correlation_id` and a nonce drawn for it; the answer
is `{rule_sha256, options}`. What the passkey signs is the SHA-256 of the JCS of

    {purpose: rule-approval, form: budget, iss, rule_id, correlation_id, actor, agent, seller,
     merchant_id, max_amount: {value, currency}, total: {value, currency}, purchases,
     valid_until, replaces, session_id, nonce}

(`replaces` is a `rule_id` or `null`). `{decision: rule-confirm, credential}` is the passkey's
answer over that draft, and only then does the rule exist, active at once: there is no proposal
to wait on. Refused, with the rule as it was and nothing written: `request_invalid` and
`rule_invalid` (HTTP 400, the shape and the caps, a seller the person never approved, an agent
not linked), `rule_limit` (403), `person_paused` (403: a stopped person makes no rule), the
passkey's own codes ("Who approves").

**Changing a rule is making another.** A rule is never edited, widened or renewed: the entry
that names its digest would stop being true. `replaces` names an active rule of the same
person; on the confirmation, under one lock, that rule is revoked (`rule.revoked`, `revoked_by:
person`, `replaced_by`) and the new one confirmed (`rule.confirmed`, `replaces`). A rule named
that is no longer active by then is left as it is, and the new one is made all the same.

**Issuing under it** is what v0.4 says: only for a request in a verified envelope, signed by
the agent the rule names, which the person still has linked; the quote is held to the agent,
the seller, the `merchant_id`, the currency and `max_amount`; and the count, the clock and,
for a budget, the total (what was issued under the rule plus this purchase, within `total`)
are reserved in one conditional update, before anything is issued. The person's own limits
hold as for any purchase, and so does a stop. `mandate.issued.approval` is `{method: rule,
rule_id, rule_sha256, use, of}`, as before. A reservation is not given back when a mandate goes
unused, in the count or in the total.

**What a stranger can check** from the authority's chain alone: every rule was confirmed with
a passkey that verified its user, within the caps above; every issuance under a rule comes
after its confirmation and before its end or its revocation, names its digest, is for that
actor, that agent, that seller and merchant, within `max_amount`, numbered in order up to
`purchases`, and, for a budget, the amounts add up within `total`. What cannot be checked is
the route of a `form: route` rule, which stays inside the digest.

## The day's allowance (since v0.14)

The ceiling in the registry says the most a person's agent may spend per purchase. The day's
allowance says what their approved purchases may add up to in one calendar day, in the
ceiling's currency: the operator's second word about a person, beside the first, and, like the
ceiling, never the person's to widen (their own limits, v0.9, only go below it). A person may
have none; then only the ceiling and their own limits hold.

**Where it is set.** When a person is let in from the People page, the admit draft may carry
`allowance` (minor units, at least 1), which the passkey's statement then includes
(`"allowance": {"value": 50000, "currency": "EUR"}` beside `ceiling` and `agents`) and
`person.admitted` carries as `allowance`. The page offers the host's default
(`admit_allowance`) and takes none when the field is left empty. From the host, at any time,
`agent-authority persons allowance <sub> <minor units>|none` sets or takes it away and writes
`allowance.set`: `actor`, `by: host`, `allowance` (`{value, currency}` or `null` for none),
`policy_version`, `build`. Never an address, a name or a `sub`.

**How it is held to.** Step 6a of the request: what the authority approved for the person
(`issued`, as the person's own budget counts it: approved, not paid; a revocation undoes
nothing) since the start of the calendar day in the zone the host names (`/health` says
`allowance_zone`; on the host of this proof of concept, `Europe/Madrid`), plus `quote.total`,
is at most the allowance; else the request is denied `allowance_exceeded` (HTTP 200, status
`denied`, no number in the sentence). Read again at the moment of issuing, under the store's
lock, since a request that fit when it was asked may not fit once an earlier one is approved.

**What a stranger can check,** from the chain alone: from a `person.admitted` with `allowance`
or an `allowance.set` on, the `mandate.issued` of that `actor` in any one calendar day of that
zone add up to no more than it, and every `mandate.denied` with `reason: allowance_exceeded`
belongs to an actor with one. **What it cannot:** the operator's reason for the number.

## A seller known by its UCP profile (since v0.15)

Some sellers publish no SPIFFE identity: their key is the one their UCP profile names, served at
their own origin, and they sign a quote as a bare ES256 JWS (a `kid`, no `typ`) with seven
fields: `jti`, `iat`, `exp`, `merchant_id`, `offer_id`, `amount` (minor units) and `currency`.
The first was `seller.anciobanu.com`, on 2026-09-29.

When the request names `seller_profile`, step 3 reads the quote that way: the header policy but
no `typ`; the profile fetched from its own origin (the seller is that origin); the quote's `kid`
one of the P-256 keys the profile lists (`keys[]`, or `ucp.keys`), else `seller_unknown`; the
signature under it, else `quote_invalid`; the seven fields present and typed, else
`quote_invalid`. Nothing the seller does not sign is read from it: no route, date, basis,
provider or correlation id. Steps 4 to 6 follow as for any seller (the window, the allow-list,
the ceiling and the currency), then the allowance, the person's own limits and the rules.

The mandates are built from what it signed: the merchant is its `merchant_id` (named by the
seller's host, its website the seller's origin), the one acceptable item its `offer_id`, the
payment amount its `amount` in its `currency`. The approval page shows "Offer `<offer_id>`, as
the seller signed it", the seller's host and the merchant, and says the seller signs the offer
and its price, not a route or a date. Two purchases are the same trip (the person's limit on the
same trip again) when they are the same offer from the same seller.

Such a seller may also sign an `itinerary` (since 2026-09-30, `seller.anciobanu.com`): `origin` and
`destination` as IATA codes and `departure_date` as `YYYY-MM-DD`, with `airline`,
`flight_number`, `depart_time`, `arrive_time` (`YYYY-MM-DD HH:MM`) and `stops` beside them. When
it is in that shape, the route and the flight are read from it: the page shows the route, the date
and the flight as for any seller and no longer says it signs none, and two purchases are the same
trip by seller, route and date. An itinerary out of that shape is not read.

A standing rule names a route, a date and the number of travellers, which such a quote does not
carry together: no rule covers it, and the person approves each purchase.

## The request (`POST /mandate-requests`)

Body, `application/json` (`mandate-request.schema.json`, `request`):

```json
{"quote_jws": "<compact quote+jwt>", "sub": "<person>", "act_sub": "spiffe://…", "cnf_jkt": "<thumbprint>", "correlation_id": "<uuid>"}
```

Two optional fields since 2026-09-13: `format`, `poc-v1` (the default) or `ap2-v0.2`, and
`cnf_jwk`, the buyer's public key (`{kty: EC, crv: P-256, x, y}`), which `ap2-v0.2` requires
because the open roots carry it whole in `cnf.jwk`. The profile of the second format is
`mandate-ap2-profile.md`.

A third optional field since 2026-09-13: `intent_ceiling`, `{value, currency}` (minor units,
ISO 4217), the ceiling the buyer took from the person's own words. It is shown on the
approval page beside the ceiling the registry holds and nowhere else: the mandates are held
to the registry's ceiling whatever it says. A value that is not a whole number at least 0
with a three-letter currency is `request_invalid`.

A fifth optional field since v0.15: `seller_profile`, the UCP profile URL of a seller known by
its profile ("A seller known by its UCP profile", below). One that is not
`https://<host>/.well-known/ucp` exactly is `request_invalid`.

A fourth optional field since v0.8: `assistant_token`, the access token of the assistant the
request came through ("Which assistant asked"): a compact JWS, 4096 characters at most. One
that is not shaped as such is `request_invalid`; one that does not hold is `assistant_unknown`.

The authority checks, in this order, and stops at the first refusal:

1. **Shape.** JSON body under 65536 bytes; every field a string; `sub` not phone-shaped
   (a value made only of digits and phone punctuation, `+ - ( ) . /` and spaces, of any
   length: it cannot be told apart from a number, so it is refused);
   `act_sub` starting with `spiffe://`; `cnf_jkt` 43 base64url characters; `correlation_id`
   a UUID; `format`, when present, one of the two; `cnf_jwk`, when present, a P-256 public
   key whose RFC 7638 thumbprint equals `cnf_jkt`, and present whenever `format` is
   `ap2-v0.2`; `intent_ceiling`, when present, `{value, currency}` as above. Failure: HTTP 400 `request_invalid`, no request created, no ledger entry.
2. **Person.** `sub` is in the registry. Failure: `subject_unknown`.
3. **Quote.** `quote_jws` is a compact JWS with `typ: quote+jwt` under the header policy; its
   payload has the fields `quote.schema.json` requires; its `kid` is the seller's instance
   key, resolved by domain: `<quote.iss>/.well-known/spiffe-svid.json` names the key and the
   JWT-SVID in it verifies under `<quote.iss>/.well-known/spiffe-bundle.json` (`use:
   jwt-svid`), with `kid` equal to the thumbprint of that key; the signature verifies; the
   quote's `correlation_id` equals the request's (a quote from another transaction buys
   nothing here); for `ap2-v0.2`, the quote also carries the UCP Checkout fields
   (`quote.schema.json` since 2026-09-13: `merchant` naming `merchant_id`, one line item
   naming `offer_id` with a title, quantity 1, unit price equal to `total`), which the open
   roots are built from. Failure: `seller_unknown` when the seller's documents cannot be read
   or do not vouch for the key; `quote_invalid` for everything else.
4. **Window.** `quote.exp` plus 60 s skew is in the future. Failure: `quote_expired`.
5. **Seller policy.** When the authority is configured with an allow-list of seller issuers,
   `quote.iss` is on it. Failure: `seller_not_allowed`. (Empty allow-list: any seller whose
   domain vouches for its key.)
6. **Ceiling.** `quote.currency` equals the ceiling's currency (`currency_not_allowed`);
   `quote.total` is at most the ceiling (`ceiling_exceeded`). **6a. The day's allowance**
   (since v0.14): when the person has one, what was approved for them since the start of the
   calendar day plus `quote.total` is at most it (`allowance_exceeded`); read again at the
   moment of issuing, as the person's own limits are (6b).
7. **Delivery.** The approval link is sent to the person by the configured notifier, to the
   destination the registry holds for `sub`, never to anything in the request. Failure:
   `approval_undeliverable`. One notifier is the exception, by design: `relay` (since
   2026-09-16) hands the link back to the requesting buyer in the pending request document
   (`approval_url`), for the person's own channel to show, since the person reaches the buyer
   through an assistant that has no number to be called on. The page is still the
   authority's, on its domain, and what it decides is still recorded here; what the relay
   gives up is a second channel between the authority and the person.

Refusals at steps 2 to 7 create the request with `status: denied` and the code as `reason`,
answered HTTP 200, and write `mandate.denied` to the ledger. Step 7 succeeding creates the
request with `status: pending`, answered HTTP 202. Either way the answer is the request
document:

```json
{"request_id": "<opaque>", "status": "pending", "correlation_id": "<uuid>", "quote_hash": "<sha256 hex>",
 "created_at": "<iso>", "expires_at": "<iso>", "poll": "/mandate-requests/<request_id>"}
```

With the `relay` notifier (step 7) a pending document also carries `approval_url`, the link
itself; it is gone once the request is decided, and absent with every other notifier.

`quote_hash` is the authority's own recomputation over the payload octets of the quote JWS
(`canonicalization.md`); the buyer compares it with its own and the seller with its own,
nobody accepts another party's value. The document never carries `sub`, a number, or the
quote's content: the buyer has the quote, and the person's identity stays in the registry.

## Waiting for the person

`GET /mandate-requests/{request_id}` answers the request document. While `status` is
`pending`, `?wait=<seconds>` (at most 25) holds the answer until the person decides or the
wait passes; without it the answer is immediate. The buyer polls until the status is not
`pending` or until `expires_at`; how long a buyer is willing to wait for a human is the
buyer's decision.

The approval link is valid for ten minutes (`freeze-manifest.json`, `approval_link`). Past
`expires_at` a pending request becomes `expired` with `reason: approval_expired`, decided
lazily on the next read, and `mandate.denied` is written once.

Every document carries `format`, the one the request named or `poc-v1`. Statuses and what
comes with them:

| `status` | Fields | Meaning |
|---|---|---|
| `pending` | `expires_at`, `poll` | The link is out; nobody has decided |
| `issued` | `decided_at`, `mandates: [<jws>, <jws>]`, `jti: {intent, cart}`; for `format: ap2-v0.2` also `ap2: {jti, checkout, payment}` | The person approved; the cart mandate is what the seller is shown, the intent mandate carries the ceiling. In the AP2 form the same approval is also an open Checkout Mandate and an open Payment Mandate (Delegate SD-JWT roots with their disclosures, `mandate-ap2.schema.json`), sharing one `jti`, which `GET /mandates/{jti}` answers and a revocation covers |
| `denied` | `decided_at`, `reason`, `detail` | Refused by policy (steps 2 to 7) or by the person (`person_denied`) |
| `expired` | `decided_at`, `reason: approval_expired`, `detail` | The link ran out |

A request is read as often as anyone likes; the mandates in an `issued` document are bound
to `cnf_jkt` and `act_sub` and are of no use to anyone else. The authority keeps the two JWS
in the request's own record for exactly that: to serve them on every read; the mandate rows
and the ledger hold digests only. A `wait` above 25 is clamped to 25; a `wait` that is not a
whole number (decimal digits only: no sign, no separator) is 400 `request_invalid`. So is a
request whose body is not declared `application/json` (parameters such as `charset` aside), and
a decision on the approval page that does not arrive as the page's own form
(`application/x-www-form-urlencoded`), the latter as HTML.

## The approval page

`GET /approve/{approval_token}`: HTML, on the authority's domain, reached only from the link
the notifier sent. It shows what the person is approving, in the person's terms and the
buyer's terms. The route and date appear as the buyer asked for them through the quote, so an
extraction error there is visible; the amount is held to the person's standing ceiling in the
registry, not to a ceiling the buyer extracted from the person's message. Since 2026-09-13 the
page also shows that extracted ceiling, when the request carried `intent_ceiling`, and since
2026-09-16 marks it when it does not cover the total or is in another currency (a difference
from the standing ceiling alone is not an error: the person's words name a limit per
purchase), so an extraction error there is visible too (architecture §6 step 2); it changes
nothing about what is issued. In this order, short (2026-09-16):

- **the route and date** from the quote, the itinerary when the quote carries one, and the seller (`aud` host) with the merchant id, in one card;
- **the total**, in the quote's currency, with the person's ceiling and the ceiling the buyer understood from the person's words (when the request named it) in small print under it;
- how long the person has to decide, the way a person reads it (`Decide within 9 minutes (by 19:05 UTC).`: whole minutes left and the clock time in UTC, both rounded down; the full `expires_at` is the `<time>` element's `datetime`), and the two buttons;
- in a box that opens on request, after the decision: the buyer instance (`act_sub`) that will present the mandate, its key (`cnf_jkt`) whole, the amount in minor units, the mandates' `jti` once issued, and what the page proves (that someone holding the link decided, not who).

Two buttons, Approve and Deny, each a `POST` with `decision`. The link is single use: the
first decision counts, a second `POST` answers HTTP 410 `link_used`, and `GET` after a
decision shows the decision. An expired link answers HTTP 410 `approval_expired`.

On **approve** the authority issues two mandates, both `mandate+jwt` under the issuing key,
with the same `sub`, `act.sub` (= `act_sub`), `aud` (= `quote.iss`), `merchant_id`, `action:
purchase`, `cnf.jkt` (= `cnf_jkt`), `policy_version`, `nbf` (= now − 5 s) and `exp` (= now +
the mandate validity, 300 s by default; minutes, per `freeze-manifest.json`), each with its
own `jti` (UUID):

| stage | `amount.value` | `quote_hash` |
|---|---|---|
| `intent` | the person's ceiling | absent |
| `cart` | `quote.total`, exactly | the authority's recomputation |

It records both `jti` as `active`, writes `mandate.issued`, and flips the request to
`issued`. On **deny** it writes `mandate.denied` with `person_denied` and flips the request
to `denied`.

After an approval the same page offers **Revoke** (`decision=revoke`), valid until the cart
mandate expires (its `exp` plus the 60 s skew, the same window the seller accepts): both
mandates of that approval become `revoked` with `revoked_by: person`, `mandate.revoked` is
written per `jti`, and the next status read answers `revoked`. A revoke after that window
answers 410 `approval_expired`: there is nothing left to revoke, and the person is told so. This is
the person's "cancel" of §5.9; the WhatsApp form of it comes with the notifier.

What the page proves depends on how the approval was taken, and its technical box says
which. By the form (every approval before v0.3, and since then any approval under `approver:
off` or of a person with no passkey under `verify`): that someone holding the link decided, not
who (architecture §12). By a passkey ("Who approves"): that a passkey enrolled for this person
at this authority signed this exact purchase, with the device saying it verified its user. A
denial or a revocation proves the first of the two in every mode.

## Status and revocation

`GET /mandates/{jti}` answers `authority-status.schema.json` for both the intent and the
cart `jti`: `{jti, status: active|revoked, revoked_at?, revoked_by?: person|operator,
policy_version}`. A `jti` the authority never issued is 404 `not_found`. An expired mandate
still answers `active`: expiry is the seller's check 8, revocation is check 10, and the two
are not conflated.

`POST /mandates/{jti}/revoke` with `Authorization: Bearer <operator token>` revokes one
mandate (`revoked_by: operator`) and answers the status document; without the credential,
401 `admin_denied`. Revoking a revoked mandate is idempotent and writes nothing.

`GET /revocations` lists every revocation, newest first, so a verifier can check a status it
was shown against the list.

A mandate revoked by a stop ("Stopping") is `revoked_by: person` or `operator` like any other,
by whoever stopped: the status document does not change, and the ledger's `mandate.revoked`
names the stop in `pause`.

The time from a revocation to the seller's first refusal is measured by the verifier on its
own clock, polling this endpoint and the seller (F-07); the authority promises nothing about
it beyond answering status reads immediately from its own store.

## The ledger

`GET /ledger` answers the buyer's document shape: `{events, head, canonicalization, signer:
{spiffe_id, kid, public_jwk}, reading}`, entries per `ledger-entry.schema.json` (JCS over
`{at, type, correlation_id, facts, previous_hash, signer}`, SHA-256, ES256 over the hex
hash). Types and facts:

| type | facts |
|---|---|
| `mandate.issued` | `jti` (cart), `intent_jti`, `stage: cart`, `amount` (cart value), `currency`, `quote_hash`, `merchant_id`, `aud`, `act_sub`, `cnf_jkt`, `actor` (SHA-256 hex of `sub`, as the buyer records it), `policy_version`, `nbf`, `exp`, `request_id`, `mandate_sha256` (cart payload digest), `intent_sha256`, `format` (since 2026-09-13); since v0.2 `requester: {verified, form, linked}` when a verified envelope asked; since v0.8 `assistant: {grant_id, client_id}` when the request named the assistant it came through ("Which assistant asked"); since v0.9 `limits_sha256`, the person's limits it was issued under, once they set any ("The person's own limits"); since v0.12 `seller_trust` when they set a least ("What a seller is trusted with"); since v0.3 `approval: {method: passkey, user_verified, credential, backup_eligible, backed_up, evidence_sha256}` when a passkey approved ("Who approves"); since v0.4 `approval: {method: rule, rule_id, rule_sha256, use, of}` when it was issued under a standing rule; for `ap2-v0.2` also `ap2_jti`, `ap2_checkout_sd_hash`, `ap2_payment_sd_hash` (base64url SHA-256 over each root with its disclosures and trailing `~`, RFC 9901 §4.3, the reference SDK's `sd_hash`: what a hop's `sd_hash`, the payment root's `payment.reference` and a receipt's `reference` are compared with) |
| `mandate.denied` | `reason`, `detail`, `request_id` (when a request exists), `quote_hash` (once the seller's signature over the quote verified, never before), `actor` (when the person is known), `policy_version`; since v0.8 `assistant: {grant_id, client_id}` when the request named one; since v0.9, for `limit_exceeded`, `limit` (which one) and `limits_sha256`; since v0.12 `seller_trust` when the person set a least |
| `mandate.revoked` | `jti`, `revoked_by`, `request_id`; since v0.6 also `pause`, the `correlation_id` of the stop that revoked it, when one did |
| `rule.confirmed` (since v0.4) | `rule_id`, `rule_sha256` (the digest the passkey signed), `actor`, `agent`, `seller`, `merchant_id`, `max_amount`, `currency`, `purchases`, `valid_until` (epoch seconds), `proposed_by` (`agent` or `operator`; since v0.11 also `person`), `approval` (as in `mandate.issued`, method `passkey`), `policy_version`. Since v0.11, for a rule the person made: `form: budget`, `total` (minor units, in `currency`) and, when it replaces one, `replaces` (that `rule_id`); an entry with no `form` is a rule of v0.4 (`form: route`). Its `correlation_id` is the rule's own, not a purchase's |
| `rule.revoked` (since v0.4) | `rule_id`, `rule_sha256`, `revoked_by` (`person` or `operator`), `used`; since v0.11 `replaced_by` (the `rule_id` of the rule that took its place), when it ended by being replaced |
| `person.paused` (since v0.6) | `actor`, `by` (`passkey`, `link` or `operator`: which door), `requests_denied` and `mandates_revoked` (how many of each the stop caused; their own entries follow), `policy_version`. Its `correlation_id` is the pause's own |
| `passkey.enrolled` (since v0.7, only under `login: on`) | `actor`, `credential` (SHA-256 hex of the credential id's bytes, as in `approval`), `by` (`login` or `operator`: which door drew the invitation), `login: {iss, subject_hmac_sha256, evidence_sha256, auth_time?, amr?}` when `by` is `login` ("Signing in to enroll"), `backup_eligible`, `backed_up`, `passkeys` (how many the person has now), `policy_version`. Its `correlation_id` is the enrollment's own |
| `person.admitted` (since v0.10) | `actor` (the person let in), `by: operator`, `operator` (the `actor` of the operator who did it), `ceiling: {value, currency}`, `agents` (the buyer agents linked), `approval` (as in `mandate.issued`, method `passkey`), `policy_version`. Never an address or a name. Its `correlation_id` is its own |
| `person.removed` (since v0.10) | `actor` (a person who was waiting), `by: operator`, `operator`, `approval`, `policy_version` |
| `limits.set` (since v0.9, only under `limits: on`) | `actor`, `limits_sha256` (the SHA-256 of the JCS of the person's limits document, which is never in the ledger), `previous_sha256` (the digest it replaces, `null` for the first), `approval` (as in `mandate.issued`, method `passkey`), `policy_version`. Its `correlation_id` is its own |
| `person.resumed` (since v0.6) | `actor`, `by` (`passkey` or `operator`), `paused_at` (epoch seconds, of the `person.paused` it ends), `approval` (as in `mandate.issued`, method `passkey`) when a passkey resumed, `policy_version`. Same `correlation_id` as the pause |

Since 2026-09-13 every type also carries `build` when the deployed code names one: the same
value `GET /health` shows (on the POC host, 12 hex of the code tarball's sha256), so a reader
can say which code wrote which line. Entries from before carry none.

Never in the ledger: a mandate, a phone number, a name, the quote's content. Mandate rows
and ledger entries hold the digests; the JWS themselves live only in the request record
that serves them to the buyer.

## Checkpoints

Since 2026-09-12 the authority seals the head of its chain the way the seller and the buyer
do (`checkpoint.schema.json`, `checkpoints-document.schema.json`): after every entry it
writes (an issuance, a denial, a revocation) and on a timer (`interval_seconds`, 600 by
default), it signs `{iss, signer, height, head, at, previous_checkpoint}` as a
`checkpoint+jwt` with the issuing key (`kid` = its thumbprint, the same key set as the
mandates), offers it to the witness at `POST <witness>/checkpoints {checkpoint_jws}`, and
keeps the receipt beside it. `GET /checkpoints` answers the document, oldest first, with
`signer.key_url` = `<issuer>/.well-known/jwks.json`: that is where a witness or a verifier
resolves the key, anchored by the authority's own DNSSEC + DANE, since the authority
publishes no SPIFFE bundle.

A witness that cannot be reached, or a receipt that does not verify under the witness's key
set or does not cite this checkpoint, does not stop the checkpoint: it is published unsealed
with `witness_error` on it, and the entry that triggered it is never failed by it. Without a
witness configured the document says `witness: null` and every checkpoint is unsealed. A
head that has not moved since the last checkpoint is not signed again; but a checkpoint for
the current head that is still unsealed is offered to the witness again on the timer and at
start, and the receipt lands on that same record (one height, one record, the error gone),
so a gap closes when the witness is back instead of waiting for the next entry.

Since 2026-09-13, with a second witness configured (`external-witness.md`), the authority
also registers each head at that public transparency log (`POST <log>/register {capsule_id:
head}`) and keeps the answer as `external` on the checkpoint, unverified here except for the
log's entry hash; the document names the log as `external_witness`. A record without a
receipt from a configured log is offered again the same way as an unsealed one.

Why this exists: the chain proves order and authorship under one key, and that key belongs
to the party that keeps the chain. A checkpoint in someone else's log is what makes a
shortened or rewritten chain visible (R-28, "ledger deletion" in the threat model); for the
authority in particular it is what makes a silently dropped issuance or revocation visible.

## Reason codes (authority side)

Listed in `reason-codes.json` under `authority_side`. The buyer records the authority's word
as `facts.authority_reason` in `mandate.denied` and never turns it into a check of its own.

| code | Where | Meaning |
|---|---|---|
| `request_invalid` | POST, 400 | Malformed body; no request, no entry |
| `subject_unknown` | denied | `sub` is not in the registry |
| `seller_unknown` | denied | The seller's domain publishes no usable SVID and bundle, or they do not vouch for the quote's key |
| `quote_invalid` | denied | Not a `quote+jwt`, header policy, missing fields, signature, or the quote belongs to another correlation |
| `quote_expired` | denied | `exp` plus skew is past |
| `seller_not_allowed` | denied | Seller policy |
| `currency_not_allowed` | denied | The quote's currency is not the ceiling's |
| `ceiling_exceeded` | denied | The total is above the person's ceiling |
| `approval_undeliverable` | denied | The notifier could not deliver the link |
| `person_denied` | denied | The person pressed Deny |
| `approval_expired` | expired | The link ran out before a decision |
| `link_used` | page, 410 | A second decision on a used link; a passkey invitation already spent |
| `passkey_required` | page, 403 | A form `approve` where the approval takes a passkey; nothing decided, no entry |
| `passkey_unknown` | approve (JSON), 403 | The credential is not one enrolled for this request's person; nothing decided, no entry |
| `passkey_invalid` | approve or enroll (JSON), 403 | A WebAuthn check failed (the sentence says which); nothing decided or enrolled, no entry |
| `invite_expired` | enroll, 410 | The passkey invitation ran out; nothing enrolled |
| `rules_off` | rules, 403 | The authority takes no standing rules; nothing proposed or confirmed |
| `rule_invalid` | POST /rules, 400 | The proposal is outside what this person or this authority allows (ceiling, currency, date, seller); no rule, no entry |
| `rule_limit` | POST /rules, 403 | The person already has five rules proposed or active |
| `person_paused` | POST /mandate-requests, POST /rules, approve, confirm and consent, 403; also `denied` | The person stopped their agent here ("Stopping"): nothing is issued, proposed, confirmed or granted for them until they resume. As an HTTP refusal it writes no entry; as the reason of a `mandate.denied` it is a request that was waiting when the person stopped |
| `session_expired` | stop (page and JSON), 410 | The ten minutes of a stop session passed, or it never signed in; open `/stop` again |
| `not_paused` | resume, 409 | The person is not stopped; nothing to resume, nothing written |
| `provider_unknown` | POST /login, 400 | The form names no identity provider this authority accepts |
| `login_state` | callback, 400 | The answer belongs to no sign-in started in this browser, or to one already finished or older than ten minutes; nothing drawn |
| `login_failed` | POST /login and callback, 502 (400 when the provider says the person refused) | The provider could not be read, refused, or its `id_token` failed a check (the sentence says which); nothing drawn, no entry |
| `identity_unbound` | callback, 403 | The sign-in is good and no person of this registry is bound to that identity; nothing drawn, no entry. The page says the request is in: letting the person in is the operator's |
| `admin_denied` | revoke, 401 | No operator credential |
| `not_found` | 404 | Unknown `jti` or request |

## Configuration the authority reads (for the operator, not the contract)

Issuer URL; state directory (issuing key, registry, store, ledger); policy version string;
approval link validity (600 s) and mandate validity (300 s); operator token; notifier (`log`
writes the link to the journal; `relay` does the same and hands it to the buyer in the request
document; `whatsapp` sends it as a template through the Cloud API);
optional seller allow-list; the https addresses of buyer agents' own pages, linked from the overview of a person whose buyer is on that host (since v0.13; empty: none); who may ask and who approves, each `off`, `verify` or `require`; standing rules, `off` or `on`; rules the person makes, `off` or `on` (on takes standing rules and stopping on; off, the section does not exist and the rules made there are inert); stopping, `off` or `on` (off, its routes do not exist; a person stopped earlier stays stopped until the operator resumes them); signing in to enroll, `off` or `on`, and the file of accepted issuers with the client registered at each (its secrets never leave the host); the witness base URL the checkpoints are sealed at (empty: none),
the public log the heads are also registered at (empty: none) and the timer interval. The registry is a file in the state directory, never served:
one entry per person with `sub`, the ceiling and the notifier destination.

## What this contract does not promise

That stopping reaches what already happened or what happens elsewhere (a checkout the seller captured before the stop stands; another authority where the person keeps another agent hears nothing; and the person's stop link is a bearer address, so whoever holds it can stop their agent, which is a nuisance and never a purchase); that a purchase issued under a standing rule is one the person would have approved that day (the rule is their word given ahead, within limits they signed; whoever can make the linked buyer ask can spend within an active rule, which is why a rule is one purchase and 48 hours at most); which human approved (§12): under `approver: off`, and for a denial or a revocation in any mode, only that someone held the link; with a passkey, that a passkey enrolled for the person signed the purchase with user verification, where who holds that passkey is the operator's word for an invitation the operator drew, and since v0.7, for an enrollment after a sign-in, the word of the identity provider named in `passkey.enrolled`: whoever controls the person's account there can enroll a passkey here and then approve as them, so that account is now as much a key as the passkey is; a reader of the ledger learns which issuer vouched and cannot check the sign-in itself (the `id_token` stays at the authority, its digest in the entry); and which identity belongs to which person is still the operator's binding, what kind of authenticator holds the key is not proven (no attestation is asked, so one in software can say it verified its user without a fresh biometric), a passkey that syncs is as safe as the person's account at the passkey provider, and what the person read before approving is this authority's own page (no browser-drawn confirmation of amount and payee, which W3C Secure Payment Confirmation would give where it exists); a DANE check of the seller's host by the authority (the buyer does it,
the authority trusts the WebPKI in v0.1 and says so); key rotation (v0.1 has one issuing key
and rotates none); a checkpoint receipt from a transparency service on every checkpoint (the witness is whichever the operator configures, today the verifier's emulator, and its receipts say so; the public log of `external-witness.md` is a second receipt behind a flag, with no retention or service promise); a Payment-stage mandate (nothing settles in this POC, D-021);
AP2 conformance (the stages are a POC profile with a pinned version).