jerry/buzz

mirror of https://github.com/block/buzz.git synced 2026-10-27 04:30:52 +00:00

Files

Will Pfleger a918e605ca docs(nips): add NIP-FA federated identity adapter spec (#8148 )

🤖 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>

2026-10-08 13:20:26 -04:00

2.8 KiB

Raw Blame History

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 (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.

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.

2.8 KiB Raw Blame History