buzz/docs/enterprise-identity-adapter.md

# Enterprise identity adapter contract

Buzz Desktop learns that a relay requires enterprise identity from the relay's
NIP-11 `federated_identity` advertisement. Discovery deliberately contains no
issuer URL, tenant ID, audience, or vendor-specific login details; those stay in
operator-controlled Desktop build configuration.

When a trusted build connects to a trusted enterprise relay, Desktop speaks the
provider-neutral HTTP contract below to the configured enterprise identity
adapter. The adapter may use Auth0, Okta, SAML, LDAP, or another upstream
identity system behind this boundary. Desktop does not implement or depend on
that upstream protocol.

## Build configuration

Enterprise builds set:

- `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS`: comma-separated allowlist of relay URLs
  for which Desktop will honor NIP-FI enterprise login.
- `BUZZ_BUILD_ENTERPRISE_AUTH_ADAPTER_BASE_URL`: base URL of the adapter
  implementing this document. Remote adapter URLs must use HTTPS. Plaintext
  HTTP is accepted only for loopback development hosts (`localhost`,
  `127.0.0.0/8`, or `::1`). Required when the relay allowlist is set.
- `BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION`: optional `1`/`true` opt-in. When
  unset, adapter identity fields are private login state only and are never
  projected into a public Nostr profile.

Hosted-community Builderlab configuration is separate:

- `BUZZ_BUILD_BUILDERLAB_API_BASE_URL` continues to configure only Builderlab
  hosted-community management. It is not used for enterprise login.

## Browser login

Desktop starts a localhost callback and generates a high-entropy handoff secret.
It opens:

```text
GET {adapter_base}/v1/login/start?return_to={callback_url}&handoff_challenge={base64url(sha256(handoff_secret))}&handoff_challenge_method=S256
```

The adapter authenticates the user however the operator chooses, binds the
completed browser login to `handoff_challenge`, and redirects to the exact
`return_to` loopback callback. Desktop always supplies
`http://127.0.0.1:{ephemeral_port}/callback/{nonce}`; adapters should accept
loopback callbacks on any port as recommended by RFC 8252 §7.3 and reject
non-loopback callback hosts. Success redirects to:

```text
{callback_url}?code={single_use_code}
```

Failures may redirect to the same callback with `error` and optional
`error_description` query parameters. Desktop surfaces `error_description` when
present, otherwise `error`.

The code alone is not a credential. The adapter MUST accept it only when the
exchange presents the matching handoff secret. Browser navigation may follow the
adapter's identity-provider redirects; the non-browser adapter calls below must
not depend on redirect handling.

## Code exchange

Desktop exchanges the browser code with a no-redirect HTTP client. Any 3xx is
treated as a failed exchange so `{code, handoff_secret}` is never replayed to a
redirect target.

```http
POST /v1/login/exchange
Content-Type: application/json

{
  "code": "single-use-code-from-callback",
  "handoff_secret": "base64url-random-secret"
}
```

Success response:

```json
{
  "session_token": "opaque-adapter-session-token",
  "expires_at": "2026-09-23T21:00:00Z",
  "email": "employee@example.com",
  "profile_projection": {
    "username": "employee",
    "display_name": "Employee Name"
  }
}
```

`email` and `profile_projection` are optional. `profile_projection` is ignored by
Desktop unless `BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION` opts into publishing
those fields as the user's public Buzz profile. The exchange `expires_at` and a
later session-check `expires_at` must describe the same fixed adapter session;
Desktop rejects mismatched values during login so a code exchange cannot commit a
different session than the one verified by `/v1/session`.

## Session check

Desktop checks or reuses an in-memory enterprise adapter session with the same
no-redirect HTTP client. Any 3xx is treated as a failed session check so Bearer
session credentials are never replayed to a redirect target.

```http
GET /v1/session
Authorization: Bearer {session_token}
```

Success response uses the same shape as the exchange response except
`session_token` is omitted:

```json
{
  "expires_at": "2026-09-23T21:00:00Z",
  "email": "employee@example.com",
  "profile_projection": null
}
```

The adapter returns non-2xx when the token is invalid or expired. Desktop then
clears only the enterprise adapter session. Builderlab hosted-community state is
not affected.

## Relay assertion

Before connecting to a NIP-FI-protected relay, the client asks the adapter for a
short-lived NIP-FI assertion naming the Nostr key it will connect with. The
request carries two credentials: the adapter session, which proves who the user
is, and a NIP-98 proof, which proves the client controls the key.

```http
POST /v1/identity/assertions
Authorization: Bearer {session_token}
Nostr-Authorization: Nostr {base64-NIP-98-event}
Content-Type: application/json

{
  "relay_url": "wss://community.example.com",
  "nostr_pubkey": "<64-char lowercase hex public key>"
}
```

- `relay_url` selects an adapter-configured relay; the adapter never fetches it.
  Clients MUST send it in the canonical form `wss://host[:port]`, with the
  scheme in lowercase, the host as its lowercase ASCII (A-label) form with no
  trailing dot, the default port omitted, and no trailing slash, path, query, or
  fragment. Adapters MUST configure relays in this canonical form and MUST
  compare `relay_url` against it exactly.
  An unknown relay MUST be rejected with 403 `authorization_denied`.
