buzz/docs/CORPORATE_IDENTITY.md

# Corporate identity

Corporate identity is an optional relay policy enabled with
`BUZZ_REQUIRE_CORPORATE_IDENTITY=true`. The relay verifies an asymmetric JWT
after the request proves control of a Nostr key, then admits the request only
when the existing community policy also succeeds.

## Required JWT policy

- `BUZZ_CORPORATE_IDENTITY_JWKS_URI` must be HTTPS and contain no credentials.
- JWTs must have a supported asymmetric algorithm, a `kid`, and valid `exp`,
  `iss`, and `aud` claims. A present `nbf` claim is enforced.
- `BUZZ_CORPORATE_IDENTITY_NPUB_CLAIM`, when configured, is mandatory and must
  equal the authenticated Nostr key. Leaving it unset enables first-use
  uid-to-key enrollment in the private binding table.
- JWKS requests have connect and total timeouts, reject redirects, cap the
  response at 1 MiB, cache keys for five minutes, and coalesce refreshes.

`BUZZ_REQUIRE_CORPORATE_IDENTITY` and
`BUZZ_ALLOW_CORPORATE_IDENTITY_DELEGATION` are strict booleans. Misspellings and
non-UTF-8 values stop configuration loading instead of silently disabling a
gate.

## Binding and revocation lifecycle

JWT validation is read-only. The relay creates or refreshes a binding only
after admission, allowlist, role, and community membership checks succeed.
Invite claims commit the binding, membership, policy evidence, and invite use
in one PostgreSQL transaction.

Revocation has three explicit meanings:

- `principal` disables every key for an issuer-qualified uid. Normal
  authentication cannot re-enroll the principal with another key.
- `key` revokes one key but does not silently authorize a replacement.
- `rotation` is the audit state written by an explicit atomic old-key to
  new-key rotation.

WebSocket and audio sessions revalidate the authoritative binding at least
every 30 seconds. Direct sessions also close at JWT expiry. Delegated sessions
check the owner's binding, so disabling an owner evicts the owner's agents as
well as the direct owner session.

Corporate NIP-OA delegation is transport-wide and therefore accepts only an
empty conditions string. Conditional tags must be evaluated for a specific
operation and are not treated as blanket corporate identity authority.

## Privacy and public assertions

`BUZZ_CORPORATE_IDENTITY_DISPLAY_CLAIM` is private. Its default (`email`) is
stored only in the community-scoped binding table and audit data; it is not
published to Nostr.

Public projection is separately opt-in with
`BUZZ_CORPORATE_IDENTITY_PUBLIC_DISPLAY_CLAIM`. When set, that claim is
published as a relay-signed NIP-85 label. Assertions carry both `active=true`
and an `expiration` no later than one hour or the JWT's expiry, whichever comes
first. Clients require the relay signature, active status, and a future
expiration. Removing the opt-in publishes an inactive replacement only when a
prior public assertion exists.

NIP-85 events are replaceable relay events and may also remain in downstream
caches or archives after replacement. Operators must choose a non-sensitive,
user-approved public label and account for that retention when configuring the
public claim.

## Route policy

Corporate identity applies to authenticated WebSocket and audio connections,
the NIP-98 event/query/count bridge, moderation reads, invite mint and claim,
Git smart HTTP, media uploads, and protected media reads.

Intentional exemptions are public media reads when media GET authentication is
disabled, health/readiness/metrics endpoints, NIP-11 and NIP-05 discovery,
operator and admin control planes with their own authentication, secret-backed
workflow hooks, public join-policy documents, invite policy-acceptance
callbacks, and static local web callbacks. These exemptions must remain in the
central route-policy test matrix when routes change.