Files
buzz/docs/nips/NIP-FI-CONFORMANCE.md
Cea Stapleton Cordasco 674440ffcf docs(nips): resolve NIP-FI review findings
Signed-off-by: Cea Stapleton Cordasco <261786559+cea-block@users.noreply.github.com>
2026-07-30 14:20:47 -05:00

35 KiB

NIP-FI conformance matrix

This companion matrix makes the normative NIP-FI specification and its formal model reviewable as executable traces. The specification remains normative; the model and this matrix must agree with it.

Use synthetic issuers, subjects, keys, assertions, and domains. A denial with “no mutation” means no binding, lifecycle, enrollment, publication, or last-seen mutation; a redacted security audit record is allowed. Internal decision names below need not be exposed on the wire: public failures use only the redacted auth-required: or restricted: classes defined by the specification.

Review LC-13 together with the model's RevokeKey transition: its active, inactive, already-revoked, lineage-drift, post-commit-reread, and Q+Y branches intentionally form one regression surface.

Stable subcase labels for allocation and mechanical regression checks are LC-13.active, LC-13.inactive, LC-13.already-revoked, LC-13.lineage-drift, LC-13.post-commit-reread, and LC-13.q-plus-y. They are parts of the single public LC-13 trace rather than additional trace IDs.

OP-3 has two separately evaluated subcases under one public trace ID: OP-3.absent is always required and proves that an unimplemented/default-off projection has no surface or advertisement; OP-3.implemented applies only when a separate privacy-approved projection exists and proves its publication and non-authority constraints. A conformance report records OP-3.implemented as not applicable — never blank or failed — when no such projection exists; when it exists, the subcase must pass.

Lifecycle lineage checks also expose stable subcases without adding public trace IDs: LC-17.valid and LC-17.lineage-drift cover re-enablement, while LC-20.valid and LC-20.lineage-drift cover recovery. Each drift subcase includes missing, mismatched, and unreadable retired-pair state.

State shorthand

  • B_i, B_k: active binding lookups for the presented identity and proven key.
  • P: retired exact-pair selector for (i, k).
  • X: disabled-identity selector for i.
  • Y: revoked-key selector for k.
  • Q: pending explicit replacement for i.
  • Q(i) = k and k in Y may coexist after key revocation: Q preserves retired-pair lineage while Y independently denies the key throughout the authorization domain.
  • “Lifecycle reads” means B_i, B_k, P, X, Y, and Q are read in the same linearizable transition.

Required traces

