feat(cli): add buzz invites mint and buzz invites claim

[ashbrener]

Closes #3014.

The relay has had a complete invite API since the desktop client shipped invite links, but buzz-cli exposed none of it. That left a fresh identity with no way onto a closed relay: buzz channels join publishes a kind:9021 join request, which a membership-gated relay rejects with relay_membership_required, and the only alternative was an operator running buzz-admin add-member out of band with the pubkey exchanged by hand. POST /api/invites/claim is deliberately exempt from that gate — it is the intended self-service path — so the CLI now speaks it, along with the join-policy flow a claim may require.

Surface

buzz invites mint  [--ttl-secs N] [--max-uses N]
  -> {"code","expires_at","max_uses","uses_remaining","url"}
buzz invites policy
  -> {"configured","version","age_attestation_required","terms_markdown","privacy_markdown"}
     or {"configured": false} (exit 0) when the operator configured no policy
buzz invites accept-policy --code <token|-> --policy-version <v> [--age-confirmed]
  -> {"receipt"}
buzz invites claim --code <token|-> [--policy-receipt <receipt|->]
  -> {"status","community_id","host","role"}      status = joined | already_member

Bounds are checked locally against the shared buzz_core::invite constants, so a bad flag is an exit-1 usage error rather than a round-trip 400.

--max-uses goes beyond the issue text, which predates the relay's move to v2 database-backed codes. Uses are now a property of the code, and a mint command that cannot produce a single-use invite cannot express the most security-conscious case.

Acceptance is never automatic

accept-policy requires the caller to name the exact --policy-version they read, and where the operator demands an age attestation, to pass --age-confirmed. Neither is inferred from the policy document: both are assertions about a human, and the CLI has no standing to make them. A version mismatch names both versions and exits 1; a missing attestation names the flag. A policy response missing age_attestation_required fails closed, so an unreadable field can never silently downgrade an age gate.

policy prints the full terms and privacy Markdown so that human has something to read — buzz invites policy | jq -r .terms_markdown. The relay also serves the same documents as browser pages at /api/join-policy/terms and /api/join-policy/privacy.

claim rewrites 403 join_policy_required into a message naming both commands and distinguishing "no receipt sent" from "receipt rejected", so a scripted caller gets a path rather than a dead end. The 403 is preserved, so the exit code stays 3.

Credentials off the command line

Invite codes and receipts are bearer credentials — holding one is the whole authorization — and as argv they are written to shell history and readable from ps by any process on the host. Every credential argument accepts the CLI's standard - stdin sentinel, matching messages send --content -, and that is the documented preferred form. Input is bounded to 8 KiB, reading one byte past the limit so oversize is rejected rather than truncated, and strips one trailing newline and nothing else. stdin is one stream, so --code - --policy-receipt - is an exit-1 usage error rather than a hang.

Retry posture

Two authenticated POST helpers rather than one, because the calls differ in a way that matters. Claiming is effectively idempotent (a second claim answers already_member), so post_authed keeps the standard retry policy. Minting is not: a blind retry can leave an unexpired invite code in circulation that the caller never saw. post_authed_once therefore sends exactly once and, following submit_moderation_event, reports ambiguous outcomes as DeliveryUnknown — including a 429 whose body does not begin with rate-limited:, since only the relay's own pre-ingest limiter proves non-execution.

accept-policy uses a third helper, post_public: the endpoint takes no NIP-98 auth, because the receipt is a MAC over (code, policy_version) bound to the invite rather than to a pubkey, so signing it would prove nothing the subsequent claim does not already prove.

Not included

invites add-member from the issue. buzz-admin add-member writes the membership row directly and needs DATABASE_URL plus BUZZ_RELAY_PRIVATE_KEY; there is no REST surface for buzz-cli to call, and adding one would mean the relay changes the issue rules out.

For the reviewer

claim returns exit 3 for 403 join_policy_required because that is the established relay-status mapping. It is arguably a user error — a missing flag — and exit 3 reads as "your key is wrong" to a scripting agent. Remapping it is a one-line change if you would prefer the clearer signal.

Separately, and outside this PR: POST /api/invites/accept-policy has neither auth nor a rate limiter, while claim has both. A receipt is worthless without a valid code, so this is likely fine, but the CLI now makes it easy to exercise at volume and it may be worth a relay-side limiter.

Testing

cargo test -p buzz-cli — 355 passed, 0 failed. Clippy clean at -D warnings, cargo fmt --check clean.

Exercised against a local relay with BUZZ_REQUIRE_RELAY_MEMBERSHIP=true and BUZZ_REQUIRE_AUTH_TOKEN=true:

case	result
mint as owner	code minted, uses_remaining honoured
non-member, before claim	403 relay_membership_required
claim as that identity	{"status":"joined","role":"member"}
same identity after claim	reads succeed, no 403
plain member mints	403 only relay owners and admins can create invites
re-claim same code	{"status":"already_member"}
bogus code	403 invite_invalid
--ttl-secs 5	rejected locally, exit 1

Plus a stub relay serving the real response shapes for every policy refusal path, the no-auth assertion on accept-policy, and the accept-policy | jq -r .receipt | claim --policy-receipt - pipeline.

Exit codes follow the CLI contract: 3 auth, 1 usage, 0 success.

[ashbrener]

just ci status, reported rather than left to be discovered.

It fails on this machine, on one test, and the failure is not from this branch:

relay_admission::tests::concurrent_429_extends_the_window_for_parked_waiters
  left: 300.001s   right: 5s
desktop-tauri-test  exit 101

Evidence it is pre-existing and load-dependent:

• passes in isolation on unmodified main
• passes in isolation on this branch
• fails only inside the full parallel just ci run

The cause looks structural rather than environmental: the test is
#[tokio::test(start_paused = true)] (desktop/src-tauri/src/relay_admission.rs:152)
and asserts an exact Instant::now() - start == 5s. With a paused clock, tokio
auto-advances to the next pending timer, so under a parallel run it can adopt a
300s timer from elsewhere instead of its own — which is exactly the 300.001s
reading. Happy to file that separately if it is not already known.

Everything this branch touches is green: cargo test -p buzz-cli 355 passed,
cargo clippy -p buzz-cli --all-targets -- -D warnings clean, cargo fmt --check
clean, and the full pre-push gate (rust-tests, desktop-check, desktop-test,
mobile-test, desktop-tauri-checks) passed on the pushes that landed here.