feat(relay): add admin HTTP routes for member restriction management

[wpfleger96]

What

Three admin HTTP routes under GET|DELETE /api/admin/v1/members/...:

• GET /members/restrictions?communityId=<uuid>[&limit={1-200}][&cursor=<token>] — lists active bans and timeouts with stable keyset pagination
• DELETE /members/{pubkey}/ban?communityId=<uuid> — lifts an active ban; 409 if no active restriction
• DELETE /members/{pubkey}/timeout?communityId=<uuid> — lifts an active timeout; 409 if no active restriction

Auth

All three routes pass through the existing NIP-98 authorization gate. Both DELETEs call require_mutation_principal; GET follows the established read-authorization pattern.

Atomicity

Both DELETE routes use transactional DB helpers (unban_member_with_audit / untimeout_member_with_audit) that perform the conditional lift UPDATE and the moderation_actions INSERT in one SQL transaction. If the audit INSERT fails the lift rolls back; the restriction stays active.

Expired-ban predicate

unban_member WHERE clause requires banned AND (ban_expires_at IS NULL OR ban_expires_at > now()) — matches all read paths. An already-expired ban returns false → 409.

Pagination (GET /members/restrictions)

GET /members/restrictions returns { "items": [...], "nextCursor": "<token>"|null }.

• limit — page size 1–200 (default 200), enforced as a SQL LIMIT. Returns 400 for values outside range.
• cursor — opaque continuation token from a prior page's nextCursor. Omit for the first page.
• Order: ORDER BY updated_at DESC, pubkey DESC. The pubkey tie-breaker ensures a deterministic cursor even when multiple rows share the same updated_at.
• Cursor encoding: base64url of {updated_at_micros}_{pubkey_hex}. Treat as opaque.
• nextCursor is null only when the returned page is smaller than limit. An exactly-full final page emits a non-null cursor; the subsequent request returns an empty page with null.
• The existing list_community_restrictions DB method (unbounded) is kept intact for the embedded dashboard bridge consumer (GET /moderation/restricted), whose bare-array response contract must not change.

Tests

All Postgres-gated tests are in the postgres_tests module (api/admin/mod.rs):

