id: auth-types title: Every credential this server accepts, and what each one may do status: open crates: [didbot-serve, didbot-pds] dependsOn: [agent-accounts, pds-writes] exitCriterion: > Every route the router serves names the credential types it accepts, a request carrying none is refused wherever the route needs a principal, and each accepted type is driven end to end by the conformance harness. #

auth-types #

Nothing authenticates. Every com.atproto.* route answers whoever reaches it, and where a route needs to know which repository it is acting on it reads that off a parameter or a header — uploadBlob takes the account from a header precisely because there is no session to take it from. Read paths are unauthenticated by accident rather than by decision, and no write path refuses anybody.

oauth builds one credential and the server that issues it. This epic is the other question, which that one does not answer: which credential types exist here at all, which routes take which, and what a route does when a request carries none. A server that implements only OAuth still has to answer the client that arrives holding an app password, and it has to answer it in a way that says so.

The types #

OAuth access tokens, bound with DPoP. The atproto-native one and the only one a third-party app should ever get. Issuing it is oauth; accepting it is here — proof verification, nonce issuance, replay, and the thumbprint check that makes the token useless to anyone who copies it.

Legacy session tokens. com.atproto.server.createSession, refreshSession and deleteSession, with an app password behind them. Most deployed atproto software speaks this and nothing else, so refusing it is a decision about who can talk to this server, not a detail.

Inter-service auth. The short-lived signed JWT from com.atproto.server.getServiceAuth, naming an audience and a method. This is how one service calls another as an account rather than on its own behalf, and it is the credential this project's own components would use.

Operator auth. e-stop and anything under com.atproto.admin.* need a caller the server trusts that is not an agent and is not an app.

The hook-stamped local identity in credentials is not on this list and must not end up on it. It says which agent is making a tool call. It is not presented over the wire and it authenticates nothing to this server.

• Inter-service auth, before something else grows into its place. Not built. Presented::Disabled("ServiceAuth") reserves the scheme name so a caller presenting one is told "recognised, not accepted" — see index's note that the first non-public read is when this becomes load-bearing.
• Per-principal rate limits. Not built.
• The caller-facing app-password lexicon methods. createSession works; com.atproto.server.{create,list,revoke}AppPassword do not exist, so an operator sets the one password this server tracks per account directly rather than a caller managing several.

The write surface, and the credential that unlocked it #

The write surface is no longer open. com.atproto.repo.createRecord, putRecord, deleteRecord, applyWrites and uploadBlob all require Credential::AgentToken now, and the authenticated DID is checked against the repository the request names — ApiError::repo_mismatch (403 RepoMismatch) is what a token from one account gets for trying to write another's, an invariant rather than a policy knob.

Getting there needed a fifth credential kind the original taxonomy above does not name, because none of the four fit the caller: didbot-hookd writes an agent's scrobbles and memories automatically, with no person at a login screen and no operator minting an app password for it, so LegacySession was the wrong vehicle — building it would have meant didbot-hookd holding a human credential shape for a caller that is never human. What it needed instead was the smallest thing plan/credentials.md's framing already asks for: a bearer token, minted once at provisioning, bound to one DID, with an expiry and no rotation. That is didbot_pds::credential — Credential::AgentToken on the HTTP side — and Provisioner::provision now issues one automatically, durable in the write-ahead log (pds.layout bumped to 3), returned once as agentToken in provisionAgent's response body. didbot-hookd carries it the same way it already carries the DID — stamped onto every scrobble alongside STAMP_KEY — and crates/didbot/tests/hook_to_record.rs proves the whole path: hook, scrobble host and server agreeing on a credential none of them minted by hand.

This is deliberately not LegacySession, not OAuth, and not inter-service auth — a fifth entry in the taxonomy the module doc above names as "the five kinds this server accepts" now, and getSession's own end-to-end proof (below) still stands as LegacySession's.

The account-admin surface, and the mistake Credential::Public let happen #

The write surface above closed com.atproto.repo.*. It left bot.did.* — this server's own account-admin surface — open, on the reasoning that provisionAgent's credential is the ProvisionRequest's attestation claim, checked inside the registry rather than at the HTTP layer. That reasoning is sound for provisionAgent alone. deleteAgent, setAgentPinned and setAgentScrobbling inherited Credential::Public alongside it without inheriting the attestation check, which is a route that destroys an account answering an unauthenticated POST — a single request, no session, no enumeration even needed because listAgents handed out every DID for free. provisionAgent is now its own credential kind, Credential::Attested, so Public can no longer mean two different things depending on which route you are reading; see crates/didbot-serve/src/auth.rs's module documentation for the full taxonomy this section only summarises.

