# Attestation

Attestation is the check `bot.did.provisionAgent` makes before it mints an
agent account: a signature proving the request came from a host whose operator
has vouched for it. It runs once, at provisioning: the claim is spent the
moment it is admitted, and what it established is written into the account's
`bot.did.registration` record as an audit artifact rather than a credential.

`crates/didbot-attest` holds the claim format and the verifiers,
`crates/didbot-agentd` is the host side, `crates/didbot-pds` holds the key
registry and the admission rules, and `crates/didbot-serve` serves the routes
and runs the polls. [The daemon on an agent host](agentd.md) draws the process
that signs; [the trust model](trust-model.md) says what a signature is worth.

## The parties, and the keys each one holds

| party | key | where it lives | who writes it |
| --- | --- | --- | --- |
| operator | their own atproto account's | the operator's own machine and their personal data server | the operator |
| server | one repository signing key per account it hosts, and its own | the deployment's store | the server |
| host | a node key, secp256k1 | one file on the host | `didbot-agentd`, once |
| context | no key: a bearer agent token | the daemon's memory | the server issues it |

**The operator** is a DID with a repository this deployment cannot write to.
They write `bot.did.operator` records there: one keyed by the server's own
hostname, which is what makes the deployment theirs
([verifying who an agent belongs to](ownership-verification.md)), and one per
host, keyed by that host's hostname. `didbot-claim` is the command that writes
them.

**The server** is the root of the tree of principals every account hangs from —
`Trust` in `crates/didbot-pds/src/admission.rs`, four edges deep by default,
which covers operator's server, platform, host, agent. It holds the
custodial signing key of every repository it serves, including each host's,
and it keeps a mirror of each host's vouch in its own repository.

**A host** is an account of kind `host`. Its node key is minted on the
daemon's first start and kept in `$XDG_STATE_HOME/didbot/agentd` — or wherever
`DIDBOT_STATE` names — as `node.key`, `0600` in a `0700` directory, under an
exclusive `flock` held for the daemon's life
(`crates/didbot-agentd/src/node.rs`). What crosses the daemon's socket is the
public half as a `did:key` and signatures over claims; the private half
crosses neither the socket nor the network. It is still a file, and anything
that can read this user's disk can copy it — `Assurance::NodeCredential` in
`crates/didbot-attest/src/claim.rs` says so in the record. The public half is
published as the `#node` verification method in the host's DID document and
stored as `AgentAccount::node_key`; the key the server minted for the host's
repository is a different key for a different job.

**A context** is a session, or a subagent inside one, keyed by both
(`crates/didbot-agentd/src/context.rs`). Each gets its own account under the
host, and the write credential for it stays in the daemon.

## How a host comes to exist

```mermaid
sequenceDiagram
    participant D as didbot-agentd
    participant S as agent pds
    participant O as operator's repository
    D->>S: reserveIdentity(public key, kind host)
    S-->>D: did, hostname, expiresAt
    Note over S: provisioning: the document serves the #node key, the repository does not
    O->>O: didbot-claim writes bot.did.operator, keyed by that hostname
    S->>O: getRecord, once per pending reservation, every 5 minutes
    O-->>S: subject, subjectKey, expiresAt
    Note over S: mirrors the record, verifies host → server, activates, registers the node key
    D->>S: provisionAgent(agentId, registration, claim signed with the node key)
    Note over S: verifies the claim, the host's standing, and agent → host → server
    S-->>D: did, handle, agentToken
```

**The reservation.** A `become` message over the daemon's socket posts the
public half to `bot.did.reserveIdentity`, which is an unauthenticated route
bounded by the e-stop, the server's lifecycle, six calls per address per ten
minutes, the account cap, and a queue of `DEFAULT_PENDING_RESERVATIONS`
reservations — thirty-two — waiting at once. `Provisioner::reserve` mints the
repository key first and draws the name from the pool seeded by that key, so
the selector an operator matches on is one the server chose. The row is
inserted `reserved` with the host's key on it and moves to `provisioning` once
the hostname's DNS record is published: the DID document serves and publishes
`#node`, the repository does not, nothing is announced. The daemon writes the
DID and hostname beside its key, and a daemon that holds an identity answers
`become` with it and asks no server, whichever one the message names.

**The lifetime.** `DEFAULT_RESERVATION_TTL` is a day, measured from the
reservation's creation, and the stale sweep reaps an expired one and returns
its name to the pool. A vouch that arrives after that is answered
`ReservationExpired`; the host reserves again, which means a daemon whose
state directory still holds the reaped identity has to be given a fresh one —
the identity file is written once and never replaced.

**The vouch.** `didbot-claim --server <server-hostname> <name> <operator>`
logs into the operator's own account and writes `bot.did.operator` into the
operator's repository, keyed by the reservation's hostname, naming the
reservation's DID as `subject` and the key the host presented as
`subjectKey`. `bot.did.listReservations?operator=` answers with the
reservations that named that operator, so an operator can read what is waiting
on them.

