@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/seal-carried-close.js

@@ -0,0 +1,179 @@
+/**
+ * `DOD-M15-CARRIEDSEAL-1` — THE CLOSE THAT DOES NOT NEED ANYONE ELSE TO BE AWAKE.
+ *
+ * Extracted from `session-seal.ts` rather than written beside it, for the reason that file's own
+ * ratchet exists: a seal path that keeps growing in one place is how the second implementation of a
+ * seal gets written next to the first. There is exactly one caller.
+ */
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+import { buildLocalSealTerminus } from "./seal-local-terminus.js";
+import { RELAY_GAVE_NO_ANSWER, relayRefusedUs } from "./seal-relay-silence.js";
+import { SessionSealLeafStore } from "./session-seal-leaf-store.js";
+/**
+ * ═══ 070-CARRIEDSEAL — THE CLOSE THAT DOES NOT NEED ANYONE ELSE TO BE AWAKE ═══
+ *
+ * Returns the escalation values for a seal closed over evidence this side already holds, or
+ * `null` when this is not that situation and the caller should fail exactly as it did before.
+ *
+ * ⚠️ `null` IS THE DEFAULT, AND THAT IS THE SAFETY PROPERTY. Every way out of here that is not a
+ * successfully written terminus returns `null`, so the caller's original refusal stands with its
+ * original reason. A bug in this method costs the receipt this order was written to save; it
+ * cannot turn a relay's ruling into a seal.
+ *
+ * The first gate is the important one: `RELAY_GAVE_NO_ANSWER` separates a relay that was not there
+ * from one that considered the leaf and declined it. Routing around a ruling is the thing a trust
+ * layer must never do, and "the submit failed" alone does not tell the two apart.
+ */
+export async function closeOverCarriedEvidence(deps, agentName, sessionId, cause, correlationId, 
+/**
+ * The relay's standing verdict about THIS AGENT, when there is a relay client to ask. The reason
+ * string cannot carry it — see `relayRefusedUs` — so it is passed alongside.
+ */
+standingRefusal) {
+    if (!RELAY_GAVE_NO_ANSWER.has(cause))
+        return null;
+    if (relayRefusedUs(standingRefusal)) {
+        /**
+         * THE RELAY ANSWERED, AND THE ANSWER WAS NO. Sealing over carried evidence here would be
+         * routing around a ruling — the relay authenticated this agent and then refused it, and that
+         * refusal is a decision about us rather than an absence of anyone to ask.
+         */
+        deps.ctx.logger.warn("session.seal.local_terminus.relay_refused", {
+            agentName, sessionId, cause, relayReason: standingRefusal?.reason, correlationId,
+            impact: "the relay REFUSED this agent rather than being unreachable, so this side did not sign its own closing leaf. No receipt was produced and the session is untouched — closing around a refusal would put a record on the chain that the witness declined to witness.",
+            guidance: "Fix what the relay refused (cello status names it — an expired credential, a rate limit, or a capacity cap), then close again. If the relay is genuinely gone rather than refusing, the close will proceed on its own.",
+        });
+        return null;
+    }
+    const kp = deps.ctx.getKeyProvider(agentName);
+    if (!kp) {
+        // Not a silent skip: without this agent's key nothing here can be signed, and the operator's
+        // action ("start the agent") is different from every other reason a close fails.
+        deps.ctx.logger.warn("session.seal.local_terminus.key_unavailable", {
+            agentName, sessionId, cause, correlationId,
+            impact: "the relay could not be reached and this agent's key is not loaded, so the closing leaf could not be signed here either. No receipt was produced and nothing about the session changed.",
+            guidance: "Start the agent (cello_start_agent) and close again.",
+        });
+        return null;
+    }
+    const ownPubkey = new Uint8Array(await kp.getPublicKey());
+    const ownPubkeyHex = Buffer.from(ownPubkey).toString("hex");
+    const carry = deps.getSealCarry(ownPubkeyHex, sessionId);
+    /**
+     * The session id comes out of the LEAVES, not out of the caller's argument. The directory checks
+     * the terminus against the same session the carried leaves name, so reading it from anywhere
+     * else would let the two disagree — and this path exists precisely for the case where no live
+     * relay registration is around to be consulted.
+     */
+    const first = carry[0] ? decodeStructure1(carry[0].structure1Cbor) : null;
+    if (!first?.ok) {
+        /**
+         * TWO DIFFERENT FACTS, AND THEY SEND THE OPERATOR TO DIFFERENT PLACES. An empty carry means the
+         * conversation was never witnessed; an undecodable first leaf means the record IS here and is
+         * damaged. Reporting the second as the first sends someone looking for something that is not
+         * missing.
+         */
+        const empty = carry.length === 0;
+        deps.ctx.logger.info("session.seal.local_terminus.no_carry", {
+            agentName, sessionId, cause, carryLength: carry.length,
+            reason: empty ? "seal_carry_empty" : "seal_carry_unreadable", correlationId,
+            impact: empty
+                ? "no witnessed leaf is held for this session, so there is no record to close over and no receipt to produce."
+                : "this session's first recorded leaf is on disk and cannot be decoded, so the record cannot be chained onto. The conversation is NOT missing — cello_transcript still shows it — but no receipt can be produced from this side.",
+        });
+        return null;
+    }
+    /**
+     * ⚠️ NO GENESIS, NO TERMINUS — and this used to be `?? new Uint8Array(32)`.
+     *
+     * The genesis is the session's agreed starting point, and it is what BOTH chain links fall back to
+     * for a party that has not spoken yet. Substituting thirty-two zero bytes does not fail: the
+     * directory's walk skips `prev_own_hash` for a sender's first leaf and never checks
+     * `last_seen_hash` at all, so the leaf notarizes and the counterparty — verifying against the real
+     * starting point — is the one who finds a link that does not reconcile. A silent substitution
+     * whose cost lands on the other party.
+     *
+     * The send path already refuses for exactly this reason ("no seed means no send… the honest
+     * outcome is to refuse rather than sign a chain anchored to nothing"). So does this.
+     */
+    const genesis = deps.ctx.leafRecords.sessionGenesisPrevRoot(agentName, sessionId);
+    if (!genesis) {
+        deps.ctx.logger.warn("session.seal.local_terminus.no_genesis", {
+            agentName, sessionId, cause, correlationId,
+            impact: "this session has no recorded starting point on this machine, so a closing leaf written here could not link to anything and its place in the conversation could never be proven. Nothing was signed and the session is untouched.",
+            guidance: "Close WITH your counterparty instead — a bilateral close does not need this value. cello_transcript still shows the conversation either way.",
+        });
+        return null;
+    }
+    const built = await buildLocalSealTerminus({
+        carry,
+        ownPubkeyHex,
+        ownPubkey,
+        sessionIdBytes: first.fields.sessionId,
+        genesis,
+        finalRootHex: deps.ctx.getSessionTreeRootHex(agentName, sessionId),
+        closeTimestamp: Date.now(),
+        sign: async (bytes) => new Uint8Array(await kp.sign(bytes)),
+    });
+    if (!built.ok) {
+        /**
+         * ⚠️ AN ALREADY-PLACED TERMINUS IS A SUCCESS BEING REPORTED AS A FAILURE — review MEDIUM-3.
+         *
+         * `seal_carry_own_ctrl_present` means a previous close already wrote our closing leaf. Returning
+         * `null` sent the caller to its original refusal, so an operator who closed successfully and then
+         * closed again — or whose reconnect retried for them — was told the RELAY was unavailable, for a
+         * session whose closing leaf is on their own disk. The terminus builder's own docblock says the
+         * caller must reuse the one that is there; nobody did.
+         *
+         * Reused rather than rebuilt: the leaf on disk is the one whose bytes were signed, and rebuilding
+         * would produce a different timestamp and therefore a different record.
+         */
+        if (built.reason === "seal_carry_own_ctrl_present") {
+            const existing = carry.find((l) => l.leafKind === 0x02 && l.senderPubkeyHex === ownPubkeyHex);
+            const priorS1 = existing ? decodeStructure1(existing.structure1Cbor) : null;
+            if (existing && priorS1?.ok) {
+                const priorRootHex = deps.ctx.getSessionTree(agentName, sessionId)
+                    .rootWithAppendedHex(Buffer.from(priorS1.fields.contentHash).toString("hex"));
+                deps.ctx.logger.info("session.seal.local_terminus.reused", {
+                    agentName, sessionId, cause, sequenceNumber: existing.sequenceNumber, correlationId,
+                    impact: "this side had already signed its closing leaf for this session, so the earlier one is carried again rather than a second being written. A second closing leaf would make the session unsealable by any directory, permanently.",
+                });
+                return { ok: true, sequenceNumber: existing.sequenceNumber, reportedRootHex: priorRootHex };
+            }
+        }
+        deps.ctx.logger.warn("session.seal.local_terminus.refused", {
+            agentName, sessionId, cause, reason: built.reason, correlationId,
+            impact: "the relay could not be reached and the record this side holds cannot be closed over as it stands, so no receipt was produced.",
+        });
+        return null;
+    }
+    if (!deps.ctx.sealLeafStore && deps.db) {
+        deps.ctx.sealLeafStore = new SessionSealLeafStore(deps.db, deps.ctx.logger);
+    }
+    const wrote = deps.ctx.sealLeafStore?.store(ownPubkeyHex, sessionId, built.leaf, Date.now()) ?? false;
+    if (!wrote) {
+        /**
+         * The store is INSERT OR IGNORE on the position, so a false means something already occupies
+         * it. Refusing is the only safe answer: carrying a leaf that is not the one on disk would
+         * present a record this daemon does not actually hold.
+         */
+        deps.ctx.logger.warn("session.seal.local_terminus.position_taken", {
+            agentName, sessionId, sequenceNumber: built.leaf.sequenceNumber, correlationId,
+            impact: "a leaf is already recorded at the position the closing leaf would take, so it was not written and no receipt was produced.",
+        });
+        return null;
+    }
+    // The reported root is the certified-root domain — content hashes, this leaf appended. The same
+    // derivation the relay path uses one method down, so both close paths report the same value for
+    // the same leaf set.
+    const reportedRootHex = deps.ctx.getSessionTree(agentName, sessionId).rootWithAppendedHex(built.contentHashHex);
+    deps.ctx.logger.info("session.seal.local_terminus.placed", {
+        agentName, sessionId, cause,
+        sequenceNumber: built.leaf.sequenceNumber,
+        carryLength: carry.length,
+        correlationId,
+        impact: "the relay did not answer, so this side signed its own closing leaf over the record it already holds. The seal proceeds on carried evidence and needs no relay.",
+    });
+    return { ok: true, sequenceNumber: built.leaf.sequenceNumber, reportedRootHex };
+}
+//# sourceMappingURL=seal-carried-close.js.map