Mutations — deleteAgent, setAgentPinned, setAgentScrobbling — are always credentialed, never toggleable. Credential::AgentSelf: the acting agent's own write credential, checked against the account the request names. didbot-hookd calls all three automatically — the same shape that argued (wrongly) for Public before — but by the time one of these fires the account already has its own write credential, and that is exactly the caller these routes are reasonable to ask one from. An agent may end or toggle itself, and that is the whole list: acting on another account would need a credential proving this deployment's operator, and there is deliberately no such credential. bot.did.hardDeleteAgent, which must not be self-service, consequently has no route at all — see agent-accounts. There is no netizen argument for letting a stranger delete an account, so this stays hard-locked regardless of the disclosure decision below.

Publish by default: the accountability argument, and why it is a principle rather than a note about four routes #

listAgents, listAgentLedgers, getAgentLedger and stats are disclosure, not mutation — reads that say which agents a deployment runs and what happened to them — and the decision for these is not "lock them like the mutations." It is Credential::Disclosure: public by default, narrowable per route by deployment configuration, and never widenable past public. auth::Disclosure carries one bool per route, every field defaulting true; a deployment may flip a field to false, and nothing may flip one back past true, because there is nothing wider than public to widen into — the same narrowing-only rule that governs every configuration tier below the owner's own repository.

The reasoning is not specific to these four routes, and should be read as one this project applies wherever a "should this be public" question of this shape comes up again — not re-derived per route:

• What is being published is the accountability mechanism, not an incidental leak. ownership exists so a stranger can ask whether an agent traces to a responsible human. That question has no answer if the deployment being asked is also the one deciding whether to be asked. Publishing which agents exist and what happened to them — the roster and the ledger — is the same argument this project already makes for publishing what it is doing elsewhere: divergence from what was promised has to be a comparison somebody outside can make, or the promise is unverifiable. A fresh deployment therefore starts open, not closed-until-configured.
• The toggle exists because "private means federation off" is a real, legitimate posture. spaces names it for the deployment as a whole; per-route disclosure is the same choice at a smaller grain, for an operator running agents on behalf of people who would rather not have every account enumerable by a stranger. Per route rather than one switch: closing the ledger while leaving the roster open (or the reverse) is a plausible posture a single flag cannot express.
• Closing a route has to be visible, or the mechanism defeats itself. The threat this default resists is an operator who cannot be audited, and the configuration tier that closes a route is a tier an on-box attacker also reaches — closing listAgents is exactly what that attacker would do to hide what a stranger needed to see. This cannot be prevented from the server alone, but it is made legible: a closed route answers DisclosureDisabled, never a 404 and never an empty list, so an outsider can tell "this server runs no agents" from "this server is not telling you" — two different facts, and only one of them is suspicious. An operator credential still reaches a closed route, so closing it narrows who may read it without narrowing who may audit it.

This closes the "state what stays open to everyone" item below for bot.did.*: public-by-accident is gone, and what remains public does so for a reason the table now states, not because nobody got to it. It is written as a decision for now, not a permanent property — the owner has said this surface will be revisited, likely with finer-grained scoping than per-route booleans, and plan/spaces.md's alternative posture is exactly the direction that revisit would move in.

com.atproto.*'s read surface is a separate question this epic does not answer. com.atproto.sync.* and the read half of com.atproto.repo.* are public because the protocol requires it: a relay crawls them and an appview indexes them, and a credential there means no relay indexes these agents and nothing they write reaches Bluesky, contradicting what this project says it does. Whether this deployment federates at all is the owner's decision, made and recorded — Credential::Public on purpose, not an accident, and plan/spaces.md's "private means federation off" is what a deployment reaches for if it decides otherwise. /.well-known/did.json, /.well-known/atproto-did and createSession are public for a third, purely structural reason: a DID that needs a credential to resolve is not a DID, and a credential requirement on the route that issues credentials is circular. See crates/didbot-serve/src/auth.rs's "Why every public route is public" for all three reasons laid out together.

Done #

