Admin and Operator Operations

Tempest has two operator surfaces:

• account tools under /account/*, authenticated with a normal account bearer token
• admin tools under /admin/* and /xrpc/_admin/status, authenticated with the configured admin bearer token

Normal account tokens must not authenticate admin routes. Admin tokens are stored as hashes through TEMPEST_ADMIN_TOKEN_HASH and verified by Tempest.AdminAuth.

Account operator UI

The account UI is for inspecting the signed-in account while developing or operating a single-user PDS. It uses the same XRPC bearer token clients use.

Routes:

• /account: identity and repository summary
• /account/repo: collections, recent records, latest commit, and CAR link
• /account/blobs: temp/public blob state, download links, and header summary
• /account/access: sessions, OAuth grants, app passwords, delegated access
• /account/security: email, password, MFA, backup codes, trusted devices, events
• /account/migration: activation and migration-readiness status
• /account/sequencer: recent sequencer events with DID/type filters
• /account/firehose: recent decoded subscribeRepos frames and WebSocket URL

The UI is intentionally read-mostly except for the protocol endpoints it links to. Secrets such as app-password values, refresh tokens, OAuth token hashes, backup code hashes, and admin tokens are never displayed.

Admin UI

Admin routes require Authorization: Bearer $ADMIN_TOKEN.

Routes:

• /admin: service, account, sequencer, storage, and relay crawl status
• /admin/invites: invite-code profile status for this deployment
• /admin/repo: repo verify/export/import actions
• /admin/backups: backup create and restore dry-run
• /admin/storage: local database directories, blob store, and backup store
• /admin/compatibility: endpoint compatibility matrix

The JSON status endpoint remains:

GET /xrpc/_admin/status

It reports database files, sequencer position, blob-store status, admin auth configuration, and per-account repo/blob counts.

Mix tasks

Development and release operations are exposed first as Mix tasks:

mix pds.repo.verify --did DID
mix pds.repo.export --did DID --output /path/to/repo.car
mix pds.repo.import --did DID --input /path/to/repo.car
mix pds.sequencer.status
mix pds.blob.gc
mix pds.backup.create [--output /path/to/backup-dir] [--upload-s3]
mix pds.backup.restore --input /path/to/backup-dir --target /path/to/data

The UI calls the same context helpers used by these tasks where possible, keeping controllers thin and reducing behavior drift.

Backups

Tempest.Admin.Backup.create/1 checkpoints SQLite WAL files, copies durable data, writes a manifest, and can upload a backup archive through the S3-compatible backup adapter.

Restore refuses to overwrite a live data directory unless the caller opts into a forced restore. The admin UI exposes a dry run only: it checks manifest presence and whether the target contains live database files, then reports what would happen without copying data.

Verification

mix test test/tempest_web/controllers/admin_controller_test.exs \
  test/tempest_web/controllers/operator_account_controller_test.exs

hurl --test --jobs 1 \
  --variable base_url=http://localhost:4000 \
  --variable suffix="$(date +%s)" \
  test/smoke/operator-account-ux.hurl

The ConnCase tests cover account/admin auth boundaries and route rendering. The smoke test covers account UI access through a running server.