package/dist/seal-carried-close.js.map

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

package/dist/seal-certificate-pull.d.ts

@@ -0,0 +1,79 @@
+/**
+ * DOD-TERMINAL-STATE-DIVERGENCE-1 — ask the directory for a seal certificate we were never pushed.
+ *
+ * `session_sealed` is pushed ONCE, over this agent's authenticated directory signaling stream. If
+ * that stream is down at the instant the directory pushes, the frame is gone: the directory's
+ * re-delivery queue is per-node while clients roam across nodes, so reconnecting elsewhere drains an
+ * empty queue. The session IS notarized and the counterparty holds a receipt; this side holds an
+ * `interrupted` row and — before this module — could never produce one.
+ *
+ * The result was a deadlock of two individually-true answers. `cello_close_session` reported
+ * `session_already_sealed`; `cello_sealed_receipt` reported `not_sealed_yet`; each pointed at the
+ * other, and the only exit an operator found was a force-abandon that PERMANENTLY forfeited this
+ * side's half of a receipt that existed on the counterparty's.
+ *
+ * THE DIRECTORY IS NOT TRUSTED HERE. A pulled certificate is recorded only if
+ * `verifyBilateralSealCertificate` accepts it — the same verifier, over the same TBS, that the push
+ * path runs. A directory that altered `legibility` or `leaf_count` changes the hash and the FROST
+ * signature fails. That is what makes serving this from ANY node safe, and it is why the pull adds
+ * no new trust in the directory even though it adds a new thing to ask it.
+ */
+import { SignalingManager } from "@cello-protocol/transport";
+import type { DaemonRegistrationPersistence } from "./registration-persistence.js";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import type { Logger } from "./types.js";
+export interface SealCertificatePullDeps {
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    signalingFor: (agentName: string) => SignalingManager | undefined;
+    sendOver: (agentName: string, frame: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    getPersistence: (agentName: string) => DaemonRegistrationPersistence;
+    getAgentPubkeyHex: (agentName: string) => string | undefined;
+}
+export type SealCertificatePullResult = 
+/**
+ * `verified` is REQUIRED, not optional, and that is the point.
+ *
+ * `verifyBilateralSealCertificate` returns `{ok:true, verified:false}` when this daemon holds no
+ * key for the certificate's signer — a legitimate state, and no longer a rare one: clearing a
+ * counterparty's pin (the remedy for the identity-refusal lockout) moves every past session with
+ * them from *verified* to *taken on their word*.
+ *
+ * Until now the pull returned `{ok:true, rootHex}` either way, so `cello_sealed_receipt` handed
+ * the agent a response byte-for-byte identical to a verified one. An operator could clear a
+ * contact, pull an old receipt, and pass it to a third party as proof. It is not proof, and
+ * nothing in the response said so. Making the field non-optional means a new caller cannot
+ * construct this result without deciding what to tell them.
+ */
+{
+    ok: true;
+    rootHex: string;
+    verified: boolean;
+}
+/**
+ * `reason` is never collapsed. Each of these sends the caller somewhere different, and the whole
+ * defect class this unit belongs to is exit-point labels standing in for causes:
+ *   no_signaling        — this daemon has no stream to ask over (not a statement about the seal)
+ *   send_failed         — the request never left
+ *   timeout             — no answer within the bound
+ *   not_found           — the directory has no VERIFIABLE certificate for us on this session
+ *   verification_failed — a certificate arrived and did NOT verify. Never recorded. This is the
+ *                         one that means something is wrong rather than merely absent.
+ */
+ | {
+    ok: false;
+    reason: "no_signaling" | "send_failed" | "timeout" | "not_found" | "verification_failed";
+    detail?: string;
+};
+/**
+ * Pull, verify and record the certificate for one session. Returns the sealed root on success.
+ *
+ * Idempotent by construction: recording a certificate we already hold is a no-op at the store, and
+ * the caller is expected to check for a local certificate first — this is the path for when there
+ * is none.
+ */
+export declare function pullSealCertificate(deps: SealCertificatePullDeps, agentName: string, sessionIdHex: string): Promise<SealCertificatePullResult>;
+//# sourceMappingURL=seal-certificate-pull.d.ts.map

package/dist/seal-certificate-pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seal-certificate-pull.d.ts","sourceRoot":"","sources":["../src/seal-certificate-pull.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AACnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IAClE,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3G,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,6BAA6B,CAAC;IACrE,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,MAAM,yBAAyB;AACnC;;;;;;;;;;;;;GAaG;AACD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE;AAClD;;;;;;;;;GASG;GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,qBAAqB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAa7H;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,uBAAuB,EAC7B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,yBAAyB,CAAC,CAmLpC"}

package/dist/seal-certificate-pull.js

@@ -0,0 +1,186 @@
+import { verifyBilateralSealCertificate } from "./session-ceremony.js";
+import { extractErrorMessage } from "./error-message.js";
+/** Bounded so a close or a receipt read cannot hang on a directory that never answers. */
+const SEAL_CERTIFICATE_PULL_TIMEOUT_MS = 10_000;
+function toU8(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Buffer.isBuffer(v))
+        return new Uint8Array(v);
+    return null;
+}
+/**
+ * Pull, verify and record the certificate for one session. Returns the sealed root on success.
+ *
+ * Idempotent by construction: recording a certificate we already hold is a no-op at the store, and
+ * the caller is expected to check for a local certificate first — this is the path for when there
+ * is none.
+ */
+export async function pullSealCertificate(deps, agentName, sessionIdHex) {
+    const { logger, sessionNodeManager, signalingFor, sendOver, getPersistence, getAgentPubkeyHex } = deps;
+    const mgr = signalingFor(agentName);
+    if (!mgr) {
+        // NOT a statement about the seal. Saying "not found" here would tell an operator their
+        // conversation was never sealed because their own daemon had no stream — a false claim of the
+        // exact kind this line exists to remove.
+        return { ok: false, reason: "no_signaling" };
+    }
+    const sessionIdBytes = Uint8Array.from(Buffer.from(sessionIdHex, "hex"));
+    const answer = await new Promise((resolve) => {
+        const timeoutHandle = setTimeout(() => {
+            unregister();
+            resolve({ type: "timeout" });
+        }, SEAL_CERTIFICATE_PULL_TIMEOUT_MS);
+        const unregister = mgr.registerInboundHandler((frame) => {
+            if (frame.type !== "seal_certificate" && frame.type !== "seal_certificate_error")
+                return;
+            // Scope to THIS session — a concurrent pull for another session must not resolve this one.
+            const sid = toU8(frame["session_id"]);
+            if (!sid || Buffer.from(sid).toString("hex") !== sessionIdHex)
+                return;
+            clearTimeout(timeoutHandle);
+            unregister();
+            if (frame.type === "seal_certificate") {
+                resolve({ type: "seal_certificate", frame: frame });
+            }
+            else {
+                resolve({ type: "seal_certificate_error", reason: typeof frame["reason"] === "string" ? frame["reason"] : "unknown" });
+            }
+        });
+        void sendOver(agentName, { type: "seal_certificate_request", session_id: sessionIdBytes }).then((r) => {
+            if (r.ok)
+                return;
+            clearTimeout(timeoutHandle);
+            unregister();
+            resolve({ type: "seal_certificate_error", reason: `send_failed:${r.reason ?? "unknown"}` });
+        });
+    });
+    if (answer.type === "timeout") {
+        logger.warn("seal.certificate.pull.timeout", { agentName, sessionId: sessionIdHex });
+        return { ok: false, reason: "timeout" };
+    }
+    if (answer.type === "seal_certificate_error") {
+        if (answer.reason.startsWith("send_failed")) {
+            logger.warn("seal.certificate.pull.send_failed", { agentName, sessionId: sessionIdHex, reason: answer.reason });
+            return { ok: false, reason: "send_failed", detail: answer.reason };
+        }
+        logger.info("seal.certificate.pull.not_found", { agentName, sessionId: sessionIdHex, reason: answer.reason });
+        return { ok: false, reason: "not_found", detail: answer.reason };
+    }
+    const f = answer.frame;
+    const sealedRoot = toU8(f["sealed_root"]);
+    const frostSignature = toU8(f["frost_signature"]);
+    const signerPubkey = toU8(f["signer_pubkey"]);
+    const leafCount = typeof f["leaf_count"] === "number" ? f["leaf_count"] : null;
+    const closeTsRaw = f["close_timestamp"];
+    const closeTimestamp = typeof closeTsRaw === "number" ? closeTsRaw : typeof closeTsRaw === "bigint" ? Number(closeTsRaw) : null;
+    if (!sealedRoot || !frostSignature || !signerPubkey || leafCount === null || closeTimestamp === null) {
+        // A certificate missing a TBS field cannot be verified, so it cannot be recorded. Refusing is
+        // the only safe answer — recording it unverified is precisely the trust the pull must not add.
+        logger.error("seal.certificate.pull.malformed", {
+            agentName, sessionId: sessionIdHex,
+            reason: "missing_certificate_fields",
+        });
+        return { ok: false, reason: "verification_failed", detail: "missing_certificate_fields" };
+    }
+    const agentPubkeyHex = getAgentPubkeyHex(agentName);
+    if (!agentPubkeyHex)
+        return { ok: false, reason: "verification_failed", detail: "agent_pubkey_unavailable" };
+    const record = sessionNodeManager.getSessionRecord(agentName, sessionIdHex);
+    const verdict = await verifyBilateralSealCertificate({
+        persistence: getPersistence(agentName),
+        agentPubkeyHex,
+        logger,
+        counterpartyPrimaryHex: record?.counterparty_primary_pubkey ?? null,
+    }, {
+        sessionId: sessionIdBytes,
+        sealedRoot,
+        leafCount,
+        closeTimestamp,
+        frostSignature,
+        signerPubkey,
+        signatureType: "frost",
+        legibility: (f["legibility"] ?? null),
+    });
+    if (!verdict.ok) {
+        // Tamper-evidence: do NOT record, do NOT mark the session sealed. Same posture as the push path
+        // on a bad signature — a certificate that fails verification is worse than none, because
+        // recording it would put a forged root behind the operator's receipt.
+        logger.error("seal.certificate.pull.invalid", { agentName, sessionId: sessionIdHex, reason: verdict.reason });
+        return { ok: false, reason: "verification_failed", detail: verdict.reason };
+    }
+    if (!verdict.verified) {
+        /**
+         * ACCEPTED WITHOUT VERIFICATION — and until now that was SILENT, on a path whose own header
+         * claims it *"distinguishes them by VERIFYING a certificate, not by trusting an answer"*
+         * (review N3).
+         *
+         * `verifyBilateralSealCertificate` returns `{ok:true, verified:false}` when it does not hold the
+         * signer's key. That is a legitimate state — but it stopped being rare the moment
+         * `cello_contact_remove` began NULLing the pin (the fix for the identity-refusal lockout). One
+         * operator action silently moved every past session with that counterparty from *verified* to
+         * *taken on trust*, and nothing said so.
+         *
+         * Forgetting a counterparty's identity genuinely DOES cost the ability to verify their old
+         * certificates — the key was thrown away on purpose. The defect was never the cost; it was that
+         * the cost was invisible while a comment two files away promised the opposite. The certificate
+         * is still recorded (it arrived over an authenticated channel), and the operator is now told
+         * what they are holding.
+         */
+        logger.warn("seal.certificate.pull.unverified", {
+            agentName,
+            sessionId: sessionIdHex,
+            reason: verdict.reason,
+            impact: "this certificate was accepted without checking its signature, because this daemon holds no key for its signer — most often because the counterparty's pinned identity was cleared by cello_contact_remove. The sealed root is recorded on the counterparty's word, not on a verified signature",
+            guidance: "if you need this receipt to be independently verifiable, ask the counterparty to re-seal, or re-establish a session with them first so their identity is pinned again",
+        });
+    }
+    const rootHex = Buffer.from(sealedRoot).toString("hex");
+    const legibility = f["legibility"];
+    if (legibility !== undefined && legibility !== null) {
+        try {
+            sessionNodeManager.recordSealCertificate(agentName, sessionIdHex, rootHex, JSON.stringify(legibility));
+        }
+        catch (error) {
+            logger.warn("seal.certificate.persist.failed", {
+                sessionId: sessionIdHex,
+                reason: extractErrorMessage(error),
+            });
+        }
+    }
+    logger.info("seal.certificate.pull.recovered", {
+        agentName,
+        sessionId: sessionIdHex,
+        sealedRoot: rootHex,
+        verified: verdict.verified,
+        // The impact line said "provable" unconditionally, which is FALSE in exactly the branch above:
+        // an unverified certificate is recorded on the counterparty's word and proves nothing to a
+        // third party. A claim that is true on the common path and false on the dangerous one is worse
+        // than no claim, because it reads as reassurance precisely when reassurance is unwarranted.
+        impact: verdict.verified
+            ? "a seal this side never received the push for is now local, and its signature was checked"
+            : "a seal this side never received the push for is now local, but its signature was NOT checked — it is recorded on the counterparty's word",
+    });
+    // STATUS FIRST AND SYNCHRONOUS, teardown second — the same terminal transition the push path
+    // makes, so a pulled seal and a pushed one leave the daemon in identical states.
+    //
+    // The comment here used to credit `destroySessionNode` with marking the row. It does not when the
+    // session has no live node — it returns early at `if (!entry) return` and writes the status below
+    // that guard — and THIS path is precisely the no-node case: a daemon pulls a certificate exactly
+    // when it was down or disconnected while the seal happened.
+    try {
+        sessionNodeManager.markSealed(agentName, sessionIdHex);
+    }
+    catch (err) {
+        logger.error("session.seal.status.write.threw", {
+            sessionId: sessionIdHex, agentName,
+            error: extractErrorMessage(err),
+            impact: verdict.verified
+                ? "the certificate was pulled and verified, but this row still reads interrupted"
+                : "the certificate was pulled (signature NOT checked), but this row still reads interrupted",
+        });
+    }
+    void sessionNodeManager.destroySessionNode(agentName, sessionIdHex, "sealed");
+    return { ok: true, rootHex, verified: verdict.verified };
+}
+//# sourceMappingURL=seal-certificate-pull.js.map

