id: oauth title: A third-party app signs in as an agent, with nobody at the consent screen status: open crates: [didbot-serve, didbot-pds, didbot-agentd] dependsOn: [pds-writes] exitCriterion: > An atproto client that has never heard of this project completes an OAuth flow against an agent and writes a record with the token. #

oauth #

The hard part is who consents. OAuth's authorize step assumes a human at a browser. An agent has none, and is provisioned and collected inside one session. The answer is that the pushed authorization request itself is the question: at PAR this server resolves the account, works out what it would grant, and writes a decision record the named account reads and answers.

The decision is made once, at PAR, from two inputs. policy's tree supplies the denials, asked about a didbot_policy::Subject::Grant — including the client refusal app-allowlist is about, which is a denyClient policy in that tree and not a check of its own. scope-policy's ceiling supplies the intersection. Where both are authored from is policy-store's.

The record is never judged again. GET /oauth/authorize and bot.did.approveAuthorization read it. Judging again at approve could only contradict a record that already told the agent allow. Issuing a token is a separate request, and POST /oauth/token judges the client again, within the account's chain, for a code exchange and a refresh alike. A policy loaded between the push and the answer leaves the record alone and refuses the token. The scope ceiling is asked again the same way, at the token endpoint and at every write: a login keeps what the record granted, and a tightened ceiling narrows it further (scope-policy).

One rule the tree cannot carry here: didbot_policy::Subject::Grant names a client_id and the requested scopes, and no account, so a per-account rule is not expressible as a policy. Adding that field is the precondition for retiring the ceiling; until then the ceiling is the deployment's own statement and applies to every agent alike.

• Test against a client that is not ours. Whether atproto client SDKs implement the did:web method at all is unknown, and it is the question the rest of this epic rests on: most atproto software has only ever resolved did:plc, and a handle-to-server path may assume a directory lookup. An agent nobody can sign into is a capability on paper. Transport is not the issue — did:web is defined over HTTPS and a resolver that only speaks HTTPS is conformant. A client using the profile's "Localhost Client Development" client_id (http://localhost, no port, its metadata carried in redirect_uri/scope query parameters) is accepted without a fetch — oauth::client_metadata::resolve_client recognises the form and builds the document from the query alone.

How an ordinary client signs in as an agent #

A pushed authorization request naming an agent becomes a decision record at the server, and the one-time consent reference minted with it is the approval token. The daemon relays the record and carries the answer back; nothing here needs a browser, and the agent is never handed a URL.

Two tool calls, and no browser anywhere:

1. The agent starts an ordinary client in the background. It binds its loopback listener, pushes an authorization request naming its own DID as the account, and prints the authorize URL instead of opening it.
2. The pushed request becomes a decision record at the server. The daemon is already long-polling for records about the accounts it issued, so it collects that one and puts it in front of the agent on its next tool call.
3. The agent runs didbot-oauth approve <token> or didbot-oauth decline <token>. The daemon redeems the token as the account the record names, and fetches the redirect the server built — which is what delivers the code.
4. The client exchanges it and holds tokens bound to its own key.

An agent that does hold a URL for a request neither path delivered can name it directly — didbot-oauth show <url>, and approve --url — which is the same authenticated getAuthorization fetch, asked for rather than noticed.

On the ordinary path the agent never handles a URL, and on neither path does it name its account. didbot-oauth is the only agent-facing command, and there is no --as <did> in it: the daemon reads the account off the record, whether the agent named that record by token or by URL. The didbot confirm command that used to take one, and the confirm ask on the socket it sent, are both gone.

• Two things a client must support, and no more. Print the URL rather than opening it, and accept an account identifier to resolve. Neither requires it to have heard of this project.
• Replace the refuse-everything default with policy. policy decides which client is denied; absent a denial the agent approves what it asked for.

Done #

• One seam, at PAR, in the record. Two things judge a sign-in and both are read inside oauth::par::push_authorization_request: the PolicyGate over a Subject::Grant, and ScopePolicy::ceiling. Every route after it reads the decision record and evaluates nothing, so no refusal can contradict a record that already said allow. oauth_agent_flow.rs's a_policy_loaded_after_par_leaves_the_record_and_refuses_the_token loads a denial between the push and the answer: the record's verdict is unchanged, GET /oauth/authorize still renders it, the approval still issues a code, the code exchanges for no token, and the next push is denied.