• Take the account off the header. uploadBlob no longer reads REPO_HEADER — deleted along with the header itself. The repository an upload lands in comes solely from the agent token auth::require_agent_token resolves.
• Require an agent's own credential on the repo write surface itself. createRecord, putRecord, deleteRecord, applyWrites and uploadBlob are Credential::AgentToken; see "The write surface, and the credential that unlocked it" above for what that credential is and why it is not LegacySession.
• Decide the set, then refuse everything else by name. crates/didbot-serve/src/auth.rs names five kinds — Public, LegacySession, AgentToken, Operator, and the two named-but-disabled schemes DPoP and ServiceAuth — and Presented::Unrecognized vs Presented::Disabled are AuthenticationRequired (401) and SchemeDisabled (403) respectively, a client-visible difference and not only an internal one.
• One extractor, and a per-route declaration of what it accepts. auth::ROUTE_CREDENTIALS is that declaration, for every com.atproto.* and bot.did.* route this server serves; a test fails if one is added without an entry, and every router this crate builds runs the same check as a debug_assert! against the routes it is about to serve.
• Answer the app-password question. This server mints them: an operator sets one through didbot_pds::SessionAuth::passwords, hashed with Argon2id (AppPasswordHash) and never stored reversibly. createSession refuses a wrong identifier and a wrong password identically, so a caller cannot use it to enumerate accounts. Not built: com.atproto.server.{create,list,revoke}AppPassword as caller-facing methods — an operator sets the one password this server tracks per account directly, a smaller surface than the full lexicon set.
• Say what an operator credential is: there is not one. No scheme this server accepts authenticates an operator, and none should. A server learns which DID operates it by reading bot.did.operator out of the operator's own repository — see handshake — a mechanism whose whole point is that no operator credential ever reaches a PDS. A header this server could compare would be one it holds, which is the thing the handshake makes unnecessary. auth::ROUTE_CREDENTIALS carries the consequences: every account-lifecycle mutation is self-service (auth::require_self, an agent token naming the account the request names), a closed disclosure route is closed to everyone, and e-stop's admin socket rests on its own 0700/0600 permissions rather than on anything presented over it. Proving control of the operator DID to this server is oauth's owner sign-in; until it exists, a surface that would need one is not built rather than gated on a stand-in.
• State what stays open to everyone. Decided and written down in auth::ROUTE_CREDENTIALS's own comments and the module doc's "Why every public route is public": three separate reasons, not one — protocol-required (com.atproto.sync.* and com.atproto.repo.*'s reads, so a relay indexes these agents), structurally required (/.well-known/did.json, /.well-known/atproto-did, createSession — a DID or a credential that needs a credential to reach is incoherent), and public-by-default-and-toggleable (Credential::Disclosure, see "Publish by default" above) for the bot.did.* surface that used to be public by accident. The write surface and the bot.did.* mutations are no longer part of this list — see above.
• Credential the account-admin mutations. deleteAgent, setAgentPinned and setAgentScrobbling are Credential::AgentSelf — see "The account-admin surface, and the mistake Credential::Public let happen" above. provisionAgent is relabelled Credential::Attested so its attestation gate is visible in the table rather than shared with a label that meant "no credential" everywhere else.
• Decide the account-admin reads, and build the toggle. listAgents, listAgentLedgers, getAgentLedger and stats are Credential::Disclosure — public by default, closeable per route by auth::Disclosure, and a closed route answering DisclosureDisabled — for every caller alike, since no credential reaches past the toggle — rather than a 404 or an empty list. See "Publish by default" above for why the default is public and why the toggle exists anyway.
• The failure shapes, and the headers that go with them. AuthenticationRequired, ExpiredToken, InvalidToken and the new SchemeDisabled are in crates/didbot-serve/src/error.rs and auth.rs, each carrying WWW-Authenticate: Bearer where a client would act on it. DPoP-Nonce is not emitted: nothing here issues DPoP tokens yet.
• A route that needs a principal and has none is a bug the tests can see. crates/didbot-serve/src/tests.rs and auth.rs's own suite cover the no-credential case for refreshSession, deleteSession, getSession and every com.atproto.repo.* write route plus uploadBlob; crates/didbot/tests/conformance/wire.rs drives the same case, plus the cross-account RepoMismatch case, through the real router and the vendored lexicon documents.
• Legacy sessions: com.atproto.server.{create,refresh,delete,get}Session, app passwords hashed with Argon2id, refresh-token rotation with family-wide revocation on reuse (didbot_pds::session).
• Agent tokens: didbot_pds::credential, minted at provisioning, durable in the write-ahead log, and required on every com.atproto.repo.* write route and uploadBlob; see "The write surface, and the credential that unlocked it" above.

Left open, on purpose: inter-service auth, per-principal rate limits, and the caller-facing app-password lexicon methods.