feat(relay): add relay-verified identity binding

[fsola-sq]

Why

Relays need a provider-neutral way to bind a verified external identity to the Nostr key that authenticated the request, while preserving Nostr proof and failing closed when identity evidence is missing or inconsistent.

builds on original work by @fsola

What

• Validate asymmetric JWTs against configured issuer, audience, key, time, subject, display-name, and optional public-key claims
• Persist issuer-qualified identity bindings with atomic enrollment, lifecycle state, revocation tombstones, authorized rotation, and recovery controls
• Keep direct identity authorization separate from delegated-owner authorization and enforce explicit precedence
• Apply identity authorization across WebSocket, HTTP bridge, moderation, media, Git, private audio, and protected admission paths
• Publish privacy-bounded relay-signed identity assertions and expose their current state to the desktop UI
• Keep the feature off by default behind explicit relay configuration

Review guide

• Identity verification: JWT and JWKS validation, trusted ingress, claim mapping, and privacy boundaries
• Binding lifecycle: migrations, atomic admission, partial-bijection enforcement, tombstones, rotation, recovery, and session eviction
• Protected transports: route classification and consistent authorization across relay, HTTP, media, Git, and audio surfaces
• Desktop presentation: relay-signed assertion handling, expiry, withdrawal, and profile surfaces

Risk assessment

Medium. This PR changes authentication, persistence, protected routing, and desktop presentation. The feature remains off by default, and configured deployments deny authorization when required evidence cannot be verified.

Testing

• JWT and JWKS algorithm, claim, key-use, key-age, refresh, and tamper cases
• PostgreSQL migration, enrollment, lifecycle, concurrency, rollback, and tombstone cases
• Protected-route, admission, delegation, and session-eviction cases
• Desktop assertion replacement, withdrawal, and expiry cases

References

• Federated identity authorization specification: NIP-FI: Federated Identity Authorization (spec + formal model) #1485
• Extended lifecycle and conformance specification: docs(nips): complete NIP-FI authorization draft #3726

Operator documentation for the identity runtime is maintained separately and tracked in #3726.

[jmecom]

edit: Sorry, Codex posted this...
edit2: Ok, reviewed Codex's comments and I agree

The binding model and transport wiring are thoughtfully structured, and the current CI run is green. I found three security-boundary gaps that make BUZZ_REQUIRE_CORPORATE_IDENTITY weaker than its configuration contract: tokens without aud are accepted, HTTP bridge bindings can originate from the unverified X-Pubkey fallback, and existing authenticated read paths bypass the identity gate. Requesting changes until these are closed and covered by regression tests.

[jmecom]

[P1] Require the audience claim itself

In jsonwebtoken 9, Validation::new requires only exp. set_audience configures the allowed value, but validation is skipped when aud is absent. As written, a correctly signed issuer token with no audience can enroll and bind a principal even though it was not issued for Buzz. Add aud to required_spec_claims (and a missing-aud regression test) before decoding.

[cea-block]

🤖 Addressed on current head. JWT validation now explicitly requires exp, iss, and aud, and rejects missing or malformed audiences. Regression tests cover both cases.

[jmecom]

[P1] Require cryptographic Nostr proof before persisting this binding

verify_bridge_auth still returns the caller-controlled X-Pubkey fallback whenever BUZZ_REQUIRE_AUTH_TOKEN=false, which is the default. This call then binds the validated JWT uid to that arbitrary key. A valid JWT holder can therefore bind another user pubkey to their own principal and leave the real owner hitting a persistent pubkey conflict. When corporate identity is enabled, force NIP-98 on these routes or reject the incompatible startup configuration.

[cea-block]

🤖 Addressed. Enabling corporate identity now forces signed NIP-98 authentication even when ordinary token auth is disabled, so the caller-controlled X-Pubkey fallback cannot create a durable binding. A regression test verifies this returns 401.

[jmecom]

[P1] Apply this gate to the other authenticated bridge paths

The new helper is called by /events, /query, and /count, but authorize_moderation_read in this same module still stops after NIP-98 replay and role authorization. With BUZZ_REQUIRE_CORPORATE_IDENTITY=true, a moderator without any identity JWT can still read reports, audit records, and restrictions. Route every community-scoped NIP-authenticated bridge entry point through the same post-proof identity check.

[cea-block]

🤖 Addressed. /moderation/reports, /moderation/audit, and /moderation/restricted now share the same corporate-identity gate after NIP-98 verification and before database reads. Binding finalization occurs only after moderator authorization succeeds.

[jmecom]

[P1] Gate authenticated media reads as well as uploads

This covers upload, but authenticate_media_read still verifies only the Blossom GET event and relay membership. When BUZZ_REQUIRE_MEDIA_GET_AUTH and BUZZ_REQUIRE_CORPORATE_IDENTITY are both true, a member key can continue GET/HEAD access to protected blobs without a JWT. Apply the same identity enforcement there using auth_event.pubkey before admitting the read.

[cea-block]

🤖 Addressed. Protected Blossom GET and HEAD requests now verify the Blossom proof, validate corporate identity, enforce membership, and only then finalize the binding before accessing storage. Public media remains an intentional documented exemption.

[jmecom]

Re-reviewed the current head. The four prior blockers are addressed: JWT audience is required, corporate mode requires signed NIP-98 proof on the HTTP bridge, and corporate identity is enforced on moderation and protected media reads.

I also reviewed the staged/finalized authorization flow, atomic invite enrollment, revocation and rotation handling, session eviction, route inventory, and expiring desktop trust projection. I found no additional blocking issues.

[cea-block]

Closing, superseded by work by @wpfleger96