feat(relay): add buzz-admin member management CLI with NIP-43 roster publish

ARCHITECTURE.md

@@ -718,11 +718,14 @@ Subcommands:
 
 | Subcommand | Purpose |
 |------------|---------|
-| `add-member` | Add a pubkey to the relay membership list (`--pubkey`, `--role`) |
+| `add-member` | Add a pubkey to the relay membership list (`--pubkey`, `--role`); accepts npub or hex; publishes kind:13534 roster |
+| `remove-member` | Remove a pubkey from the relay membership list (`--pubkey`, optional `--role` guard); publishes kind:13534 roster |
 | `list-members` | List all relay members |
 | `generate-key` | Generate a new Nostr keypair (for bootstrapping) |
 | `reconcile-channels` | Emit kind:39000/39002 discovery events for channels missing them (idempotent) |
 
+The `buzz-admin` binary is shipped in the relay Docker image (`/usr/local/bin/buzz-admin`) and is the recommended way to manage relay membership in production. Use `./run.sh add-member`, `./run.sh remove-member`, and `./run.sh list-members` in Docker Compose deployments.
+
 ---
 
 ### buzz-test-client — Integration Test Harness

Dockerfile

@@ -44,7 +44,9 @@ COPY --from=planner /build/recipe.json recipe.json
 RUN cargo chef cook --release --recipe-path recipe.json
 COPY . .
 RUN cargo build --release --locked -p buzz-relay --bin buzz-relay \
-    && strip target/release/buzz-relay
+                                   -p buzz-admin --bin buzz-admin \
+    && strip target/release/buzz-relay \
+    && strip target/release/buzz-admin
 
 # ─── Stage 4: web bundle (pnpm + vite) ──────────────────────────────────────
 # Independent of the Rust layers so a CSS change doesn't bust Rust cache and
@@ -82,6 +84,7 @@ RUN apt-get update \
                 --create-home --shell /usr/sbin/nologin buzz
 
 COPY --from=builder    /build/target/release/buzz-relay /usr/local/bin/buzz-relay
+COPY --from=builder    /build/target/release/buzz-admin /usr/local/bin/buzz-admin
 COPY --from=web-builder /build/web/dist                 /srv/buzz/web
 
 ENV BUZZ_WEB_DIR=/srv/buzz/web

NOSTR.md

@@ -471,6 +471,117 @@ is dual-sourced: local snapshot metadata plus upstream edit events (kind:40003 
 
 ---
 
+## Relay Membership (NIP-43)
+
+When `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true`, every authenticated connection is checked against the
+`relay_members` table. Only pubkeys with a row in that table may use the relay. The relay owner
+is bootstrapped automatically from `RELAY_OWNER_PUBKEY` on startup.
+
+### CLI: Managing Members
+
+Use `buzz-admin` — the operator CLI shipped in the relay image — to manage relay membership.
+In a Docker Compose deployment, use `run.sh`:
+
+```bash
+# Add a member (accepts bech32 npub or 64-char hex; default role: member)
+./run.sh add-member npub1abc...
+./run.sh add-member <64-char-hex-pubkey>
+./run.sh add-member npub1abc... --role admin
+
+# Remove a member
+./run.sh remove-member npub1abc...
+./run.sh remove-member npub1abc... --role member   # only removes if role matches
+
+# List all members
+./run.sh list-members
+```
+
+Or invoke `buzz-admin` directly inside the container:
+
+```bash
+docker compose exec relay buzz-admin add-member --pubkey npub1abc...
+docker compose exec relay buzz-admin add-member --pubkey npub1abc... --role admin
+docker compose exec relay buzz-admin remove-member --pubkey npub1abc...
+docker compose exec relay buzz-admin list-members
+```
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation error (bad pubkey, bad role, usage error) |
+| 2 | Not found (remove: member does not exist) |
+| 3 | Cannot remove relay owner (use `RELAY_OWNER_PUBKEY` to change owner) |
+| 4 | Role mismatch (`--role` check failed) |
+| 5 | DB/Redis/internal error |
+
+**Required environment variables for member management:**
+
+| Variable | Notes |
+|----------|-------|
+| `DATABASE_URL` | Postgres connection string |
+| `REDIS_URL` | Redis connection string |
+| `BUZZ_RELAY_PRIVATE_KEY` | Hex private key — required to sign kind:13534 events |
+
+### NIP-43 Admin Events (WebSocket)
+
+Relay membership can also be managed over WebSocket using NIP-43 admin events. These require
+the sender to be authenticated (NIP-42) as the relay owner or an admin.
+
+| Kind | Action | Required tags |
+|------|--------|---------------|
+| 9030 | Add member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin"]` |
+| 9031 | Remove member | `["p", "<hex-pubkey>"]`, optional `["role", "member\|admin"]` |
+| 9032 | Change role | `["p", "<hex-pubkey>"]`, `["role", "member\|admin"]` |
+
+Example using `nak`:
+
+```bash
+# Add a member (owner or admin must sign)
+nak event -k 9030 \
+  --tag "p=<target-hex-pubkey>" \
+  --tag "role=member" \
+  --auth --sec <owner-or-admin-privkey> \
+  ws://localhost:3000
+
+# Remove a member
+nak event -k 9031 \
+  --tag "p=<target-hex-pubkey>" \
+  --auth --sec <owner-or-admin-privkey> \
+  ws://localhost:3000
+
+# Change a member's role to admin
+nak event -k 9032 \
+  --tag "p=<target-hex-pubkey>" \
+  --tag "role=admin" \
+  --auth --sec <owner-or-admin-privkey> \
+  ws://localhost:3000
+```
+
+After each add/remove/role-change, the relay publishes a kind:13534 membership list event
+(relay-signed, NIP-70 protected) that clients can subscribe to:
+
+```bash
+# Subscribe to the live membership roster
+nak req -k 13534 --auth --sec <privkey> ws://localhost:3000
+```
+
+### Known Limitations
+
+1. **CLI intentionally does not emit kind 8000/8001 deltas** — `publish_nip43_delta` is
+   in-process-only (no Redis hop), so a sidecar call stores but never pushes. The 13534 list
+   snapshot is the authoritative roster and rides Redis to live clients. Do not wire a delta call
+   that passes in-process tests and silently no-ops in the deployed `compose exec` path.
+
+2. **The `custom_created_at = max(now, newest_existing_13534 + 1s)` bump defeats same-second
+   domination for serial invocations; it does NOT serialize concurrent CLI processes** — two
+   near-simultaneous adds can read the same newest timestamp and collide on the bumped second.
+   `run.sh` serialization is the guard against parallel adds (e.g. `xargs -P`). When adding
+   multiple members in a loop, add `sleep 1` between invocations.
+
+---
+
 ## Relay Environment Variables (NIP-29 relevant)
 
 | Variable | Required | Default | Description |

crates/buzz-admin/Cargo.toml

@@ -15,9 +15,18 @@ path = "src/main.rs"
 buzz-db = { workspace = true }
 buzz-core = { workspace = true }
 buzz-auth = { workspace = true }
+buzz-pubsub = { workspace = true }
+buzz-search = { workspace = true }
+buzz-audit = { workspace = true }
+buzz-workflow = { workspace = true }
+buzz-media = { workspace = true }
 nostr = { workspace = true }
 tokio = { workspace = true }
 serde_json = { workspace = true }
 anyhow = { workspace = true }
 hex = { workspace = true }
+deadpool-redis = { workspace = true }
+tracing = { workspace = true }
+sqlx = { workspace = true }
+uuid = { workspace = true }
 clap = { version = "4", features = ["derive"] }