mirror of
https://github.com/block/buzz.git
synced 2026-11-03 07:51:22 +00:00
a918e605ca
🤖 Moves the enterprise identity adapter's wire contract into a new normative spec, `docs/nips/NIP-FA.md` (Federated Identity Adapter), so third-party adapters have a spec to conform to. The Desktop-only material stays in a guide, renamed from `docs/enterprise-identity-adapter.md` to `docs/federated-identity-adapter.md` to match the NIP's name. - `NIP-FA.md` holds browser login, code exchange, session check, relay assertion (including the denial table), NIP-FI assertion transport, security considerations, and privacy. Agent-key assertions are out of scope. - `docs/federated-identity-adapter.md` is a short Desktop guide for the client in block/buzz-app: build configuration (`BUZZ_BUILD_ENTERPRISE_AUTH_*`), what is implemented today (build config, discovery gate) versus planned (browser login, session check, assertion fetch, profile projection), and the vendor-specific headers adapters must not use as session credentials. Endpoints, fields, headers, and denial codes are unchanged. The NIP converts lowercase requirements to BCP 14 keywords and pins rules the old guide left open: - `/v1/session` reports a bad session as 401 `session_required` / `session_expired`; clients discard the session only on those, and keep it and retry with backoff on 429, 5xx, and network failures, matching the assertion endpoint. - The assertion `aud` is `https://` plus the canonical `relay_url` authority (`wss://c.example.com:8443` → `https://c.example.com:8443`), and adapters issue dedicated `nip-fi+jwt` assertions. Relay authorities on port 80 are not supported. - Codes are single-use and short-lived, only `S256` challenges are accepted, and adapters accept only `127.0.0.1` and `[::1]` callback hosts. - After code exchange the client must call `/v1/session` and compare the RFC 3339 `expires_at` instants before committing the login. - `session_token` is sent only to adapter endpoints, never to a relay, and no credential is logged. - NIP-98 proofs carry exactly one `method` and one `payload` tag; retries honor `Retry-After` and surface failure after bounded attempts; IPv6 relay hosts have a canonical form. - The relay-proof header example is scoped to NIP-98-protected HTTP, with WebSocket (NIP-42 AUTH) and Blossom (kind 24242) deferred to NIP-FI. --------- Signed-off-by: Will Pfleger <pfleger.will@gmail.com> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# Federated Identity Adapter: Desktop implementation guide
|
|
|
|
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 is planned to speak the
|
|
HTTP contract defined in [NIP-FA](nips/NIP-FA.md) (Federated Identity Adapter)
|
|
to the configured adapter. This guide covers only Desktop build configuration
|
|
and Desktop behavior; the wire contract lives in the NIP.
|
|
|
|
## 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 NIP-FA. 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. This is the operator opt-in described
|
|
in NIP-FA's Privacy section.
|
|
|
|
## Desktop behavior
|
|
|
|
Buzz Desktop's client is implemented in
|
|
[block/buzz-app](https://github.com/block/buzz-app).
|
|
|
|
### Implemented
|
|
|
|
- Build configuration: `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS` and
|
|
`BUZZ_BUILD_ENTERPRISE_AUTH_ADAPTER_BASE_URL`.
|
|
- Discovery gate: Desktop honors a relay's NIP-11 `federated_identity`
|
|
advertisement only for relays in `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS`.
|
|
|
|
### Planned
|
|
|
|
- Browser login callback: Desktop always supplies
|
|
`http://127.0.0.1:{ephemeral_port}/callback/{nonce}`.
|
|
- Adapter session: Desktop checks or reuses an in-memory enterprise adapter
|
|
session.
|
|
- Browser login failures: Desktop surfaces the callback's `error_description`
|
|
when present, otherwise `error`.
|
|
- Session check failure: on 401 `session_required` or `session_expired`,
|
|
Desktop clears only the enterprise adapter session; other failures keep it.
|
|
Builderlab hosted-community state is not affected.
|
|
- `BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION` is not read yet. Once it is,
|
|
`profile_projection` is ignored unless
|
|
`BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION` opts into publishing those fields
|
|
as the user's public Buzz profile.
|
|
- Assertion fetch: Desktop requests a NIP-FA assertion before connecting to an
|
|
enterprise relay.
|
|
|
|
## Vendor-specific headers
|
|
|
|
NIP-FA adapter sessions use only `Authorization: Bearer`. Desktop and adapters
|
|
must not send or accept the Builderlab-specific `X-BB-Session-Credential`
|
|
header or `Authorization: BBIdentity` scheme as adapter session credentials.
|