refactor(relay): NIP-98 admin auth with Operator/Moderator roles and NIP-11 discovery

[wpfleger96]

Adds authenticated, role-based moderation to the relay admin API. On main the admin API is read-only and gated only by Host/Origin matching; this branch adds NIP-98 authentication, a two-tier Operator/Moderator principal model, mutation and staffing endpoints, and NIP-11 auto-discovery so clients never type the admin URL by hand.

Authentication (BUZZ_ADMIN_AUTH)

BUZZ_ADMIN_AUTH accepts nip98 or disabled. Leaving it unset defaults to nip98 (fail-secure). Configuration fails closed: any other value aborts startup, while a lingering BUZZ_ADMIN_TOKEN is ignored with a startup warning — token (bearer) authentication is not supported. Host/Origin matching is retained in every mode as defense-in-depth.

• nip98 (default) — per-request signed NIP-98 (kind 27235) events, resolved to an Operator or Moderator principal with per-person attribution and individual revocability. Read-write per resolved principal.
• disabled — no credential; relies entirely on network-layer controls (reverse proxy, VPN, firewall) and logs a WARN on every boot. Always read-only: authorize() resolves no principal, so mutation and staffing routes always 403.

Roles

Buzz has two independent authority axes after this change. Relay-level roles (new here) are deployment-global: they act across every community on the relay, through the admin API. Community-level roles (pre-existing, unchanged by this PR) are tenant-scoped: they act inside one community, through signed Nostr moderation commands.

Relay level (new)

Role	Description
Operator	Full control of the deployment's moderation surface: read all reports, feedback, and attachments across every community; resolve reports with enforcement (delete/kick/ban/timeout) or decisions (dismiss/escalate); reopen and cancel; update feedback status; and manage the Operator/Moderator roster via the staffing endpoints.
Moderator	Day-to-day triage: everything an Operator can do except staffing — cannot view or change the roster.

How a pubkey acquires a relay role (resolution order; config always outranks DB):

1. Listed in RELAY_OPERATOR_PUBKEYS → Operator (source config)
2. Equals RELAY_OWNER_PUBKEY while RELAY_OPERATOR_PUBKEYS is empty → Operator (source owner_fallback, a break-glass grant for self-hosters that deactivates once any operator is configured)
3. Row in the relay_operators table → Operator or Moderator (source db, managed via the staffing endpoints)
4. No match → 403

Community level (pre-existing, unchanged)

Role	Description
Owner (community)	Full authority within their community: every moderation action (delete, kick, ban/unban, timeout/untimeout, resolve reports, view queue) plus member, role, and invite management. No guard rails.
Admin (community)	Same community-wide moderation capabilities as owner, except an admin cannot ban or time out the owner or a fellow admin — only the owner may action an admin. Manages members and invites; only the owner grants the admin role.
Member (community)	Standard participant; no moderation capability.
Owner / Admin (channel)	Channel-local authority only: delete messages and kick users within their own channel.
Member / Guest / Bot (channel)	No moderation authority.

There is no community-level Moderator tier in v1; relay-level Moderator is the only role by that name.

Escalation scoping

The operator report queue is an escalation backstop, not the community's day-to-day triage surface (per VISION_MODERATION, the severe class is the platform's to review rather than the community's). Two rules enforce that:

• Escalated-by-default listing. GET /reports with no status parameter returns only escalated reports. An explicit status=<open|resolved|dismissed|escalated> filter is always honored as given, and full visibility across every status stays available for platform-safety and legal review via scope=all (which lists reports regardless of status). scope accepts only all and is ignored when an explicit status is present.
• Auto-escalated illegal reports. Member reports whose category is illegal are ingested with status=escalated rather than open, so the severe class reaches the operator backstop without waiting for a community admin to forward it. Every other category still lands open. Auto-escalation only sets the queue status — it records no moderator decision and stamps no resolver, so an auto-escalated report is indistinguishable downstream from an admin-escalated one: the reopen route returns it to open on the same terms, keyed only on status, never on how the report became escalated.

Principal resolution and NIP-98 admission

resolve_admin_principal() returns AdminPrincipal { pubkey, role, source } per the resolution order above; None never falls through as a role. Admission is ordered so the replay guard is a privilege, not a public surface: signature/URL/method/payload-hash verification first, roster check second, and only then is the deployment-scoped replay id atomically consumed — a validly-signing but unrostered key never allocates a replay slot. Redis failure fails closed.

Report resolution, recovery, and enforcement provenance

POST /reports/{id}/resolve is a crash-safe enforcement state machine: decision-only outcomes (dismiss/escalate) are a single CAS-plus-audit transaction; enforcement (delete/kick/ban/timeout) claims the report (open→processing), runs the durable mutation, then finalizes — a re-drive resumes at the step marker and converges to exactly-one enforcement, fenced by a lease and an outbox claim token.

