Skip to content

Commit 56e7414

Browse files
author
Eva
committed
docs(nip-fi): resolve contradictions between the spec, its own rules, and the deployed wire
External line-by-line review against the implementation found compositions no internal-consistency pass could see: rules that contradict each other across documents, and registry text that denies the wire the deployed proxy actually signs. Every reading failed closed, but a correct implementation could not be built from the text alone. Fixes, one per defect: - EDGE strip rule no longer removes the NIP-98 proof: requirement 1 named "authorization" among the fields every trusted edge strips, while core reserves the Authorization header for the NIP-98 proof that must reach final admission. The rule now names the three NIP-FI fields plus other edge profiles' fields, explicitly preserves Authorization, and a negative conformance sentence makes stripping or rewriting it nonconformant. - Proof-transport codes 0x03 (Git smart-HTTP session) and 0x04 (Blossom media) are reserved with fixed meanings: the deployed proxy emits both inside the MAC input, and the registry declared them unassigned, so a conforming verifier denied every Git and Blossom envelope. Allocation completes when each transport contract is published; until then the codes are valid only under an explicit shared proxy/verifier contract and are not portable interoperability. - Replay moves from evidence_rejected to authorization_denied: replay status is committed per-principal server state, so classing it as evidence rejection contradicted the supplied-evidence privacy rule and let an attacker resubmit captured evidence to learn whether the original request committed. The CONF fixture table mirrors the move. - The current-status witness match now requires issuer equality: the witness tuple carried iss but the match rule checked only subject and session, so on a shared status source an issuer-B witness could satisfy a pre-revocation issuer-A assertion. The stale-status oracle gains the mismatch arm. - The interoperability exit test is deferrable while no independent implementation exists (machine-readable reason, re-evidenced when the second implementation claims), and the canonical shared exit fixture gains provenance: editor-authored, published at docs/nips/fixtures/nip-fi-conf-exit.json with its SHA-256 digest. A required gate no implementation could ever pass was, by this document's own standard, a defect in the document. - The "RFC 9068 access token" class is renamed at+jwt access token at all three sites: it selects on typ and aud and validates under this document's claim contract, not the full RFC 9068 profile. - EDGE states the unbound-body-metadata rule directly instead of by cross-document inference, and the negative matrix gains the Content-Type/Content-Encoding mutation row. - Absent or incomplete edge provenance maps to missing_evidence; present but failing provenance maps to evidence_rejected. The CONF fixture table gains the absent-provenance row; rows are renumbered, which is safe because CONF itself requires that no text reference rows by number. - A payload tag on an authorization-irrelevant body is validated identically, closing a verifier divergence the text left open. Oracle census is unchanged at 58 (30 core, 6 EDGE, 11 LIFECYCLE, 7 DELEG, 4 CONF): the two table additions are a negative-matrix row and a denial-fixture row, neither in the oracle denominator. One review item (equivalence classification of revalidation dependencies) is deliberately not in this commit pending model verification that the reclassification opens no authority-extension path. Co-authored-by: Eva <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz> Signed-off-by: Eva <011987e296fd5006292d2f930b574be47c7801048d1983c46c425d3c95f0cffd@buzz.block.builderlab.xyz>
1 parent 4f913a8 commit 56e7414

3 files changed

Lines changed: 93 additions & 35 deletions

File tree

‎docs/nips/NIP-FI-CONF.md‎

Lines changed: 37 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,9 @@ different text: a claim that does not name the revision it was judged against
5252
is unfalsifiable once the specification moves, and a suite that does not name
5353
its fixture cannot be shown to have run the pinned inputs. A report contains
5454
every applicable oracle from core and every claimed profile exactly once, with
55-
status `pass` or `not-applicable` only. Blank, skipped, expected-failure, and
55+
status `pass` or `not-applicable` only, except that `FI-CONF-INTEROP-EXIT`
56+
alone may instead carry `deferred` under the condition defined in
57+
**Interoperability exit test**. Blank, skipped, expected-failure, and
5658
not-run results cannot support a claim (`FI-CONF-CLAIM-COMPLETE`).
5759

