6 Commits

Author	SHA1	Message	Date
Will Pfleger	032198ce43	feat(relay): add community reads to the admin API (#8011) ... The in-app Admin Console needs to work on any community the relay serves, not only the one the desktop is connected to. This adds four read-only routes under `/api/admin/v1` that the stacked desktop PR builds on, puts every admin route under one explicit access rule, and binds every admin request's signature to its real method, which fixes signed `HEAD` on reads. ## Access rule | Mode | Moderation reads | Writes | Staffing (`/operators`) | |---|---|---|---| | `nip98` (default) | signed, any staff role | signed, role-checked | signed Operator | | `disabled` | served to anyone who can reach the relay | `403` | `403` | "Moderation reads" means every read: reports, feedback and attachments, restrictions, and the four community routes below. `nip98` behavior is unchanged, and the Operator API (`/operator/*`) is untouched. **Existing `BUZZ_ADMIN_AUTH=disabled` deployments start serving the four new reads** (community directory, member search, member lookup without staff status, and stored events by ID) with no config change. The startup `WARN`, `docs/admin/README.md`, `.env.example`, `deploy/compose/.env.example` and the `just admin` comment list exactly what disabled mode exposes, say it should be reachable only by people allowed to see all moderation data in every community, and say the whole relay port must be private: the admin API is on the relay's main listener and its hostname check uses the caller's `Host` header. `just admin` binds the relay to `127.0.0.1` unless `BUZZ_ADMIN_AUTH` is exactly `nip98`, so an unset, padded or misspelled value stays local. In code, `authorize()` returns `AdminAccess`, either `NetworkTrusted` (disabled mode, no identity) or `Staff(AdminPrincipal)` (`nip98`, any rostered Operator or Moderator). Each route makes one check: **view** (`authorize()` succeeding), **act** (`AdminAccess::act()`, must be `Staff`, then the existing role checks) or **operator** (`AdminAccess::operator()`, must be an Operator). Act and operator refuse `NetworkTrusted` with `403 this endpoint requires BUZZ_ADMIN_AUTH=nip98`; no principal is ever created for an anonymous caller. `every_route_makes_its_check_in_both_auth_modes` lists every mounted admin route with its check and asserts the result in both modes, and `every_route_is_listed` fails when `router()` mounts a route that list does not name. ## Routes All four live in `api/admin/reads.rs`; `mod.rs` only registers them. Their queries reject unknown fields, like `ReportQuery`. The three `?communityHost=` routes share `CommunityQuery`, which now rejects unknown fields too, so the existing unban, untimeout and direct-action routes that use it do the same; their desktop callers send only `communityHost`. Every admin route that takes `limit` validates it with the module's shared `limit()` helper, so an out-of-range value is `400 invalid_limit`. | Route | Returns | |---|---| | `GET /communities?q=&cursor=&limit=` | `{items: [{id, host, icon\|null}], nextCursor\|null}` | | `GET /members/search?communityHost=&q=&limit=` | `{items: [{pubkey, displayName\|null, nip05\|null, avatarUrl\|null}]}` | | `GET /members/{pubkey}?communityHost=` | `{pubkey, profile: {displayName, nip05, avatarUrl, about}\|null, role: "owner"\|"admin"\|"member"\|null, banned, mutedUntil\|null, isStaff: bool\|null}` | | `GET /events/{id}?communityHost=` | `{id, authorPubkey, kind, content, createdAt, deletedAt\|null, channelId\|null}` | - **One community per read.** Community-scoped routes bind `communityHost` through the tenant binder (`400 unknown_community_host`) and read only that community's `users`, `relay_members`, `community_bans` and `events` rows. - **Directory.** It uses the binder's liveness rule (not archived, not deleted, `deletion_state = 'active'`), so every listed host can be opened. `q` is an escaped, case-insensitive host prefix of at most 255 characters (`400 invalid_query`). Results are ordered and paged by `lower(host)`, which is unique, so the opaque base64url cursor carries only the last host; a malformed cursor is `400 invalid_cursor`. `limit` is 1 to 100 with a default of 50. - **Member search.** It reuses `search_users`, which already escapes, binds and scopes, with no second escaping layer. `q` is trimmed and must be 1 to 100 characters (`400 invalid_query`), and `limit` is 1 to 50 (default 20). It searches community profiles, so former members appear. - **Member lookup.** `isStaff` uses the same roster lookup as the direct-action staff guard and is returned to signed staff only: it is `null` in disabled mode, where the roster is never read. A roster lookup failure is a 500, never "not staff". - **Event preview.** It reads the event by `(community_id, id)` and never returns a private kind (see below). A malformed id, an id stored only in another community and a private kind are all `404 event_not_found`, the same answer as an absent event. ## Private events Admin reads never reveal events the relay keeps private. `admin_hidden_kinds()` combines the four private kind sets in `buzz_core::kind`: `AUTHOR_ONLY_KINDS`, `RESULT_GATED_KINDS`, `P_GATED_KINDS` and `SHARED_GATED_KINDS`. The whole shared-gated set is hidden, including events tagged `["shared","true"]`; the shared tag is never evaluated. Every HTTP response applies it the way it treats a missing event: event preview is `404 event_not_found`, report detail returns the report with `message: null` and `targetAuthorPubkey: null`, and the report list returns a null target author. Moderators can still act on these events, they just cannot read them. Report detail is one query with the hidden-kind list as a parameter, exposed two ways: `admin_get_report` hides private kinds and backs every HTTP response (GET detail, the resolve response, reopen, cancel and the reporter-notice worker), while `admin_get_report_for_enforcement` reads the target unfiltered and is used only by the resolve handler's enforcement load (the staff-target check and ban, timeout and kick target derivation) and by the recovery worker for interrupted actions. Its result is never serialized, so a ban from a report on a private persona bans the real author while GET still shows nothing. ## Method binding Axum serves `HEAD` through `GET` handlers, but the read handlers authorized with a literal `"GET"`, so a correctly signed `HEAD` was rejected. Admin reads now authorize through `authorize_read` and writes through `authorize_write`, both of which use the request's real method and full target, so no handler hardcodes a method string. A database error behind any admin route is now logged before it becomes a 500. ## Directory query plan `idx_communities_host` is on `lower(host)` in the default collation, so the prefix `LIKE` is a filter, not an index condition. The plan walks the index in order and stops once it has `limit` matches. A common prefix is cheap (on local Postgres 16 with 21,359 communities, a first page skipped 2,728 index rows in 3.9 ms), but a prefix with few or no matches walks every index entry, so its cost grows with the number of communities. A `COLLATE "C"` index would turn the prefix into an index range; it is left out because the admin directory is low-traffic and the cost is small at current scale. The cursor condition is `lower(host) > COALESCE($2, '')`, with no `OR`, so it remains an index condition under a generic plan: ```text -> Bitmap Index Scan on idx_communities_host Index Cond: (lower((host)::text) > COALESCE($2, ''::text)) ``` --------- Signed-off-by: Will Pfleger <pfleger.will@gmail.com> Signed-off-by: Will Pfleger <wpfleger@block.xyz> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz> Co-authored-by: Hayt <211b96e6a2b7f45fd4047988976c7bbbeeda0c15f3ae7b32eec20834b5a55118@buzz.block.builderlab.xyz>	2026-10-07 16:07:38 -04:00
Will Pfleger	86b9142a09	refactor(relay): NIP-98 admin auth with Operator/Moderator roles and NIP-11 discovery (#3777) ... 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](https://github.com/block/buzz/pull/4768) (desktop admin console consuming the `admin_api` field), [squareup/bb-public#339](https://github.com/squareup/bb-public/pull/339) (Phase 4 rollout config) --------- Signed-off-by: Will Pfleger <pfleger.will@gmail.com> Signed-off-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>	2026-08-28 11:43:05 -04:00
Luke Tornquist	dcee330b5c	Fix Admin feedback filter overflow (#6825) ... ## Why Long community hostnames can make the native Community select exceed the Admin feedback filter grid, pushing the Received and Status controls outside the filter bar and creating horizontal overflow. ## What - Allow filter labels and selects to shrink within their grid tracks - Add a browser regression test covering an unusually long community hostname ## Risk Assessment Low — this is limited to Admin feedback filter sizing and preserves the existing desktop and mobile grid layouts. ## Before The Community select expands past the filter bar and pushes the Received and Status controls outside it.  ## After Long community names remain contained, keeping all four controls inside the filter bar.  ## References - Verified on Blox at the local checkout revision: Admin checks passed and all 9 Playwright tests passed Generated with Codex	2026-08-26 10:05:01 -04:00
Kalvin C	f069a85503	feat(admin): show reported message content in report detail (#3149) ... ## Summary - include the reported event's complete stored content, author, creation time, and deletion state in the admin report detail response - resolve the event through a community-scoped join so an event ID collision cannot cross tenant boundaries - render the message only on report detail, with an explicit unavailable state when retention has removed it - preserve the existing report list contract so message bodies are not returned during queue browsing ## Security - the existing admin host/origin authorization runs before the detail database read; a route test pins that ordering - the target event is selected using both `events.community_id = moderation_reports.community_id` and `events.id = moderation_reports.target_event_id` - the client supplies only the report UUID; it cannot choose a community or arbitrary event ID - soft-deleted content is visible only through this restricted admin detail route and is labeled deleted - responses retain the admin API's `no-store`, CSP, `nosniff`, frame denial, and referrer policy middleware ## Testing - `pnpm -C admin-web check` - `pnpm -C admin-web test:e2e` (10 passed) - `cargo test -p buzz-db` (84 passed, 130 ignored) - `cargo clippy -p buzz-db -p buzz-relay --all-targets -- -D warnings` - focused admin authorization tests - pre-push Rust and desktop/Tauri suites passed The new Postgres integration test is ignored under the repository convention and will run when explicitly enabled against migrated Postgres. Local Postgres and Redis were unavailable, so the full `buzz-relay --lib` run had 8 existing infrastructure-dependent failures after 749 tests passed. --------- Signed-off-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@buzz.block.builderlab.xyz> Signed-off-by: Kalvin Chau <kalvin@block.xyz> Signed-off-by: npub122y0pqkertljmedu303rl0aqrj3w8pvu43t6jxm6875lzg6f2pwqegc3xc <5288f082d91aff2de5bc8be23fbfa01ca2e3859cac57a91b7a3fa9f12349505c@buzz.block.builderlab.xyz> Co-authored-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@buzz.block.builderlab.xyz> Co-authored-by: npub122y0pqkertljmedu303rl0aqrj3w8pvu43t6jxm6875lzg6f2pwqegc3xc <5288f082d91aff2de5bc8be23fbfa01ca2e3859cac57a91b7a3fa9f12349505c@buzz.block.builderlab.xyz>	2026-07-27 12:49:21 -07:00
Kalvin C	d7f918e3cb	feat: proxy feedback-scoped admin attachments (#2059) ... Signed-off-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@sprout-oss.stage.blox.sqprod.co> Co-authored-by: Wes <wesbillman@users.noreply.github.com>	2026-07-18 15:15:57 +00:00
Kalvin C	68e670e001	feat: add read-only deployment moderation dashboard (#1999) ... Signed-off-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub1ntr8jjcqq6gt06q5avvqttfjgpwshmra22pcmcagdnukw4ja4nqqsa9g54 <9ac6794b000690b7e814eb1805ad32405d0bec7d52838de3a86cf967565dacc0@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub1dccv64krpcpse5cmkzfeh998cftungyatw3djt8jwdw6g43f7fyqzzmrf7 <6e30cd56c30e030cd31bb0939b94a7c257c9a09d5ba2d92cf2735da45629f248@sprout-oss.stage.blox.sqprod.co>	2026-07-17 12:50:06 -07:00