feat: relay invite links (mint + claim + landing page + deep link)

[baxen]

Summary

Adds shareable invite links for relay membership, replacing the manual "install app → find your npub → send it to the owner → owner adds you via NIP-43 admin event → owner sends you the relay URL" dance with a single link.

New flow: owner mints a link in Relay Access settings → shares it → invitee opens https://<relay-host>/invite/<code> → landing page offers download + "Open in Buzz" (buzz://join?relay=...&code=...) → desktop claims the invite with the invitee's own key and adds/switches to the workspace.

What's included

Relay (Rust)

• Stateless HMAC invite tokens (crates/buzz-relay/src/invite_token.rs): payload.mac format, community-scoped, TTL'd (default TTL), key derived server-side — no new DB table. Codes minted for one community fail verification on another.
• HTTP routes (api/invites.rs):
  • POST /api/invites — mint; owner/admin only, NIP-98 authenticated. Returned landing URL follows deployment TLS posture (https for wss://, http for ws://).
  • POST /api/invites/claim — deliberately outside the relay-membership gate (invitee isn't a member yet); NIP-98 signed by the claimer; per-pubkey sliding-window rate limiter (invite_claim_rate_limiter on AppState) bounds brute-force probing. Idempotent: returns joined vs already_member; membership added via add_relay_member (ON CONFLICT DO NOTHING); expired codes return invite_expired.
• SPA fallback fix in router.rs so /invite/* paths containing . aren't 404'd.

Web

• /invite/<code> landing page (web/src/features/invite/ui/InvitePage.tsx) with download links and "Open in Buzz" deep link.

Desktop

• buzz://join?relay=...&code=... deep link: Rust parse_join_deep_link + TS listener that claims the invite then adds/switches workspace.
• "Invite Code (optional)" field in AddWorkspaceDialog for joining additional relays manually; invite_expired mapped to friendly copy.
• InviteLinkSection create-invite-link UI in RelayMembersSettingsCard.

Testing

• Invite token: 8 unit tests. Claim/mint routes: 4 Postgres-gated tests (pass with --ignored).
• Deep link: all 26 deep_link Rust tests pass; desktop TS + tauri tests green.
• Web typecheck/build/biome green; buzz-db/auth/core/conformance green.
• Mobile checks not run locally (no dart/flutter) — CI covers them. Mobile app support for invite links is not included; follow-up candidate.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 85a2a8a64f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Bound invite-claim limiter entries

Because /api/invites/claim is intentionally reachable before relay membership, a remote client can generate fresh NIP-98 keypairs and send one claim attempt per pubkey; each call inserts a new key here and this DashMap never expires or removes entries, so the limiter can be turned into unbounded process memory growth instead of throttling. Please use a bounded/TTL cache and/or an IP/global limiter for this pre-membership path.

Useful? React with 👍 / 👎.

[wpfleger96]

🤖 Reviewed via 3 parallel Claude specialists (Security & Reliability, Design & Simplicity, Functionality & Testing). All 3 reported HIGH confidence. CI is fully green (27/27).

Verdict: Approve — no blocking issues. Well-designed stateless HMAC invite system with sound crypto, proper NIP-98 auth, and clean UX flow.

Strengths:

• Crypto verification order is exemplary — MAC verified before any payload field is trusted, constant-time comparison via hmac::verify_slice, error oracle is tight.
• Key derivation is domain-separated (sha256(secret || "buzz-invite-v1")), blast radius is clear.
• invite_token.rs is an ideal module boundary — fully isolated from HTTP, self-contained error type, thorough test matrix.
• Idempotency is explicitly designed and integration-tested (already_member on re-claim).

[wpfleger96]

🤖 Should Fix — Rate limiter not scoped to tenant/community

The invite_claim_rate_limiter is keyed purely by pubkey bytes. In a multi-tenant deployment, an adversary controlling one community can exhaust a pubkey's rate-limit budget across all communities by hammering claims on their own relay — preventing the victim key from claiming an invite on a different community.

Fix: key by (community_id, pubkey_bytes), consistent with how observer_rate_limiter and mesh_connect_rate_limiter are scoped elsewhere in AppState.

[wpfleger96]

🤖 Should Fix — Inline scheme derivation duplicates nip98_expected_url

This wss → https / ws → http block is the same logic as bridge::nip98_expected_url — the comment on L135 even acknowledges this. Consider calling through the existing helper or extracting a shared one-liner, rather than adding another copy of the pattern.

[wpfleger96]

🤖 Should Fix — NIP-98 auth helpers duplicated across invites.ts and moderation.ts

nip98PostHeader, sha256Hex, the NIP98_KIND constant, and the invitePost fetch wrapper are ~80% identical to moderation.ts:222-234. These belong in shared/api/nip98.ts or shared/api/tauri.ts to prevent drift:

// shared/api/nip98.ts
export const NIP98_KIND = 27235;
export async function nip98PostHeader(url: string, body: string): Promise<string>
export async function nip98GetHeader(url: string): Promise<string>

[wpfleger96]

🤖 Should Fix — relayHttpFromWs passes through unexpected schemes unchanged

If the input starts with neither wss:// nor ws://, the raw URL is returned unchanged to fetch. The deep-link path is safe (Rust validates ws/wss), but claimInvite is also called from AddWorkspaceDialog with freeform user input via normalizeRelayUrl. As defense-in-depth, add a scheme check here:

export function relayHttpFromWs(wsUrl: string): string {
  if (wsUrl.startsWith("wss://")) return `https://${wsUrl.slice(6)}`;
  if (wsUrl.startsWith("ws://")) return `http://${wsUrl.slice(5)}`;
  throw new Error(`Expected ws:// or wss:// URL, got: ${wsUrl}`);
}

(Also: this is exported but unused outside invites.ts — consider unexporting or moving to shared/lib/ if intended for reuse.)

[wpfleger96]

🤖 Consider — InvitePayload field names are cryptic in Rust code

Nit: Fields c, r, e, n are compact on the wire but every other public struct in the codebase uses descriptive names. Wire compactness could be preserved with #[serde(rename)] on descriptive field names:

#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct InvitePayload {
    #[serde(rename = "c")]
    pub community: String,
    #[serde(rename = "r")]
    pub role: String,
    #[serde(rename = "e")]
    pub expires_at: u64,
    #[serde(rename = "n")]
    pub nonce: String,
}

[wpfleger96]

🤖 Consider — Stale URL visible during re-mint

Nit: On a second "Create invite link" click, the old invite URL stays visible while the new mint request is in-flight (only the button is disabled). A user could copy the stale URL during this window. Adding setInvite(null) at the start of handleCreate would clear it immediately.

[wpfleger96]

🤖 Consider — No test for invite_expired string mapping

Nit: The string "invite_expired" is used as a sentinel to branch to a user-friendly message. The same pattern exists in the deep-link handler (deep-link.ts:99-104). A backend rename of this string would silently break the UX with no test catching it. Worth either a shared constant or a test asserting the mapping.