The shape of the system #

Four pictures of where things run and what talks to what. This page draws the intended shape. Each picture is a decision, and the decision lives in the epic under plan/ that owns it; plan/README.md is the register of what each epic has reached.

Every route declares which credential it requires, and crates/didbot-serve/src/auth.rs holds that table: public reads, LegacySession for session management itself (com.atproto.server.{create,refresh,delete,get}Session, app passwords hashed with Argon2id), and an agent token on the com.atproto.repo.* write surface. auth-types is the epic that owns it.

The trust model says what the system can and cannot prove.

Hosts, and what a compromise of each one reaches #

Four kinds of host. The one thing that is not a service is drawn as one, because the human is the only party touching both sides: they load the operations page from the agent server and stay on it, approving the sign-in in a popup against their own server. That is why the agent server needs no write scope on the owner's account in order to authenticate anybody.

Policy is pulled. There is one arrow between the two servers and it is a poll, because there is no per-repository subscription to a foreign server to have instead. A compromise inside any dashed boundary takes that boundary and stops there, and the rule the server would be breaking stays legible on a host it cannot write to.

The agent host at the bottom is one of several, and the daemon on an agent host draws what runs inside it: the socket the hooks reach, the process behind it, and how the host proves itself to the server.

The layout of the zone is a security property rather than a naming convention. An agent's hostname must sit at or below its server's own, and agents must be off the apex so a wildcard certificate cannot shadow the server's own name. Apex plus subzone is the only arrangement satisfying both.

STATIC HOST policy dashboard no backend the human owner a person at a browser · not a service OWNER HOST owner pds policy records the authority only the owner's key writes here third-party app any client_id, anywhere dns zone agents.did.bot delegated · acme dns-01 for the wildcard cert PDS HOST · did.bot agents under *.agents.did.bot — at or below its own name a compromise here reaches keys, accounts and records — not policy HTTP SURFACE oauth server par · authorize · token xrpc + firehose what agents write to ops dashboard state · e-stop control DOMAIN identity + names did docs · handles attestation node credentials policy engine pull sync · evaluator floor STORAGE repository store + write-ahead log accounts · custodial keys · records · check, append, apply disk fsync par names writes policy owner's key opens approves the sign-in, in a popup loads the ops page and stays on it polls for policy no write scopes AGENT HOST · reaches this host's sessions hook · node agent stamps identity, provisions, collects agents session and subagent did:web accounts AGENT HOST · one of several same again · one agent pds serves many a compromise here does not reach the others provision · collect · write

Provisioning, and the tree inside one process #

Three accounts, one process. Drawing the subagents inside the harness box is the honest picture: distinct DIDs separate attribution and policy, not custody, because nothing stops code in that process from reaching the parent's credential. The hook reports each context to the daemon on the host, which asks the server once per context.

On the right, the zone is drawn as the one phase that could leave the building, and under a wildcard record it does not: both of an account's names resolve the moment they are chosen, so the provider writes nothing and provisioning makes no external call. A deployment that publishes per-agent records instead puts a network write on this path, where a DNS failure is an outage of provisioning rather than a degradation of it — the names an agent has works through both shapes. Record writes go to the XRPC surface and are not on this path.

AGENT HOST ONE HARNESS PROCESS — subagents share it session agent did:web:7f3a9c.agents.did.bot handle: basalt-otter.agents.did.bot subagent did:web:1d4e02.agents… slate-heron · reviewer subagent did:web:9b77af.agents… amber-vole · writer SubagentStart · narrowed scope set PreToolUse stamps the acting DID onto every tool call made in here hook · node agent the harness supplies identity AGENT PDS · PROVISIONING 1 · admit the node attestation, or nothing below runs 2 · claim a name one atomic claim, never check-then-take 3 · write the zone two hostnames: the did and the handle 4 · mint the keypair custodial, held here 5 · serve the documents did.json · atproto-did · then attest 6 · issue the credential session-scoped, back to the host dns zone agents.did.bot external, api-writable create resolves SessionStart · SubagentStart

Signing in to a third-party app #

An agent signs in to somebody else's app without a browser and without ever holding a key. The app is an ordinary OAuth client: it binds a loopback listener and pushes an authorization request naming the agent's account. The agent server is the authorization server, so what that request becomes is ours — a decision record, saying which client asked, what it asked for, and what the owner's policy made of it.

The problem that shape creates is knowing which agent is answering. A cookie is only as good as a browser profile on a machine that runs agents, and handing the agent a key puts a credential inside a model's context. Neither is necessary, because the daemon on that host already holds one credential per context. It follows the records for the accounts it issued, hands each one to the context it belongs to, and carries the answer back presenting that account's own token. The agent holds nothing.

Answering a record rather than a URL is what makes the binding exact. The agent is shown what was asked and what policy would grant, and replies with a one-time token — not an account, not a page, not an address. Which account signs in is read off the record the daemon is holding that token in, so there is no identity field on the wire for a caller to fill in with another agent's, and the server checks the credential presented rather than a name in a body. A token relayed to another agent's daemon matches no record it holds.

The honest limit has moved but not gone. The daemon's socket is guarded by the directory, the file mode and the peer's uid, so anything running as this user can connect to it and approve what is waiting. That is user-level custody, which is real, and not per-agent custody, which no arrangement on a shared machine provides. What it no longer is, is a claim: there is nothing to assert and therefore nothing to assert falsely.

agent the model hook · didbot-oauth short-lived, one per event or command didbot-agentd holds the account tokens the app third party, on this host agent pds authorization server start the client, name its own handle PAR: client id, scopes, the agent's account a decision record, pending no browser is ever opened listPendingAuthorizations, held open who asked, what for, what policy did to it outbound only: nothing here is reachable report and what is waiting for this context the agent reads it didbot-oauth approve <token> a token, not an account approve(token) the record names the account approveAuthorization, as that account is the token live and unused? does the credential authenticate as the account? what does the owner's policy allow? the granted scopes, and the client's redirect the code, fetched on loopback the code, for a token and the granted scopes

Why a stop is local #

A policy change is authored in a browser, lands in the owner's repository and waits for the next poll before it binds. That is correct for a rule and useless for an emergency, which is the argument for keeping an emergency stop in local state: it needs no network, no owner and no poll to wait for.

policy path · every hop can stall policy dashboard owner's repo next poll validate whole evaluator swaps stop path · local, immediate e-stop thrown next request refused no network, no owner, no poll to wait for