package/dist/seal-certificate-pull.js.map

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

package/dist/seal-certified-root-check.d.ts

@@ -0,0 +1,37 @@
+import type { SealCarryLeaf } from "./session-seal-leaf-store.js";
+/**
+ * REBUILD THE CERTIFIED ROOT FROM THIS DAEMON'S OWN LEAVES — `DOD-M15-SEALWIRE-1` bullet 2.
+ *
+ * The receipt used to prove only that the directory signed SOMETHING: the client took the sealed
+ * root off the wire, confirmed the directory's signature over those bytes, stored it, and threw
+ * away the root it had computed a step earlier. At co-signing time that means **your key signs a
+ * root you never checked.**
+ *
+ * Bullet 1 moved the certified root into the content-hash domain, which is the domain this daemon
+ * can actually rebuild — each carry leaf's `content_hash` is the leaf hash (RFC 6962 §2.1 "hash"
+ * leaves are used as-is), and the carry is ordered by the relay's canonical `sequence_number`,
+ * which is the order the directory rebuilds in.
+ *
+ * ─── Why this returns "cannot judge" instead of always answering ───────────────────────────
+ *
+ * A root comparison that is WRONG makes every session unsealable, and force-abandon — no receipt —
+ * becomes the only exit. That failure is worse than the one being guarded, and this file already
+ * carries two comments saying so about other gates.
+ *
+ * The carry is this daemon's view, and it is not guaranteed complete at the instant a certificate
+ * arrives: the counterparty's SEAL ctrl leaf is what TRIGGERS the seal, so it may not have been
+ * witnessed here yet. So completeness is checked FIRST, against the certificate's own leaf count.
+ * A short carry means this daemon cannot judge — which is a different answer from "the roots
+ * disagree", and conflating them would turn a local timing gap into an accusation.
+ */
+export declare function verifyCertifiedRoot(getSealCarry: (agentPubkeyHex: string, sessionIdHex: string) => SealCarryLeaf[], agentPubkeyHex: string, sessionIdHex: string, certifiedRoot: Uint8Array, certifiedLeafCount: number): {
+    verdict: "match";
+} | {
+    verdict: "mismatch";
+    ownRootHex: string | null;
+    detail: string;
+} | {
+    verdict: "cannot_judge";
+    reason: string;
+};
+//# sourceMappingURL=seal-certified-root-check.d.ts.map

