id: onboarding title: An operator establishes a server before the server can establish anyone else status: open crates: [didbot-attest, didbot-pds, didbot-serve, didbot-setup, didbot-reconcile] dependsOn: [ownership, deploy] exitCriterion: > An operator takes a freshly applied deployment — instance up, no accounts, nothing configured beyond Terraform's defaults — through generating and installing the real secrets, an operator attestation step, and the first-run ownership handshake, then points one agent host's harness at it and gets a working, provisioned account, using only documented steps and no fact this file invents. #

onboarding #

Every other epic in this directory describes a system already running: an account exists, a zone resolves, policy is being polled. Nothing describes the hour before any of that is true — Terraform has applied, an EC2 instance is up, and the operator has not yet done anything the server would recognise as them. dev-setup covers the symmetric gap on the other side, wiring one machine's harness to a stack; this is the half it does not cover, and the half that has to happen first.

The bootstrap paradox #

A provisioning request carries a host's claim. bot.did.provisionAgent mints only under a claim signed with the node key of a host the operator has vouched for — see handshake. The key is generated on the host and never leaves it, so there is no shared secret to distribute or get wrong.

So the paradox is not what it was. It was: the secret that lets an operator act on a fresh deployment must reach the host before the deployment can be acted on. There is no such secret now, and the question that replaces it is narrower — a fresh deployment has to reach a state its operator can claim, using only what the deployment already has.

That question is answered elsewhere and this epic should not re-answer it. The server mints its own identity through an administrative path that never travels the xrpc write path, so its did:json and signing key exist before it serves anything; the operator then claims it from their own machine with didbot-claim, and the server observes that claim through its own poll. See handshake and docs/server-lifecycle.md.

What onboarding still owes is the sequence, not the mechanism:

• Write the operator's first commands, in order, against a real deployment: what to run, on which machine, and what each one is waiting for. didbot-claim has the local half and didbot-claim --check has the pre-flight; nothing walks a first-time operator through them.
• Say how an operator tells whether the server has seen the claim yet. The poll is the only thing that moves the server to claimed, and its interval is the delay an operator experiences as "nothing happened".
• Say what a deployment does before it has any operator policy. policy puts a pre-flight between provisioning and claimed, so an instance is never online and unpolicied. The commands for that half belong here too.

What "first log in" means here #

There is no human user account on this server, so "log in" is not the right frame and the epic should stop implying one. What exists instead:

• --owner — a DID string the server writes into every registration record as who is answerable for that account. It is not verified at startup: any string parses.
• The bot.did.operator handshake — the operator writes a record into their own repository and this server reads it (crates/didbot-serve/src/ownership_poll.rs). Nothing is presented to the server and nothing is compared by it. There is no operator credential, and no HTTP surface is gated on one — see auth-types.
• Local access to the box, which is what the e-stop admin socket's 0700/0600 permissions amount to and the whole of that socket's authorization story.

Neither of the first two is the full handshake ownership asks for. Ownership's own checklist says the agent-side owner claim exists (written by the server at provisioning) and the human's vouch of the server is meant to come from the owner's own repository — but ownership's "three statements" item is still open, including "the server answers its controlling DID on an unauthenticated status endpoint," which is the piece that would let a stranger, or the operator themselves, confirm the server agrees who its owner is. Until that exists, nothing on first boot confirms --owner names a DID that has actually agreed to be named — the server just asserts it, on one process argument, forever.

• A first-run check that --owner resolves to something real before the server starts minting accounts against it — at minimum, that the DID document exists and is fetchable. --owner today is Zone::new'd alongside the zone but is never itself validated.
• The unauthenticated status endpoint ownership.md names, so an operator (or anyone) can ask a running server "who do you say owns you" and compare it against what they meant to configure. This is ownership's item to build; onboarding is where a first-run check would use it.
• Write down, plainly, that there is no bidirectional claim yet. Until the status endpoint above exists, "first log in" is --owner plus a bot.did.operator record this server reads one way, and that is a weaker claim than the rest of plan/ sometimes assumes. Say so somewhere a new operator reads before they conclude ownership is already checked because the flag is there.

Required operator attestation #

The owner's framing names this explicitly, and it is worth being precise about what it is not: attestation is about the node an agent runs on — proving a machine before it is trusted with provisioning. The operator is a different subject. Nothing in this codebase today asks the operator to prove anything to the server over HTTP at all: the handshake runs the other way, with the server reading a record the operator wrote in their own repository. That is a claim about a DID rather than possession of a string, which is the right direction — but this server never checks a signature over a challenge it chose, so it is a claim it reads, not one it verifies interactively.

What an operator attestation step would need to establish, before the server mints its first account:

• That the handshake actually completed — i.e. this server has read a bot.did.operator record naming it, rather than still waiting for one. This is the loud version of the bootstrap-paradox item above, scoped to "before minting begins" rather than "eventually."
• That the --owner DID is one the operator controls, which is a real proof — sign a nonce with the DID's own key, or an equivalent — not merely a string on the command line. Nothing here does this yet; it is the missing half of "first log in," restated as a checkable step rather than left implicit.
• Decide whether operator attestation is a one-time ceremony or a standing credential. A node's attestation is spent once, at provisioning, and the node's ongoing claim to be trusted rests on holding a node credential afterward (node). The operator has no equivalent today, and — since there is deliberately no operator credential at all — no "hold a narrower credential afterward" half to build one out of. oauth's owner sign-in is the candidate mechanism. Whether the operator needs a standing credential at all, or the read-only handshake plus host access is the whole story, is this epic's to decide, not to assume.

The first agent #

Once a server is up, the handshake has completed, and --owner is established, a person still has to get one agent host talking to it. didbot-setup does the machine half: it describes which services this machine runs and says whether they are answering. What it explicitly does not do, checked against its own source:

• It never sets DIDBOT_PDS_URL. A harness client falls back to http://localhost:3000 when it is unset, and didbot-setup never writes it — its whole flow is built and tested against didbot-pds's own defaults. Pointing a harness at a deployed server is presently "set an environment variable by hand, correctly, on your own," with no didbot-setup step that asks for a URL and writes it anywhere. There is no secret to set alongside it: provisioning takes the host's claim, which didbot-agentd signs.

• A session with no usable account provisions one on its first tool call, so once the variables above are set correctly by hand, that call is what actually creates the account — there is no separate "first login" moment to perform.

• A didbot-setup flow — or documented manual steps, if the flow is not worth building yet — for wiring a harness against a server that is not didbot-pds's own defaults: the URL, landing in the same place check already looks, and the host's become against that server.

• didbot-setup check should say which server a profile is configured for, so a harness silently pointed at a stale or wrong deployment is caught before the first session rather than after a refusal with no context.

Failure modes worth naming #

These are not hypothetical: each is a documented gap or an enforced-but-silent default above, restated as what an operator actually sees when it happens.

• A server that started but was never given a real secret. Cannot happen for the attestation secret against a non-.localhost zone — didbot-pds refuses to start. Can absolutely happen for the operator secret, which only warns, and the warning is the only signal until an e-stop needs releasing.

• DNS delegated but not propagated. What it looks like from the operator's seat now has an answer: didbot-claim --check <hostname> resolves the name through the operator's own stub resolver and reports dns FAILED with the resolver's reason, skipping the checks downstream of it rather than reporting three more failures for one cause. What is still open is the second half — how long to wait before it is a bug rather than propagation. Nothing names a number, and a check that has failed for an hour looks exactly like one that has failed for a minute.

• A certificate that has not issued yet. --tls acme is wired now — didbot-pds refuses at startup without --data, a real zone and --route53-zone-id (crates/didbot-serve/src/bin/didbot-pds.rs), and infra/pds/templates/user_data.sh.tftpl's ExecStart passes it. What is still unverified, per deploy's own Done entry, is the protocol exchange itself against a real ACME directory — nobody has run it from an environment with the network access to try. An operator's first boot is where that gets exercised for the first time, and the failure mode worth naming is: a startup that passes every local check above but still cannot complete a DNS-01 challenge against Let's Encrypt, for a reason none of those checks can catch in advance. didbot-claim --check's tls check is what now catches it — a real HTTPS request from the operator's machine, so a certificate that never issued, was never loaded, or covers the wrong name all fail the same way and say so. It does not make the exchange any more verified; it makes a failed one visible from the seat that matters instead of silent.

• Wire the zone reconciler's intent to the account registry. The machine is built and is didbot_reconcile::ZoneReconciler (below, and docs/zone-reconciliation.md), but nothing in didbot-serve constructs one yet: it takes its intent through a ZoneIntent trait, and the implementation that answers "every hostname this deployment published, and what each should point at" from the account store does not exist. Until it does, a deployment still has nobody whose job the zone is.

• Give the reconciler an authoritative read of a remote zone. Its other half, and the one that will look done when it is not. ProviderView reads through DnsProvider::target, which answers from local bookkeeping, so it is a fresh view of the zone only to the extent its refresh hook makes that bookkeeping match. Route53Dns::resync is the obvious hook and does not: it inserts what it finds, discards a collision with what is already cached, and removes nothing. Wired that way the reconciler reads the zone every five minutes and reports it in sync no matter what — blind to a record deleted at the AWS console and blind to one repointed there, which are the two drifts it exists to repair. Either resync becomes authoritative or the reconciler gets a ZoneView that is a real read; the choice belongs with whoever wires the intent above, because a reconciler that cannot see drift is worse than no reconciler — it is a green light over a broken zone.

• An operator who has lost access to the DID that operates a server. There is nothing to rotate — the server holds no credential — but the recovery question is real and unanswered: a server watching a bot.did.operator record in a repository its operator can no longer write has no path to being told about a new one, short of restarting it with a different --owner. Whether that restart is the answer, or something narrower is, is undecided.

Done #