5860
Enrollment mode is part of the claim unit and is private. It is recorded in the
@@ -111,19 +113,21 @@ which owns that mapping and the exact response bytes.
111113
| # | Private condition | Public class | Defined by |
112114
|---|---|---|---|
113115
| 1 | assertion, proof, or delegation evidence absent | `missing_evidence` | core |
114-
| 2 | evidence present but rejected: signature, key selection, issuer, audience, time, size, ambiguity, token class, body binding, or edge provenance/replay | `evidence_rejected` | core, NIP-FI-EDGE |
115-
| 3 | `key_mismatch` — asserted key is not the proven actor | `authorization_denied` | core |
116-
| 4 | `attestation_required` — attested-key enrollment without a matching key claim | `authorization_denied` | core |
117-
| 5 | `binding_conflict` — either side of the active relation is taken | `authorization_denied` | core |
118-
| 6 | `pair_retired` | `authorization_denied` | core |
119-
| 7 | `key_revoked` | `authorization_denied` | core |
120-
| 8 | `policy_denied` — local operation policy | `authorization_denied` | core |
121-
| 9 | `binding_required` — enrollment policy creates no binding at this request: provisioned mode with no binding, or any unrecognized policy value | `authorization_denied` | core |
122-
| 10 | `identity_disabled` | `authorization_denied` | NIP-FI-LIFECYCLE |
123-
| 11 | `explicit_replacement_required` — pending lineage | `authorization_denied` | NIP-FI-LIFECYCLE |
124-
| 12 | `binding_expired` — administrative expiry | `authorization_denied` | NIP-FI-LIFECYCLE |
125-
| 13 | `delegation_not_current` — owner or relationship no longer current | `authorization_denied` | NIP-FI-DELEG |
126-
| 14 | `dependency_unreadable` | `authorization_unavailable` | core |
116+
| 2 | edge provenance absent or incomplete on an edge-required route (assertion may be present) | `missing_evidence` | NIP-FI-EDGE |
117+
| 3 | evidence present but rejected: signature, key selection, issuer, audience, time, size, ambiguity, token class, body binding, or edge provenance (present but rejected) | `evidence_rejected` | core, NIP-FI-EDGE |
118+
| 4 | replayed evidence — committed replay identity already claimed | `authorization_denied` | core, NIP-FI-EDGE |
119+
| 5 | `key_mismatch` — asserted key is not the proven actor | `authorization_denied` | core |
120+
| 6 | `attestation_required` — attested-key enrollment without a matching key claim | `authorization_denied` | core |
121+
| 7 | `binding_conflict` — either side of the active relation is taken | `authorization_denied` | core |
122+
| 8 | `pair_retired` | `authorization_denied` | core |
123+
| 9 | `key_revoked` | `authorization_denied` | core |
124+
| 10 | `policy_denied` — local operation policy | `authorization_denied` | core |
125+
| 11 | `binding_required` — enrollment policy creates no binding at this request: provisioned mode with no binding, or any unrecognized policy value | `authorization_denied` | core |
126+
| 12 | `identity_disabled` | `authorization_denied` | NIP-FI-LIFECYCLE |
127+
| 13 | `explicit_replacement_required` — pending lineage | `authorization_denied` | NIP-FI-LIFECYCLE |
128+
| 14 | `binding_expired` — administrative expiry | `authorization_denied` | NIP-FI-LIFECYCLE |
129+
| 15 | `delegation_not_current` — owner or relationship no longer current | `authorization_denied` | NIP-FI-DELEG |
130+
| 16 | `dependency_unreadable` | `authorization_unavailable` | core |
127131

128132
The names in the private-condition column are fixture identifiers for this
129133
enumeration. Some are the symbols core's preparation pseudocode denies by name;
@@ -333,6 +337,13 @@ produce equal bytes however correct both are, so the run is parameterized by a
333337
- one frozen evaluation instant, and the skew and lifetime bounds in force; and
334338
- the domain, target resource, operation, and enrollment policy for each case.
335339

340+
The canonical shared exit fixture is authored by this document's editors, not
341+
by any claiming implementation, and is published as a single file in the same
342+
repository as these documents, at `docs/nips/fixtures/nip-fi-conf-exit.json`,
343+
together with its SHA-256 digest. Both sides MUST load that file, MUST verify
344+
the digest before the run, and MUST record the digest with the evidence. A run
345+
against any other fixture instance is not `FI-CONF-INTEROP-EXIT` evidence.
346+
336347
**Request compared object.** A minted request cannot be compared as bytes. Two
337348
conforming implementations may produce different signature octets for the same
338349
semantic input — randomized `ES256` and BIP-340 with fresh auxiliary input do,
@@ -381,6 +392,14 @@ would reject conforming pairs; the exit test itself is then the defect. The
381392
control is retained with the evidence, because a comparison that only ever
382393
reports equality proves nothing about what it would have caught.
383394

