feat(buzz-auth): NIP-FI Phase A PR 4 — production authority interface spine

[wpfleger96]

What

Adds the closed types and entry points PR 5 (relay ingress) branches from: the two-phase prepared/committed authorization contract, the PostgreSQL preparation and final-admission functions, and the complete error-to-DenialClass mapping.

Why

NIP-FI final admission requires two things that must be frozen before the relay ingress can be built: the Rust interface — sealed types, entry-point signatures, error enum — and the PostgreSQL implementation behind it. This PR delivers both in one commit so PR 5 has an exact branch point with no placeholder behavior.

Changes

buzz-auth: nip_fi/authority.rs (new)

• PreparedAuthorization — sealed read-only evidence package produced by prepare_direct (FI-INV-08). pub constructor requires a VerifiedAssertion, proven actor, community UUID, BindingProposal, authority deadlines, PreparedDependencyVersions, and a correlation ID. Every field PR 5 reads is exposed via accessor methods; verified_assertion() provides the confidential JWS handle for revalidation.
• BindingProposal — closed enum (Existing | Enroll) with BindingProvenance (AttestedKey / Provisioned / Tofu) aligned to the identity_bindings.binding_provenance column CHECK constraint.
• PreparedDependencyVersions — snapshot of policy_revision, invalidation_generation, and authority_epoch read atomically during preparation. Final admission re-reads these to detect stale state.
• CommittedAuthorization — sealed authority token produced by commit_admission. pub constructor requires all outputs of the atomic write. Accessors cover every field the relay ingress enforces without re-reading the DB.
• AdmissionError — 13-variant closed enum; every variant maps to exactly one DenialClass via denial_class() and to a unique stable machine code via code(). No variant carries credential material (FI-INV-13). Variant uniqueness and denial-class mapping verified by unit tests.

buzz-db: store/nip_fi_authority.rs (new)

• prepare_direct — reads Y_D(k), T_D(i,k), B_D(i), B_D(k), enrollment policy, and invalidation generation in a single REPEATABLE READ read-only transaction. Evaluates the binding proposal via the NIP-FI.md PrepareDirect pseudocode. Returns PreparedAuthorization. Writes nothing (FI-INV-08).
• commit_admission — re-verifies deadline liveness, assertion equivalence (identity-class bytes, bounds-class deadline regression), and contract-ID stability before writing. SERIALIZABLE transaction: re-reads invalidation generation; re-checks binding conflicts for Enroll proposals; inserts enrollment receipt + lifecycle history + binding row (generated binding_version read back) or locks the existing binding FOR NO KEY UPDATE; inserts the protected-mutation receipt and admission result. All commit or none (FI-INV-09). Returns CommittedAuthorization.
• PrepareError — 7-variant closed error with denial_class() and unique code().

Wire-up

buzz-db gains buzz-auth as a direct dependency (buzz-auth has no dependency on buzz-db — no cycle). New types re-exported from both crate roots.

Stack: #7109 → this PR

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

Changes requested

Reviewed head eab11dce773f3b59380d83dad6be39e25b61e0e8 against base 122ac4329e9090667ac27984fb43883405f1d3d0. This is the production authority spine and its stacked database/JWKS foundations, not the later relay-ingress implementation. The contract is read-only preparation followed by atomic, current-evidence final admission and protected use.

P1: Align the production SQL with the schema this PR installs

nip_fi_authority.rs:526–535 queries current_epoch, but migration 0042 defines authorization_authority_epochs.authority_epoch. An otherwise valid preparation therefore returns DependencyUnavailable before it can produce a token. This is not just a spelling error: the fence read/write at lines 543–545 and 1051–1059 uses nonexistent fence_generation/last_operation_* columns and a four-column conflict target, whereas the installed table has a three-column primary key and requires the actor, binding, policy, epoch, fence and receipt witnesses. The epoch upsert at lines 858–867 also omits mandatory fence/receipt fields.

The enrollment transaction has the same producer/schema integration gap: line 1476 hardcodes successor_binding_version = 1 before the global identity sequence allocates the actual binding version, breaking the exact-birth foreign key after an earlier allocation; it also omits the enrollment authorization_events row required by 0042's deferred receipt/event cardinality trigger. These are independently fatal even after the first column error is fixed.

Fix/exit: use the installed authority/receipt model end to end, read the generated binding version into its history, and write the required enrollment audit evidence. Exercise the actual public prepare → commit → protected-use path against the migrated schema, including an existing binding, multiple fresh enrollments and transaction rollback. The inspected migration-catalog and enum tests do not execute this path.

Scope of the following safety findings: the SQL failure currently prevents successful admission. They are defects in the proposed production contract that remain after that failure is repaired, not claims of a demonstrated deployed-ingress exploit.

P1: Seal the proof-origin context instead of accepting arbitrary raw values