• A token is judged when it is issued. POST /oauth/token asks the same gate about a Subject::Token before a code exchange or a refresh mints anything (oauth::token::GateAdmission). A refusal is invalid_grant and ends nothing: the family keeps its refresh token, unrotated, until it expires or the policy lifts. A replayed refresh token still ends its family first. Tests: oauth::token's a_refused_refresh_keeps_its_family and a_replay_ends_its_family_even_under_a_refusal, and crates/didbot-serve/tests/denied_app.rs.

• The agent completes the flow itself. The profile has no device grant and no client credentials grant: every flow assumes a browser. The agent needs none: POST /oauth/par mints the decision, and the account named in it reads and answers it over bot.did.*. A headless browser is still served — GET /oauth/authorize renders the same record — and is no longer on the path.

  `login_hint` is resolved at PAR (`crate::routes::resolve_identifier`),
  and no status or body this endpoint answers with may depend on
  whether the hint names an account — timing is a smoke-tested best
  effort, not a claim this makes (see the next item's own note on
  that): a hint naming nobody gets the identical `201`
  a real account's push gets, and a real account whose own pending
  bound is already full also gets that `201` rather than the `403` an
  account-keyed bound would otherwise answer with — see the next item
  for why *that* is load-bearing, not incidental. Proved end to end,
  with no browser and no network, by `crates/didbot-serve/tests/
  oauth_agent_flow.rs`, which drives the real router through
  `tower::ServiceExt::oneshot`.
  

• Confirm after the page, through an identity-aware call. bot.did.approveAuthorization takes the decision's one-time token under Credential::AgentSelf, so the acting account is the one the presented agent token authenticates as and never a value in the body. Two checks: the reference is live and unused, and the account named in the request is the account approving — the second enforced by the credential. There is no third. A record whose verdict is deny mints no reference, so whether policy allows this is answered in the record before anything reaches here. It is the only way an authorization is approved: there is no unauthenticated route that takes an acting DID as a field in a body.

  Each check has its own unit test in `oauth::consent`, and
  `oauth_agent_flow.rs` drives both to a refusal over the real router —
  replay and an approval by the wrong account — confirming no code is
  issued on either.
  

