@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/inclusion-proof.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Proving that ONE message sits under the root the directory notarized.
+ *
+ * ─── WHAT MAKES THIS A PROOF AND NOT A DATA STRUCTURE ────────────────────────────────────────
+ *
+ * Two things, and both are easy to get wrong in a way that still looks like a proof.
+ *
+ * **1. The root comes from the CERTIFICATE, never from the proof.** A proof that carries its own
+ * root and is checked against it proves that the machine which wrote the proof is self-consistent —
+ * and that machine is the one a sceptic distrusts. So `verifyInclusionProof` REQUIRES the root as a
+ * separate argument, supplied by whoever holds the directory-signed certificate, and the root inside
+ * the proof is only ever compared to it. Drop that argument and the whole file becomes theatre.
+ *
+ * **2. The leaf is recomputed from the MESSAGE BYTES, never taken from the proof.** The Merkle leaf
+ * is a content hash, and since `DOD-M15-SEALWIRE-1` that hash is `HMAC-SHA256(salt, 0x00 ‖ content)`
+ * for a salted session. A proof over the leaf hash alone answers "is this opaque 32-byte number in
+ * the tree", and the operator's question is about a sentence. So the salt and the algorithm NAME
+ * travel with the proof, the verifier recomputes the leaf from the plaintext it holds, and a message
+ * that differs by one byte produces a different leaf and fails — which is the assertion the whole
+ * feature exists to make.
+ *
+ * Neither hash nor Merkle maths is reimplemented here. `contentHashFor` (wire-content-hash.ts) is
+ * the daemon's ONE content-hash derivation and `verifyInclusion` (@cello-protocol/crypto) is the ONE
+ * RFC 6962 verifier. A second copy of either drifts from the seal, and the drift surfaces as a lost
+ * dispute rather than as a failing test.
+ *
+ * Crypto refs: RFC 6962 §2.1.1 (Merkle audit paths), RFC 2104 (HMAC), FIPS 180-4 (SHA-256).
+ */
+import { type ContentHashAlg } from "./wire-content-hash.js";
+/** Everything a third party needs alongside the message bytes and the certificate. */
+export interface InclusionProof {
+    /** Proof format version. Bumped when any field below changes meaning. */
+    readonly version: 1;
+    /** The session this proof is about, hex — so a proof cannot be silently read against another. */
+    readonly session_id: string;
+    /**
+     * The root this proof lands on, hex. NOT authoritative on its own: `verifyInclusionProof`
+     * compares it to the root the caller took from the certificate and refuses if they differ.
+     */
+    readonly certified_root: string;
+    /** Zero-based position of this message's leaf under the certified root. */
+    readonly leaf_index: number;
+    /** How many leaves the certified root covers (content leaves AND the seal's control leaves). */
+    readonly leaf_count: number;
+    /** The leaf hash this proof is for, hex — recomputed by the verifier, never trusted from here. */
+    readonly leaf_hash: string;
+    /** RFC 6962 §2.1.1 audit path: sibling hashes, hex, leaf level upward. */
+    readonly proof_path: readonly string[];
+    /** How the leaf hash is derived from the message bytes. Named, never assumed. */
+    readonly content_hash_alg: ContentHashAlg;
+    /**
+     * The session salt, hex. Required — this build issues salted proofs only, and a proof carrying no
+     * salt is refused rather than checked. The type stays nullable because the shape check runs over
+     * an object off the wire, and "carried null" must be refusable BY NAME rather than by a crash.
+     */
+    readonly content_salt: string | null;
+}
+/**
+ * Why a verification did not conclude "verified".
+ *
+ * A CLOSED set with a total guidance map below, so a new code cannot be added without something the
+ * reader can act on. `message_does_not_match_leaf` and `proof_path_invalid` are the two that mean
+ * "the proof is bad"; the rest mean "this proof was not checkable as presented".
+ */
+export declare const INCLUSION_VERIFY_REASONS: {
+    /** The proof object is not a v1 proof, or a field is missing / the wrong width. */
+    readonly PROOF_MALFORMED: "proof_malformed";
+    /** The proof names a root that is not the one in the certificate the caller holds. */
+    readonly ROOT_NOT_FROM_CERTIFICATE: "root_not_from_certificate";
+    /**
+     * The root SUPPLIED by the caller is not a 32-byte hex value — so there is nothing to compare.
+     *
+     * Separate from the reason above because that one's guidance says *"the proof lands on a DIFFERENT
+     * root than the certificate you supplied"*, and for a truncated paste or a stray quote that is
+     * false: no root was supplied at all. Naming the exit point instead of the cause is the defect
+     * Invariant 3 is about, and it costs an operator the one thing they can actually fix.
+     */
+    readonly CERTIFIED_ROOT_MALFORMED: "certified_root_malformed";
+    /** The proof names a hash algorithm this build cannot reproduce. */
+    readonly UNKNOWN_HASH_ALG: "unknown_content_hash_alg";
+    /**
+     * The proof is over an UNSALTED content hash. Refused rather than checked.
+     *
+     * There is no compatibility branch here on purpose. An unsalted leaf hash is `sha256(0x00 ‖
+     * content)` — a value anyone holding the plaintext can compute, so it correlates the message
+     * across every record that carries it, which is exactly what the session salt exists to stop.
+     * Verifying one anyway would hand back `ok: true` for a proof carrying strictly weaker protection
+     * than the one this build issues, under the same word.
+     */
+    readonly UNSALTED_PROOF: "unsalted_proof_refused";
+    /** The salted algorithm was named and no salt was carried. */
+    readonly SALT_MISSING: "salt_missing";
+    /** The message hashes to a different leaf than the proof is for — the message was altered. */
+    readonly MESSAGE_DOES_NOT_MATCH_LEAF: "message_does_not_match_leaf";
+    /** The audit path does not reconstruct the certified root from this leaf at this index. */
+    readonly PROOF_PATH_INVALID: "proof_path_invalid";
+};
+export type InclusionVerifyReason = (typeof INCLUSION_VERIFY_REASONS)[keyof typeof INCLUSION_VERIFY_REASONS];
+/** What the reader should DO about each. Total over the union by construction. */
+export declare const INCLUSION_VERIFY_GUIDANCE: Record<InclusionVerifyReason, string>;
+export type InclusionVerifyResult = {
+    ok: true;
+    session_id: string;
+    leaf_index: number;
+    leaf_count: number;
+    certified_root: string;
+    content_hash_alg: ContentHashAlg;
+    /** Always false: no part of this check binds a session id. See the note at the return site. */
+    session_id_verified: false;
+} | {
+    ok: false;
+    reason: InclusionVerifyReason;
+    detail: string;
+    guidance: string;
+};
+/**
+ * The Merkle root over an ordered list of leaf HASHES (hex).
+ *
+ * `kind: "hash"` because these values already ARE leaf hashes — the certified root the directory
+ * signs is built the same way (`directory-node.ts`, over each leaf's `s2.content_hash`), and
+ * applying a leaf prefix here would produce a root nobody else computes.
+ */
+export declare function rootOverLeafHashes(leafHashesHex: readonly string[]): string;
+/**
+ * Build the audit path for one leaf of a leaf-hash list.
+ *
+ * Delegates to `inclusionProof`. Deliberately NOT a local tree walk: the seal and the proof must
+ * come from the same Merkle implementation or they drift, and the drift is invisible until a real
+ * dispute.
+ */
+export declare function proofPathFor(leafHashesHex: readonly string[], index: number): string[];
+/**
+ * Is this a structurally valid v1 proof? Shape only — says nothing about whether it verifies.
+ *
+ * Separated so the daemon's verify handler can refuse a malformed object by name before it reaches
+ * any hashing, and so a test can assert the two failure classes apart.
+ */
+export declare function isInclusionProofShape(value: unknown): value is InclusionProof;
+/**
+ * VERIFY — the whole point of the file, and it touches no database.
+ *
+ * Three inputs and nothing else: the proof, the message bytes, and the root the caller took from the
+ * directory-signed certificate. That is what makes it runnable by a third party who has never seen
+ * the daemon that issued the proof.
+ *
+ * `certifiedRootHex` is REQUIRED and is the anchor. Making it optional — defaulting to the root
+ * inside the proof — would turn every call into the proof checking itself, which is the exact shape
+ * this feature exists to replace.
+ */
+export declare function verifyInclusionProof(proof: unknown, messageBytes: Uint8Array, certifiedRootHex: string): InclusionVerifyResult;
+//# sourceMappingURL=inclusion-proof.d.ts.map

