Tightens `docs/enterprise-identity-adapter.md` to define the enterprise
adapter contract implemented by kgoose in
[cash-server#132770](https://github.com/squareup/cash-server/pull/132770)
and the Buzz Desktop client in
[buzz-app#562](https://github.com/block/buzz-app/pull/562).
- Requires canonical `wss://host[:port]` relay URLs with a lowercase
scheme, the lowercase ASCII (A-label) host form with no trailing dot,
the default port omitted, and no trailing slash, path, query, or
fragment. Adapters MUST configure relays in canonical form, compare
`relay_url` against that exact form, and reject unknown relays with 403
`authorization_denied`.
- Requires NIP-98 proof freshness of at most 60 seconds old and at most
5 seconds in the future, with the proof bound to the endpoint, method,
and exact request body.
- Rejects content-encoded request bodies with 400 `invalid_request`.
- Caps assertions at `exp - iat <= 300` seconds and the adapter session
expiry, requires `typ` `nip-fi+jwt`, and validates the echoed
`nostr_pubkey`.
- Defines refusal and retry handling: Clients MUST retry 429 and 503
with bounded backoff whatever the `error` code. Clients MUST treat any
other status, a 400/401/403/413 response with a contract-undefined code,
or a rejected `200` response including one it cannot parse, as a
refusal: keep the session, show it as refused, and not retry
automatically. Network failures retry with bounded backoff.
This tightens the enterprise adapter contract restored in
[#8064](https://github.com/block/buzz/pull/8064).
---------
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Alia <d32955ad69077062930cc46cfe2df30ca9aaf6f8e76422681265e9e9af704d78@buzz.block.builderlab.xyz>
🤖 Restores `docs/enterprise-identity-adapter.md`, the vendor-neutral
HTTP contract between Buzz Desktop and an enterprise identity adapter,
and adds the request that turns an adapter session into a NIP-FI relay
assertion.
The login, code exchange, session check, transport, and privacy sections
are byte-for-byte the text from the head of #7715 (`4ef08e23`). Buzz
Desktop's enterprise login client
([buzz-app#525](https://github.com/block/buzz-app/pull/525)) already
calls those routes.
The new **Relay assertion** section defines `POST
/v1/identity/assertions`:
- **Request:** a JSON body with `relay_url` and `nostr_pubkey`. The
adapter session goes in `Authorization: Bearer`, and a NIP-98 proof
signed by that key, bound to the endpoint URL, method, and exact body
hash, goes in `Nostr-Authorization`. Clients and adapters must not log
either header's value.
- **Response:** `assertion`, `nostr_pubkey`, and `expires_at`. Under
this contract an assertion lives at most 5 minutes and never outlives
the adapter session; that cap is the adapter contract's rule, not a
relay constant. The assertion's `typ` and `aud` rules point to NIP-FI.
The assertion key must be the key that signs the NIP-42 relay login.
- **Denials:** a table of status, error code, meaning, and the client
action for each. A missing session is 401 `session_required`; missing or
repeated proof headers, a repeated `Authorization` header, multiple
session credential kinds, malformed bodies, and unknown fields are 400
`invalid_request`. 401s clear the session and return to login; 403
`authorization_denied` keeps the session and disconnects from that relay
without automatic retry; other 403s, 400, and 413 keep the session and
show the error without retry; 429, 503, and network failures retry with
bounded backoff. Adapters may return `session_required` for any invalid,
expired, or revoked credential, and clients handle both 401 codes
identically.
Agent keys are out of scope and need a separate design.
Related:
[cash-server#132756](https://github.com/squareup/cash-server/pull/132756)
implements this contract in kgoose.
---------
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: Duncan <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
