Skip to content

Commit 447951a

Browse files
wpfleger96Hayt
andauthored
🤖 docs(nip-fi): remove implementation references from the spec (#7912)
This removes implementation references and implementation status from `docs/nips/NIP-FI.md` so the spec holds normative text only. It drops the Blossom compliance note, the known-gap notes, crate/file paths and PR numbers, roadmap "supersedes" sentences, doc-history lines, and the design-rationale note on session-only vs deny-until-TTL (its restart re-push SHOULD remains stated normatively elsewhere). Two wording changes carry normative weight: `PUT /media/upload` is listed as a plain kind-24242 upload route instead of a temporary alias, and the JWKS fetcher's SSRF controls become a MUST instead of a description. It doesn't depend on any enforcement PR and can merge at any time. Related: #7265 --------- Signed-off-by: Will Pfleger <[email protected]> Co-authored-by: Hayt <211b96e6a2b7f45fd4047988976c7bbbeeda0c15f3ae7b32eec20834b5a55118@buzz.block.builderlab.xyz>
1 parent ebe99a4 commit 447951a

1 file changed

Lines changed: 12 additions & 64 deletions

File tree

‎docs/nips/NIP-FI.md‎

Lines changed: 12 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -190,15 +190,15 @@ community configuration is missing or unavailable.
190190

191191
### Multi-issuer registry
192192

193-
The global [`IssuerRegistry`](../../crates/buzz-auth/src/nip_fi/config.rs) remains
193+
The global `IssuerRegistry` remains
194194
shared for issuer policy and JWKS lookup; community authorization is a separate
195195
deployment mapping from canonical host URI to
196196
`(expected_aud, authorized_issuers)`. `VerifyAssertion` consumes the
197197
Host-resolved mapping, so a globally known issuer is not implicitly trusted by
198198
every community.
199199

200200
The `nostr_pubkey` claim is unconditionally required — absence rejects
201-
regardless of issuer policy (NIP-FI v2, PR #7221).
201+
regardless of issuer policy.
202202

203203
### JWKS snapshot
204204

@@ -396,40 +396,6 @@ specified below is the recovery path for lost propagation, exactly as for relay
396396
restart. A success response from the receiving process does not imply
397397
cluster-wide application.
398398

399-
> **Note — adopted position (session-only vs deny-until-TTL):**
400-
>
401-
> The session-only model closes existing connections but places no
402-
> protocol-level bound on reconnection. For session-only, if the issuer also
403-
> stops issuing new assertions after a disconnect call, cumulative residual
404-
> access is bounded by:
405-
>
406-
> ```
407-
> max(0, min(exp, iat + maximum_assertion_age) - now)
408-
> ```
409-
>
410-
> `max_connection_lifetime_seconds` only partitions that interval into
411-
> individual sessions; it does not shorten the total window. If the issuer
412-
> continues issuing new assertions, cumulative access extends indefinitely.
413-
>
414-
> The **deny-until-TTL** model closes this reconnect window. The relay holds a
415-
> memory-resident deny set keyed by `(iss, pubkey)`, with absolute expiry
416-
> carried by the issuer as `until` in the disconnect command. Any admission
417-
> attempt for that key is denied until the entry expires. The issuer must boot
418-
> the deny TTL to outlast the longest live assertion it may have already
419-
> issued; otherwise an unexpired assertion lets the client back in the moment
420-
> the entry expires.
421-
>
422-
> The deny set is RAM-cache, not a database — the same operational posture as
423-
> the JWKS snapshot. A relay restart clears the set; the issuer, as the
424-
> durable system of record for revocations, SHOULD re-push still-active denies
425-
> when it observes a relay restart (same publish/cache pattern as JWKS). A
426-
> fresh relay MAY consult the issuer before first admissions to close the
427-
> startup race; this is non-normative.
428-
>
429-
> This design was chosen because session-only disconnection must outlast
430-
> the live socket to mean anything as a revocation primitive; a self-expiring
431-
> RAM entry preserves the zero-persistence guarantee while closing the window.
432-
433399
### Transport
434400

435401
The disconnect endpoint is an authenticated issuer→relay API, not a public
@@ -515,7 +481,7 @@ VerifyCommandJwt(token, request_method, request_path, request_body_pubkey):
515481
// leaves neither behind: the jti is not burned, and the caller may safely
516482
// retry the same signed command. Performing the jti reservation alone
517483
// (without the deny-entry insertion) would burn the command identity on a
518-
// capacity failure, making the new 503 contract unimplementable. Capacity
484+
// capacity failure, making the 503 contract unimplementable. Capacity
519485
// is checked against the per-issuer bound for claims.iss; a different
520486
// issuer's capacity exhaustion does not produce a 503 here.
521487
// On same-key collision: retain max(existing_until, until) — never shorten
@@ -535,9 +501,6 @@ VerifyCommandJwt(token, request_method, request_path, request_body_pubkey):
535501
Any failure at any step is fail-closed: no side effects occur and the relay
536502
returns the appropriate error.
537503

538-
This verifier and the disconnect API endpoint are follow-on code changes
539-
outside this PR.
540-
541504
### Request
542505

543506
```text
@@ -620,10 +583,9 @@ to all three requirements on all three endpoints, including both POST
620583
endpoints; it is not a payload-only exemption.
621584

622585
This exemption is required by Git's credential protocol. The credential helper
623-
receives only credential metadata and never sees request bodies
624-
(`crates/git-credential-nostr/src/lib.rs:98-132`), so a body hash cannot exist
625-
in the signed event. This limitation is architectural to Git's credential
626-
protocol.
586+
receives only credential metadata and never sees request bodies, so a body
587+
hash cannot exist in the signed event. This limitation is architectural to
588+
Git's credential protocol.
627589

628590
The NIP-FI assertion and pairing requirement is unchanged and applies per
629591
request on every one of these endpoints. Each request MUST still carry and
@@ -645,8 +607,7 @@ The following compensating controls are REQUIRED for this proof pattern:
645607
7. Every push MUST pass pre-receive hook push authorization.
646608

647609
This exemption applies solely to the Git credential-helper proof pattern on
648-
these three endpoints. It is not a precedent for any other surface. A client
649-
change that enables per-request signing supersedes this exemption.
610+
these three endpoints. It is not a precedent for any other surface.
650611

651612
### Media possession-proof exception (Blossom, kind 24242)
652613

@@ -656,16 +617,15 @@ alternative possession format — not a general "signed Nostr event" escape hatc
656617
and not precedent for any other surface. Any future alternative proof format
657618
requires an explicit axis-by-axis security review covering: payload/resource
658619
binding, method/operation scope, audience/tenant scope, freshness, signature/key
659-
pairing, transport cardinality, and cross-endpoint replay. Per-request NIP-98
660-
support supersedes this exception when available.
620+
pairing, transport cardinality, and cross-endpoint replay.
661621

662622
#### Scope fence
663623

664624
Kind-24242 proofs are valid **only** on the following routes and operations:
665625

666626
| Proof type (`t` tag) | Valid route | Method |
667627
|---|---|---|
668-
| `upload` | `PUT /upload` (and temporary alias `PUT /media/upload` until that alias is removed) | PUT |
628+
| `upload` | `PUT /upload`, `PUT /media/upload` | PUT |
669629
| `get` | `GET /media/{hash…}`, `HEAD /media/{hash…}` | GET, HEAD |
670630

671631
No other protected route may accept a kind-24242 proof. A kind-24242 event
@@ -738,17 +698,6 @@ requirement: full assertion verification, exact key equality between the
738698
assertion's `nostr_pubkey` claim and the kind-24242 event's public key, and
739699
deny-map enforcement (see Admission procedure, steps 1–6).
740700

741-
The effectiveness of deny-map enforcement is contingent on the real
742-
issuer-scoped deny map. Until that map is operational, the stub implementation
743-
constitutes a **known gap** in this section's security guarantees.
744-
745-
#### Compliance note
746-
747-
The implementation as of PR #7264 pairs via a permissive Blossom verifier and
748-
is explicitly non-compliant with this section. The named gaps are:
749-
multi-tag acceptance, a 3600-second proof window, and an optional `server`
750-
tag. These are resolved when the bounded hardening task lands.
751-
752701
### Request format
753702

754703
Each protected HTTP request MUST present both of the following:
@@ -868,7 +817,6 @@ normative behavior for them:
868817
- Directory integration and account-offboarding automation: issuer-side.
869818
- Audit logging beyond what the relay operator chooses to retain: issuer-side.
870819
- Delegation: out of scope.
871-
- Companion profiles (NIP-FI-EDGE, NIP-FI-LIFECYCLE, NIP-FI-DELEG, NIP-FI-CONF, NIP-FI-MODEL): removed.
872820

873821
## Discovery
874822

@@ -979,10 +927,10 @@ gap by requiring assertion verification on every protected HTTP request.
979927
The per-request re-verification model means there is no cached admission
980928
window; a deny-set entry takes effect on the very next request.
981929

982-
**SSRF.** The JWKS fetcher implements SSRF protection: HTTPS-only URI
930+
**SSRF.** The JWKS fetcher MUST enforce SSRF protection: HTTPS-only URI
983931
validation, DNS resolution with IP deny-list enforcement, address pinning to
984-
prevent DNS rebinding TOCTOU, and redirect denial. The complete IANA
985-
Special-Purpose address deny table is implemented; see `crates/buzz-core/src/network.rs`.
932+
prevent DNS rebinding TOCTOU, and redirect denial. The IP deny-list covers
933+
the complete IANA Special-Purpose address registry.
986934

987935
**Issuer compromise.** A compromised assertion issuer can impersonate any
988936
identity but cannot prove possession of the assertion-named Nostr key. The NIP-42

0 commit comments

Comments
 (0)