package/dist/inclusion-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclusion-proof.d.ts","sourceRoot":"","sources":["../src/inclusion-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAEhC,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,gBAAgB,EAAE,cAAc,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;IACnC,mFAAmF;;IAEnF,sFAAsF;;IAEtF;;;;;;;OAOG;;IAEH,oEAAoE;;IAEpE;;;;;;;;OAQG;;IAEH,8DAA8D;;IAE9D,8FAA8F;;IAE9F,2FAA2F;;CAEnF,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE3E,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAkC3E,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,cAAc,CAAC;IACjC,+FAA+F;IAC/F,mBAAmB,EAAE,KAAK,CAAC;CAC5B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAYnF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAG3E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAGtF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAkB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,UAAU,EACxB,gBAAgB,EAAE,MAAM,GACvB,qBAAqB,CAgGvB"}

package/dist/inclusion-proof.js

@@ -0,0 +1,228 @@
+/**
+ * Proving that ONE message sits under the root the directory notarized.
+ *
+ * ─── WHAT MAKES THIS A PROOF AND NOT A DATA STRUCTURE ────────────────────────────────────────
+ *
+ * Two things, and both are easy to get wrong in a way that still looks like a proof.
+ *
+ * **1. The root comes from the CERTIFICATE, never from the proof.** A proof that carries its own
+ * root and is checked against it proves that the machine which wrote the proof is self-consistent —
+ * and that machine is the one a sceptic distrusts. So `verifyInclusionProof` REQUIRES the root as a
+ * separate argument, supplied by whoever holds the directory-signed certificate, and the root inside
+ * the proof is only ever compared to it. Drop that argument and the whole file becomes theatre.
+ *
+ * **2. The leaf is recomputed from the MESSAGE BYTES, never taken from the proof.** The Merkle leaf
+ * is a content hash, and since `DOD-M15-SEALWIRE-1` that hash is `HMAC-SHA256(salt, 0x00 ‖ content)`
+ * for a salted session. A proof over the leaf hash alone answers "is this opaque 32-byte number in
+ * the tree", and the operator's question is about a sentence. So the salt and the algorithm NAME
+ * travel with the proof, the verifier recomputes the leaf from the plaintext it holds, and a message
+ * that differs by one byte produces a different leaf and fails — which is the assertion the whole
+ * feature exists to make.
+ *
+ * Neither hash nor Merkle maths is reimplemented here. `contentHashFor` (wire-content-hash.ts) is
+ * the daemon's ONE content-hash derivation and `verifyInclusion` (@cello-protocol/crypto) is the ONE
+ * RFC 6962 verifier. A second copy of either drifts from the seal, and the drift surfaces as a lost
+ * dispute rather than as a failing test.
+ *
+ * Crypto refs: RFC 6962 §2.1.1 (Merkle audit paths), RFC 2104 (HMAC), FIPS 180-4 (SHA-256).
+ */
+import { verifyInclusion, buildMerkleTree, merkleRoot, inclusionProof } from "@cello-protocol/crypto";
+import { CONTENT_HASH_ALGS, contentHashFor, isKnownContentHashAlg, } from "./wire-content-hash.js";
+/**
+ * Why a verification did not conclude "verified".
+ *
+ * A CLOSED set with a total guidance map below, so a new code cannot be added without something the
+ * reader can act on. `message_does_not_match_leaf` and `proof_path_invalid` are the two that mean
+ * "the proof is bad"; the rest mean "this proof was not checkable as presented".
+ */
+export const INCLUSION_VERIFY_REASONS = {
+    /** The proof object is not a v1 proof, or a field is missing / the wrong width. */
+    PROOF_MALFORMED: "proof_malformed",
+    /** The proof names a root that is not the one in the certificate the caller holds. */
+    ROOT_NOT_FROM_CERTIFICATE: "root_not_from_certificate",
+    /**
+     * The root SUPPLIED by the caller is not a 32-byte hex value — so there is nothing to compare.
+     *
+     * Separate from the reason above because that one's guidance says *"the proof lands on a DIFFERENT
+     * root than the certificate you supplied"*, and for a truncated paste or a stray quote that is
+     * false: no root was supplied at all. Naming the exit point instead of the cause is the defect
+     * Invariant 3 is about, and it costs an operator the one thing they can actually fix.
+     */
+    CERTIFIED_ROOT_MALFORMED: "certified_root_malformed",
+    /** The proof names a hash algorithm this build cannot reproduce. */
+    UNKNOWN_HASH_ALG: "unknown_content_hash_alg",
+    /**
+     * The proof is over an UNSALTED content hash. Refused rather than checked.
+     *
+     * There is no compatibility branch here on purpose. An unsalted leaf hash is `sha256(0x00 ‖
+     * content)` — a value anyone holding the plaintext can compute, so it correlates the message
+     * across every record that carries it, which is exactly what the session salt exists to stop.
+     * Verifying one anyway would hand back `ok: true` for a proof carrying strictly weaker protection
+     * than the one this build issues, under the same word.
+     */
+    UNSALTED_PROOF: "unsalted_proof_refused",
+    /** The salted algorithm was named and no salt was carried. */
+    SALT_MISSING: "salt_missing",
+    /** The message hashes to a different leaf than the proof is for — the message was altered. */
+    MESSAGE_DOES_NOT_MATCH_LEAF: "message_does_not_match_leaf",
+    /** The audit path does not reconstruct the certified root from this leaf at this index. */
+    PROOF_PATH_INVALID: "proof_path_invalid",
+};
+/** What the reader should DO about each. Total over the union by construction. */
+export const INCLUSION_VERIFY_GUIDANCE = {
+    [INCLUSION_VERIFY_REASONS.PROOF_MALFORMED]: "This is not a well-formed CELLO inclusion proof. Ask whoever gave it to you for the exact JSON " +
+        "object cello_get_inclusion_proof returned — a proof that has been reformatted, truncated, or " +
+        "had fields renamed cannot be checked.",
+    [INCLUSION_VERIFY_REASONS.ROOT_NOT_FROM_CERTIFICATE]: "The proof lands on a DIFFERENT root than the certificate you supplied. It may be a proof for " +
+        "another session, or for an earlier seal of this one. Check the session id on both, and take the " +
+        "root from the certificate (cello_sealed_receipt reports it as sealed_root) — never from the proof.",
+    [INCLUSION_VERIFY_REASONS.CERTIFIED_ROOT_MALFORMED]: "The certified_root you supplied is not a 64-character hex value, so there was nothing to check " +
+        "the proof against and NOTHING about the proof has been established either way. Copy sealed_root " +
+        "from cello_sealed_receipt exactly — a truncated paste, an added quote or a stray newline is the " +
+        "usual cause.",
+    [INCLUSION_VERIFY_REASONS.UNKNOWN_HASH_ALG]: "The proof names a content-hash algorithm this build does not implement, so there is no value to " +
+        "compare against. This is a version difference, NOT evidence of tampering. Upgrade the client and " +
+        "check again before drawing any conclusion.",
+    [INCLUSION_VERIFY_REASONS.UNSALTED_PROOF]: "This proof is over an UNSALTED content hash, which this build does not accept — a leaf anyone " +
+        "holding the plaintext can recompute is the exact correlation the session salt exists to prevent. " +
+        "It has NOT been shown to be false; it has not been checked. Ask for a proof from a salted " +
+        "session (cello_sealed_receipt reports whether the session's content hashes are salted).",
+    [INCLUSION_VERIFY_REASONS.SALT_MISSING]: "The proof names the salted algorithm and carries no salt, so the leaf cannot be recomputed from " +
+        "the message. Ask for the proof to be re-issued; do not treat this as a failed verification.",
+    [INCLUSION_VERIFY_REASONS.MESSAGE_DOES_NOT_MATCH_LEAF]: "THE MESSAGE YOU SUPPLIED IS NOT THE ONE THIS PROOF IS ABOUT. Its bytes hash to a different leaf. " +
+        "Either the text was altered (even by one character, or by trailing whitespace a copy/paste added) " +
+        "or this proof belongs to a different message. Compare against the exact bytes from cello_transcript.",
+    [INCLUSION_VERIFY_REASONS.PROOF_PATH_INVALID]: "The audit path does not rebuild the certified root from this message. The proof does not " +
+        "establish that this message is in the sealed conversation. Ask for a freshly issued proof; if a " +
+        "fresh one fails the same way, the record and the certificate genuinely disagree.",
+};
+const HEX32 = /^[0-9a-f]{64}$/;
+function hexToBytes(hex) {
+    return new Uint8Array(Buffer.from(hex, "hex"));
+}
+function bytesToHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+/**
+ * The Merkle root over an ordered list of leaf HASHES (hex).
+ *
+ * `kind: "hash"` because these values already ARE leaf hashes — the certified root the directory
+ * signs is built the same way (`directory-node.ts`, over each leaf's `s2.content_hash`), and
+ * applying a leaf prefix here would produce a root nobody else computes.
+ */
+export function rootOverLeafHashes(leafHashesHex) {
+    const inputs = leafHashesHex.map((h) => ({ kind: "hash", data: hexToBytes(h) }));
+    return bytesToHex(merkleRoot(buildMerkleTree(inputs)));
+}
+/**
+ * Build the audit path for one leaf of a leaf-hash list.
+ *
+ * Delegates to `inclusionProof`. Deliberately NOT a local tree walk: the seal and the proof must
+ * come from the same Merkle implementation or they drift, and the drift is invisible until a real
+ * dispute.
+ */
+export function proofPathFor(leafHashesHex, index) {
+    const inputs = leafHashesHex.map((h) => ({ kind: "hash", data: hexToBytes(h) }));
+    return inclusionProof(buildMerkleTree(inputs), index).map(bytesToHex);
+}
+/**
+ * Is this a structurally valid v1 proof? Shape only — says nothing about whether it verifies.
+ *
+ * Separated so the daemon's verify handler can refuse a malformed object by name before it reaches
+ * any hashing, and so a test can assert the two failure classes apart.
+ */
+export function isInclusionProofShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const p = value;
+    if (p["version"] !== 1)
+        return false;
+    if (typeof p["session_id"] !== "string" || p["session_id"].length === 0)
+        return false;
+    if (typeof p["certified_root"] !== "string" || !HEX32.test(p["certified_root"]))
+        return false;
+    if (typeof p["leaf_hash"] !== "string" || !HEX32.test(p["leaf_hash"]))
+        return false;
+    if (!Number.isInteger(p["leaf_index"]) || p["leaf_index"] < 0)
+        return false;
+    if (!Number.isInteger(p["leaf_count"]) || p["leaf_count"] <= 0)
+        return false;
+    if (p["leaf_index"] >= p["leaf_count"])
+        return false;
+    const path = p["proof_path"];
+    if (!Array.isArray(path) || path.some((s) => typeof s !== "string" || !HEX32.test(s)))
+        return false;
+    if (typeof p["content_hash_alg"] !== "string")
+        return false;
+    const salt = p["content_salt"];
+    if (salt !== null && (typeof salt !== "string" || salt.length === 0 || !/^([0-9a-f]{2})+$/.test(salt))) {
+        return false;
+    }
+    return true;
+}
+/**
+ * VERIFY — the whole point of the file, and it touches no database.
+ *
+ * Three inputs and nothing else: the proof, the message bytes, and the root the caller took from the
+ * directory-signed certificate. That is what makes it runnable by a third party who has never seen
+ * the daemon that issued the proof.
+ *
+ * `certifiedRootHex` is REQUIRED and is the anchor. Making it optional — defaulting to the root
+ * inside the proof — would turn every call into the proof checking itself, which is the exact shape
+ * this feature exists to replace.
+ */
+export function verifyInclusionProof(proof, messageBytes, certifiedRootHex) {
+    const fail = (reason, detail) => ({
+        ok: false,
+        reason,
+        detail,
+        guidance: INCLUSION_VERIFY_GUIDANCE[reason],
+    });
+    if (!isInclusionProofShape(proof)) {
+        return fail(INCLUSION_VERIFY_REASONS.PROOF_MALFORMED, "the proof is not a version-1 inclusion proof with the required fields at their required widths");
+    }
+    if (typeof certifiedRootHex !== "string" || !HEX32.test(certifiedRootHex.toLowerCase())) {
+        return fail(INCLUSION_VERIFY_REASONS.CERTIFIED_ROOT_MALFORMED, `the certified root supplied is not a 32-byte hex value (got ${typeof certifiedRootHex === "string" ? `${certifiedRootHex.length} chars` : typeof certifiedRootHex})`);
+    }
+    const anchor = certifiedRootHex.toLowerCase();
+    if (proof.certified_root !== anchor) {
+        return fail(INCLUSION_VERIFY_REASONS.ROOT_NOT_FROM_CERTIFICATE, `the proof lands on ${proof.certified_root} and the certificate names ${anchor}`);
+    }
+    if (!isKnownContentHashAlg(proof.content_hash_alg)) {
+        return fail(INCLUSION_VERIFY_REASONS.UNKNOWN_HASH_ALG, `the proof names content-hash algorithm "${proof.content_hash_alg}"`);
+    }
+    if (proof.content_hash_alg !== CONTENT_HASH_ALGS.HMAC_SALT_V1) {
+        return fail(INCLUSION_VERIFY_REASONS.UNSALTED_PROOF, `the proof names content-hash algorithm "${proof.content_hash_alg}"; only ${CONTENT_HASH_ALGS.HMAC_SALT_V1} is accepted`);
+    }
+    if (proof.content_salt === null) {
+        return fail(INCLUSION_VERIFY_REASONS.SALT_MISSING, `algorithm ${proof.content_hash_alg} needs a salt and the proof carries none`);
+    }
+    // The leaf is DERIVED from the bytes in hand, never read out of the proof. This line is what makes
+    // a one-byte edit fail.
+    const recomputed = bytesToHex(contentHashFor(messageBytes, { alg: proof.content_hash_alg, salt: hexToBytes(proof.content_salt) }));
+    if (recomputed !== proof.leaf_hash) {
+        return fail(INCLUSION_VERIFY_REASONS.MESSAGE_DOES_NOT_MATCH_LEAF, `the message supplied hashes to ${recomputed} under ${proof.content_hash_alg}; the proof is for leaf ${proof.leaf_hash}`);
+    }
+    const verified = verifyInclusion(hexToBytes(recomputed), proof.leaf_index, proof.leaf_count, proof.proof_path.map(hexToBytes), hexToBytes(anchor));
+    if (!verified) {
+        return fail(INCLUSION_VERIFY_REASONS.PROOF_PATH_INVALID, `the audit path (${proof.proof_path.length} sibling hashes) does not rebuild ${anchor} from leaf ${proof.leaf_index} of ${proof.leaf_count}`);
+    }
+    return {
+        ok: true,
+        /**
+         * ⚠️ UNVERIFIED, AND THE FIELD SAYS SO ONE LEVEL UP — the caller must not present this as checked.
+         *
+         * Nothing here binds a session id: the anchor is the ROOT, and the root is what the certificate
+         * signs. This value is copied out of the proof, so a relabelled proof reports a session it was
+         * never checked against. It is returned because a reader holding several proofs needs to tell
+         * them apart, not because it has been established.
+         */
+        session_id: proof.session_id,
+        session_id_verified: false,
+        leaf_index: proof.leaf_index,
+        leaf_count: proof.leaf_count,
+        certified_root: anchor,
+        content_hash_alg: proof.content_hash_alg,
+    };
+}
+//# sourceMappingURL=inclusion-proof.js.map