395+
`FI-CONF-INTEROP-EXIT` is REQUIRED only once a second implementation meeting
396+
the independence conditions above exists. Until one exists the test cannot be
397+
run, and a conformance claim MUST instead record it as deferred with the
398+
machine-readable reason `no-independent-implementation`. A deferred exit test
399+
MUST be run and passed before the second implementation's conformance claim is
400+
accepted, and the first implementation's claim MUST be re-evidenced against
401+
that run.
402+
384403
## Applicability
385404

386405
`not-applicable` requires a machine-readable reason and behavioral proof that
@@ -414,7 +433,9 @@ that the protected-ingress inventory has no uncovered or competing authority;
414433
that every listed oracle has a killed, attributed, reachable mutant and every
415434
survivor is recorded; that the denial-fixture enumeration is complete for the
416435
claimed profiles and its negative control fails as required; that the
417-
interoperability exit test has passed against an independent implementation;
436+
interoperability exit test has passed against an independent implementation, or
437+
is recorded as deferred under **Interoperability exit test** because no
438+
independent implementation exists;
418439
that every named deployment artifact exists at the claimed deployment revision;
419440
and that public and operational sinks pass privacy-canary inspection.
420441

@@ -425,7 +446,7 @@ They close no item in this gate.
425446

426447
| ID | Required outcome |
427448
|---|---|
428-
| `FI-CONF-CLAIM-COMPLETE` | A report missing an applicable oracle, duplicating one, carrying a result from another claim tuple, or claiming a status other than `pass`/`not-applicable` is rejected. |
449+
| `FI-CONF-CLAIM-COMPLETE` | A report missing an applicable oracle, duplicating one, carrying a result from another claim tuple, or claiming a status other than `pass`/`not-applicable` — or `deferred` on any oracle other than `FI-CONF-INTEROP-EXIT` — is rejected. |
429450
| `FI-CONF-DENIAL-FIXTURES` | Every enumerated private condition has a fixture; core and each claimed profile pass exact identifier/class/owner enumeration agreement; anonymity-set responses compare byte-identical; the distinguishing negative control fails. |
430451
| `FI-CONF-MUTATION` | Every listed oracle has a singly-applied, attributed, reachability-witnessed mutant killed by that entry's own oracle; survivors are recorded, not waived. |
431452
| `FI-CONF-INTEROP-EXIT` | Two independent implementations produce, from the documents alone, valid requests equal over the request compared object and per-class denials equal over the denial compared object, and accept each other's output. |

‎docs/nips/NIP-FI-EDGE.md‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,12 @@ fallback to `client-attached` or another edge profile.
3737

3838
Every trusted edge MUST:
3939

40-
1. strip every inbound copy of each assertion, identity, authorization, capability,
41-
provenance, and client-peer field before inserting its own fields;
40+
1. strip every inbound copy of each `Nostr-Federated-Identity`,
41+
`Nostr-Federated-Identity-Provenance`, and `Nostr-Federated-Identity-Client-Peer`
42+
field, and of every other edge profile's assertion, identity, capability,
43+
provenance, and client-peer field, before inserting its own fields. A trusted
44+
edge MUST NOT remove or modify the `Authorization` field, which remains reserved
45+
for the independent NIP-98 proof and MUST reach final admission unmodified;
4246
2. cryptographically authenticate the immediate edge to the accepting origin and
4347
isolate the origin from direct or alternate ingress;
4448
3. integrity-protect every request component used by authorization;
@@ -55,7 +59,10 @@ Every trusted edge MUST:
5559
Header presence, source address, private-network location, hostname, or reachability
5660
alone is not provenance. Accepting unsigned identity or capability headers, or
5761
accepting signed headers without authenticating and isolating the immediate caller,
58-
is nonconformant.
62+
is nonconformant. A trusted edge that strips, rewrites, or reorders the
63+
`Authorization` field, or that admits a proof-transport-`0x02` request whose
64+
`Authorization` field did not arrive at the verifier byte-identical to the
65+
client-sent value, is nonconformant.
5966

6067
An adapter's reviewed contract MUST identify its accepting origins, direct-origin
6168
controls, field-stripping point, immediate-caller authentication, protected request
@@ -161,6 +168,11 @@ time.
161168
- **Proof transport:** Serialize exactly one assigned octet from the registry below.
162169
- **Client peer:** Serialize the exact canonical ASCII field value.
163170