package/dist/seal-certified-root-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seal-certified-root-check.d.ts","sourceRoot":"","sources":["../src/seal-certified-root-check.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,aAAa,EAAE,EAC/E,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,UAAU,EACzB,kBAAkB,EAAE,MAAM,GACzB;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA6FzI"}

package/dist/seal-certified-root-check.js

@@ -0,0 +1,127 @@
+/**
+ * `DOD-M15-SEALWIRE-1` / `DOD-M15-CARRIEDSEAL-1` — DOES THIS CERTIFICATE DESCRIBE WHAT I HOLD?
+ *
+ * Moved out of `session-seal.ts` whole, with no change to the verdicts, when 070-CARRIEDSEAL needed
+ * room under that file's ratchet. It belongs out here on its own terms: everything else in the seal
+ * class drives a ceremony, and this only ever ANSWERS A QUESTION about a leaf set — no transport, no
+ * lifecycle, no state of its own.
+ *
+ * Crypto refs: RFC 6962 §2.1 (Merkle hash trees).
+ */
+import { buildMerkleTree, merkleRoot } from "@cello-protocol/crypto";
+import { LEAF_KIND_CTRL } from "./session-relay-client.js";
+import { carryContentHashInputs } from "./session-node-types.js";
+/**
+ * REBUILD THE CERTIFIED ROOT FROM THIS DAEMON'S OWN LEAVES — `DOD-M15-SEALWIRE-1` bullet 2.
+ *
+ * The receipt used to prove only that the directory signed SOMETHING: the client took the sealed
+ * root off the wire, confirmed the directory's signature over those bytes, stored it, and threw
+ * away the root it had computed a step earlier. At co-signing time that means **your key signs a
+ * root you never checked.**
+ *
+ * Bullet 1 moved the certified root into the content-hash domain, which is the domain this daemon
+ * can actually rebuild — each carry leaf's `content_hash` is the leaf hash (RFC 6962 §2.1 "hash"
+ * leaves are used as-is), and the carry is ordered by the relay's canonical `sequence_number`,
+ * which is the order the directory rebuilds in.
+ *
+ * ─── Why this returns "cannot judge" instead of always answering ───────────────────────────
+ *
+ * A root comparison that is WRONG makes every session unsealable, and force-abandon — no receipt —
+ * becomes the only exit. That failure is worse than the one being guarded, and this file already
+ * carries two comments saying so about other gates.
+ *
+ * The carry is this daemon's view, and it is not guaranteed complete at the instant a certificate
+ * arrives: the counterparty's SEAL ctrl leaf is what TRIGGERS the seal, so it may not have been
+ * witnessed here yet. So completeness is checked FIRST, against the certificate's own leaf count.
+ * A short carry means this daemon cannot judge — which is a different answer from "the roots
+ * disagree", and conflating them would turn a local timing gap into an accusation.
+ */
+export function verifyCertifiedRoot(getSealCarry, agentPubkeyHex, sessionIdHex, certifiedRoot, certifiedLeafCount) {
+    const carry = getSealCarry(agentPubkeyHex, sessionIdHex);
+    if (carry.length === 0)
+        return { verdict: "cannot_judge", reason: "no_carry" };
+    /**
+     * COMPLETENESS IS ESTABLISHED FROM THE CARRY'S OWN EVIDENCE, NEVER FROM THE CERTIFICATE.
+     *
+     * Review F3, and the first cut had this exactly backwards. It gated on
+     * `carry.length !== certifiedLeafCount`, where `certifiedLeafCount` is a field the DIRECTORY
+     * chooses and signs — so the party being checked controlled whether it was checked. A directory
+     * certifying a root over a different conversation had only to state a `leaf_count` that did not
+     * match, and the client answered "cannot judge" and accepted. The signature still verified,
+     * because the count is signed inside the same TBS.
+     *
+     * That is the hole §2b names in as many words: *"an attacker who wants to evade a mismatch check
+     * simply never supplies a checkable proof. Treating 'we could not tell' as harmless is the
+     * hole."* I defended against a false POSITIVE and left the false NEGATIVE one field away.
+     *
+     * The carry can answer the question by itself. A complete bilateral leaf set is:
+     *   - sequences contiguous from 1 — no gap where a leaf this daemon never saw would sit; and
+     *   - exactly two SEAL ctrl leaves, from two DISTINCT senders — which is what a bilateral seal
+     *     is, and is the condition that says the counterparty's closing leaf has landed here.
+     * Both predicates already exist in `seal-escalation.ts`; this reuses their shape rather than
+     * inventing a second opinion about the same question.
+     *
+     * When the carry IS self-evidently complete, a `leaf_count` that disagrees is no longer "I
+     * cannot tell" — it is the certificate describing a different leaf set, which is a MISMATCH.
+     */
+    const sequences = carry.map((l) => l.sequenceNumber).sort((a, b) => a - b);
+    const contiguousFromOne = sequences.every((n, i) => n === i + 1);
+    const ctrlSenders = new Set(carry.filter((l) => l.leafKind === LEAF_KIND_CTRL).map((l) => l.senderPubkeyHex));
+    const selfEvidentlyComplete = contiguousFromOne && ctrlSenders.size === 2;
+    /**
+     * 🚨 THE CERTIFICATE MAY COVER EXACTLY WHAT THIS SIDE HOLDS — ASK THAT FIRST.
+     *
+     * `DOD-M15-UNILATERAL-1`. The completeness predicate below describes a BILATERAL leaf set: two
+     * SEAL ctrl leaves, from two distinct senders. **A solo seal can never satisfy it**, because the
+     * counterparty is gone and never posts one — that is the entire premise. So on the solo path
+     * this returned `cannot_judge` every time, `session-ceremony.ts` refuses to co-sign on anything
+     * that is not `match`, and **the sealing party refused to co-sign its own unilateral seal.** The
+     * FROST ceremony never reached threshold, the directory never completed, and the close came back
+     * `seal_unilateral_timeout` — the label that names our own wait. Measured against the real
+     * binaries: `j-unilateral` failed on exactly this, with the directory having already verified the
+     * chain and recorded the counterparty ABSENT.
+     *
+     * Completeness was only ever needed to tell TWO KINDS OF DISAGREEMENT apart — "the roots differ
+     * because my carry is behind" (cannot judge) from "the roots differ because the directory
+     * certified something else" (mismatch). It answers nothing when the roots AGREE: a certificate
+     * whose root and leaf count are exactly what this daemon holds is, by construction, over this
+     * daemon's own leaves. Nothing is taken on trust — both values are recomputed here from the
+     * carry, and an adversary who could satisfy them would have to have produced this leaf set.
+     *
+     * Deliberately BOTH values. A count that disagreed while the root matched would be a certificate
+     * contradicting itself, and this is not the place to wave that through.
+     */
+    const carryInputs = carryContentHashInputs(carry);
+    if (carryInputs !== null &&
+        carry.length === certifiedLeafCount &&
+        Buffer.compare(Buffer.from(merkleRoot(buildMerkleTree(carryInputs))), Buffer.from(certifiedRoot)) === 0) {
+        return { verdict: "match" };
+    }
+    if (!selfEvidentlyComplete) {
+        return {
+            verdict: "cannot_judge",
+            reason: contiguousFromOne
+                ? `carry_incomplete: ${ctrlSenders.size} of 2 SEAL ctrl leaves witnessed here`
+                : `carry_noncontiguous: hold ${carry.length} leaves with a gap in the relay sequence`,
+        };
+    }
+    if (carry.length !== certifiedLeafCount) {
+        // The carry proves itself complete and the certificate claims a different size, so the
+        // certificate is over a different leaf set. Accusing is correct here.
+        return {
+            verdict: "mismatch",
+            ownRootHex: null, // no root computed — the sets differ in SIZE, which is decisive on its own
+            detail: `leaf_count_disagrees: this daemon holds a provably complete ${carry.length}-leaf set, the certificate claims ${certifiedLeafCount}`,
+        };
+    }
+    if (carryInputs === null) {
+        // A leaf this daemon cannot decode is a leaf it cannot judge. Never an accusation.
+        return { verdict: "cannot_judge", reason: "structure1_content_hash_unreadable" };
+    }
+    const ownRoot = merkleRoot(buildMerkleTree(carryInputs));
+    const ownRootHex = Buffer.from(ownRoot).toString("hex");
+    return Buffer.compare(Buffer.from(ownRoot), Buffer.from(certifiedRoot)) === 0
+        ? { verdict: "match" }
+        : { verdict: "mismatch", ownRootHex, detail: "root_disagrees: same leaf count, different leaves or different order" };
+}
+//# sourceMappingURL=seal-certified-root-check.js.map