Person-directed enforcement on an event-kind report derives its target from the stored event's author (server-owned truth, never the reporter's p tag) via a single derive_enforcement_target shared by the HTTP driver and the recovery worker. If the reported event was purged before its author could be read, person-directed actions are rejected pre-claim and the report stays open; delete needs only the event id and is exempt.

GET /reports/{id} and the resolve response carry an activeAction field surfacing the enforcement that actually executed — a report dismissed after a reopen still reports the ban that ran. POST /reports/{id}/reopen returns a terminal report to open (idempotent on requestId). POST /reports/{id}/cancel is the sole recovery path for a pre-mutation failed action, attributed via relay_admin_actions.cancelled_by.

Feedback

GET /feedback and /feedback/{id} survive a tenant purge: provenance columns are severed to NULL rather than cascade-deleted, and the attachment path fails closed to 404 on a severed row. PATCH /feedback/{id} updates lifecycle status (new/reviewed/archived).

Staffing and probe

GET/PUT/DELETE /operators/{pubkey} are Operator-only; mutating a config-backed pubkey returns 409 Conflict. GET /operators returns the union of config and DB principals with per-entry source. GET /probe reports auth mode, role, source, canAct, and canStaff for the desktop console.

NIP-11 auto-discovery

The NIP-11 relay-information document gains an optional admin_api field carrying the canonical admin origin (scheme://host[:port], no path), present iff BUZZ_ADMIN_HOST is set and omitted otherwise. The scheme follows the same loopback rule as NIP-98 u-tag verification via a shared scheme_for_host helper, so the advertised origin and the origin the relay verifies against can never diverge.

Operator API origin decoupling

RELAY_OPERATOR_API_ORIGIN is no longer required at boot when RELAY_OPERATOR_PUBKEYS is set — it is used only by the community-provisioning endpoints, which fail closed at request time (with a boot-time WARN) until it is set. The admin console needs no origin.

Admin-web adaptation

The standalone admin-web dashboard signs each request as a NIP-98 event via a NIP-07 browser extension, discovers the auth mode with a single unauthenticated probe (200 → disabled, anything else → nip98, fail-secure), and carries no token entry surface. Playwright coverage exercises the NIP-98 and CSP paths.

Security hardening

Three findings from security review are folded in:

• Append-only roster audit. PUT/DELETE /operators/{pubkey} mutate the deployment-wide root of trust, but the upsert overwrites role/added_by in place and the delete removes the only row — so a grant→revoke sequence left no trace of who was ever granted or by whom. Each mutation now writes an relay_operator_audit row (actor, target, grant/revoke, pre-image prev_role, new_role, timestamp) inside the same transaction as the mutation. A per-target transaction-scoped advisory lock serializes concurrent mutations of the same pubkey before the pre-image read, so the recorded prev_role is always the true predecessor even under a concurrent-grant race. Chronology is keyed on a BIGINT GENERATED ALWAYS AS IDENTITY seq column, not the wall clock: the serializing lock guarantees insertion order and seq captures it, so ordered reads (ORDER BY seq) follow the true privilege chain even across a backward NTP step that a clock_timestamp() ordering would invert. created_at (clock_timestamp()) is retained as informational occurrence time only. Append-only by construction — no UPDATE/DELETE path and no API surface. A no-op delete writes nothing.
• expirationSecs overflow. The timeout path built Utc::now() + Duration::seconds(secs as i64) from an attacker-controlled u64: i64::MAX panicked the handler, and a wrapped-negative magnitude minted a past expiry that still passed validation. compute_timeout_until now rejects zero, rejects magnitudes above a documented MAX_TIMEOUT_SECS (365 days), and uses checked try_seconds/checked_add_signed so no input can panic or produce a past expiry — over-cap, zero, i64::MAX, and wrapping-negative inputs all return a clean 4xx.
• Uppercase-hex config-backed bypass. Config pubkeys are lowercased at parse, but the 409 immutability check raw-string-compared the path param while decode_hex_pubkey accepted uppercase — so PUT /operators/{UPPERCASE} skipped the guard and wrote a shadow row for the same 32 bytes. The validated param is now canonicalized (lowercased) before the 409 check, DB write, DELETE, and response body.

Migrations

• 0035_relay_operators.sql — relay_operators roster table (deployment-global), actor_authority on moderation_actions, processing status plus active_action_id on moderation_reports, status on product_feedback.
• 0036_relay_admin_actions.sql — enforcement-action table with a request_id idempotency key, a step_marker for crash recovery, and a cancelled_by attribution column.
• 0037_relay_admin_action_lease.sql — lease fencing for the action worker.
• 0038_relay_admin_outbox_claim_token.sql — fenced claim token on the outbox worker.
• 0039_relay_operator_audit.sql — append-only relay_operator_audit trail for roster mutations (see Security hardening).

docs/admin/README.md documents the full principal model, NIP-98 event requirements, capabilities by role, the startup error matrix, and the discovery field.

Production blast radius

A relay without BUZZ_ADMIN_HOST is completely unaffected — the admin surface stays disabled and BUZZ_ADMIN_AUTH is ignored; a lingering BUZZ_ADMIN_TOKEN logs a startup warning and must be removed. Where BUZZ_ADMIN_HOST is set, unset BUZZ_ADMIN_AUTH defaults to nip98 (per-person signed auth); BUZZ_ADMIN_AUTH=disabled reproduces main's prior Host/Origin-only gating but is read-only (mutation routes 403). The five migrations add tables and columns without touching existing data.

---

Related: block/buzz#4768 (desktop admin console consuming the admin_api field), squareup/bb-public#339 (Phase 4 rollout config)

[kalvinnchau]

Re-reviewed at d014e40. The fail-closed config contract, constant-time bearer validation, host/origin ordering, insecure network-boundary mode, dashboard token lifecycle, authenticated attachment fetches, and CSP/static routing are coherent and covered. Deployment dependency is external: land bb-public#339 and wait for Argo rollout before deploying this relay image.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Two blockers remain at exact head 31551f2e566ea6944b1fa6fb56f734605cae06c8:

1. Do not navigate attacker-controlled attachment bytes as typed blob documents. Feedback imeta supplies the MIME and filename shown by the admin SPA. The authenticated attachment fetch preserves the media response type, requestObjectUrl turns it into a blob URL, and both the image and generic-file paths expose that URL through target="_blank". A hash-valid active payload such as HTML or SVG can therefore be opened as a document derived by the admin origin, creating an execution/phishing surface for an operator reviewing hostile feedback. Never navigate untrusted bytes: serve them through a forced-attachment response or rebuild downloads as application/octet-stream, and inline-render only server-verified passive image formats. Add regressions for active MIME/extension combinations.

2. Preserve at least one effective Operator across roster mutations. PUT /operators/{pubkey} and DELETE /operators/{pubkey} require the caller to be an Operator, but then directly upsert/remove a DB row. The DB serializes only the target key; it has no roster-wide invariant. A sole DB-backed operator can demote or delete itself, and concurrent operators can mutate different targets down to zero, permanently removing staffing authority until config/DB repair. Enforce a transactionally serialized roster-wide invariant that at least one effective Operator remains, with self-demotion/deletion and concurrent-last-operator regression coverage. An add-first transfer flow would make the safe path explicit.

The prior feedback-lifecycle/nullability blockers are fixed at this head. I also verified the earlier stale-lease failure fence, affected-user notices, tombstone target/reason propagation, and per-request NIP-98 nonce fixes. CI’s code/test lanes are green; the remaining failed/skipped jobs are review workflow state, not evidence against these source-level blockers.

Evidence: App.tsx, api.ts, admin/mod.rs, relay_operators.rs.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

No blocking findings at exact head 812566506dd9e9c3eaeee1584532b10e9d8d09a7 against base 0808ab485c39c3c12ef02af2188c65a5145eb99d.

I traced the admin-auth and moderation-action contract across NIP-98 verification, Operator/Moderator resolution, config and NIP-11 discovery, the report-resolution state machine, leased action/outbox recovery, database constraints, and the admin web consumer. The closed role/status/target/action sets agree across producers, wire types, persistence, and UI; malformed or unknown values fail closed. Replay is claimed only after signature and roster validation, privileged mutations are role-gated, stale action/outbox workers are fenced, and successful finalization transactionally creates deduplicated notices.

This was a read-only diff and exact-head source review; no PR code was checked out or executed. The stale migration numbering in the PR description is non-blocking documentation cleanup.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

No blocking findings at exact head b2884b70114038ac24bb2e5ee9257f524ed6dbac against base 80177e4c8e97e7bf1f1a3760c4e3503aace22860.

I traced the admin-auth and moderation-action contract across NIP-98 verification and replay protection, Operator/Moderator resolution, config and NIP-11 discovery, all admin handlers, report enforcement/recovery, database constraints and migrations, leased action/outbox fencing, notices, and admin-web consumers. The closed role/status/target/action sets agree across producers, wire types, persistence, and UI; malformed or unknown values fail closed. Replay is claimed only after signature, roster, host, and origin validation; privileged mutations are role-gated; stale workers are fenced; and successful finalization transactionally creates deduplicated notices.

This was a read-only diff and exact-head source review; no PR code was checked out or executed. Non-blocking cleanup: the PR description's migration numbers and the ADMIN_CSP comment about a sessionStorage operator token are stale.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Approved at b2884b70114038ac24bb2e5ee9257f524ed6dbac. I found no remaining code, product, or security blockers. The stale migration references in the PR description and stale ADMIN_CSP comment are non-blocking documentation cleanup.