**The admission.** While the server's own claim stands, every tick of the
ownership poll (`DEFAULT_POLL_INTERVAL`, five minutes) reads that record once
per pending reservation and requires it to name the DID exactly, to name the
key the host itself presented, and not to have expired
(`crates/didbot-serve/src/ownership_poll.rs`). `Registry::admit_reservation`
then mirrors the record into the server's own repository at the same key, and
`Registry::admit` verifies the host → server edge from that mirror the way it
verifies every other edge. The account lands its profile and registration
records, goes `active`, and its node key enters the attestation verifier. The
ledger entry for the transition names the operator, which is what says who
vouched.

**The mirror, afterwards.** Each tick re-reads the operator's record for up to
`VOUCH_REREAD_LIMIT` — a hundred — standing hosts, resuming where the last
tick stopped, and makes the mirror say what the operator's repository says
now: an unchanged record moves nothing, a changed one is overwritten, and a
record the operator deleted is removed. Only a repository that answered and
held nothing counts as absence; a repository that could not be reached leaves
every mirror as it was and ends the pass. The mirror is what the tree is read
from, so it is what a lapsed vouch changes.

## What a provisioning claim is

`AttestationClaim` (`crates/didbot-attest/src/claim.rs`) carries four fields,
camelCase on the wire: `nodeId`, the host's DID; `nonce`, sixteen random bytes
in hex; `issuedAt`, RFC 3339; and `evidence`, the signature in lowercase hex.

The signature covers a canonical string and nothing else
(`crates/didbot-attest/src/signing.rs`): a domain separator, a newline, then
each of the node id, the nonce and the UTC timestamp as a netstring — its byte
length, a colon, the bytes, a comma.

```text
didbot-attest/v1/node-credential
24:did:web:host.pds.example,
4:n001,
20:2026-08-24T12:00:00Z,
```

Length prefixes mean exactly one tuple of fields can produce a given
signature, and the domain separator means a signature made for one backend
never verifies at another. The agent id, the requested handle and the
registration travel beside the claim, outside the signature.

**Verification**, in `Registry::provision` and
`NodeCredentialBackend::attest_at`, in this order:

1. The registration's `parent`, when it names one, has to be the node the
   claim names. The signature is the fact; the registration is the harness's
   word.
2. The node has to be one the verifier holds a key for. That registry is the
   allowlist: it holds the secp256k1 node key of each active account, built at
   startup and grown by one when a reservation is admitted.
3. The timestamp has to sit within `DEFAULT_WINDOW_SECS` — five minutes —
   either side of the server's clock. A refusal carries both clocks and names
   clock skew.
4. The signature has to verify under that node's key.
5. The claim is spent. `SeenNonces` keys on the whole signed tuple, sweeps
   entries once they are too stale to accept anyway, and lives in one
   process's memory.
6. The host has to stand: `active`, with no lock hung on it.
7. The chain is walked before anything is published — agent → host, matched
   against `NodeMembership`, which admits only the backend the host is trusted
   through and only the host's own node id; then host → server, re-read from
   the mirror, which checks the DID, the key the child holds now, and the
   record's expiry.

A claim is spent by step 5 whether or not the steps after it pass, so a
refused attempt signs a fresh claim rather than re-presenting one. The daemon
signs one claim per provisioning request, with a nonce drawn per claim.

**The parent.** The daemon names the host's DID as the registration's parent
for every context it asks for, session or subagent alike
(`crates/didbot-agentd/src/serve.rs`), and the server sets
`AgentAccount::parent` to the host that signed. Every context on a host is
therefore a direct child of that host, and `Registry::boundary` reads the
chain context → host → server. That chain is what a lock cascades down and
what a policy binding's "everything admitted beneath" means.

The account's registration record says `admittedBy: node-credential` and
`assurance: node-credential`, and `actor.parent` names the host. The response
carries the DID, the handle the deployment chose, the DID document and the
agent token, which is sent once.

## The refusals, by name

Four gates close `bot.did.provisionAgent` before the claim is read at all:
`Halted` (the e-stop, which also fires when the server's own operator claim
has lapsed), `ServerNotReady` (the lifecycle — see
[the server lifecycle](server-lifecycle.md)), `RateLimitExceeded` (a thousand
calls per address per minute) and `AccountCapReached`. Then:

| name | status | what it means | what the host does |
| --- | --- | --- | --- |
| `AttestationRequired` | 403 | the body carries no claim | get an identity; there is nothing to re-sign |
| `ParentDisagrees` | 400 | the registration names a parent the claim does not | send the signing host as the parent |
| `AttestationRefused` | 403 | the claim did not verify: an unregistered node, a stale timestamp, a bad signature, a spent nonce or a malformed field — the message says which | check the clock, the identity and the key |
| `HostNotAdmitted` | 403 | the host is not `active`; the message carries its state | wait for the operator's vouch |
| `AccountLocked` | 403 | the host is active with a lock hung on it; the message names every tag | the party that hung the tag lifts it |
| `AdmissionRefused` | 403 | an edge of the chain could not be verified, or the chain reached no root; the message names the edge | restore the vouch above the host |