• list_restrictions_returns_active_bans_and_timeouts — seeds a ban + timeout, GET returns both; nextCursor is null when all records fit in one page
• list_restrictions_pagination_exhaustive — seeds 201 rows: 199 with distinct timestamps (1s apart, newest first) plus a tied pair sharing an identical older timestamp (now()-1000s), pinned to sort positions 200/201 so the default-200 page boundary splits the tie. Asserts: (1) limit=201 → 400; (2) a no-limit request returns exactly 200 items + non-null nextCursor (falsifiable binding of default=200 and SQL cap — reverting the route default to the shared helper's 50 fails this assertion); (3) continuation walk to exhaustion with exactly-once coverage over all 201 pubkeys, exercising the tie-breaker at the page boundary.
• unban_member_returns_204_clears_ban_and_inserts_audit — 204, ban cleared, timeout survives (restriction independence), audit row verified, tenant isolation confirmed
• untimeout_member_returns_204_clears_timeout_and_inserts_audit — 204, timeout cleared, ban survives (restriction independence), second-community timeout survives (community_id predicate), audit row verified
• unban_member_returns_409_for_expired_ban — expired ban → 409, no audit row
• unban_with_audit_rolls_back_lift_when_audit_insert_fails (buzz-db) — forced CHECK constraint failure proves Err + ban still active (rollback proof)

[github-actions]

🔐 Codex Security Review

Note: This is an automated, security-focused review generated by Codex.
Use it as a supplement to human review; false positives are possible.

Scope

• Exact PR diff: a61239f0d8036aff58176f5c0ce7f080c66e21b7...319c97874b4f1c9c51bd75e70da93bb91e7fa652
• Model: gpt-5.6-sol

💡 Click "edited" above to see earlier reviews for this PR.

---

Review Summary

Overall Risk: NONE

No concrete security, correctness, or reliability issues were identified in the authorized pull request range.

Findings

No concrete security, correctness, or reliability findings were identified.

Notes

• Review was limited to read-only static inspection; repository scripts, builds, and tests were not executed as requested.

---

_{Generated by Codex Security Review |
Requested by: @wpfleger96 |
Workflow run}

[TheSentinel454]

P1 — bound and paginate the new restriction-list endpoint

Verified at exact head c7106d808716eeddaa75b52e4df9f449d7093863.

GET /api/admin/v1/members/restrictions calls list_community_restrictions (crates/buzz-relay/src/api/admin/mod.rs:1159-1182), whose DB query orders all active restrictions and then uses unbounded fetch_all without a LIMIT (crates/buzz-db/src/store/moderation.rs:626-647). A roster-authorized caller can repeatedly make PostgreSQL scan and the relay materialize every active restriction for a community.

This conflicts with the repository rule to “Bound every resource, loop, and process tree” (AGENTS.md:194-202). The PR body acknowledges this deferral, but no follow-up issue is linked.

Please add:

1. A capped limit with a maximum of 200 and stable keyset/cursor pagination.
2. The bound in the SQL query itself, rather than slicing after fetch_all.
3. Continuation metadata in the HTTP response.
4. A production-route PostgreSQL regression test that seeds more than the cap, proves no page exceeds it, and proves pagination returns every row exactly once.

updated_at alone is not a unique cursor. Use a deterministic tie-breaker (for example (updated_at, pubkey)) in both ORDER BY and the keyset predicate so equal timestamps cannot duplicate or omit rows.

Severity: P1. This endpoint is NIP-98 roster-gated, so this is a remotely repeatable availability cost rather than a demonstrated confidentiality or data-loss issue. The authorization, tenant predicates, transactional lift-and-audit behavior, active/expired semantics, and independent ban/timeout handling otherwise looked sound at this SHA.

[wesbillman]

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

Source review clear

Reviewed head 86a5ebb506f57b4bc400488204ff34f6f2e2ebb0 against base 75f101d8b4f5b4b26f9891b73b87c67fedac25a0. No actionable code, product, or security blocker found. This is a review comment, not approval.

• Contract and authority: these routes extend the existing deployment-admin HTTP plane. The shared NIP-98 gate binds method and full query-bearing URL, resolves deployment Operator/Moderator authority, and retains Host/Origin and replay checks. Both DELETEs reject disabled-mode mutations; community-local roles do not grant deployment access.
• State and compatibility: traced both lifts through the scoped conditional UPDATE and atomic audit INSERT, schema action/authority vocabularies, and the admission/write consumers of the same restriction rows. Ban and timeout remain independent; absent/expired restrictions do not produce a lift audit. The existing community command path and /moderation/restricted bare-array response remain compatible. Keyset order, strict continuation predicate, timestamp precision, and the documented extra empty page after an exactly-full final page agree. Pagination is not a snapshot across concurrent changes.
• Validation limits: reviewed the changed source and tests, exact-base product/architecture/testing guidance, and independent authorization and DB review lanes. No PR code was checked out, built, tested, imported, or executed; runtime and CI outcomes are not certified by this review. Client UI and lift-notification behavior were not changed here. Additional route-specific malformed-cursor/disabled-mode tests and concurrent-lift coverage would strengthen the suite, but source review found no concrete defect to block on.

[wesbillman]

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

Source review clear

Reviewed head 319c97874b4f1c9c51bd75e70da93bb91e7fa652 against base a61239f0d8036aff58176f5c0ce7f080c66e21b7, carrying forward the prior source clearance at 86a5ebb506f57b4bc400488204ff34f6f2e2ebb0. No actionable regression found. This is a review comment, not approval.

• Delta: one main merge plus two test-only lint fixes. The net branch change is a pagination-test loop rewritten as while let; cursor advancement, termination guard, page bound, and exhaustive/tie-break assertions remain intact. Production code in the two PR-owned files is unchanged since the prior clearance, not production code throughout the merged repository.
• Integration: checked main’s changed NIP-98 verifier, ban-enforcement state transition, test-state setup, schema, and legacy restriction consumers against the existing contract. Deployment authority and disabled-mode mutation rejection, community-scoped atomic lift/audit, independent ban/timeout state, bounded keyset pagination, and the legacy bare-array response remain compatible. Pagination remains intentionally non-snapshot; no new UI or lift-notification requirement is imposed.
• Evidence and limits: source-only review on the pinned Blox host with exact-base product/testing/architecture guidance and an independent metadata lane. No PR code was checked out, built, tested, imported, or executed. The exact-head CI snapshot at 2026-09-21 18:02:44Z had 54 successful and 26 skipped checks, with none failing or pending. Existing optional coverage suggestions are not promoted into new blockers.