171+
No authorization decision, target, resource, capability, or effect selector
172+
derives from any request component outside the protected pre-MAC components;
173+
body interpretation follows the server-resolved body semantics, never
174+
unprotected transport metadata such as `Content-Type` or `Content-Encoding`.
175+
164176
### Freshness, replay, and key rotation
165177

166178
The deployment configures a positive finite `maximum_provenance_age` and a
@@ -177,6 +189,11 @@ Equality at the age bound is expired. A direct lease deadline is no later than
177189
state deadline.
178190

179191
Absent, malformed, stale, future-dated, wrong-key, or mismatched provenance denies.
192+
On a route that requires edge provenance, absent or incomplete provenance —
193+
including provenance that omits the proxy-authenticated end-client peer — maps
194+
to the `missing_evidence` public class, regardless of whether an assertion is
195+
present. Provenance that is present and complete but fails verification maps to
196+
`evidence_rejected`.
180197
A v1 envelope denies. A verifier MAY try only a configured finite set of active
181198
secrets. Rotation does not change nonce identity: replay uniqueness is scoped to
182199
`(authorization_domain_id, trusted-proxy-hmac-v2, nonce)` and is independent of the
@@ -196,7 +213,9 @@ requires confidentiality and integrity.
196213
| `0x00` | Invalid; MUST deny. |
197214
| `0x01` | NIP-42 connection proof. |
198215
| `0x02` | NIP-98 HTTP proof. |
199-
| `0x03`–`0x7f` | Unassigned; allocation requires a published stable specification. |
216+
| `0x03` | Git smart-HTTP session proof: the proxy verifies a session-scoped Nostr authorization for a Git smart-HTTP request before forwarding. Reserved; allocation completes on publication of its transport contract (see below). |
217+
| `0x04` | Blossom media proof: the proxy verifies a Blossom media-HTTP authorization event for the request before forwarding. Reserved; allocation completes on publication of its transport contract (see below). |
218+
| `0x05`–`0x7f` | Unassigned; allocation requires a published stable specification. |
200219
| `0x80`–`0xfe` | Private use under an explicit shared proxy/verifier contract only. |
201220
| `0xff` | Reserved for a future extended encoding; invalid in HMAC-v2. |
202221

@@ -206,6 +225,13 @@ incompatible meaning receives a new code. Unknown, unconfigured, or private-use
206225
codes without the same configured contract at proxy and verifier deny. Private-use
207226
codes MUST NOT be advertised as portable NIP-FI-EDGE interoperability.
208227

228+
Codes `0x03` and `0x04` are reserved to fix their meanings and prevent
229+
reassignment; their transport contracts are not yet published, so their
230+
allocations are not complete. Until the contract for such a code is published,
231+
the code is valid only under an explicit shared proxy/verifier contract,
232+
exactly as for private use, and MUST NOT be presented as portable NIP-FI-EDGE
233+
interoperability.
234+
209235
## Bounded payload acquisition
210236

211237
Every protected `(authorization_domain_id, route, proof_transport_code)` tuple MUST
@@ -334,6 +360,7 @@ Every implementation MUST run these normative negative cases:
334360
| Envelope | Absent/repeated/comma-combined fields, `v1`, missing/extra component, padding, alternate alphabet, nonce below 16 octets or above configured max, and MAC lengths 31 or 33 all deny. |
335361
| Domain | Uppercase/nonhyphenated UUID config fails configuration; mixed-endian UUID bytes or any one-bit domain transplant fails the baseline MAC; duplicate active UUID fails startup. |
336362
| Request | Mutating assertion, method, authority, path/query, body, proof code, or peer while retaining Vector 1's MAC denies. |
363+
| Metadata | Mutating `Content-Type` or `Content-Encoding` in flight changes no authorization decision, target, capability, or effect selector; a request whose server-resolved body semantics no longer hold denies. |
337364
| Path | `%2F`→`%2f`, decoding to `/`, reordering repeated query values, or adding/removing an empty `?` fails the baseline MAC. |
338365
| Authority | Unbracketed or non-RFC-5952 IPv6, uppercase host, trailing dot, or missing port denies before MAC comparison. |
339366
| Peer | Textual `::ffff:192.0.2.128`, padded IPv4, uppercase/noncanonical IPv6, or whitespace denies before MAC comparison. |

0 commit comments

Comments
 (0)