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 configurable authentication (BUZZ_ADMIN_AUTH), a two-tier Operator/Moderator principal model backed by a config-union-plus-DB roster and NIP-98 HTTP auth, mutation and staffing endpoints, and NIP-11 auto-discovery so clients never type the admin URL by hand.

Authentication (BUZZ_ADMIN_AUTH)

Introduces BUZZ_ADMIN_AUTH, accepting token (default), disabled, or nip98. On main the admin API authenticates only by Host/Origin matching with no configurable mode; this branch adds explicit authentication that fails closed on missing or malformed configuration — any unrecognized value or conflicting combination aborts startup. Host/Origin matching is retained in all modes as defense-in-depth.

Principal resolution (NIP-98 mode)

resolve_admin_principal() returns AdminPrincipal { pubkey, role, source }:

• Operator/Config — pubkey is in RELAY_OPERATOR_PUBKEYS
• Operator/OwnerFallback — pubkey equals RELAY_OWNER_PUBKEY and RELAY_OPERATOR_PUBKEYS is empty (config-evaluated, never from runtime DB rows)
• Operator or Moderator / Db — row in the relay_operators table
• No match → 403

Config always outranks DB, and None never falls through as a role. A malformed RELAY_OWNER_PUBKEY alongside nip98 is a startup error, since the owner key can be a break-glass root and silently discarding it would be a lockout.

NIP-98 admission is ordered so the replay guard is a privilege, not a public surface: authorize_nip98 verifies signature, URL, method, and payload hash and returns the pubkey and event id without claiming the replay slot; resolve_admin_principal runs the roster check next; only then does claim_nip98_replay atomically consume the deployment-scoped replay id. A validly-signing but unrostered key (any network-admitted client) is rejected at principal resolution and never allocates a replay slot. Redis failure remains fail-closed and the deployment-scoped key format is unchanged.

Token and disabled modes

Read routes work in all modes. Mutation and staffing routes require nip98; token and disabled modes receive 403 from require_mutation_principal. disabled mode logs a WARN on every boot and relies entirely on network-layer controls.

Report resolution, recovery, and enforcement provenance

POST /reports/{id}/resolve is an enforcement state machine with idempotency:

• Decision-only (dismiss/escalate): CAS open→terminal plus an audit row in one transaction.
• Enforcement (delete/kick/ban/timeout): claims the report (open→processing), runs the durable mutation, then finalizes to resolved. Crash-safe — re-drive resumes at the step marker and converges to exactly-one enforcement, fenced by a lease and a claim token on the outbox.

Person-directed enforcement (kick/ban/timeout) needs a target user, but an event-kind report row stores only the reported event id — the reporter-supplied p tag is validation-shape only and never persisted. A single derive_enforcement_target overlays the reported event's author (server-owned truth read from the stored events row, never the reporter's claim) as the target for event reports, keeping the event id; pubkey/blob reports pass through unchanged. The HTTP driver and the crash-recovery worker both call it, so a stranded action always re-derives against the same target it claimed — no persisted target column required. A soft-deleted event still carries its author, so enforcement stays valid. When the reported event is wholly absent (purged before its author could be determined), a pre-claim guard rejects person-directed actions with InvalidAction, leaving the report open and unclaimed rather than stranding it; delete needs only the event id and is exempt.

GET /reports/{id} and the /resolve response carry an activeAction field (AdminActionDto | null) derived via a LEFT JOIN LATERAL over relay_admin_actions — matching the report's active_action_id or its terminal succeeded enforcement, ORDER BY created_at DESC, id DESC. This surfaces the enforcement that actually executed against a target, so a report dismissed after a reopen still reports the ban/kick/delete that ran — honest enforcement history rather than a null. reopen audit rows are excluded from the join (action IN ('delete','kick','ban','timeout')), and the DTO's reason/expiresAt/errorMessage are required-nullable (always emitted, null when absent).

POST /reports/{id}/reopen returns a terminal report (resolved/dismissed/escalated) to open and records a durable reopen audit row. Idempotent on requestId — a retry returns the same success without re-reopening a report that has since been re-resolved; 409 if the report is not terminal.

POST /reports/{id}/cancel cancels a pre-mutation failed enforcement action, returning the report to open. The acting principal is persisted in relay_admin_actions.cancelled_by and surfaced as AdminActionDto.cancelledBy, so cancel — the one mutation that would otherwise leave no actor trail while BUZZ_AUDIT_ENABLED=false — is attributed like every other. Cancel is the only recovery path for a failed action — a composed client-side retry has a failure window and implies an atomicity the relay does not provide. The response embeds the just-cancelled action DTO as the last look at that record, since a subsequent detail read (report back to open) serves activeAction: null; a 409 means the action is no longer cancellable (already cancelled, superseded, or past the mutation point) — treat as "refresh detail".

GET /feedback and /feedback/{id} use LEFT JOIN communities with nullable communityId/communityHost so feedback survives a tenant purge that severs provenance (product_feedback.community_id set NULL, not cascade-deleted). The attachment path fails closed to 404 on a severed row — no tenant to bind, and its media was purged with the community. Feedback DTOs also expose the lifecycle status.

PATCH /feedback/{id} updates product_feedback.status (new/reviewed/archived); requires nip98.

Staffing endpoints

GET/PUT/DELETE /operators/{pubkey} are Operator-only. PUT/DELETE against a config-backed pubkey returns 409 Conflict. GET /operators returns the union of config and DB principals with per-entry source attribution.

Probe endpoint

GET /probe reports auth mode, role, source, canAct, and canStaff for the desktop console.

NIP-11 admin-API 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 the admin surface is configured (BUZZ_ADMIN_HOST set) and omitted entirely otherwise. The scheme follows the same loopback rule as NIP-98 u-tag verification (http for localhost/127.x/::1, else https), extracted into a shared scheme_for_host helper so the advertised origin and the origin the relay verifies against can never diverge. Clients read this to auto-discover the admin console instead of requiring manual URL entry.

Loopback example:

{ "admin_api": "http://127.0.0.1:3000" }

Operator API origin decoupling

RELAY_OPERATOR_API_ORIGIN is no longer required at boot when RELAY_OPERATOR_PUBKEYS is set. The allowlist is shared by the NIP-98 admin console (which needs no origin) and the community-provisioning endpoints (which do). Configuring the admin console no longer drags in an origin the operator does not use: the relay logs a WARN naming the affected feature, and the provisioning endpoints (POST /operator/communities) fail closed at request time — authorize_operator_request rejects with a clean 500 before any replay or DB access — until RELAY_OPERATOR_API_ORIGIN is set.

Admin-web adaptation

admin-web gains NIP-98 request signing via a NIP-07 browser extension, auth-mode discovery, and a token prompt for token mode, so the standalone dashboard authenticates under every new mode. Playwright coverage exercises the auth and CSP paths.

Migrations

• 0032_relay_operators.sql — relay_operators table (deployment-global; registered in _operator_global_tables), actor_authority on moderation_actions, processing status plus active_action_id on moderation_reports, status on product_feedback.
• 0033_relay_admin_actions.sql — relay_admin_actions enforcement-action table with a request_id idempotency key, a step_marker for crash recovery, and a cancelled_by actor column attributing cancels.
• 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.

Documentation

docs/admin/README.md documents the full principal model, NIP-98 event requirements (query string, method tag, payload tag for body mutations), owner-fallback semantics, role/source table, capabilities by role, roster management, the startup error matrix, the NIP-11 auto-discovery field, and the origin decoupling. .env.example and deploy/compose/.env.example describe RELAY_OPERATOR_API_ORIGIN and the admin console/provisioning split.

---

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.