package/dist/inclusion-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inclusion-proof.js","sourceRoot":"","sources":["../src/inclusion-proof.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export type { Logger, LockFileContent, IpcRequest, IpcResponse, IpcResponseOk, IpcResponseError, IpcNotification, IpcFrame, AgentState, AgentInfo, ConnectionStatus, ConnectionInfo, DirectorySignalingState, DaemonStatusResponse, DaemonConfig, IManifestProvider, IManifestVersionStore, IManifestPollScheduler, IDirectoryChallengeVerifier, } from "./types.js";
+export { startDaemon, type DaemonHandle } from "./daemon.js";
+export { readLock, acquireLock, removeLock, removeLockIfOwned, isProcessAlive } from "./lock-file.js";
+export { acquireSingletonLock, probeSingletonLock, DaemonAlreadyRunningError, SINGLETON_LOCK_FILENAME, type SingletonLock, } from "./singleton-lock.js";
+export { loadAgents, type LoadedAgent, type FailedAgent, type AgentLoadResult } from "./agent-loader.js";
+export { createIpcServer, type IpcServer, type IpcHandler, type IpcServerConfig, type IpcDisconnectHandler } from "./ipc-server.js";
+export { connectToDaemon, type IpcClient, IpcError } from "./ipc-client.js";
+export { connectOrStart, type ConnectResult } from "./connect-or-start.js";
+export { RetryQueue, type RetryQueueEntry, type ResendFn, type ResendResult, RETRY_QUEUE_CAP } from "./retry-queue.js";
+export { NonceDedupStore, NONCE_DEDUP_CAP } from "./nonce-dedup.js";
+export { TransportSelector, LocalTransportSelectorStub, TRANSPORT_ERROR, DEFAULT_DIRECT_DIAL_TIMEOUT_MS, selectAdvertisedAddress, } from "./transport-selector.js";
+export type { ITransportSelector, TransportResult, TransportDialer, TransportDialOptions, AdvertisedAddress, } from "./transport-selector.js";
+export { RandomizedPollScheduler, ImmediatePollScheduler } from "./manifest-poll-scheduler.js";
+export { InMemoryManifestVersionStore } from "./manifest-version-store.js";
+export { DbManifestVersionStore } from "./manifest-version-store-db.js";
+export { ManifestDirectoryChallengeVerifier, TestDirectoryChallengeVerifier } from "./challenge-verifier.js";
+export { TypeRegistry, type TypeClassification, type UnclassifiedType, type TypeLookupResult, type RegistryDocument } from "./type-registry.js";
+export { DbRegistryVersionStore, type IRegistryVersionStore } from "./registry-version-store-db.js";
+export { pollRegistryOverHttp, startRegistryPoll, type RegistryPollOutcome, type RegistryPollFailureReason } from "./registry-poll.js";
+export { documentsEnabled, documentLayerState, DOCUMENTS_FLAG_ENV } from "./document-flag.js";
+export { DUAL_SURFACE_VERBS, MCP_ONLY_TOOLS, NON_TOOL_IDENTIFIERS, DEAD_CLI_VERBS, deadCliVerbPattern, RENAMED_AWAY_TOOLS, knownToolNames, isDocumentVerbName, toCliGuidance, renderForSurface, type DualSurfaceVerb, type ClientSurface, } from "./vocabulary.js";
+export { NetworkDirectoryNode, runNetworkDkg, runNetworkRefresh, } from "./network-directory-node.js";
+export type { FrostAuthSigner } from "./network-directory-node.js";
+export { resolveAgentState, isAgentRunning } from "./agent-state.js";
+export type { AgentStateInputs } from "./agent-state.js";
+export { createBackup, restoreBackup, inspectBackup } from "./backup-restore.js";
+export type { BackupResult, RestoreResult } from "./backup-restore.js";
+export { noAgentsGuidance, botHandle, WAITLIST_URL, BOT_HANDLE_PRODUCTION, BOT_HANDLE_STAGING } from "./onboarding-guidance.js";
+export { consortiumFingerprintShort, consortiumFingerprintFull, consortiumFingerprintPreimage, describeConsortiumFingerprint, } from "./consortium-fingerprint.js";
+export { BUNDLED_CONSORTIUM_MANIFEST, BUNDLED_CONSORTIUM_ROOT_KEYS, BUNDLED_CONSORTIUM_THRESHOLD, } from "./bundled-consortium-manifest.js";
+export { EmbeddedManifestProvider } from "./file-manifest-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,8FAA8F;AAE9F,OAAO,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtG,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAA4D,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAE,eAAe,EAAoF,MAAM,iBAAiB,CAAC;AACpI,OAAO,EAAE,eAAe,EAAkB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAA0D,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEpE,6DAA6D;AAC7D,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AASjC,8CAA8C;AAC9C,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,kCAAkC,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAE7G,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAgG,MAAM,oBAAoB,CAAC;AAChJ,OAAO,EAAE,sBAAsB,EAA8B,MAAM,gCAAgC,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAA4D,MAAM,oBAAoB,CAAC;AAEvI,oGAAoG;AACpG,oGAAoG;AACpG,kGAAkG;AAClG,wBAAwB;AACxB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE9F,oGAAoG;AACpG,qGAAqG;AACrG,sCAAsC;AACtC,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AAEzB,qGAAqG;AACrG,yFAAyF;AACzF,mFAAmF;AACnF,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,qGAAqG;AACrG,qGAAqG;AACrG,oGAAoG;AACpG,mCAAmC;AACnC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGrE,6FAA6F;AAC7F,iFAAiF;AACjF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjF,+FAA+F;AAC/F,kGAAkG;AAClG,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEhI,8FAA8F;AAC9F,kGAAkG;AAClG,6DAA6D;AAC7D,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,kCAAkC,CAAC;AAE1C,uFAAuF;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/initiate-session-handler.d.ts