• A zone that drifts after the server is running is somebody's job. didbot_reconcile::ZoneReconciler — the second didbot-fsm consumer, and deliberately not folded into the server lifecycle. Its states are about the zone (in-sync, drifted, reconciling, blocked) and it runs in every server state including claimed, forever, because withdrawing a hostname breaks agents that already exist whether or not an operator's claim currently stands.

  Unlike `didbot-claim`'s checks it **acts**: it reads the zone, compares
  it against what this deployment published, and republishes the
  difference. What "wrong" means is decided per name — a missing record
  is republished, one pointing elsewhere is replaced, a **wrong TTL is
  left alone** (structurally: `RecordTarget` carries none, and lowering a
  TTL before a migration is ordinary practice), `TXT` values belong to the
  ACME renewal path, and the `NS` delegation above the zone is the
  operator's.
  
  A record it did not publish is **never touched**, and not by a check
  somebody remembered to write: `Repair` has `Publish` and `Replace` and
  no third variant, `Drift::Unattributed` yields no repair at all, and a
  failed read is a `ViewError` rather than an empty zone. It never gates
  serving either — `ZonePolicy` carries no capability that could, which a
  test asserts by destructuring it over every state.
  
  Bounded at five minutes with backoff doubling to an hour, two confirming
  reads before anything is written, twenty-five writes per tick, and five
  attempts per name before it is quarantined and reported. That last
  budget is the one aimed at people: somebody changing a record by hand
  gets argued with five times rather than forever. Between the interval
  and the confirmation count, drift is repaired five to ten minutes after
  it happens — this epic's answer to the "how long is propagation"
  question the items above kept deferring.
  
  It is also the caller that brought `didbot_fsm::Gates` back. A repair
  awaiting its confirming read is `Pending`, not `Failed`, and collapsing
  the two would make a healthy first tick look like an outage — which is
  exactly the signal the backoff is computed from.
  

• A server lifecycle, so "not finished being born" is a state rather than a latch. didbot_pds::ServerState — booting, provisioning, unclaimed, claimed — with a capability policy per state and one enforcement point per capability; docs/server-lifecycle.md carries the diagram and the table, generated from the types and checked against them by a test. The machinery is didbot-fsm, a reusable core (states with a consumer-shaped policy, transitions taken atomically under one lock, one-way capabilities claimed under a permit, persistence as a hook); this lifecycle is its first consumer.

  The axis is **reads against writes**. `unclaimed` — where a deployment
  spends most of its early life, and where a server whose claim lapsed
  returns to — reads everything `claimed` does and writes nothing: no
  agent accounts, no records, no blobs, no outward announcements.
  Withdrawing reads would protect nothing and would retroactively break
  every signature made under a `did:web` document this server has already
  served.
  
  Three things it makes structurally true. A second self-bootstrap
  keypair cannot be minted, because `ServerLifecycle::begin_bootstrap` is
  the only source of the `BootstrapPermit` a mint takes by value and it
  shuts the door in the same critical section. Never-claimed and lapsed
  are one state with one recovery — run `didbot-claim` again — so the
  bootstrap flow is exercised on every re-claim rather than once per
  server lifetime. And the emergency stop cannot be thrown before an
  identity exists: `ServerPolicy::may_halt` is false in `booting` and
  `provisioning`, so the boot-time self-pause that used to stand in for a
  lifecycle state is gone.
  

• Claimability checked from the operator's machine, not the server's. didbot_claim::preflight, exposed as didbot-claim --check <hostname>: DNS resolving, TLS terminating, the did:web document serving and naming this host, and describeServer agreeing with it. Read-only — no OAuth, no browser, no record — so it is safe to run on a loop while waiting for DNS or an ACME order, and it exits non-zero so a script can wait on it.

  They live there because a server checking its own DNS confirms only
  what it wrote, a server checking its own TLS is often checking a
  loopback path, and the failure worth catching — a *different*
  deployment answering the same name — is invisible from inside the one
  that is wrong. The claim flow runs the same function first, so a check
  that passes and a claim that then fails on it is a real race rather
  than two implementations disagreeing.
  

• bot.did.pollOperatorClaim, a nudge with no authority. claimed is entered only by the server observing a standing bot.did.operator record through its own poll. This route lets a caller ask it to look sooner: no body, no credential, no operator named, and its whole effect is to wake a task that was going to run anyway.

  Bounded on the server's **outbound** rate rather than on inbound
  requests. `MIN_POLL_INTERVAL` is a floor between two polls and every
  nudge inside one window coalesces into the same single poll, so an
  unbounded burst costs the operator's PDS one extra request — which the
  timer was going to spend anyway. `a_burst_of_nudges_produces_at_most_one_extra_poll`
  fires two hundred and asserts exactly one extra outbound read.
  

• An onboarding surface. GET /onboarding shows which state the server is in, whether it holds its own identity, whether a claim currently stands, which surfaces answer, and what to run next on the operator's own machine. It is a status and guidance page: it accepts no credential, offers nowhere to type one, and exposes no route that changes anything, because nothing exists by which a browser could prove control of the operator DID. Its copy is placeholders; its facts are not.