- `nostr_pubkey` is the lowercase hex key the client will authenticate to the
  relay with. The NIP-98 event MUST be signed by this key, use kind `27235`,
  carry exactly one `u` tag equal to the absolute URL of this endpoint, a
  `method` tag of `POST`, and a `payload` tag equal to the lowercase hex SHA-256
  of the exact request body bytes. Its `created_at` MUST be no more than 60
  seconds old and MUST NOT be more than 5 seconds in the future.
- The request body is limited to 4096 bytes and MUST NOT be content-encoded. A
  content-encoded body, such as a gzipped body, MUST be rejected with 400
  `invalid_request`. Unknown fields are rejected.
- Clients and adapters MUST NOT log the values of the `Authorization` or
  `Nostr-Authorization` headers.

Success response (`200`, `Cache-Control: no-store`):

```json
{
  "assertion": "<compact-JWS-assertion>",
  "nostr_pubkey": "<64-char lowercase hex public key>",
  "expires_at": 1790000300
}
```

`expires_at` is the assertion `exp` as Unix seconds. Adapters MUST issue
assertions with `exp - iat <= 300` seconds and MUST NOT set `exp` later than the
adapter session's expiry. Clients MAY refuse an assertion with more than 300
seconds remaining when it arrives. The 5-minute cap is this contract's rule, not
a relay constant: the relay enforces the token `exp` and its own
deployment-configured `maximum_assertion_age`. The assertion itself follows
[NIP-FI](nips/NIP-FI.md): a dedicated assertion's protected `typ` MUST be exactly
`nip-fi+jwt`, and its `aud` MUST exactly match the canonical host URI of the
community the relay resolves from the connection's `Host`. The assertion's
`nostr_pubkey` MUST be the key that signs the NIP-42 relay login; the relay
rejects any other key. Clients MUST reject a response whose `nostr_pubkey`
differs from the key sent in the request.
A client that rejects a `200` response, including one it cannot parse, MUST
treat it as a refusal: keep the session, show it as refused, and not retry
automatically.

Denials return a JSON body `{"error": "<code>"}` with `Cache-Control: no-store`:

| Status | `error` | Meaning | Client action |
|---|---|---|---|
| 400 | `invalid_request` | Malformed body, unknown fields, a missing or repeated `Nostr-Authorization` header, a repeated `Authorization` header, or more than one kind of session credential | Keep the session, show the error, do not retry automatically |
| 401 | `session_required` | No adapter session was presented, or the presented one is not usable | Clear the adapter session and return to browser login |
| 401 | `session_expired` | The adapter session ended | Clear the adapter session and return to browser login |
| 403 | `authorization_denied` | The user or relay is not authorized for assertions | Keep the session, disconnect from that relay, show access denied, do not retry automatically; a manual retry or app restart asks again |
| 403 | `invalid_proof` | The NIP-98 proof failed verification | Keep the session, show the error, do not retry automatically |
| 403 | `binding_mismatch` | The adapter has bound this user to a different Nostr key | Keep the session, show the error, do not retry automatically |
| 413 | `request_too_large` | The body exceeds 4096 bytes | Keep the session, show the error, do not retry automatically |
| 429 | `rate_limited` | Too many requests | Keep the session, retry with bounded backoff |
| 503 | `issuance_unavailable` | The adapter could not issue an assertion | Keep the session, retry with bounded backoff |

Clients MUST retry 429 and 503 with bounded backoff whatever the `error` code.
Clients MUST treat any other status, or a 400/401/403/413 with a code this
contract does not define, as a refusal: keep the session, show it as refused,
and not retry automatically.

A missing session is always 401 `session_required`, never 400. Network failures
are handled like 429 and 503: keep the session and retry with bounded backoff.

An invalid, expired or revoked credential may return `session_required`;
adapters that distinguish ended sessions may return `session_expired`. Clients
handle both identically.

Assertions for agent keys are not covered by this contract yet and need a
separate design.

## NIP-FI assertion transport

The adapter session header above is only for Desktop↔adapter account/session
requests. It is not the relay's NIP-FI proof transport.

When Desktop (or another Buzz client) later accesses a NIP-FI-protected relay or
HTTP route, the relay proof uses the NIP-FI headers defined by
[docs/nips/NIP-FI.md](nips/NIP-FI.md):

```http
Authorization: Nostr <base64-NIP-98-event>
Nostr-Federated-Identity: Bearer <compact-JWS-assertion>
```

That separation is intentional: `Authorization: Bearer <session_token>` belongs
to the enterprise identity adapter, while relay proof keeps the NIP-98 event in
`Authorization` and carries the identity assertion in `Nostr-Federated-Identity`.
The public contract MUST NOT use `Authorization` for both an adapter session and
a NIP-FI assertion on the same request, and MUST NOT use Builderlab-specific
`X-BB-Session-Credential` or `Authorization: BBIdentity` schemes.

## Privacy

NIP-FI defines no public identity projection. Adapter responses are private login
state by default. Operators that want managed public profiles must make that a
build-time policy choice and provide explicitly publishable `profile_projection`
fields; raw upstream claims, legal names, emails, issuer identifiers, subjects,
and assertion contents must not be written to public Nostr events implicitly.