@sentropic/h2a 0.96.1 → 0.97.0

package/dist/runtime/memory/d11-ceremony.d.ts

@@ -0,0 +1,731 @@
+/**
+ * D11 ceremony orchestrator — WP11 slice 5 (build brief). Anti-fabrication
+ * FIXED in two rounds, each closing a hole an independent review NO-GO'd.
+ * See "D11 FIX — ROUND 1" and "D11 FIX — ROUND 2" below for what changed, in
+ * order, and why; the rest of this doc describes the ceremony's unchanged
+ * shape.
+ *
+ * Composes the double-consensus END TO END: launch the two independent legs,
+ * collect their INLINE verdicts, gate on slice 3's `checkDoubleConsensusPreconditions`
+ * (the SAME structural check, not a reimplementation) as a cheap pre-write
+ * reject, write the verdict + attestation artifacts, READ THEM BACK from a
+ * REAL, construction-time-bound durable store and cryptographically verify
+ * them (ROUND 1 + ROUND 2 together), and only then dispatch through
+ * `promoteNoteWithDoubleConsensus` — now fed the READ, VERIFIED verdicts,
+ * never the caller-controlled inline ones.
+ *
+ * SCOPE (bounded), same shape as the rest of `runtime/memory/`: the actual
+ * model-leg launching and the verdict/attestation FILE WRITES are INJECTED
+ * (`deps.launchLeg`, `deps.writeVerdict`, `deps.writeAttestation`,
+ * `deps.port`) and stubbed in tests — never implemented for real here. This
+ * module is the ORCHESTRATION only: what gets called, in what order, and
+ * what refuses the ceremony before the next step ever runs. Real Ed25519
+ * signature verification (`verifySignature`, the default), the concrete
+ * `trustedKeystore` backing store, AND (ROUND 2) the default verdict-artifact
+ * READER (`readVerdict`, a real path-bound filesystem reader) ARE
+ * implemented for real — crypto, and "read back exactly what is actually
+ * persisted", are not "out of scope, inject a stub" concerns the way
+ * launching a model or writing a file are. The keystore's actual key
+ * material/distribution and the durable store's actual deployment location
+ * remain a WP5 concern (see ROUND 1 §1 and ROUND 2 below).
+ *
+ * ===========================================================================
+ * D11 FIX — ROUND 1 — the anti-fabrication anchor (signature verification).
+ * ===========================================================================
+ *
+ * THE HOLE (proven by an independent review): before this fix, `launchLeg`
+ * returned verdicts INLINE (caller-controlled), `writeVerdict` returned ref
+ * strings that were NEVER READ BACK, and the consensus gate checked only the
+ * caller-supplied inline verdicts. A `writeVerdict` that returns invented ref
+ * strings without ever creating a file still reached `promoteNote` with
+ * `promoted: true` — a caller fabricating "2 GO" verdicts as plain JavaScript
+ * objects could promote a note with no real evidence anywhere. This is the
+ * classic fabricated-verdict hole: an assertion was trusted where a document
+ * should have been demanded.
+ *
+ * THE FIX, in three parts:
+ *
+ * 1. `createD11Ceremony({ trustedKeystore, verifySignature? })` — a FACTORY
+ *    that CLOSES OVER the trusted keystore (and, optionally, the signature
+ *    verifier). It returns the actual `runD11Ceremony(input, deps)` function.
+ *    This is the load-bearing design choice: `trustedKeystore` is a
+ *    CONSTRUCTION-TIME input, never part of the per-call `RunD11CeremonyDeps`.
+ *    At the time of THIS round, `readVerdict` and `launchLeg` were BOTH still
+ *    per-call (caller-injected, untrusted); if signature verification used a
+ *    per-call-supplied keystore too, a caller could simply hand the ceremony
+ *    ITS OWN keystore (mapping its own throwaway key to whatever leg it
+ *    likes) and sign its own fabrication — the hole would just move one layer
+ *    down. The keystore must come from a trusted CONSTRUCTION site (a
+ *    conductor/bootstrap that wires `createD11Ceremony` once, not a value an
+ *    arbitrary per-call caller of the returned `runD11Ceremony` can swap).
+ *    `trustedKeystore` is documented here as the LOCAL anchor for today
+ *    (an in-process map/interface from leg identity to an Ed25519 public
+ *    key); it is designed to be swapped later for the WP5 system-wide
+ *    identity keystore WITHOUT a rewrite of this module — `D11TrustedKeystore`
+ *    is a one-method lookup interface (`getPublicKey(leg)`) precisely so a
+ *    different backing store (network-fetched, rotated, cross-repo) can
+ *    implement it later; the ceremony's own logic never changes.
+ *
+ * 2. `readVerdict(ref) => Promise<VerdictArtifact | null>` — at THIS round, a
+ *    per-call dep. It OPENS+READS the verdict artifact actually persisted at
+ *    `ref` (or returns `null` if absent/unreadable — the exact shape of the
+ *    proven counter-example: a `writeVerdict` that never created a file).
+ *    Distinct from `MemoryVerdict` (slice 3's in-memory, caller-asserted
+ *    shape): `VerdictArtifact` additionally carries a `signature` — proof the
+ *    artifact was actually produced by whoever holds the claimed leg's
+ *    private key, not merely narrated by whoever called this ceremony.
+ *    ROUND 2 (below) moves this dep to construction-time too — read that
+ *    section for why leaving it per-call was itself still a hole.
+ *
+ * 3. The gate (fail-closed at every step, `promoteNote` NEVER reached on any
+ *    failure): after `launchLeg` → `writeVerdict` produce the two refs, for
+ *    EACH ref —
+ *      a. `readVerdict(ref)` → REFUSE if `null` (closes the proven
+ *         counter-example structurally: an invented ref with no real file).
+ *      b. Look up the trusted public key for the artifact's OWN CLAIMED
+ *         `leg` (`trustedKeystore.getPublicKey(artifact.leg)`) — REFUSE if
+ *         the keystore has no entry (unknown leg OR an empty keystore; a
+ *         missing key is never treated as "skip verification", it is always
+ *         a refusal — I5 fail-closed applies to the keystore lookup too).
+ *         Verify the artifact's `signature` against THAT key over the exact
+ *         payload `{noteId, verdict, leg, at}` — REFUSE if invalid. Because
+ *         the key is looked up BY THE CLAIMED LEG, a verdict that declares
+ *         leg A but was actually signed with leg B's key (even though B's
+ *         key IS in the keystore) fails here: leg A's public key cannot
+ *         verify a signature produced by leg B's private key.
+ *      c. REFUSE unless the READ `verdict === "GO"`.
+ *      d. REFUSE unless the READ `noteId` equals the note actually being
+ *         promoted (`input.note.noteId`) — ANTI-REPLAY. The signed payload
+ *         in (b) already binds `noteId` into what the signature covers, so a
+ *         genuinely-signed verdict for note X cannot be replayed to promote
+ *         note Y: either its `noteId` fails this pin (this check), or an
+ *         attacker who edits the `noteId` field to match Y invalidates the
+ *         signature (check (b) fires instead). Either way: REFUSE.
+ *    Then, across the two READ artifacts (off the READ content only, never
+ *    the inline verdicts or the legSpecs):
+ *      e. REFUSE if the two artifacts' `leg`s are not structurally distinct.
+ *      f. REFUSE if either artifact's `leg.session === authorId` (separation
+ *         of powers, re-checked off what was actually read — a `readVerdict`
+ *         that returns a different leg than the one that was launched is
+ *         still caught here).
+ *    Then, per artifact again:
+ *      g. REFUSE unless the READ content is COHERENT with the INLINE verdict
+ *         `launchLeg` returned for that same position (`noteId`, `verdict`,
+ *         `leg` must all match) — a mismatch means what got signed/persisted
+ *         disagrees with what the leg claimed inline, which is refused
+ *         rather than silently preferring one over the other.
+ *    Only if ALL of (a)-(g) pass for both legs: the FINAL verdicts and
+ *    attestation fed to `promoteNoteWithDoubleConsensus` are built from the
+ *    READ, VERIFIED artifacts (never the inline ones) — so even a bug in this
+ *    module's own gate logic cannot cause a fabricated inline verdict to
+ *    reach the port, because the inline verdicts are never what gets
+ *    promoted. `promoteNoteWithDoubleConsensus` re-runs
+ *    `checkDoubleConsensusPreconditions` on that verified data as an
+ *    unconditional second layer (unchanged from slice 3) before ever
+ *    touching the port.
+ *
+ * ===========================================================================
+ * D11 FIX — ROUND 2 (this build) — `readVerdict` moves to construction time.
+ * ===========================================================================
+ *
+ * THE HOLE ROUND 1 LEFT (proven by an independent review, a SECOND, separate
+ * leg from the one that forced ROUND 1): ROUND 1 moved `trustedKeystore` and
+ * `verifySignature` to construction-time, but left `readVerdict` as a
+ * PER-CALL, caller-injected dep. An adversarial per-call caller can inject a
+ * `readVerdict` that returns a NON-NULL, TRUSTED-SIGNED artifact that exists
+ * ONLY in memory — a ref string pointing at NO durable file anywhere — and
+ * the gate above (§3a) only refuses `null`; a fabricated-but-signed in-memory
+ * object sails through every check in ROUND 1 §3. ROUND 1's signature
+ * verification only actually defends anything IF the per-call caller lacks
+ * the trusted legs' private keys — but nothing in this module, or in what it
+ * composes, ESTABLISHES that. Key custody is a WP5 wiring concern that is not
+ * yet specified; assuming the caller can't sign is exactly the kind of
+ * unverified assumption D11 exists to eliminate. We do not rely on it here.
+ * The deeper problem: a trust-critical READER that the untrusted per-call
+ * caller can inject is an EMPTY ANCHOR — no matter how strong the
+ * verification logic downstream of it is, the caller controls whether that
+ * logic ever sees real data at all. This is the same injected-deps lesson
+ * ROUND 1 only half-applied (it anchored the VERIFIER but not the READER).
+ *
+ * THE FIX:
+ *
+ * 1. `readVerdict` moves from `RunD11CeremonyDeps` (per-call) to
+ *    `CreateD11CeremonyOptions` (construction-time) — EXACTLY like
+ *    `trustedKeystore` and `verifySignature`, and for the identical reason:
+ *    the per-call caller of the returned `runD11Ceremony(input, deps)` is the
+ *    UNTRUSTED adversary this whole ceremony exists to defend against. A
+ *    trust-critical dependency that adversary can inject or override is not
+ *    a defense, it is a hook for the exact fabrication being defended
+ *    against. `RunD11CeremonyDeps` no longer has a `readVerdict` field at
+ *    all (a type-level guarantee, not merely a runtime check) — and even if
+ *    a caller attaches an extra `readVerdict` property to the `deps` object
+ *    at runtime anyway (JS does not enforce the TS shape), `runD11Ceremony`
+ *    never reads `deps.readVerdict` — it always uses the reader CLOSED OVER
+ *    at construction. Proven in tests: an attached-but-unused
+ *    `deps.readVerdict` records zero calls.
+ *
+ * 2. The DEFAULT construction-time reader, `defaultReadVerdict`, is a REAL
+ *    in-module durable-store reader with PATH-BINDING: `ref` IS a filesystem
+ *    path, and the reader does a genuine `readFile` at exactly that path,
+ *    then JSON-parses and shape-validates the result. It returns `null` on
+ *    ANY failure — missing file, unreadable, malformed JSON, wrong shape —
+ *    which is exactly ROUND 1's proven counter-example (an invented ref with
+ *    no real file behind it) and stays refused for the identical reason.
+ *    Because the reader always dereferences the REAL filesystem at the ref's
+ *    own path, what it returns is BOUND to that ref — it is literally what
+ *    is stored there — never a caller-fabricated in-memory object: there is
+ *    no code path by which an in-memory `VerdictArtifact`, however validly
+ *    signed, can reach `promoteNote` without first being real bytes on disk
+ *    at the exact path the ceremony itself derived from `writeVerdict`'s
+ *    return value. `readVerdict` remains overridable AT CONSTRUCTION for
+ *    tests only — a test may supply a fake store-reader (e.g. an in-memory
+ *    `Map<ref, VerdictArtifact>`) to `createD11Ceremony({ readVerdict: ... })`
+ *    so tests don't need real disk I/O for every scenario — but that
+ *    override is wired ONCE, at the same trusted construction site as
+ *    `trustedKeystore`, never by the per-call caller under test.
+ *
+ * 3. Everything from ROUND 1 §3 is UNCHANGED: signature-by-claimed-leg,
+ *    GO, anti-replay (noteId pin), cross-artifact distinctness, separation
+ *    of powers off the READ content, and coherence with the inline verdict.
+ *    ROUND 2 only changes WHERE `readVerdict` comes from and WHAT its
+ *    default implementation actually does; it adds no new gate steps because
+ *    none were missing — the missing piece was that the existing gate could
+ *    be handed fabricated input before it ever ran.
+ *
+ * WHAT THIS DOES NOT CLAIM (residual, stated honestly): the CONSTRUCTION
+ * SITE — whoever calls `createD11Ceremony({ trustedKeystore, readVerdict })`
+ * — remains a trusted wiring point (WP5 domain, unchanged from ROUND 1 §1):
+ * its choice of keystore, its choice of durable-store reader (or acceptance
+ * of the real filesystem default), and the actual key material/store
+ * deployment behind both are not re-verified by this module. That is ONE
+ * trusted wiring point exercised once at bootstrap, not any of the
+ * potentially many per-call callers of the returned `runD11Ceremony` — a
+ * much smaller, much more auditable surface than ROUND 1 left. This module
+ * defends against a per-call caller fabricating a plausible-looking verdict,
+ * signed or not, durable or not; it does not defend against a compromised
+ * private key for a leg genuinely registered in the trusted keystore, a
+ * compromised/malicious construction site, or a durable store an attacker
+ * can write to directly (bypassing `writeVerdict`) — those remain
+ * key-management, wiring, and storage-access concerns, not gaps in this
+ * gate.
+ *
+ * ===========================================================================
+ * D11 FIX — ROUND 3 (this build) — `defaultReadVerdict` is now PATH-CONFINED.
+ * ===========================================================================
+ *
+ * THE HOLE ROUND 2 LEFT (proven by a THIRD, independent review, a separate
+ * leg from the two that forced ROUNDS 1 and 2): ROUND 2 moved `readVerdict`
+ * to construction time, closing the "fabricated in-memory artifact" hole.
+ * But the DEFAULT construction-time reader, `defaultReadVerdict`, still did
+ * a plain `readFile(ref)` — and `ref` is `writeVerdict`'s PER-CALL,
+ * caller-controlled return value. Moving the READER to construction time
+ * defends against a caller substituting a DIFFERENT reader; it does nothing
+ * to confine WHERE the real, trusted, construction-time reader looks, when
+ * that location is still a bare string the untrusted per-call caller
+ * chose. Three attacks reached `promoteNote` with `promoted: true` at
+ * ROUND 2 (@824b633e):
+ *   1. TRAVERSAL — `writeVerdict` returns a `../../…` ref pointing at some
+ *      OTHER, genuinely signed verdict file outside the intended zone (e.g.
+ *      one written by a real leg for a DIFFERENT ceremony run entirely).
+ *   2. SYMLINK — `writeVerdict` "writes" its ref location as a symlink to
+ *      an attacker-controlled file (or makes an ancestor directory a
+ *      symlink); `readFile` follows it transparently.
+ *   3. TOCTOU — `writeVerdict`'s ref looks confined and could even pass a
+ *      naive check, but the file at that path is swapped between the
+ *      moment any confinement check runs and the moment bytes are actually
+ *      read — a real risk IF that check and that read are two separate
+ *      pathname-based filesystem operations ("realpath(ref), then
+ *      separately re-open(ref)" is itself racy this way).
+ *
+ * THE FIX, REUSING the path-confinement technique already proven and MERGED
+ * in this repo — `packages/h2a-runtime/src/identity-cull/cull.ts` (PR
+ * #160): `realpathSync` canonicalization of a TRUSTED root,
+ * `openSync(..., O_RDONLY | O_DIRECTORY | O_NOFOLLOW)` descriptor-relative
+ * directory walking that refuses a symlink at ANY path component, and — the
+ * TOCTOU-closing move — a SINGLE held file descriptor carried from open
+ * through the `fstatSync` regular-file check to the actual read, never a
+ * second, pathname-based open. This module reimplements the same
+ * primitives locally (`h2a` does not depend on `h2a-runtime` at build time;
+ * the peer dependency is optional) — the TECHNIQUE is reused, not
+ * reinvented, per that module's own comments on the same primitives.
+ *
+ * 1. `createD11Ceremony({ ..., authorizedRoot })` — a new construction-time
+ *    option, REQUIRED whenever the REAL default reader is in use (no custom
+ *    `readVerdict` override): constructing without it throws synchronously,
+ *    the same fail-loud pattern as a missing `trustedKeystore`. A real
+ *    filesystem reader with no confinement root IS the hole this round
+ *    closes; there is no safe default for it.
+ *
+ * 2. `deriveVerdictRef(authorizedRoot, noteId, leg)` — a new, exported,
+ *    PURE function (no filesystem access): the ONE location a leg's verdict
+ *    for a note may ever be read from — `beneath(authorizedRoot,
+ *    sanitized(noteId), sanitized(legId))`. Both `noteId` and the leg's
+ *    `{model, session}` are sanitized (reject `/`, `\`, NUL, `.`, `..`) —
+ *    REFUSED outright (thrown, caught, turned into a ceremony refusal)
+ *    rather than silently stripped, so a hostile value can never be
+ *    "cleaned" into some OTHER, ambiguous, colliding path. This is derived
+ *    from `legSpec1`/`legSpec2` — the ceremony's OWN dispatch decision,
+ *    already checked structurally distinct and non-author BEFORE launch —
+ *    never from anything `launchLeg` or `writeVerdict` claim back. (A
+ *    deliberate, narrow exception to I1's "opaque, never parsed/derived
+ *    from" stance for `noteId`/leg identity: here they are used ONLY to
+ *    build a confined filesystem path, via sanitize-or-refuse, never
+ *    split/parsed/compared piecewise.)
+ *
+ * 3. Per leg, BEFORE any filesystem access on `writeVerdict`'s ref: the
+ *    ceremony computes the derived path and requires
+ *    `resolve(writeVerdictRef) === derivedPath`, EXACTLY, string-for-string
+ *    — REFUSED otherwise, before `readVerdict` is ever called with it. This
+ *    alone closes TRAVERSAL structurally: a `../`-laden ref can never be
+ *    textually identical to the clean, sanitized, ceremony-derived path, so
+ *    it is refused without a single filesystem call ever touching it.
+ *
+ * 4. `defaultReadVerdict(ref, authorizedRoot)` (signature change from
+ *    ROUND 2 — now confined) opens the verdict file via the cull.ts-style
+ *    descriptor-relative O_NOFOLLOW walk from the realpath'd
+ *    `authorizedRoot` down through `ref`'s path components — refusing a
+ *    symlink at ANY component (closes SYMLINK) — then, from the ONE
+ *    resulting file descriptor: `fstatSync`s it (must be a regular file),
+ *    re-derives its canonical path via `realpath("/proc/self/fd/<fd>")` as
+ *    defense-in-depth confirmation it is still beneath `authorizedRoot`,
+ *    and reads its bytes from THAT SAME descriptor — never a second,
+ *    pathname-based open (closes TOCTOU: there is no gap between "this is
+ *    confirmed a regular file beneath the root" and "these are the bytes
+ *    verified" — both statements are about the identical open file
+ *    description).
+ *
+ * 5. When a construction site supplies a CUSTOM `readVerdict` (an
+ *    alternate, non-default store — still construction-time-only,
+ *    unchanged from ROUND 2), the ref-derivation VALIDATION in (3) still
+ *    applies whenever `authorizedRoot` is ALSO configured (defense in
+ *    depth, cheap, store-agnostic — pure string comparison); it is skipped
+ *    only when a construction site both overrides the reader AND supplies
+ *    no `authorizedRoot`, in which case that override remains, as in
+ *    ROUND 2, a fully trusted construction-time decision this module does
+ *    not second-guess.
+ *
+ * Everything from ROUND 1 §3 and ROUND 2 remains UNCHANGED: signature-by-
+ * claimed-leg, GO, anti-replay (noteId pin), cross-artifact distinctness,
+ * separation of powers off the READ content, and coherence with the inline
+ * verdict. ROUND 3 adds a confinement gate BEFORE that pipeline runs; it
+ * removes no existing check.
+ *
+ * ===========================================================================
+ * D11 FIX — ROUND 3 §B (this build) — `authorId` is now BOUND to a verified
+ * author signature; `input.authorId` is no longer trusted for anything.
+ * ===========================================================================
+ *
+ * THE HOLE: `RunD11CeremonyInput.authorId` was a bare, per-call,
+ * caller-supplied string. Every separation-of-powers check compared a leg
+ * against WHATEVER `authorId` the caller happened to supply — a caller could
+ * simply lie (supply an `authorId` distinct from every leg) even when the
+ * TRUE author was genuinely one of the two legs reviewing its own note, and
+ * the ceremony had no way to detect it.
+ *
+ * WHY NOT a trusted-author field on the note itself: graphify verified
+ * (@67bf73c7) that `MemoryNote` carries NO trusted author field — graphify
+ * authors nothing at admission (its anti-cycle boundary, §8, forbids it from
+ * verifying signatures there). So this cannot be closed by reading a field
+ * graphify stamped; it must be closed INSIDE the ceremony, the same way the
+ * verdict-fabrication hole was: bind the claim to an unforgeable signature,
+ * verified against a trust anchor this module already owns.
+ *
+ * THE FIX — reuses the EXACT SAME trust anchor as verdict signatures, no
+ * second trust root:
+ *
+ * 1. The note carries an AUTHOR SIGNATURE in its open extension field
+ *    (`note["h2a.author_signature"]`, `D11CeremonyNote`'s `[key: string]:
+ *    unknown` slot — `MemoryNoteInput`/`note-builder.ts` already carry such
+ *    an open slot; graphify stores it OPAQUE/unverified, it never inspects
+ *    or verifies it). The shape, `AuthorSignature`, mirrors `VerdictArtifact`:
+ *    `{authorLeg: LegIdentity, noteId, signature}` — a base64 Ed25519
+ *    signature over the canonicalized `{authorLeg, noteId}` payload, binding
+ *    the identity claim to BOTH who claims it and which note it is for
+ *    (anti-replay, identical shape to how verdict signatures bind `noteId`).
+ *    `authorLeg` reuses `LegIdentity` (not a new taxonomy, I4) precisely so
+ *    it can be looked up in the SAME `trustedKeystore` a leg's key is.
+ *
+ * 2. `runD11Ceremony` RE-VERIFIES this signature — FIRST, before any other
+ *    check — against the SAME construction-time `trustedKeystore` +
+ *    `verifySignature` already closed over for verdicts (`verifyNoteAuthor`,
+ *    below). No per-call/caller-injected dependency is consulted for this
+ *    (injected_deps_hide_fabrication_hole discipline, same as ROUND 1/2/3's
+ *    other anchors): an attacker who controls `deps` cannot make their own
+ *    verifier say yes.
+ *
+ * 3. On success, the VERIFIED signer's identity — `authorLeg.session` — is
+ *    what EVERY separation-of-powers check in this module now compares
+ *    against, replacing every prior use of `input.authorId`.
+ *    `RunD11CeremonyInput.authorId` remains in the type (callers may still
+ *    pass it) but is STRUCTURALLY NEVER READ for a trust decision anywhere
+ *    in this module — at most an unverified, decorative hint. Lying about it
+ *    has zero effect: it is not consulted.
+ *
+ * 4. FAIL-CLOSED: a note with no author signature, a malformed one, one
+ *    whose `noteId` does not match the note it is attached to, or one that
+ *    does not verify against the trusted keystore, REFUSES the entire
+ *    ceremony immediately — `launchLeg` is never called, exactly like the
+ *    other pre-launch fail-closed checks (I5).
+ *
+ * PARKED (owner-gated, not this round): having graphify itself stamp a
+ * trusted `authored_by` field at admission (via `AdmissionDeps`) — a
+ * heavier, graphify-contract change. This round stays entirely h2a-side,
+ * zero graphify change, closing the hole with a mechanism this module
+ * already had (signature verification against its own trust anchor).
+ *
+ * ===========================================================================
+ * D11 FIX — ROUND 4 (this build) — same-note verdict REPLAY is now refused
+ * (a fresh, gate-issued ceremony nonce), and separation-of-powers is now
+ * enforced on CANONICAL CRYPTO PRINCIPALS (public-key fingerprints), not
+ * session strings.
+ * ===========================================================================
+ *
+ * THE TWO HOLES (proven by an independent review, a FOURTH, separate leg from
+ * the three that forced ROUNDS 1-3): at ROUND 3 (@64e3f8a4), the signed
+ * verdict payload was `{noteId, verdict, leg, at}` — signed, noteId-pinned
+ * against cross-note replay, but with NO freshness, NO nonce, NO one-shot
+ * consumption. An attacker holding NO private key at all could REPLAY the
+ * already-signed BYTES of two OLD, genuinely-produced GO verdicts for the
+ * SAME noteId (from a prior, real ceremony) straight into a FRESH ceremony's
+ * confined artifact locations and mint a fresh promotion — BLOCKER 1,
+ * SAME-NOTE REPLAY. Separately, separation-of-powers derived and compared
+ * `authorLeg.session` / `leg.session` STRINGS only, never the verified
+ * PUBLIC KEY those sessions claim to speak for; `D11TrustedKeystore` never
+ * enforced that a public key maps to at most one identity. If the same
+ * keystore mapped ONE Ed25519 key to TWO (or three) different
+ * `{model, session}` identities, the SAME cryptographic principal could
+ * author a note under one alias and review it — genuinely signing, no forged
+ * signature anywhere — under another, or "independently" review it TWICE
+ * under two reviewer aliases — BLOCKER 2, CRYPTO AUTHOR/REVIEWER (and
+ * REVIEWER/REVIEWER) ALIAS. Both reach `promoteNote({promoted:true})` at
+ * @64e3f8a4 without ever forging a signature.
+ *
+ * FIX 1 — REPLAY: a fresh, gate-issued, unpredictable ONE-SHOT ceremony
+ * nonce.
+ *
+ * 1. `runD11Ceremony` generates `ceremonyNonce = randomBytes(32).toString(
+ *    "base64")` (`node:crypto`, NOT `Math.random`/`Date.now` — unpredictable)
+ *    as the FIRST thing it does, every call. Never persisted, never reused
+ *    across calls — a fresh value exists ONLY for the lifetime of this one
+ *    ceremony invocation ("stateless one-shot": no server-side nonce store
+ *    is needed because the GATE regenerates its own value every run and
+ *    trusts nothing else).
+ * 2. The nonce is threaded to `launchLeg(note, legSpec, ceremonyNonce)` (new
+ *    3rd arg), so an honest leg's inline verdict — now `LegVerdict =
+ *    MemoryVerdict & {ceremonyNonce}` (a LOCAL extension; slice 3's own
+ *    `MemoryVerdict` is untouched, I4) — can carry it through `writeVerdict`
+ *    into what actually gets signed. `VerdictArtifact` and
+ *    `verdictSignedPayload` gain `ceremonyNonce`; the signature now covers
+ *    `{noteId, verdict, leg, at, ceremonyNonce}`.
+ * 3. THE GATE (load-bearing): for each READ artifact, (a) REQUIRE
+ *    `artifact.ceremonyNonce === ceremonyNonce` (THIS run's generated value)
+ *    — reject a stale/replayed artifact immediately, before any signature
+ *    math; AND (b), independently, verify the signature over a payload
+ *    REBUILT from the GATE's OWN `ceremonyNonce` variable — never
+ *    `artifact.ceremonyNonce` as the source of truth for what to verify. A
+ *    replayed old artifact's real signed bytes covered a DIFFERENT (or
+ *    absent) nonce, so (b) alone already fails to verify against a payload
+ *    built with the CURRENT run's nonce, even hypothetically without (a).
+ *    Both (a) and (b) independently refuse a same-note replay — proven by
+ *    the ROUND 4 mutation-check in the test file (each neutralized alone,
+ *    then together, then restored — see that file's comments for the
+ *    ACTUAL, reproduced results).
+ * 4. `coherentWithInline` is extended to also require
+ *    `artifact.ceremonyNonce === inline.ceremonyNonce`.
+ *
+ * FIX 2 — ALIAS: separation-of-powers on canonical CRYPTO PRINCIPALS.
+ *
+ * 1. `canonicalKeyFingerprint(pem)` — `createPublicKey` then re-export as
+ *    SPKI DER, SHA-256 of that DER, base64. Two differently-formatted PEM
+ *    encodings of the identical key canonicalize to the SAME fingerprint
+ *    (robust to encoding, unlike a raw PEM string compare); an unparseable
+ *    key throws (caught and turned into a ceremony refusal, I5).
+ * 2. `verifyNoteAuthor` resolves and returns the VERIFIED author's
+ *    fingerprint alongside its `authorId` — the SAME public key it already
+ *    looked up to verify the author signature, so no extra trust decision is
+ *    introduced.
+ * 3. Separation-of-powers now requires THREE PAIRWISE-DISTINCT crypto
+ *    principals (author, reviewer1, reviewer2), by fingerprint, fail-closed
+ *    on any missing/unparseable key:
+ *      - PRE-LAUNCH: `legSpec1`/`legSpec2`'s trusted keys are resolved and
+ *        fingerprinted BEFORE `launchLeg` is ever called (symmetric with the
+ *        existing pre-launch session-string checks) — refuses before a
+ *        single model call is ever made.
+ *      - POST-READ: re-checked off the ACTUAL READ artifacts' `leg`s'
+ *        fingerprints (the SAME trusted keys that just verified each
+ *        artifact's signature) — a `readVerdict` returning a different leg
+ *        than the one launched is still caught, symmetric with ROUND 1's
+ *        existing "off the READ content only" discipline.
+ *    The existing session-string distinctness checks (`sameLegSpec`,
+ *    `.session === verifiedAuthorId`) are KEPT, unchanged, as defense in
+ *    depth; the fingerprint checks are the AUTHORITATIVE crypto layer added
+ *    this round — a `.session` alias backed by a shared key now refuses even
+ *    when every session string looks pairwise distinct (the
+ *    reviewer/reviewer variant ROUND 3 could not catch, since `sameLegSpec`
+ *    only compares `{model, session}`, never the key behind them).
+ *
+ * Everything from ROUNDS 1-3 remains UNCHANGED: path confinement,
+ * signature-by-claimed-leg, GO, cross-note noteId anti-replay, the two
+ * artifacts' structural (session) distinctness, coherence with the inline
+ * verdict, and author-signature verification. ROUND 4 adds a freshness gate
+ * and a crypto-principal gate; it removes no existing check.
+ *
+ * ===========================================================================
+ * (Unchanged) FLOW summary and invariants.
+ * ===========================================================================
+ *
+ * I5 — fail-closed at EVERY injected/lookup step: `deps` itself,
+ * `deps.legSpecs`, `deps.launchLeg`, `deps.writeVerdict`, `deps.writeAttestation`,
+ * `deps.port`, the CONSTRUCTION-TIME `readVerdict` (ROUND 2), and the
+ * `trustedKeystore` lookup are all treated as untrusted or fallible — absent,
+ * wrong shape, throwing, rejecting, or (for the keystore, and for
+ * `readVerdict`'s return) simply "nothing there" all REFUSE with a structured
+ * `{promoted:false, reason}`, never a silent success. A ceremony that fails
+ * partway NEVER reaches `promoteNote` (slice 3's raw dispatch) — proven in
+ * tests via counting stubs showing later steps are never invoked once an
+ * earlier one refuses.
+ *
+ * I1 — durable identity slot: `note.noteId`, `note.principal_owner`,
+ * `authorId`, and every `legSpec.{model,session}` / `leg.{model,session}` are
+ * OPAQUE strings here — compared with `===` only (via slice 3's own
+ * equality, or the local `sameLegSpec` mirror below), never parsed, split or
+ * derived-from. The `trustedKeystore` is looked up BY the opaque `LegIdentity`
+ * value, not by any string built from parsing it.
+ * I4 — no new capabilities vocabulary: this module reuses `MemoryVerdict`,
+ * `IndependenceAttestation`, `LegIdentity`, `checkDoubleConsensusPreconditions`
+ * and `promoteNoteWithDoubleConsensus` UNCHANGED from `./promote-client.ts`;
+ * `LegSpec` is a type alias of `LegIdentity`, not a second taxonomy, and
+ * `D11CeremonyResult` reuses slice 3's own `PromoteNoteResult` shape — a
+ * ceremony IS a (composed) promotion attempt, not a new outcome vocabulary.
+ * `VerdictArtifact` is the one genuinely NEW shape this fix introduces — the
+ * READ, signed record `MemoryVerdict` never was.
+ */
+import type { MemoryContext, MemoryProducerPort } from "./port-v1.js";
+import { type IndependenceAttestation, type LegIdentity, type MemoryVerdict, type PromoteNoteResult } from "./promote-client.js";
+/** A leg's launch spec — the same opaque `{model, session}` shape as `LegIdentity`. */
+export type LegSpec = LegIdentity;
+/**
+ * The note the ceremony reviews. Deliberately narrow (I1: `noteId` and
+ * `principal_owner` are opaque, carried, never derived); open beyond that
+ * for whatever else a caller's note representation happens to carry.
+ */
+export interface D11CeremonyNote {
+    readonly noteId: string;
+    readonly principal_owner: string;
+    readonly [key: string]: unknown;
+}
+export interface RunD11CeremonyInput {
+    readonly note: D11CeremonyNote;
+    /**
+     * D11 FIX ROUND 3 §B: this is an UNVERIFIED, per-call, caller-supplied
+     * hint — structurally NEVER READ for a trust decision anywhere in this
+     * module. Separation of powers ("no leg may equal the author") is
+     * enforced against the VERIFIED signer of `note["h2a.author_signature"]`
+     * (see `verifyNoteAuthor`, below), not against this field. Kept in the
+     * type only so a caller may still attach it for its own bookkeeping.
+     */
+    readonly authorId: string;
+}
+/**
+ * D11 FIX ROUND 3 §B — the note's AUTHOR SIGNATURE, carried in the note's
+ * open extension slot (`note[AUTHOR_SIGNATURE_KEY]`). Mirrors
+ * `VerdictArtifact`'s shape deliberately: `authorLeg` reuses `LegIdentity`
+ * (I4 — not a new taxonomy) precisely so it is looked up in the SAME
+ * `trustedKeystore` a leg's key is — no second trust root. The signature
+ * covers the canonicalized `{authorLeg, noteId}` payload, binding the
+ * identity claim to both who claims it and which note it is for.
+ */
+export interface AuthorSignature {
+    readonly authorLeg: LegIdentity;
+    readonly noteId: string;
+    /** Base64 Ed25519 signature over the canonicalized payload `{authorLeg, noteId}`. */
+    readonly signature: string;
+}
+/** The note extension key `AuthorSignature` is carried under (`D11CeremonyNote`'s open `[key: string]: unknown` slot). */
+export declare const AUTHOR_SIGNATURE_KEY: "h2a.author_signature";
+/**
+ * A verdict ARTIFACT — what `readVerdict` returns after actually opening and
+ * reading the file persisted at a ref (D11 FIX ROUND 1, path-bound for real
+ * by ROUND 2's default reader). Distinct from `MemoryVerdict`
+ * (`./promote-client.ts`), which is the in-memory shape a `launchLeg` call
+ * returns INLINE and is never, by itself, trusted for a promotion decision:
+ * `VerdictArtifact` additionally carries `signature`, proof of authorship
+ * the inline shape has no room for.
+ */
+export interface VerdictArtifact {
+    readonly noteId: string;
+    readonly verdict: "GO" | "NO-GO";
+    readonly leg: LegIdentity;
+    readonly at: number;
+    /**
+     * D11 FIX ROUND 4 FIX 1 — the FRESH, gate-issued, unpredictable nonce this
+     * verdict was signed under (`crypto.randomBytes(32)`, base64). The gate
+     * REQUIRES this equal THIS RUN's own generated nonce (never trusted from
+     * the artifact alone) and rebuilds the signed payload from ITS OWN nonce
+     * value when verifying — see `verdictSignedPayload` and the ROUND 4 module
+     * doc. Closes SAME-NOTE REPLAY: an old, genuinely-signed artifact for the
+     * SAME noteId carries a DIFFERENT (stale) nonce and fails both checks.
+     */
+    readonly ceremonyNonce: string;
+    /**
+     * Base64 Ed25519 signature over the canonicalized payload
+     * `{noteId, verdict, leg, at, ceremonyNonce}` (exactly these five fields,
+     * nothing else) — binds the verdict to the note it reviews (anti-replay
+     * across notes), the leg that claims to have produced it
+     * (anti-impersonation), and the ceremony run it was produced for
+     * (anti-replay of the SAME note, ROUND 4).
+     */
+    readonly signature: string;
+}
+/**
+ * D11 FIX ROUND 4 FIX 1 — the inline verdict a leg returns, extended with the
+ * ceremony's own freshly-generated nonce so it can flow through
+ * `writeVerdict` into what actually gets signed. A LOCAL extension of slice
+ * 3's `MemoryVerdict` (I4 — not a new taxonomy: every `MemoryVerdict` field
+ * is untouched; `ceremonyNonce` is additive and never leaves this module —
+ * `toMemoryVerdict` strips it back out before anything reaches
+ * `promoteNoteWithDoubleConsensus`).
+ */
+export type LegVerdict = MemoryVerdict & {
+    readonly ceremonyNonce: string;
+};
+/**
+ * The trusted keystore — an opaque `LegIdentity` -> Ed25519 public key (PEM)
+ * lookup. D11 FIX ROUND 1 §1: NEVER supplied per-call (that would make it
+ * caller-swappable, reopening the fabrication hole) — it is closed over at
+ * `createD11Ceremony` construction time by a trusted wiring site. Today this
+ * is the LOCAL anchor (an in-process map/interface); it is designed to be
+ * swapped later for the WP5 system-wide identity keystore WITHOUT a rewrite
+ * of this module — only a different `D11TrustedKeystore` implementation is
+ * needed, same one-method shape.
+ */
+export interface D11TrustedKeystore {
+    /**
+     * The Ed25519 public key (PEM), trusted for this CLAIMED leg, or
+     * `undefined`/`null` if the leg is not known to the keystore (including an
+     * entirely empty keystore) — treated as fail-closed REFUSE by the
+     * ceremony, never as "no key, skip verification".
+     */
+    getPublicKey(leg: LegIdentity): string | undefined | null;
+}
+/**
+ * The signature-verification seam. Real Ed25519 (`defaultVerifySignature`,
+ * below) in production; stubbable at `createD11Ceremony` construction time
+ * for tests. Injected at CONSTRUCTION, like the keystore, and for the same
+ * reason: per-call injection would let a caller supply a verifier that
+ * always says yes.
+ */
+export type VerifySignatureFn = (payload: unknown, signature: string, publicKey: string) => boolean;
+/**
+ * D11 FIX ROUND 2: the verdict-artifact reader seam. Real, CONFINED,
+ * path-bound filesystem I/O (`defaultReadVerdict`, below — ROUND 3 makes it
+ * confined) in production; stubbable at `createD11Ceremony` construction
+ * time for tests. Injected at CONSTRUCTION, like the keystore and the
+ * verifier, and for the identical reason: per-call injection is exactly
+ * what let a caller hand the ceremony a fabricated, durability-free "read"
+ * in the hole ROUND 2 closes. `ref` here is always a value THIS MODULE
+ * derived (ROUND 3 §3), never the raw, unvalidated string a per-call
+ * `writeVerdict` returned.
+ */
+export type ReadVerdictFn = (ref: string) => Promise<VerdictArtifact | null>;
+export interface RunD11CeremonyDeps {
+    /**
+     * Launch one leg's review. INJECTED — real model-launching is out of scope
+     * here. D11 FIX ROUND 4 FIX 1: the 3rd arg is THIS ceremony run's freshly
+     * generated `ceremonyNonce` — an honest leg threads it into its returned
+     * `LegVerdict` so it flows through `writeVerdict` into what gets signed.
+     */
+    readonly launchLeg?: ((note: D11CeremonyNote, legSpec: LegSpec, ceremonyNonce: string) => Promise<LegVerdict>) | undefined | null;
+    /** Persist one verdict, return its REF (locator). INJECTED — real file I/O is out of scope here. */
+    readonly writeVerdict?: ((verdict: LegVerdict) => Promise<string>) | undefined | null;
+    /** Persist the attestation, return its REF. INJECTED — real file I/O + signing are out of scope here. */
+    readonly writeAttestation?: ((attestation: IndependenceAttestation) => Promise<string>) | undefined | null;
+    /** The two legs to launch. Must be structurally distinct (checked BEFORE launch). */
+    readonly legSpecs?: readonly [LegSpec, LegSpec] | undefined | null;
+    readonly port?: MemoryProducerPort | undefined | null;
+    readonly ctx: MemoryContext;
+}
+/** Reuses slice 3's result shape unchanged — a ceremony IS a composed promotion attempt. */
+export type D11CeremonyResult = PromoteNoteResult;
+/** What `createD11Ceremony` closes over — construction-time only, never per-call. */
+export interface CreateD11CeremonyOptions {
+    /** The trust anchor for verdict signatures. See `D11TrustedKeystore` above. */
+    readonly trustedKeystore: D11TrustedKeystore;
+    /** Defaults to real Ed25519 (`defaultVerifySignature`). Override only for tests. */
+    readonly verifySignature?: VerifySignatureFn | undefined;
+    /**
+     * D11 FIX ROUND 2: the verdict-artifact reader. Defaults to
+     * `defaultReadVerdict`, a REAL, CONFINED, path-bound filesystem reader
+     * (ROUND 3). Override ONLY for tests — e.g. a fake, construction-time
+     * `Map`-backed store-reader — wired at the SAME trusted construction site
+     * as `trustedKeystore`, never by a per-call caller of the returned
+     * `runD11Ceremony`.
+     */
+    readonly readVerdict?: ReadVerdictFn | undefined;
+    /**
+     * D11 FIX ROUND 3: the confinement root for verdict reads. REQUIRED
+     * (construction throws otherwise) whenever the REAL default reader is in
+     * use (no `readVerdict` override) — a real filesystem reader with no
+     * confinement root is exactly the hole ROUND 3 closes. When supplied
+     * alongside a CUSTOM `readVerdict`, it still activates the ref-derivation
+     * validation (ROUND 3 §3/§5) as defense in depth, even though that
+     * override reader itself is not required to be filesystem-backed.
+     */
+    readonly authorizedRoot?: string | undefined;
+}
+export type RunD11Ceremony = (input: RunD11CeremonyInput, deps: RunD11CeremonyDeps | undefined | null) => Promise<D11CeremonyResult>;
+/**
+ * The default, real signature verifier: Ed25519 over the canonicalized
+ * payload, via `node:crypto` — the same primitive `./signature.ts` uses
+ * elsewhere in h2a, applied here to a raw base64 signature string (this
+ * seam's shape) rather than the `H2ASignature{by,alg,value}` envelope.
+ */
+export declare function defaultVerifySignature(payload: unknown, signature: string, publicKeyPem: string): boolean;
+/**
+ * D11 FIX ROUND 4 FIX 2 — the canonical CRYPTO PRINCIPAL fingerprint for an
+ * Ed25519 public key: parse the PEM, re-export as SPKI DER (a canonical
+ * encoding independent of the ORIGINAL PEM's own formatting/line-wrapping),
+ * then SHA-256 that DER. Two differently-formatted PEM encodings of the
+ * IDENTICAL key canonicalize to the SAME fingerprint — robust to encoding,
+ * unlike a raw PEM string compare. Throws on an unparseable key; callers
+ * MUST catch this and turn it into a fail-closed ceremony refusal (I5) —
+ * there is no safe default fingerprint for a key that cannot even be parsed.
+ */
+export declare function canonicalKeyFingerprint(publicKeyPem: string): string;
+/**
+ * D11 FIX ROUND 3: the ONE location a leg's verdict for a note may ever be
+ * read from — `beneath(authorizedRoot, sanitized(noteId), sanitized(legId))`.
+ * Pure (no filesystem access) so the ceremony can compute it and compare it
+ * against `writeVerdict`'s per-call return value BEFORE touching disk.
+ * Derived from the ceremony's OWN dispatch decision (the `legSpec` it
+ * actually launched, already checked distinct/non-author before launch) —
+ * never from anything `launchLeg`/`writeVerdict` claim back.
+ */
+export declare function deriveVerdictRef(authorizedRoot: string, noteId: string, leg: LegIdentity): string;
+/**
+ * D11 FIX ROUND 2/3 — the default, REAL, CONFINED durable-store reader.
+ * `ref` IS a filesystem path, opened only via the confined,
+ * descriptor-relative, O_NOFOLLOW walk (`readConfinedFileBytes`, ROUND 3)
+ * beneath `authorizedRoot` — never a bare `readFile(ref)` — then
+ * JSON-parsed and shape-validated. Returns `null` on ANY failure — missing
+ * file, escaped root, a symlink anywhere in the chain, permission error,
+ * malformed JSON, or a well-formed-but-wrong-shape value — never throws.
+ * What it returns, when non-null, is PATH-BOUND: literally the bytes
+ * actually persisted at `ref`, confirmed beneath `authorizedRoot`, never a
+ * value the caller constructed in memory and never bytes read via a path
+ * that could have been re-resolved after any check.
+ */
+export declare function defaultReadVerdict(ref: string, authorizedRoot: string): Promise<VerdictArtifact | null>;
+/**
+ * Factory: builds the actual `runD11Ceremony` function, CLOSED OVER
+ * `trustedKeystore` (and, optionally, `verifySignature` and `readVerdict`).
+ * This is the anti-fabrication anchor (D11 FIX ROUND 1 §1 + ROUND 2 §1):
+ * signature verification always uses THIS keystore, and the verdict
+ * read-back always uses THIS reader (real filesystem by default) — never
+ * one a caller of the returned function can inject per-call. Throws
+ * synchronously on a missing/malformed `trustedKeystore` — a
+ * construction-site wiring bug should fail loudly and immediately, not
+ * silently produce a ceremony that can never verify anything.
+ */
+export declare function createD11Ceremony(options: CreateD11CeremonyOptions): RunD11Ceremony;
+//# sourceMappingURL=d11-ceremony.d.ts.map