authority.rs:268–293 exposes every VerifiedServerDirectContext field, and new at lines 304–327 is public and performs no validation. A sibling consumer can construct an arbitrary actor, proof ID, proof deadline and community without supplying a Nostr signature; prepare_direct then trusts those coordinates. The raw channel UUID can also disagree with the object hash used for subsequent authority and receipt matching. The type is documented as origin-sealed, but currently enforces none of that contract.

Fix/exit: make the context immutable and mint it only through successful server-target and Nostr-proof validation, deriving the object coordinate from that same target. Add negative API coverage for unverified construction/substitution. A caller comment cannot substitute for the promised proof boundary (NIP-FI FI-INV-04/05).

P1: Reject a present asserted key that differs from the proven actor

build_proposal:1320–1326 treats a nonmatching asserted key as ordinary TOFU, and the Existing branch likewise never compares the asserted key with the actor. No unconditional comparison precedes binding evaluation. The verifier accepts only the token, not an actor; commit re-verifies the assertion against itself rather than against the proof.

Source counterexample: supply a valid assertion explicitly naming K1 and a genuine proof by K2, with no binding under TOFU, or an existing identity/K2 binding. The authority path does not reject this contradiction. TOFU permits an absent key claim, not an explicitly different one (NIP-FI line 338).

Fix/exit: reject every present-key mismatch before proposal evaluation, with AuthorizationDenied, for both Existing and enrollment paths. Test this independently of context sealing, which cannot establish agreement between two separately valid evidence sources.

P1: Recompute enrollment eligibility when its policy changes

commit_admission_inner:771–798 selects the current enrollment mode but only extracts its revision. A changed revision reruns the fixed capability/object/intent matrix, not enrollment eligibility. The Enroll branch then uses the old proposal's provenance and policy revision at lines 1407–1412 and 1505–1506. The schema allows that historical revision and has no latest-mode backstop.

Source counterexample: prepare an unattested first-use enrollment under TOFU, change policy to provisioned or attested-key, then commit. Final admission still attempts the original TOFU enrollment despite the now-disallowed creation. This violates NIP-FI's explicit final recomputation of enrollment and policy state.

Fix/exit: recompute the binding proposal against the current policy in the commit transaction, preserving the rule that policy changes affect future creation rather than retroactively changing existing provenance. Cover both restrictive policy transitions and no-authority-mutation on denial.

P1: Preserve and revalidate current authority at the protected-use boundary

authorize_protected_use:1004–1033 discards the current invalidation generation and checks only binding version/state. CommittedAuthorization has discarded binding expiry, the assertion/revalidation handle, contract IDs and snapshot/invalidation witnesses; the use API accepts no verifier or callback. It also never rechecks the resource.

Source counterexample: commit a binding whose expiry precedes the proof/assertion deadlines, then attempt use after that binding expiry without changing its row. expires_at() considers only proof/assertion, and the binding read omits expires_at, so this boundary cannot detect that authority ended. Resource deletion and signing-key removal expose the same missing-current-authority contract, rather than separate findings.

Fix/exit: retain the required bounds and witnesses and perform current revalidation before granting a use, or fail closed for a use the spine cannot yet validate. Cover passive binding expiry, invalidation, resource deletion and key-snapshot removal through the real gate (NIP-FI lines 436–450).

P2: Preserve dependency-unavailable errors during final revalidation

commit_admission_inner:667–669 maps every verifier failure to AssertionEquivalenceViolation, which becomes EvidenceRejected. Prepare valid live evidence, then make its current key source unavailable: the verifier returns KeySourceUnavailable with AuthorizationUnavailable, but admission changes that into a 403 evidence rejection instead of the required 503 availability denial.

Fix/exit: preserve the verifier's dependency-unavailable class via AuthoritativeDependencyUnavailable; test the prepare → commit outage transition, not only the enum mapping table.

Validation and exclusions

All delegated lanes are closed and integrated. Discovery/JWKS/network inspection established no additional material blocker; actual HTTP/DNS, deadline/cancellation behavior and unrelated network-helper callers outside the cached scope were not runtime-validated.

Source and test-oracle inspection only, against exact-SHA blobs and exact-base product/NIP documents. No checkout, build, import, execution of PR code, runtime tests or conformance PASS is claimed. The current-status posture and non-Phase-A operation tuples intentionally fail closed; later ingress/lifecycle/profile implementations are outside this PR's delivery contract. The failures above concern the production entry points this PR does expose.

[wpfleger96]

🤖 This attempt is superseded by #7148, which replaces the PR 4 architecture and is the active correction vehicle. Closing this one so we do not present two PRs as Phase A PR 4.

[wpfleger96]

🤖 Canonical pointer: #7157 is the sole Phase A PR 4. This interface-spine attempt remains superseded and closed; its applicable feedback is consolidated on #7157.