• The account is checked server-side, not by the daemon. There is nowhere in bot.did.approveAuthorization's request to name an account: the decision it spends is looked up by its token and answered as unknown unless it is addressed to the account the credential authenticates as. A daemon relaying a token it should not hold learns nothing from the refusal.

  The same server-side-only checking holds one endpoint earlier, at
  `POST /oauth/par`, which is unauthenticated rather than under-credentialed:
  whether an account exists is a fact this deployment checks for itself,
  never one an unauthenticated caller may read back. Two things had to be
  true for that to hold, and neither did at first.
  
  The first is the status itself. On a deployment with nothing denied —
  every deployment this project ships, until an operator loads a policy —
  an unresolvable `login_hint` used to answer `400 invalid_request`
  naming the account as the reason, while every account that *does*
  exist answers `201`, whatever the ceiling and the gate go on to decide
  for it (a grant, a narrowing, or a `deny` verdict on a decision record
  that still mints no token — `plan/app-allowlist.md`'s "a denied client
  is refused at the push itself" is the one *exception* to this, since
  `didbot_policy::Subject::Grant` names no account and so answers the
  same way for every `login_hint` including a nonexistent one, which is
  what keeps it from reopening the same hole). `201` vs `400` was the
  whole oracle: push one request per candidate handle or DID and read
  account existence back from the status, reachable without ever calling
  `bot.did.listAgents` and so unaffected by narrowing that route's
  `Credential::Disclosure`. The fix is `oauth::par::
  push_for_unresolved_hint`: a `login_hint` naming nobody now gets the
  identical `201`, `request_uri` and `expires_in` a real account's push
  gets, and nothing is stored under it that `GET /oauth/authorize` or
  `bot.did.getAuthorization` could ever redeem — the former because the
  `request_uri` never reaches `ParStore`, so it answers exactly as an
  expired or already-used real one does (`oauth::authorize`'s
  `an_expired_pushed_request_and_one_that_never_existed_answer_alike`
  checks the two are the same answer, not just similarly worded); the
  latter because a decision record is addressed to an account and no
  credential could ever authenticate as a string that resolved to none.
  
  The second is the bound, and a first attempt at it reopened the first
  fix by a different door. `pending_per_account` is an oracle of its
  own if a real account's `(per_account + 1)`th concurrent push answers
  `403` and a `login_hint` naming nobody never could: an attacker only
  has to push one candidate enough times to watch for the `403` a
  loaded, existing account would eventually answer with. A version of
  `push_for_unresolved_hint` closed *that* by putting a `DecisionRecord`
  through `DecisionStore::put` addressed to the raw `login_hint` string
  — but `resolve_identifier` folds a handle, its DID, and one written
  with a redundant `:port`/`%3Aport` into the single DID that names a
  real account, so a real account's bucket is one bucket however it is
  spelled, while every distinct spelling of a nonexistent one got its
  own. Push eight variously-spelled requests naming one candidate and a
  ninth: a real account's ninth bucket-fills and a made-up one's never
  does, whatever either bucket's *refusal* is worded — the aliasing
  itself is the oracle. It was also a new denial-of-service surface
  past the account-existence one: nothing bounds how many distinct
  invented strings exist, so a handful of addresses at the per-address
  rate limit could keep `pending_total` permanently full with entries
  no real account ever asked for, where before a stranger could not
  occupy a slot without naming one.
  
  The fix an account-keyed bound cannot have is not to bound unresolved
  hints by account at all: `push_for_unresolved_hint` stores nothing —
  no `ParStore` entry, no `DecisionRecord` — reusing only
  `ParStore::mint` for the `request_uri` it hands back.
  And a real account past its own bound is answered the same way,
  *not* `403`: the push lands, and the account's *oldest* undecided
  record makes way for it. `login_hint` names whoever the caller likes,
  so a bound that dropped the newest push let a stranger keep an account
  from signing in to anything by filling its slots every two minutes;
  displacing the oldest keeps the bound and keeps an account's freshest
  attempt — the one an agent is waiting on — always answerable.
  Per-account fairness still holds exactly as it did before — an account
  loses only its own excess, and no other account's bound is touched —
  logged at `info`, sampled one in a hundred against a process-wide
  counter rather than every occurrence, since the account is already
  known to be at its bound and logging every push against it would let
  the log line itself be flooded from as many addresses as a caller
  likes. An operator still sees a flood happening even though the caller
  cannot tell it from an ordinary push. The one `403` this endpoint
  answers with is `DecisionRefused::TooMany` — the *server's* bound, a
  fact about load that is true identically for every caller, real or
  not, checked for an unresolved hint through `DecisionStore::check_room`
  without writing anything.
  
  Undoing a record means undoing *both* stores it touched, not just
  `ParStore`: `consent::begin` mints a `ConsentReference` before
  `DecisionStore::put` is even asked, since a reference has to name the
  record it approves, and a version of this fix that only took the
  `request_uri` back out of `ParStore` left that reference's
  `PendingConsent` behind in `MemoryConsentStore` — which had no way to
  remove an entry short of it being presented, and nothing ever
  presents one for a record that no longer exists. On the displacement
  path that is a live entry a stranger could leak, unauthenticated, once
  per push, against any real account it names enough to reach its bound
  — the exact kind of unbounded growth this whole fix exists to close,
  just moved into a different store.
  `ConsentStore::discard` removes the reference on both undo branches
  now, and `MemoryConsentStore::mint` sweeps expired, unpresented
  entries the same way `MemoryDecisionStore::put` already sweeps its
  own map, since before this it was the one store in the module an
  abandoned entry outlived forever.
  
  The honest signal an operator or an admitted agent needs is
  unaffected: `bot.did.listAgents` still answers when disclosure is
  public, and a request naming a real account under its own bound is
  still recorded exactly as before, narrowing included, whatever the
  gate answers. `oauth_agent_flow.rs`'s
  `eight_spellings_of_a_real_account_and_a_ninth_unresolvable_hint_all_answer_201`,
  `the_nth_plus_one_push_for_a_real_account_lands_and_displaces_the_oldest`,
  `a_stranger_filling_an_accounts_pending_bound_cannot_lock_it_out`,
  `many_invented_hints_never_fill_the_servers_own_bound` and
  `a_full_store_refuses_a_real_account_and_an_unresolvable_hint_with_one_body`
  hold these over the real router; `oauth::par`'s own
  `a_displacing_push_leaves_the_consent_store_at_its_previous_size` and
  `oauth::consent`'s
  `an_unpresented_reference_is_swept_once_it_has_expired` hold the two
  halves of the consent-store fix;
  `an_unresolvable_hint_costs_about_the_same_as_a_real_push` is a smoke
  test on the clock, not a guard, and says in its own doc that the two
  paths do not do the same work — only that the gap is nowhere near
  large enough to time.
  

