Skip to content

Commit a918e60

Browse files
wpfleger96Duncan
andauthored
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 <[email protected]> Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
1 parent 7afdc2a commit a918e60

3 files changed

Lines changed: 247 additions & 245 deletions

File tree

‎docs/enterprise-identity-adapter.md‎

Lines changed: 0 additions & 245 deletions
This file was deleted.

‎docs/federated-identity-adapter.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Federated Identity Adapter: Desktop implementation guide
2+
3+
Buzz Desktop learns that a relay requires enterprise identity from the relay's
4+
NIP-11 `federated_identity` advertisement. Discovery deliberately contains no
5+
issuer URL, tenant ID, audience, or vendor-specific login details; those stay in
6+
operator-controlled Desktop build configuration.
7+
8+
When a trusted build connects to a trusted enterprise relay, Desktop is planned to speak the
9+
HTTP contract defined in [NIP-FA](nips/NIP-FA.md) (Federated Identity Adapter)
10+
to the configured adapter. This guide covers only Desktop build configuration
11+
and Desktop behavior; the wire contract lives in the NIP.
12+
13+
## Build configuration
14+
15+
Enterprise builds set:
16+
17+
- `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS`: comma-separated allowlist of relay URLs
18+
for which Desktop will honor NIP-FI enterprise login.
19+
- `BUZZ_BUILD_ENTERPRISE_AUTH_ADAPTER_BASE_URL`: base URL of the adapter
20+
implementing NIP-FA. Remote adapter URLs must use HTTPS. Plaintext
21+
HTTP is accepted only for loopback development hosts (`localhost`,
22+
`127.0.0.0/8`, or `::1`). Required when the relay allowlist is set.
23+
- `BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION`: optional `1`/`true` opt-in. When
24+
unset, adapter identity fields are private login state only and are never
25+
projected into a public Nostr profile. This is the operator opt-in described
26+
in NIP-FA's Privacy section.
27+
28+
## Desktop behavior
29+
30+
Buzz Desktop's client is implemented in
31+
[block/buzz-app](https://github.com/block/buzz-app).
32+
33+
### Implemented
34+
35+
- Build configuration: `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS` and
36+
`BUZZ_BUILD_ENTERPRISE_AUTH_ADAPTER_BASE_URL`.
37+
- Discovery gate: Desktop honors a relay's NIP-11 `federated_identity`
38+
advertisement only for relays in `BUZZ_BUILD_ENTERPRISE_AUTH_RELAYS`.
39+
40+
### Planned
41+
42+
- Browser login callback: Desktop always supplies
43+
`http://127.0.0.1:{ephemeral_port}/callback/{nonce}`.
44+
- Adapter session: Desktop checks or reuses an in-memory enterprise adapter
45+
session.
46+
- Browser login failures: Desktop surfaces the callback's `error_description`
47+
when present, otherwise `error`.
48+
- Session check failure: on 401 `session_required` or `session_expired`,
49+
Desktop clears only the enterprise adapter session; other failures keep it.
50+
Builderlab hosted-community state is not affected.
51+
- `BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION` is not read yet. Once it is,
52+
`profile_projection` is ignored unless
53+
`BUZZ_BUILD_ENTERPRISE_PROFILE_PROJECTION` opts into publishing those fields
54+
as the user's public Buzz profile.
55+
- Assertion fetch: Desktop requests a NIP-FA assertion before connecting to an
56+
enterprise relay.
57+
58+
## Vendor-specific headers
59+
60+
NIP-FA adapter sessions use only `Authorization: Bearer`. Desktop and adapters
61+
must not send or accept the Builderlab-specific `X-BB-Session-Credential`
62+
header or `Authorization: BBIdentity` scheme as adapter session credentials.

0 commit comments

Comments
 (0)