ID Pre-state / configuration Presented evidence Atomic reads Decision Mutation Lease / session effect Public result Specification / model anchors
TR-1 Trusted-proxy profile; direct verifier ingress is reachable or inbound assertion copies are not stripped Client-controlled proxy header and otherwise valid proof None Reject non-conforming ingress None None restricted: or connection rejection without claim detail Transport, Trust
TR-2 Browser WebSocket client without a trusted proxy Assertion in URL/query string None Reject forbidden transport None None No authenticated session; token never logged Transport, Privacy
TR-3 Client-attached HTTP profile Valid assertion and valid NIP-98 proof on different requests None Reject evidence that is not co-located None None HTTP 401 with redacted body Transport, Rejection
TR-4 Client-attached profile Malformed, non-Bearer, or multiple bearer assertion values None Reject presented-invalid evidence None None restricted: / HTTP 403 with redacted body Transport, Rejection
AS-1 Accepted issuer configured Missing assertion, or missing Nostr proof None Deny missing independent evidence None None auth-required: / HTTP 401 Transport, Proof, Rejection, Proof model
AS-2 Accepted issuer configured Bad signature; symmetric/none algorithm; wrong issuer or audience None Reject assertion None None restricted: / HTTP 403 without validation detail Validation, Validation model
AS-3 Accepted issuer configured Missing/expired exp, future nbf or iat beyond skew None Reject assertion None None restricted: / HTTP 403 Validation, Validation model
AS-4 Accepted issuer configured; exercise the optional npub normalization when advertised Missing, empty, ambiguous, or wrong-type sub; malformed or ambiguous key claim; valid all-lowercase and all-uppercase bare NIP-19 Bech32 npub encodings of the same key; invalid Bech32m/mixed-case/checksum/prefix/TLV/length variants None Accept only valid configured encodings that resolve to one 32-byte key and canonicalize both permitted npub case forms to the same lowercase hex; reject every malformed, Bech32m, or ambiguous variant None None Normal processing for the valid canonical key; otherwise restricted: / HTTP 403 Validation, Validation model
AS-5 Key set unavailable, stale beyond policy, or unknown kid after a fresh bounded fetch Otherwise plausible JWT None Fail closed; do not drive unbounded refreshes None None restricted: / HTTP 403 Validation, Validation model
AS-6 Issuers A and B use the same sub Valid assertion from each issuer Issuer-qualified lifecycle reads Treat (A, sub) and (B, sub) as different identities Only the selected identity may enroll Independent leases Normal result for each qualified identity Definitions, Domain terms
PR-1 Any binding state Invalid, stale, replayed, wrong-target, or wrong-payload NIP-42/NIP-98 proof None Reject proof before authorization None None restricted: / HTTP 403 Proof, Proof model
AU-1 Any binding state Valid assertion with k_a != k None Deny key_mismatch before state access None None restricted: without either key Authorization, Transition
AU-2 B_i = B_k = (i, k) and no lifecycle gate Matching valid assertion and proof Lifecycle reads and known expiry bounds Allow existing binding None Create direct lease bounded by the earliest assertion, binding, policy, and implementation limit Success Authorization, Transition
AU-3 B_i = (i, k_old) Valid assertion for i; proof by k_new Lifecycle reads Deny binding_conflict None None restricted: without conflict detail Authorization, Binding invariant
AU-4 B_k = (i_other, k) Valid assertion for i; proof by k Lifecycle reads Deny binding_conflict None None restricted: without conflict detail Authorization, Binding invariant
AU-5 B_i = B_k = (i, k) and no lifecycle gate Matching assertion and proof; display-name, email, or similar metadata changed Lifecycle reads Same allow decision as unchanged metadata No binding or authorization mutation from metadata Equivalent bounded lease Success without exposing profile values Validation, Terms
EN-1 No binding or lifecycle gate; attested-key mode Valid assertion with k_a = k; valid proof Lifecycle reads Allow created binding Create (i, k) with attested-key provenance Create bounded lease Success Enrollment, Transition
EN-2 No binding or lifecycle gate; attested-key mode Valid assertion without key claim; valid proof Lifecycle reads Deny key_attestation_required None None restricted: Enrollment, Transition
EN-3 No active binding or lifecycle gate; provisioned mode Valid assertion and proof Lifecycle reads Deny binding_required None None restricted: Enrollment, Transition
EN-4 No binding or lifecycle gate; tofu mode Valid assertion without key claim; valid proof Lifecycle reads Allow created binding with accepted TOFU risk Create (i, k) with tofu provenance Create bounded lease Success Enrollment, Transition
EN-5 No binding or lifecycle gate; tofu mode Valid assertion with k_a = k; valid proof Lifecycle reads Allow created binding Create (i, k) with attested-key provenance Create bounded lease Success Enrollment, Transition
EN-6 Existing (i, k) has attested-key provenance Later valid assertion omits the key claim; valid proof by k Lifecycle reads and stored provenance Allow existing binding without downgrade Preserve attested-key provenance exactly Create bounded direct lease Success Enrollment, Transition
EN-7 provisioned mode; no active binding for i or k; i not disabled or pending; k not revoked; exact (i, k) not retired Separately authorized provisioning Enrollment mode, active, and lifecycle state Allow privileged provisioning Atomically create (i, k) with provisioned provenance and append provision history No direct lease; later direct authority still requires valid assertion and fresh proof by k Operator transition; not an Authorize response Enrollment, Lifecycle model
EN-8 Non-provisioned mode; active binding for i or k; i disabled or pending; k revoked; exact (i, k) retired; a required mode, active-binding, or lifecycle-selector read is unreadable; or a concurrent competing provision wins Separately authorized provisioning Serialized attempts to read mode, active, lifecycle, and history state Deny ineligible, unreadable, or losing provision None; never overwrite or clear active/lifecycle state or append provision history No lease Privileged transition failure without selector detail Enrollment, Lifecycle model
CC-1 No binding or lifecycle gate Concurrent identical first use of (i, k) Serialized lifecycle reads One create; all others observe exact match and allow existing Exactly one insertion Equivalent bounded leases Success Authorization, Transition
CC-2 No binding or lifecycle gate Concurrent (i, k1) / (i, k2) or (i1, k) / (i2, k) Serialized lifecycle reads At most one create; conflicting attempt denies At most one insertion Lease only for committed pair Conflicting request receives restricted: Authorization, Binding invariant
CC-3 Any prospective enrollment Lifecycle lookup, insertion, or committed-result reread fails Required state is unavailable Fail closed None beyond a transaction proven committed No new lease from an unreadable result restricted: Authorization, Safety
LC-1 (i, k) in P; no active binding Still-valid matching assertion and proof, with or without matching key claim Lifecycle reads Deny pair_retired None No lease restricted: without tombstone detail Revocation, Lifecycle model
LC-2 i in X, including before first enrollment Valid assertion for i; proof by any key Lifecycle reads Deny identity_disabled None Invalidate/deny direct and dependent delegated leases restricted: Revocation, Lifecycle model
LC-3 k in Y, including without an active binding Valid assertion for any identity; proof by k Lifecycle reads Deny key_revoked None Invalidate/deny every lease depending on k restricted: Revocation, Lifecycle model
LC-4 Q(i) = k_old; no active binding Valid assertion for i; proof by fresh k_new Lifecycle reads Deny explicit_replacement_required None No lease restricted: Revocation, Lifecycle model
LC-5 Active (i, k_old); Q(i) is absent; eligible unbound k_new Separately authorized rotation; fresh target-bound proof by k_new; current assertion for i with k_a = k_new when attestation is required Old/new active, Q, lifecycle, proof, and optional attestation state Allow privileged rotation Atomically remove (i, k_old) from B, add that exact pair to P, create (i, k_new) with deterministic provenance, preserve Q(i) as absent, and append distinct rotation history; do not add k_old to domain-scoped key revocation After commit, invalidate old direct and dependent delegated leases; new pair may later obtain a bounded lease Operator transition; not an Authorize response Revocation, Lifecycle model
LC-6 i in X, Q(i) = k_old, and (i, k_old) in P Separately authorized recovery with otherwise eligible k_new Identity, pending-replacement, retired-pair, and new-key state Deny identity_disabled None, including no selector clearing or history append No new lease Privileged transition failure without private detail Revocation, Lifecycle model
LC-7 Eligible active old pair or pending replacement; k_new is active, revoked, or (i, k_new) is retired Separately authorized rotation or recovery with otherwise valid proof Old/new active and lifecycle state Deny ineligible replacement-key state None; do not retire the old pair or disturb the conflicting binding No new lease Privileged transition failure without selector detail Revocation, Lifecycle model
LC-8 One eligible active old pair; two distinct eligible replacement keys Concurrent separately authorized rotations with valid replacement proofs Serialized old/new active and lifecycle state At most one complete rotation succeeds Exactly one rotation and history record; loser makes no mutation Old leases invalidated once; lease possible only for committed replacement One operator transition succeeds at most Revocation, Safety
LC-9 Any eligible provision, retire, disable, revoke, rotate, recover, or re-enablement transition Injected failure while writing active state, selectors, or lifecycle history Transactional active, lifecycle, and history state Fail closed Entire transition rolls back; prior state and history remain unchanged No new lease or partial invalidation claim Privileged transition failure Lifecycle model, Safety
LC-10 Authorization and provision/retire/disable/revoke/rotate/recover/re-enable race Valid evidence plus concurrent lifecycle transition Serialized active and lifecycle state Serialization decides; completed lifecycle state cannot be violated No post-transition resurrection or partial replacement Matching leases invalidated when transition is observed Result matches the serialized state; no stale allow or private detail Authorization, Safety
LC-11 Active (i, k) with absent Q(i) Separately authorized pair retirement; inject present or unreadable Q(i) Active pair, Q, other selectors, and lifecycle history Commit valid retirement; deny lineage drift without mutation Atomically recheck absent Q(i), remove (i, k), add it to P, set Q(i) = k, and append one history record. Present or unreadable Q(i) rolls back with no selector or history mutation Invalidate matching direct and dependent delegated leases only after a successful commit Operator transition or redacted failure; not an Authorize response Revocation, Lifecycle model
LC-12 Identity i may be active with absent Q(i), pending replacement without an active binding, or never enrolled Separately authorized identity disablement; inject present or unreadable Q(i) for the active branch Active pair, X, P, Q, and lifecycle history Commit valid disablement; deny active-branch lineage drift without mutation Atomically recheck absent Q(i) when active, add i to X, remove and retire any active pair, set Q(i) for that pair, and append one history record. Present or unreadable Q(i) in the active branch rolls back with no mutation; without an active pair, preserve any existing Q(i) Invalidate direct and dependent delegated leases for i only after a successful commit Operator transition or redacted failure; not an Authorize response Revocation, Lifecycle model
LC-13 LC-13.active: k has a unique active pair and absent Q(i). LC-13.inactive: k is inactive or never bound. LC-13.already-revoked: inactive k is already in Y. LC-13.lineage-drift: the active pair has present or unreadable Q(i). LC-13.post-commit-reread and LC-13.q-plus-y evaluate the committed branch states Separately authorized key revocation, including a repeated invocation; execute every labeled subcase Active pair, Y, P, Q, and lifecycle history before commit; durable Y and any affected P/Q state after commit Commit valid revocation; deny active-branch lineage drift without mutation Atomically add or preserve k in Y and append exactly one history record per successfully committed separately authorized invocation. If the unique active pair exists, first recheck absent Q(i), then retire the pair and set Q(i) = k; present or unreadable Q(i) rolls back the invocation with no history append. If no active pair exists, make no P or Q mutation and preserve every pre-existing Q. Reread the committed state: the active-pair result with simultaneous Q(i) = k and k in Y is expected and neither selector is cleared or normalized away; the inactive or already-revoked result retains k in Y without P or Q mutation Invalidate every direct or delegated lease depending on k only after a successful commit Operator transition or redacted failure; not an Authorize response Revocation, Lifecycle model
LC-14 Successful LC-5 rotation or LC-20 recovery has committed (i, k_new) and retired the exact old pair Fresh valid assertion and proof for k_new Lifecycle reads Allow existing replacement binding None Create a bounded direct lease for k_new; the old pair remains denied by LC-1 and the old key is denied across the authorization domain only after LC-13 Success only for k_new Revocation, Liveness
LC-15 (i, k) is pair-retired and pending replacement; k is not in Y and has no active binding Eligible first enrollment for distinct identity j with proof by k Lifecycle reads for (j, k) Apply normal enrollment policy; pair retirement alone does not revoke k across the authorization domain Create (j, k) only when the configured enrollment mode permits Bounded direct lease only for (j, k) Normal result for j; no authority for i Revocation, Lifecycle model
LC-16 Q(i) = k_old and (j, k_old) is active; eligible distinct k_new; i is enabled for recovery or disabled for re-enablement Separately authorized matching transition for i with valid replacement proof Old/replacement active and lifecycle state Apply recovery only when i is enabled, or re-enablement only when i is disabled, without treating pair retirement as domain-scoped key revocation Create only (i, k_new), preserve retired (i, k_old), and do not disturb (j, k_old) or add k_old to Y Invalidate only dependencies of the retired pair; new binding may later obtain a lease Operator result without disclosing j Revocation, Lifecycle model
LC-17 LC-17.valid: i in X, with or without Q(i) = k_old; when Q is present, (i, k_old) in P; eligible k_new. LC-17.lineage-drift: Q(i) = k_old but the exact retired pair is missing, mismatched, or unreadable Separately authorized enablement with fresh target-bound proof by k_new and current matching assertion when required; execute each lineage subcase Identity, old/new key, proof, readable pending/retired-pair selectors, and history state inside the atomic transition Valid: allow privileged enablement. Drift or stale compare: deny fail closed before mutation Valid: atomically create (i, k_new) with deterministic provenance, clear X, preserve absent Q or conditionally compare-and-clear present Q(i) = k_old, append enablement history, and preserve exact old-pair retirement without domain-scoped key revocation. Drift or stale compare: no binding, selector, or history mutation Valid: after commit, invalidate prior-pair dependencies; new binding may later obtain a bounded direct lease. Drift or stale compare: no lease or invalidation Operator transition or redacted failure; ordinary enrollment never sees an ungated re-enabled identity Revocation, Lifecycle model
LC-18 Eligible rotation, recovery, or re-enablement; replacement proof is valid and issuer attestation is optional Supplied current assertion for i has k_a != k_new Old/new active, lifecycle, proof, and assertion state Deny mismatched supplied attestation None; do not create a binding or record attested provenance No new lease Privileged transition failure without claim detail Revocation, Lifecycle model
LC-19 Two privileged state transitions affect the same identity or key, including two recoveries from one Q(i) = k_old to distinct eligible replacement keys or recovery racing disablement/re-enablement Concurrent provision, retire, disable, revoke, recover, rotate, or re-enable requests with valid transition-specific evidence for their observed pre-state Serialized active, selector, and history state with precondition and conditional-comparison recheck At most one incompatible transition commits; a still-eligible serialized successor may commit only from the complete new state, and a recovery cannot commit after disablement wins Each committed transition is atomic with one typed history append; a stale compare-and-clear loser makes no mutation Invalidation follows only committed transitions; a loser triggers none Deterministic operator results without private selector detail Revocation, Lifecycle model
LC-20 LC-20.valid: Q(i) = k_old, (i, k_old) in P, no active binding for i, and eligible unbound k_new. LC-20.lineage-drift: Q(i) = k_old but the exact retired pair is missing, mismatched, or unreadable Separately authorized recovery with fresh target-bound proof by k_new and current matching assertion when required; execute each lineage subcase Old/new active, readable pending/retired-pair selectors, proof, and optional attestation state inside the atomic transition Valid: allow privileged recovery. Drift or stale compare: deny fail closed before mutation Valid: atomically preserve retired (i, k_old), create (i, k_new) with deterministic provenance, conditionally compare-and-clear Q(i) from k_old to absent, and append distinct recovery history without revoking k_old across the domain. Drift or stale compare: no binding, selector, or history mutation Valid: after commit, invalidate old-pair dependencies; new pair may later obtain a bounded lease. Drift or stale compare: no lease or invalidation Operator transition or redacted failure; not an Authorize response Revocation, Lifecycle model
LC-21 Otherwise eligible rotation, recovery, or re-enablement, including when issuer attestation is optional Supplied key-attestation assertion is stale, resolves to an identity other than i, or has no key claim Assertion policy, assertion, proof, active, and lifecycle state Deny invalid supplied replacement attestation; invalid evidence cannot degrade to absent optional evidence None No new lease Privileged transition failure without identity or claim detail Revocation, Lifecycle model
LC-22 Otherwise eligible rotation, recovery, or re-enablement Missing, stale, replayed, wrong-target, or wrong-key Nostr proof for k_new Proof, active, and lifecycle state Deny replacement-key control failure None No new lease Privileged transition failure without proof detail Proof, Lifecycle model
LC-23 Otherwise eligible provision, retire, disable, revoke, rotate, recover, or re-enablement Missing or invalid lifecycle authority, or authority bound to another operation or domain Lifecycle-authority scope plus active and lifecycle state Deny unauthorized privileged transition None No lease or invalidation Privileged transition failure without authority detail Revocation, Lifecycle model
LC-24 Otherwise eligible rotation, recovery, or re-enablement in a domain that requires issuer attestation Attestation evidence is absent, or the supplied current assertion for i has no key claim Assertion policy, proof, active, and lifecycle state Deny missing required replacement attestation None No new lease Privileged transition failure without claim detail Revocation, Lifecycle model
SE-1 HTTP endpoint Valid assertion and NIP-98 proof Lifecycle reads Apply decision to this request only Enrollment only when allowed No reusable HTTP lease implied Per-request result Sessions, Session model
SE-2 Active direct WebSocket lease reaches its earliest assertion, binding, policy, or implementation bound No new upgrade assertion Current time and observed dependencies Reject protected operations or close None Direct lease expires; renewal requires a new connection, fresh assertion, and fresh NIP-42 proof restricted: / closure without private detail Sessions, Session model
SE-3 One WebSocket authenticates k1 and k2; only k1 is authorized Operations attributed to each key Per-key lease lookup Allow only operations attributed to k1 None k1 lease never authorizes k2 Independent per-key result Sessions, Session model
SE-4 Direct or delegated lease depends on binding/policy/delegation state that becomes invalid Previously valid session Observed dependency state Deny after the documented detection bound None Invalidate every dependent lease; do not claim immediate revocation when polling Redacted denial/closure Sessions, Safety
SE-5 Active delegated WebSocket lease reaches its earliest owner-binding, delegation, policy, or mandatory finite implementation bound No newly validated delegated decision Current time and observed dependencies Reject protected operations or close None Lease expires; a new delegated decision requires fresh delegate proof, an active owner binding, and revalidated delegation, but no delegate assertion restricted: / closure without private detail Delegation, Delegation model
DG-1 Owner has an eligible active binding; delegation is valid and narrower; finite delegated-lease maximum configured Delegate proves its own key; no delegate assertion Active owner binding plus delegation conditions; cached owner lease alone is insufficient Allow only intersected delegated operations No binding or lifecycle-selector mutation for the owner or delegate Delegated lease is bounded by the mandatory finite implementation maximum and shorter owner-binding, delegation, or policy limits; no independent assertion bound Success for allowed delegated operation Delegation, Delegation model
DG-2 Owner binding is retired/revoked, or delegation expired/revoked Delegate presents formerly valid proof Owner and delegation dependencies Deny None Invalidate dependent delegated lease on documented detection schedule restricted: Delegation, Delegation model
DG-3 No finite delegated-lease maximum is configured Otherwise valid owner binding, delegation, and delegate proof Delegation configuration Deny delegated authorization; delegation is unsupported None No delegated lease restricted:; discovery must omit/disable delegation Delegation, Discovery
BD-1 Two server-resolved authorization domains Client attempts to choose another domain or reuse evidence across domains State only for trusted resolved D Ignore/reject client domain choice; no cross-domain authority None outside selected domain Domain-scoped lease only Redacted denial when no selected-domain authority exists Definitions, Safety
OP-1 Conflict, validation failure, or lifecycle denial Any denied request As required by the decision Deny without disclosing the conflicting identity, key, claims, or selector None None or matching lease invalidation Only auth-required: / restricted: or HTTP 401/403 Rejection, Privacy
OP-2 Relay supports a subset of transports, enrollment modes, or delegation NIP-11 query Supported configuration, including the finite delegated-lease maximum when delegation is enabled Advertise only supported behavior None None When delegation is enabled, publish a positive delegated_lease_max_seconds; expose no issuer-internal tenant, claim, or audience detail Discovery, Conformance hooks
OP-3 OP-3.absent: projection unimplemented/default-off; OP-3.implemented: separate projection privacy-approved and implemented For each applicable subcase, query discovery/publication and present any available projection as auth evidence; in the implemented subcase also publish an approved label Projection availability plus normal NIP-FI evidence and lifecycle state only OP-3.absent: pass only with no projection surface or advertisement. OP-3.implemented: report not applicable when no separate projection exists; otherwise pass only when approved non-private labels publish. Both applicable decisions: never accept projection as authorization evidence Both keep projection separate from binding state; the absent subcase creates no projection state No authorization lease from either subcase Absent: no projection surface. Implemented: N/A or no iss, sub, bearer material, or private claim disclosure Privacy, Safety
OP-4 NIP-FI authorization succeeds or fails Assertion, iss, sub, and mutable profile claims are available internally Protocol output, publication, history, and operational log/metric capture Authorization result is independent of publication; private material remains access-controlled No assertion/private-claim insertion into events, tags, filters, or relay history; no raw bearer or unredacted identity/profile claim in operational logs or metrics Normal lease effect only No private material in protocol output Transport, Privacy

Conformance claim

An implementation may claim NIP-FI conformance only for the transport profiles, enrollment mode, and delegation behavior it advertises and tests. Every applicable trace above must pass against the same reviewed implementation revision. Trusted-proxy traces such as TR-1 additionally require deployment evidence for both properties: origin isolation, proving that untrusted clients cannot reach verifier ingress, and inbound assertion-header stripping. That evidence names the enforced isolation control and records negative bypass and header-injection tests; code-only tests cannot establish full trusted-proxy conformance. Unsupported optional NIP-FI behavior must be omitted from discovery rather than represented as implemented. OP-3's absent/default-off branch applies to every implementation; its implemented branch is reported not applicable when no separate projection protocol exists and must pass when one does. That protocol is not part of NIP-FI conformance or discovery.