A host still waiting on its vouch holds a key the verifier does not, so its
claim would be an unregistered node; `Registry::provision` looks the host up
and reports `HostNotAdmitted` instead, because the two call for different
actions. `AdmissionRefused` is what a withdrawn vouch produces in the window
between the poll that removed the mirror and the confinement pass that
quarantines the host; after that pass the same request is `AccountLocked`.

`bot.did.reserveIdentity` has its own: `QueueFull` when the reservation queue
is at its cap, `KindNotReservable`, `NoNamePool` for a deployment that issues
no names, and `RateLimitExceeded`.

The daemon reports the server's name and sentence to the context that asked,
which stays owed a name and is provisioned on its first call after the
refusal clears (`crates/didbot-agentd/src/registrar.rs`).

## What the credentials last

**The agent token.** `DEFAULT_AGENT_TOKEN_TTL` is 365 days from issue
(`crates/didbot-pds/src/credential.rs`). One live token per account; issuing
another revokes the first; the server keeps a SHA-256 digest and sends the
bytes once. Nothing extends it and nothing shortens it: using it daily and
leaving it idle for a year come to the same expiry, after which every route
that takes it answers `ExpiredToken`. The daemon holds each context's token in
memory for as long as the context lasts.

**OAuth.** `ACCESS_TTL` is 5 minutes and `REFRESH_TTL` is 14 days
(`crates/didbot-serve/src/oauth/token.rs`). Every refresh rotates both tokens
and sets the refresh expiry to fourteen days from that refresh
(`rotate` in `crates/didbot-pds/src/oauth.rs`), so an app that refreshes at
least fortnightly keeps one login indefinitely. Presenting a refresh token
that has been rotated away, or one whose fourteen days have passed, ends the
whole family. The app then signs in again, which puts a fresh decision record
in front of the agent, and the daemon approves it with that account's own
agent token. Grants are durable across a restart for a `--data` run; the
scope ceiling is asked again at every refresh and every write, so a login
never outlives what current policy allows.

The session lifetimes in `crates/didbot-pds/src/session.rs` belong to the
app-password path, which is for a person at a client rather than for an agent
a host provisioned. Erasing an account ends every
credential it has at once — the agent token, its OAuth grants and its
unredeemed authorization codes. A lock ends none of them; it refuses the
write.

## Locks, withdrawals, and losses

A lock hung on a host is hung on everything live beneath it as
`Party::Parent`, and comes off below only when it comes off above — see
[the account lifecycle](account-lifecycle.md). A host under any lock mints
nothing new beneath itself, and keeps its key.

| situation | what attestation does | who recovers it |
| --- | --- | --- |
| a lock on the host | provisioning is `AccountLocked`; the contexts beneath it keep their tokens and have their writes refused | the party that hung the tag lifts it |
| the operator deletes, re-keys or retargets the vouch | the next poll tick drops or rewrites the mirror: provisioning is `AdmissionRefused`, then `AccountLocked` once the confinement pass quarantines the host and its subtree | the operator writes the matching record again; the next pass releases the subtree |
| the operator's repository is unreachable | every mirror stays as it is and hosts keep standing; the server's own claim has `DEFAULT_GRACE_WINDOW`, six hours plus one poll interval, before the server pauses itself and every route here answers `Halted` | the operator's server comes back |
| the node key is lost | the host account keeps the key it was vouched for and nothing can sign for it; its contexts keep the tokens they hold | a fresh state directory, a new reservation, a new vouch; the operator deletes the old host's record to confine what it admitted |
| the server is down longer than a refresh window | claims are unaffected — each is made fresh for one request — and a reservation older than a day is reaped on the way back; agent tokens are unaffected; every OAuth refresh token last rotated more than fourteen days ago ends its family at the next attempt | apps sign in again |
| the server restarts | spent nonces are forgotten, and provisioning answers `ServerNotReady` until the first poll reads the operator's claim | the poll, on its own |

The confinement poll (`crates/didbot-serve/src/confinement_poll.rs`) re-derives
every inherited tag from the tree on the same five-minute clock the ownership
poll runs on, so a lapsed vouch and a lapsed operator claim are noticed at the
same rate.

## The `.localhost` development exception

`didbot-pds` sets `AuthState::unattested_provisioning` from
`LoopbackDns::accepts(zone.host())`, which is true for `localhost` and any
name under `.localhost`, and nothing else in the binary can turn it on. Under
it, `auth::require_attestation` lets a request carrying no claim through to
the registry, where it is minted as a root — no parent — and recorded as
`admittedBy: unauthenticated`, `assurance: self-asserted`, which is what its
registration record says forever. A request that does carry a claim is checked
exactly as it is anywhere else. The same zone check decides that no ownership
poll runs and that the lifecycle starts `claimed`, which is why the exception
exists: a `.localhost` stack has no operator repository to read a vouch from.