@@ -0,0 +1,55 @@
+import type { IpcHandler } from "./ipc-server.js";
+import type { SessionNodeManager, RelayConnectParams } from "./session-node-manager.js";
+import type { Logger } from "./types.js";
+import type { ConnState } from "./contact-handlers.js";
+import { type ITransportSelector, type SessionNegotiator } from "./transport-selector.js";
+import type { SessionAssignment } from "@cello-protocol/protocol-types";
+import type { IAutoNatService } from "@cello-protocol/transport";
+export interface InitiateSessionDeps {
+    /**
+     * SYNC-P5 (R39, review F5): an OUTBOUND session succeeding is the initiator-side
+     * party-became-reachable signal — fired after the session is usable, best-effort.
+     */
+    onSessionOpened?(agentName: string, counterpartyPubkey: string): void;
+    handlers: Map<string, IpcHandler>;
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    getConnState: (connectionId: string) => ConnState | undefined;
+    resolveCurrentAgent: (connState: ConnState | undefined, explicitAgent?: string) => string | null;
+    NO_CURRENT_AGENT_RESPONSE: unknown;
+    resolvedSessionNegotiator: SessionNegotiator;
+    transportSelector: ITransportSelector;
+    autoNatService: IAutoNatService;
+    buildRelayConnectParams: (agentName: string, assignment: SessionAssignment) => Promise<RelayConnectParams | undefined>;
+    getRelayCircuitAddress?: () => string;
+    /**
+     * M16: is this LOCAL agent a broadcast channel? A channel never opens a session, so the opener
+     * refuses before any directory traffic.
+     */
+    isChannelAgent: (agentName: string) => boolean;
+}
+/**
+ * Registers `cello_initiate_session` and returns the agent-scoped opener behind it, so a worker can
+ * open a session without an IPC connection. See `openSessionAs`.
+ */
+export declare function registerInitiateSessionHandler(deps: InitiateSessionDeps): {
+    /**
+     * The raw opener. `params` is forwarded to the negotiator as MCP wire names — an INTERNAL caller
+     * should use `openSessionFor` instead, which cannot get those names wrong.
+     */
+    openSessionAs(agentName: string, params: Record<string, unknown> | undefined): Promise<Record<string, unknown>>;
+    /**
+     * Open a session as `agentName` with a counterparty, named in TypeScript rather than in wire
+     * strings.
+     *
+     * This exists because the wire names are not guessable and a wrong one fails silently-ish: the
+     * negotiator reads `target_pubkey` (falling back to `counterparty_pubkey`) and nothing else, so a
+     * caller passing `pubkey` gets `invalid_target_pubkey` — an error that sends whoever reads it to
+     * look at the PEER's key when the bug is in the caller's own field name. The same class of defect
+     * already exists one seam over in the close handler (`session_id` vs `sessionId`).
+     */
+    openSessionFor(agentName: string, target: {
+        targetPubkey: string;
+    }): Promise<Record<string, unknown>>;
+};
+//# sourceMappingURL=initiate-session-handler.d.ts.map

package/dist/initiate-session-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initiate-session-handler.d.ts","sourceRoot":"","sources":["../src/initiate-session-handler.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAA2B,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGnH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IAC9D,mBAAmB,EAAE,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,aAAa,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjG,yBAAyB,EAAE,OAAO,CAAC;IACnC,yBAAyB,EAAE,iBAAiB,CAAC;IAC7C,iBAAiB,EAAE,kBAAkB,CAAC;IACtC,cAAc,EAAE,eAAe,CAAC;IAChC,uBAAuB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IACvH,sBAAsB,CAAC,EAAE,MAAM,MAAM,CAAC;IACtC;;;OAGG;IACH,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,mBAAmB,GAAG;IACzE;;;OAGG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC;;;;;;;;;OASG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrC,CA2UA"}