• A pushed request is a decision record. crates/didbot-serve/src/oauth/decision.rs. POST /oauth/par resolves login_hint through the registry, narrows the requested scope to ScopePolicy::ceiling, runs a didbot_policy::Subject::Grant past the PolicyGate, and stores a DecisionRecord: the client's origin and content key, whether this account has seen that key before, what was asked, the verdict (allow, narrow naming what it cut and the rule that cut it, or deny naming the reason and the rule), and the one-time token that approves it. An approval covers the whole request, so a narrow cut is withheld for now, not refused: didbot-oauth pending ends a narrowed line with approves=asked ceiling-checked=each-use, and the consent page and the approve answer list the scopes requested, then the scopes current policies would allow. A deny mints no token. A request naming one of scope-policy's hard-blocked capabilities is denied before the ceiling is consulted at all. Every narrowing and every denial writes a payload-free row to the evaluation log. Records live as long as their pushed request, are swept when it expires, and are bounded per account and in total, because PAR is unauthenticated — [oauth] pending_per_account and pending_total, beside scope_ceiling, which is where an operator writes the ceiling down. Four routes, all Credential::AgentSelf, all naming no account:

  - `GET bot.did.listPendingAuthorizations?cursor&wait` long-polls this
    account's live decisions, holding the request open up to 30 seconds
    or until this process is asked to stop; answers
    `{cursor, pending: [record]}`. The cursor names the store's epoch as
    well as a place in it, so one held across a restart lists from the
    beginning rather than stranding its holder on a sequence the new
    store will not reach.
  - `GET bot.did.getAuthorization?requestUri` answers one record.
  - `POST bot.did.approveAuthorization {token}` issues the code for the
    whole request and answers `{requestUri, granted, redirect}`, where
    `granted` is what the ceiling grants of it now.
  - `POST bot.did.declineAuthorization {token, reason?}` answers
    `{requestUri}` and spends the token, so a "no" is recorded rather
    than left to look like an expiry.
  
  The client's own `client_name`, `client_uri` and `logo_uri` are kept
  with the record and never serialized — `app-allowlist`'s "record the
  client's own copy; do not show it". Driven end to end over the real
  router in `crates/didbot-serve/tests/oauth_agent_flow.rs`.
  

• The daemon is the user-agent, and that is a request the model influenced. Every fetch it makes on a request the model touched is bounded: the deprecated page path accepts only the authorize endpoint this deployment publishes in its own discovery document, the approval path fetches only a redirect the server built, and both deliver only to loopback (didbot_agentd::loopback), with redirects turned off on every client so there are no chains. The server cannot make that last fetch itself — the client is listening on the agent host and, by the architecture rule, the server is not on it.

• The daemon relays, outbound only. One long poll per account it issued (didbot_agentd::poll, listPendingAuthorizations?wait=25), backing off from a second to half a minute when the server is not answering, started when a context is provisioned and stopped when the harness says that context has ended. Nothing on the agent host listens for the server. Decisions ride the answer to an exchange the hook started, so an agent learns of one at its next tool call; that latency is accepted rather than hidden. seen_request_uris on a report is the fast path for a client that printed its URL in the tool call being reported, fetched with getAuthorization when no poll has delivered it yet.

• The granular atproto scope grammar. crates/didbot-serve/src/oauth/scope.rs: Scope::parse/ScopeSet::parse read the wire grammar directly, not a parallel one — repo:, rpc:, blob:, identity:, account:, include:, atproto, and the three transition:* legacy scopes. Scope::contains and ScopeSet::intersect are the two operations scope-policy's ceiling check needs, and both are covered against the asymmetric cases a ceiling has to get right: a narrower action set against a broader one, rpc:'s aud narrowing, an empty ceiling, an empty request, a scope naming a collection outside the ceiling, and a ceiling whose atoms admit a ceiling-order-independent grant (the one intersect bug review already found here). An unrecognised kind: fails the whole scope string at parse time — see the module doc's "Unknown prefixes" section — so a client sending a prefix this server doesn't implement gets no grant at all, rather than a grant scoped to whatever this server understood. crates/didbot-claim/src/scope.rs is the first real consumer, building didbot-claim's own request scope out of the grammar instead of a hand-written literal.

