From 8f4f95a1eefe210ede25d4954ff30a18b419a8ef Mon Sep 17 00:00:00 2001 From: Santhi Prakash Date: Sun, 16 Aug 2026 05:07:38 +0000 Subject: [PATCH] fix(docs): correct CLI gotcha and test credential setup in AGENTS.md and TESTING.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Problem: AGENTS.md Common Gotchas item 3 says `messages search` requires `--kinds`, but the flag does not exist on that subcommand and cmd_search hardcodes its own kind filter. TESTING.md § 4 instructs `buzz-admin mint-token`, which does not exist. - Fix: Rewrite gotcha #3 to state that messages search already scopes kinds internally and point to messages get --kinds for explicit filtering. Replace TESTING.md § 4 mint-token flow with the real generate-key + add-member bootstrap, and replace the phantom scope reference table with the actual pubkey-based auth model. - Verification: Verified against upstream main crates/buzz-cli/src/lib.rs (MessagesCmd::Search struct takes --query/--author/--since/--limit; messages get takes --kinds) and crates/buzz-admin/src/main.rs (Command enum has generate-key and add-member, not mint-token). Signed-off-by: Santhi Prakash --- crates/buzz-cli/TESTING.md | 53 +++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/crates/buzz-cli/TESTING.md b/crates/buzz-cli/TESTING.md index 77234b7faab..39a82bdc7c3 100644 --- a/crates/buzz-cli/TESTING.md +++ b/crates/buzz-cli/TESTING.md @@ -53,46 +53,47 @@ The `.env` should have `BUZZ_REQUIRE_AUTH_TOKEN=false` for local dev. --- -## 4. Mint Test Credentials -### Option A: buzz-admin (full scopes including admin) +## 4. Bootstrap Test Credentials -This mints a token with all CLI-relevant scopes (including `admin:channels`) -via direct DB access. Use this for testing admin operations (archive, -delete-channel, add/remove-channel-member). +The CLI authenticates via NIP-42 (WebSocket) and NIP-98 (HTTP) using a +Nostr keypair — there is no `mint-token` command. Use `buzz-admin +generate-key` to create a keypair, then `buzz-admin add-member` to +register it with the relay. + +### Generate a keypair and register as a member ```bash -DATABASE_URL="${DATABASE_URL:?set DATABASE_URL for the local Buzz database}" \ -cargo run -p buzz-admin -- mint-token \ - --name "cli-test" \ - --scopes "messages:read,messages:write,channels:read,channels:write,users:read,users:write,files:read,files:write,admin:channels" +cargo run -p buzz-admin -- generate-key ``` -This generates a keypair and prints: -- **Private key (nsec)** — save for `BUZZ_PRIVATE_KEY` testing +Copy the printed **nsec** (private key) and **npub** (public key). -Export: +```bash +cargo run -p buzz-admin -- add-member --pubkey --role member +# Use --role admin for admin operations (archive, delete-channel, etc.) +``` + +### Export for CLI use ```bash export BUZZ_RELAY_URL="http://localhost:3000" -export BUZZ_PRIVATE_KEY="nsec1..." # from the mint output +export BUZZ_PRIVATE_KEY="nsec1..." # from generate-key output ``` -### Scope reference +### Authorization model -| Scope | Self-mintable | Needed for | -|-------|:---:|------------| -| `messages:read` | ✅ | `messages get`, `messages thread`, `messages search`, `feed get` | -| `messages:write` | ✅ | `messages send`, `messages edit`, `messages delete`, `reactions`, `messages vote` | -| `channels:read` | ✅ | `channels list`, `channels get`, `channels members` | -| `channels:write` | ✅ | `channels create`, `channels update`, `channels join`, `channels leave`, `channels topic`, `channels purpose` | -| `users:read` | ✅ | `users get`, `users presence` | -| `users:write` | ✅ | `users set-profile`, `users set-presence`, `users set-status` | -| `files:read` | ✅ | — | -| `files:write` | ✅ | — | -| `admin:channels` | ❌ | `channels archive`, `channels unarchive`, `channels delete`, `channels add-member`, `channels remove-member` | +The relay authenticates the event's key (NIP-42 over WebSocket, NIP-98 over +HTTP) and authorizes against the relay membership and per-channel role. +Without `BUZZ_PRIVATE_KEY`, every relay command exits with error code 3 +(`CliError::Auth`). Scoped API tokens exist in the schema +(`buzz-db/src/api_token.rs`) but are not exposed through any CLI command +or relay route in the current release. ---- +| Role | Needed for | +|------|------------| +| `member` | `messages get`, `messages thread`, `messages search`, `feed get`, `messages send`, `messages edit`, `messages delete`, `reactions`, `messages vote`, `channels list`, `channels get`, `channels members`, `channels create`, `channels update`, `channels join`, `channels leave`, `channels topic`, `channels purpose`, `users get`, `users presence`, `users set-profile`, `users set-presence`, `users set-status` | +| `admin` | Everything `member` can do, plus `channels archive`, `channels unarchive`, `channels delete`, `channels add-member`, `channels remove-member` | ## 5. Unit Tests