feat(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 an explicit authentication mode (BUZZ_ADMIN_AUTH), 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 token (default), nip98, or disabled. Configuration fails closed: any unrecognized value or conflicting combination (nip98 + BUZZ_ADMIN_TOKEN, token mode without a valid 64-hex BUZZ_ADMIN_TOKEN, a malformed RELAY_OWNER_PUBKEY alongside nip98) aborts startup. Host/Origin matching is retained in every mode as defense-in-depth.

• token — bearer auth with a deployment-wide shared secret. Read-write when the relay has a stable identity (a configured BUZZ_RELAY_PRIVATE_KEY, or the deterministic dev key when BUZZ_REQUIRE_AUTH_TOKEN=false): mutations and staffing are attributed to the relay's own pubkey as Operator — the same identity that signs moderation notices, the honest actor for a shared deployment secret. Without a stable identity it stays read-only (mutations 403), preserving the never-NULL-actor invariant. Per-person attribution requires nip98.
• nip98 — per-request signed NIP-98 (kind 27235) events, resolved to an Operator or Moderator principal with per-person attribution and individual revocability.
• disabled — no credential; relies entirely on network-layer controls and logs a WARN on every boot. Read-only.

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

In token mode with a stable relay identity, the shared token synthesizes an Operator principal attributed to the relay's own pubkey (source relay_token) — no roster lookup; the deployment identity is the actor.

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.

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 gains NIP-98 signing via a NIP-07 browser extension, auth-mode discovery, and a token prompt for token mode, with Playwright coverage of the auth and CSP paths.

Migrations

• 0032_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.
• 0033_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.
• 0034_relay_admin_action_lease.sql — lease fencing for the action worker.
• 0035_relay_admin_outbox_claim_token.sql — fenced claim token on the outbox worker.

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 both BUZZ_ADMIN_AUTH and BUZZ_ADMIN_TOKEN are ignored. Where it is set, this is a breaking change: the relay now requires an explicit authentication choice at boot (unset BUZZ_ADMIN_AUTH defaults to token, which demands a valid BUZZ_ADMIN_TOKEN; BUZZ_ADMIN_AUTH=disabled reproduces main's prior Host/Origin-only gating), so the rollout config must land the env var alongside the image. In token mode, mutations are enabled and attributed to the relay identity when a stable relay key is present (production deployments already set one); without it, and in disabled mode, mutation routes return 403. The four 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.