• DPoP, verifier side. crates/didbot-serve/src/oauth/dpop.rs: DpopVerifier::verify checks a proof's typ, alg, embedded jwk and signature, htm/htu against the request, iat against a named clock-skew window, and jti against a replay cache bounded by that same window; jwk_thumbprint gives RFC 7638 thumbprints standalone, for an access token's cnf.jkt. Nonce issuance and the use_dpop_nonce retry path are in the same file. The authorization server that calls it is still open, above.

• The authorization server. Pushed authorization requests, authorize, token, refresh rotation, client metadata fetching and validation. crates/didbot-serve/src/oauth/{par,authorize,token,client_metadata}.rs. Both grants are driven through the real router in crates/didbot-serve/tests/oauth_agent_flow.rs, which is where the rotation's wire behaviour lives: a client that spends a refresh token twice loses the family, and one that presents the right token under the wrong key is refused without losing it. The two things that judge a request are read at push_authorization_request and nowhere else: plan/policy.md's gate over a Subject::Grant, and plan/scope-policy.md's ceiling. With no denial loaded each permits, as policy's empty set does; see oauth::authorize::GrantAnyScope.

• DPoP, wired end to end. OAuthState::default builds the real verifier (oauth::dpop::DpopVerifier, via its impl oauth::dpop_seam::DpopVerifier), /oauth/token binds a proof's htu to this deployment's own zone service document rather than a header (oauth::discovery::request_htu), and OAuthTokenStore::validate_access requires the caller to supply a proven thumbprint, not a bare token string. com.atproto.repo.*'s write routes accept a DPoP-bound access token now, through auth::require_agent_token_or_dpop. See plan/adversarial.md's DPoP-binding tests for the seam this closed.

• Pick an access-token lifetime and write it down. The profile says under 30 minutes, under 15 without individual revocation, 5 recommended. The number decides how fast pausing issuance drains a swarm.

  **5 minutes** (`oauth::token::ACCESS_TTL`). This deployment has no
  revocation endpoint (see the next item) and no per-token introspection,
  so by the profile's own rule it does not qualify for the 30- or
  15-minute allowance — those are for a server that can revoke an
  individual token out from under a client without waiting for it to
  expire. This one can't: a live access token is good until it expires,
  full stop, and the only lever this deployment has over an agent that
  should stop making requests is the e-stop (`EstopRefusal::Token`),
  which blocks *new* issuance and does nothing to a token already
  outstanding. That makes the lifetime the actual bound on how long a
  paused or de-admitted agent keeps working — not a compliance number,
  the number. 5 minutes means an operator's e-stop, or an
  `app-allowlist` de-admission, is fully in effect within 5 minutes of
  being thrown, refresh rotation notwithstanding (a family already
  revoked, or a client already refused at `token`, gets no new pair to
  wait out). The refresh token (`oauth::token::REFRESH_TTL`, 14 days) is
  long precisely because it is *not* the safety boundary — the access
  token is — and rotates on every use with reuse detection, the same
  design `didbot_pds::session::SessionAuth` already carries for legacy
  sessions.
  

• No revocation endpoint exists in the profile, and none is needed: withdrawal is refusal at the write path, because this server is also the store. See write-policy. Confirmed by the access-token lifetime decision above, which treats the absence of one as a fact the lifetime has to account for rather than as an omission to fix.

• Rate-limit the authorize path, which does work for unauthenticated callers. A fixed-window limiter keyed on the caller's address (crate::rate_limit, shared with createSession's limiters — one module, not a second copy under oauth), the same self-contained- primitive approach didbot_pds::session uses rather than a new dependency for one call site. Keyed on the real TCP peer address by default (axum's ConnectInfo, wired at serve_router/serve_tls), not X-Forwarded-For/X-Real-IP — this deployment terminates TLS itself with no reverse proxy in front of it (didbot-tls, reached directly on 443), so trusting those headers unconditionally would let a caller mint a fresh budget on every request just by forging a new one. A deployment may opt into reading them instead via AuthState::trust_forwarded_headers (off by default, wired today as didbot-pds --trust-forwarded-headers), once a real reverse proxy sets them and strips any client-supplied copy. See crate::rate_limit's own doc.

• Server metadata, and the DID document pointing at it, or discovery fails before any of the above runs. GET /.well-known/oauth-authorization-server (oauth::discovery) derives its issuer from the same service document GET /.well-known/did.json already serves for the zone host, rather than recomputing a hostname — so the two can never disagree, and nothing here hardcodes pds.did.bot or any other name.