@cello-protocol/daemon 0.0.181 → 0.0.183

package/dist/assignment-verify.js

@@ -0,0 +1,185 @@
+/**
+ * assignment-verify.ts — DOD-M15-ASSIGN-1.
+ *
+ * `session-assignment-parser.ts` shape-validates a session assignment. Its header said the
+ * signature "is verified downstream by the transport/session layer against the directory's pinned
+ * key" — and that site did not exist: `buildSessionEstablishmentTbs` was called to SIGN, and
+ * nowhere to verify. This module is the downstream the comment promised.
+ *
+ * SEPARATE FROM THE PARSER on purpose. Parsing answers "is this the right shape"; verifying answers
+ * "did the right party say it". Keeping them apart means the second cannot be quietly skipped by a
+ * caller that only wanted the first — which is how the gap existed.
+ */
+// `verify` (plain Ed25519) is deliberately NOT imported: the single-key branch that used it was
+// removed with the downgrade refusal (review F1). Verifying `directory_signature` against the
+// `directory_pubkey` riding beside it in the same unsigned frame checks a key against itself, and
+// having that call available is how a future edit reintroduces the bypass.
+import { verifyFrostSignature, CONTEXT_SESSION_ESTABLISHMENT } from "@cello-protocol/crypto";
+import { buildSessionEstablishmentTbs, computeGenesisPrevRoot } from "@cello-protocol/protocol-types";
+/**
+ * DOD-M15-ASSIGN-1 — verify a session assignment's signature before anything trusts it.
+ *
+ * REFUSES, never logs-and-continues. The whole finding here is a comment naming a verification the
+ * tree does not perform, so a check that ran and then let the session proceed anyway would be the
+ * same defect with more code. `DOD-M15-ASSIGN-1`'s receiver gate reads this assignment; gating on a
+ * document nobody verified relocates trust rather than closing it.
+ */
+export async function verifyAssignmentSignature(assignment, persistence, logger, agentName, correlationId) {
+    // RECOMPUTED, not taken from the frame — and that is a strengthening rather than a workaround.
+    // `genesis_prev_root` is not on the wire at all: the directory derives it from
+    // (pubA, pubB, session_id, timestamp) and so must we. A value we derive cannot be chosen for us,
+    // so the TBS we verify against is anchored to the assignment's own participants and id.
+    const genesisPrevRoot = computeGenesisPrevRoot(assignment.participant_a.pubkey, assignment.participant_b.pubkey, assignment.session_id, assignment.session_timestamp);
+    const tbs = buildSessionEstablishmentTbs(assignment.session_id, assignment.participant_a.pubkey, assignment.participant_b.pubkey, genesisPrevRoot, assignment.session_timestamp, assignment.initiator_session_peer_id, assignment.initiator_session_addrs, assignment.counterparty_session_peer_id, assignment.counterparty_session_addrs, assignment.transport_mode);
+    /**
+     * LOAD THE REGISTRATION BEFORE BRANCHING ON `signature_type` — review F1, and this ordering is
+     * the entire fix.
+     *
+     * `signature_type` rides in the frame and is covered by no signature. The parser reads any value
+     * that is not the string "frost" — including an ABSENT field — as "single". So while this load
+     * lived inside the frost branch, a hostile directory disabled every check below by omitting one
+     * field: it put its own freshly-minted key in `directory_pubkey`, signed a TBS naming an
+     * impostor as the counterparty, and the single-key branch verified that signature against that
+     * same key and returned ok. The anti-circularity comparison, the threshold verify and the
+     * fail-closed were all simply stepped over.
+     *
+     * Reading the registration first closes it: an agent that HAS a threshold registration knows its
+     * assignments are FROST-signed, so a non-FROST one is a downgrade attempt and is refused by
+     * name — never quietly routed to a weaker check.
+     */
+    const reg = await persistence.loadRegistrationState();
+    if (!reg) {
+        // FAIL CLOSED. Without our own registration we cannot know whose quorum should have signed,
+        // so the signature is unverifiable — which is not the same as valid.
+        logger.warn("session.assignment.verify.no_identity", {
+            agentName, correlationId,
+            impact: "this agent has no persisted registration, so the signer of its own session assignment cannot be established; the session was refused rather than accepted unverified",
+        });
+        return {
+            ok: false,
+            reason: "assignment_unverifiable_no_registration",
+            guidance: "This agent has no registration on record, so the directory's session assignment cannot be checked against the key that should have signed it. Re-register with cello register-agent, then try again.",
+        };
+    }
+    if (assignment.signature_type !== "frost") {
+        /**
+         * THE DOWNGRADE REFUSAL. Checked against the producer, not assumed: the directory constructs
+         * `signature_type: "frost"` unconditionally at a single site (`directory-node.ts`), with no
+         * branch that can emit anything else. There is no legitimate producer of a single-key session
+         * assignment for a registered agent, so this is not a compatibility path being closed — it is
+         * a shape that only an attacker or a broken directory can send.
+         */
+        logger.error("session.assignment.signature_type_downgraded", {
+            agentName, correlationId,
+            offeredType: assignment.signature_type,
+            impact: "the assignment claimed a weaker signature type than this agent's registration can produce, which would have routed it to a check that verifies a key against itself; it was refused, and no session was established",
+        });
+        return {
+            ok: false,
+            reason: "assignment_signature_type_downgraded",
+            guidance: "The directory returned a session assignment that does not carry a threshold signature, though this agent is registered with one. Nothing was established and no message was sent. Retry the session; if it repeats, the directory you reached is not producing valid assignments and cello status will show which one that is.",
+        };
+    }
+    {
+        // THE ANTI-CIRCULARITY CHECK. `signer_pubkey` comes from the frame; `reg.primaryPubkey` comes
+        // from this machine's own registration. Comparing them is what makes verifying against
+        // `signer_pubkey` mean anything at all.
+        const expected = reg.primaryPubkey.toLowerCase();
+        const offered = Buffer.from(assignment.signer_pubkey).toString("hex").toLowerCase();
+        if (offered !== expected) {
+            logger.error("session.assignment.signer_mismatch", {
+                agentName, correlationId,
+                expectedPrefix: expected.slice(0, 16), offeredPrefix: offered.slice(0, 16),
+                impact: "the assignment was signed by a key that is not this agent's own threshold group key; it was refused, and no session was established",
+            });
+            return {
+                ok: false,
+                reason: "assignment_signer_not_this_agent",
+                guidance: "The directory returned a session assignment signed by a key that is not this agent's own. Nothing was established and no message was sent. This is refused rather than reported as an error because the observation cannot distinguish a directory fault from an attempt to broker a session on your behalf; cause undetermined.",
+            };
+        }
+        if (!verifyFrostSignature(assignment.directory_signature, tbs, CONTEXT_SESSION_ESTABLISHMENT, assignment.signer_pubkey)) {
+            logger.error("session.assignment.signature_invalid", {
+                agentName, correlationId, signatureType: "frost",
+                impact: "the assignment's threshold signature did not verify over its own contents; it was refused, and no session was established",
+            });
+            return {
+                ok: false,
+                reason: "assignment_signature_invalid",
+                guidance: "The directory's session assignment did not verify against the key that should have signed it. Nothing was established. Retry the session; if it repeats, the directory you reached is not producing valid assignments and cello status will show which one that is.",
+            };
+        }
+        return { ok: true };
+    }
+}
+/**
+ * DOD-M15-RESPONDER-VERIFY-1 — the RESPONDER's half, which until now did not exist.
+ *
+ * The initiator verifies its assignment against its own threshold group key (above). The responder
+ * did not verify at all: it logged `session.inbound.assignment.unverified` and proceeded, so every
+ * field it then acted on — the dialer it opens its receiver to, the `signer_pubkey` it persists as
+ * the seal trust anchor — was whatever the directory said.
+ *
+ * ─── Why this could not simply reuse the function above ────────────────────────────────────────
+ *
+ * That one compares `signer_pubkey` against the agent's OWN persisted `primaryPubkey`. The responder
+ * is not the signer — the assignment is signed by the INITIATOR's quorum — so it has no equivalent
+ * value, and verifying a frame's signature against a key from the same frame is circular: mint a
+ * key, sign with it, name it. That circularity is why the check was deferred rather than written.
+ *
+ * ─── What breaks the circle ────────────────────────────────────────────────────────────────────
+ *
+ * The TOFU pin. For a counterparty this agent has completed a session with, `expectedSignerHex` is
+ * what THIS daemon recorded then — a value no directory can retroactively change. Verifying against
+ * that is a real check: a compromised directory can produce a signature, but not one that verifies
+ * under a key it does not hold.
+ *
+ * ─── Two modes, and the weaker one is honest about being weaker ────────────────────────────────
+ *
+ * PINNED (`expectedSignerHex` given): the signature must verify under the PINNED key. Non-circular.
+ * This is the mode that matters, and it covers every repeat counterparty.
+ *
+ * UNPINNED (first contact): there is nothing independent to verify against, so this checks INTERNAL
+ * CONSISTENCY only — the signature verifies over the TBS recomputed from the assignment's own
+ * contents, under the key the frame names. That does NOT authenticate the directory, and it is not
+ * claimed to. What it does catch is a TAMPERED or garbage assignment — one whose fields were altered
+ * after signing, or whose signature is noise — which today reaches the seal path unchallenged and
+ * gets PINNED, poisoning every later session with that counterparty. Refusing it here is what stops
+ * a bad first contact becoming a permanent one.
+ */
+export function verifyInboundAssignment(assignment, expectedSignerHex) {
+    if (assignment.signature_type !== "frost") {
+        return {
+            ok: false,
+            reason: "inbound_assignment_not_frost",
+            detail: `signature_type was ${String(assignment.signature_type)}; the directory produces frost for every session assignment`,
+        };
+    }
+    const signer = assignment.signer_pubkey;
+    if (!signer || signer.length !== 32) {
+        return { ok: false, reason: "inbound_assignment_no_signer", detail: "signer_pubkey missing or not 32 bytes" };
+    }
+    // PINNED beats named. When we hold an independent value, the frame's own claim about who signed is
+    // not consulted at all — using it would reintroduce the circularity the pin exists to break.
+    const verifyAgainst = expectedSignerHex !== null ? Buffer.from(expectedSignerHex, "hex") : signer;
+    if (expectedSignerHex !== null && Buffer.from(signer).toString("hex").toLowerCase() !== expectedSignerHex.toLowerCase()) {
+        return {
+            ok: false,
+            reason: "inbound_assignment_signer_not_pinned",
+            detail: "the assignment names a different signer than this agent recorded for this counterparty",
+        };
+    }
+    const genesisPrevRoot = computeGenesisPrevRoot(assignment.participant_a.pubkey, assignment.participant_b.pubkey, assignment.session_id, assignment.session_timestamp);
+    const tbs = buildSessionEstablishmentTbs(assignment.session_id, assignment.participant_a.pubkey, assignment.participant_b.pubkey, genesisPrevRoot, assignment.session_timestamp, assignment.initiator_session_peer_id, assignment.initiator_session_addrs, assignment.counterparty_session_peer_id, assignment.counterparty_session_addrs, assignment.transport_mode);
+    if (!verifyFrostSignature(assignment.directory_signature, tbs, CONTEXT_SESSION_ESTABLISHMENT, new Uint8Array(verifyAgainst))) {
+        return {
+            ok: false,
+            reason: "inbound_assignment_signature_invalid",
+            detail: expectedSignerHex !== null
+                ? "the signature did not verify under the key this agent recorded for this counterparty"
+                : "the signature did not verify over the assignment's own recomputed contents — the frame is tampered or malformed",
+        };
+    }
+    return { ok: true, mode: expectedSignerHex !== null ? "pinned" : "internal" };
+}
+//# sourceMappingURL=assignment-verify.js.map

package/dist/assignment-verify.js.map

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

package/dist/backup-restore.d.ts

@@ -0,0 +1,102 @@
+/**
+ * DOD-M15-BACKUP-1 — export an agent's identity, and put it back on another machine.
+ *
+ * ─── What a backup has to contain, and why the obvious answer is wrong ─────────────────────────
+ *
+ * The DoD line says *"Backup = exporting the SQLCipher database for transport."* Exporting the
+ * database alone produces a file nobody can ever open.
+ *
+ * The database is encrypted and its key is a separate 32-byte file at `<db>.key` — `sqlcipher-db.ts`
+ * calls it "the ONE plaintext key file on disk". A fresh daemon on a new machine mints its own key,
+ * which cannot open a database encrypted under a different one. An operator restoring a
+ * database-only archive would be told it worked, and find out on the day they needed it that the
+ * contents are unreadable forever.
+ *
+ * So the archive carries BOTH, and the round-trip test restores into a directory holding a
+ * different key precisely to prove it.
+ *
+ * ─── The consequence of that, which the tool must say out loud ─────────────────────────────────
+ *
+ * A file containing that key IS the agent. Whoever holds it can sign as them, read every
+ * transcript, and use their identity. Nothing about the word "backup" suggests a file this
+ * dangerous, so the response says it at the moment one is written. `DOD-M15-CLAIM-SCREEN-1`'s rule
+ * applies to affordances as much as claims: silence is not an option.
+ *
+ * ─── Why `VACUUM INTO` rather than copying the file ────────────────────────────────────────────
+ *
+ * The daemon holds the database open with a write lock. Copying the file byte-for-byte while it is
+ * open can capture a torn page or miss a WAL frame, producing an archive that restores into a
+ * corrupt database — the worst outcome available here, because it looks like a successful backup.
+ * `VACUUM INTO` asks SQLite for a consistent snapshot, and on SQLCipher the target inherits the
+ * source's cipher settings, so the snapshot is encrypted under the same key.
+ *
+ * ─── Restore is validated in full BEFORE anything is touched ───────────────────────────────────
+ *
+ * Restore OVERWRITES. A truncated or wrong file that is accepted destroys the working agent the
+ * operator still had — the backup tool becomes the thing that loses the identity. So the container
+ * is parsed, its checksum verified and its payloads decompressed entirely in memory first; only
+ * then does anything reach the disk.
+ *
+ * ─── V1 scope, per the DoD ─────────────────────────────────────────────────────────────────────
+ *
+ * Export plus overwrite-restore. MERGE — restoring onto a device that has its own live state — is
+ * explicitly deferred, and this module does not pretend otherwise: restore replaces, and says so.
+ */
+import type { Logger } from "./types.js";
+export type BackupResult = {
+    ok: true;
+    path: string;
+    bytes: number;
+    guidance: string;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+export type RestoreResult = {
+    ok: true;
+    dbPath: string;
+    guidance: string;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+/**
+ * Take a consistent snapshot of the live database and write a portable archive.
+ *
+ * `dbPath` is the live database. It may be open in this process; `VACUUM INTO` is safe against that
+ * and is why the snapshot goes through SQLite rather than a file copy.
+ */
+export declare function createBackup(opts: {
+    dbPath: string;
+    outPath: string;
+    logger: Logger;
+    keyPath?: string;
+    /** A backup is not a scratch file: replacing one is deliberate, never incidental. */
+    overwrite?: boolean;
+}): Promise<BackupResult>;
+/** Read an archive's metadata without restoring it. */
+export declare function inspectBackup(archivePath: string): Promise<{
+    ok: true;
+    createdAt: number;
+    hasKey: boolean;
+    dbBytes: number;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Replace this machine's database and key with the archive's.
+ *
+ * OVERWRITE, not merge — merge is explicitly deferred, and pretending otherwise would silently pick
+ * a winner between two divergent histories. The caller is responsible for the daemon not holding
+ * the database open; the handler enforces that.
+ */
+export declare function restoreBackup(opts: {
+    archivePath: string;
+    dbPath: string;
+    logger: Logger;
+    keyPath?: string;
+}): Promise<RestoreResult>;
+//# sourceMappingURL=backup-restore.d.ts.map

package/dist/backup-restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-restore.d.ts","sourceRoot":"","sources":["../src/backup-restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAoCzC,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAYpD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,OAAO,CAAC,YAAY,CAAC,CA0FxB;AAED,uDAAuD;AACvD,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAS5G;AA0DD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,aAAa,CAAC,CA6FzB"}

package/dist/backup-restore.js

@@ -0,0 +1,340 @@
+/**
+ * DOD-M15-BACKUP-1 — export an agent's identity, and put it back on another machine.
+ *
+ * ─── What a backup has to contain, and why the obvious answer is wrong ─────────────────────────
+ *
+ * The DoD line says *"Backup = exporting the SQLCipher database for transport."* Exporting the
+ * database alone produces a file nobody can ever open.
+ *
+ * The database is encrypted and its key is a separate 32-byte file at `<db>.key` — `sqlcipher-db.ts`
+ * calls it "the ONE plaintext key file on disk". A fresh daemon on a new machine mints its own key,
+ * which cannot open a database encrypted under a different one. An operator restoring a
+ * database-only archive would be told it worked, and find out on the day they needed it that the
+ * contents are unreadable forever.
+ *
+ * So the archive carries BOTH, and the round-trip test restores into a directory holding a
+ * different key precisely to prove it.
+ *
+ * ─── The consequence of that, which the tool must say out loud ─────────────────────────────────
+ *
+ * A file containing that key IS the agent. Whoever holds it can sign as them, read every
+ * transcript, and use their identity. Nothing about the word "backup" suggests a file this
+ * dangerous, so the response says it at the moment one is written. `DOD-M15-CLAIM-SCREEN-1`'s rule
+ * applies to affordances as much as claims: silence is not an option.
+ *
+ * ─── Why `VACUUM INTO` rather than copying the file ────────────────────────────────────────────
+ *
+ * The daemon holds the database open with a write lock. Copying the file byte-for-byte while it is
+ * open can capture a torn page or miss a WAL frame, producing an archive that restores into a
+ * corrupt database — the worst outcome available here, because it looks like a successful backup.
+ * `VACUUM INTO` asks SQLite for a consistent snapshot, and on SQLCipher the target inherits the
+ * source's cipher settings, so the snapshot is encrypted under the same key.
+ *
+ * ─── Restore is validated in full BEFORE anything is touched ───────────────────────────────────
+ *
+ * Restore OVERWRITES. A truncated or wrong file that is accepted destroys the working agent the
+ * operator still had — the backup tool becomes the thing that loses the identity. So the container
+ * is parsed, its checksum verified and its payloads decompressed entirely in memory first; only
+ * then does anything reach the disk.
+ *
+ * ─── V1 scope, per the DoD ─────────────────────────────────────────────────────────────────────
+ *
+ * Export plus overwrite-restore. MERGE — restoring onto a device that has its own live state — is
+ * explicitly deferred, and this module does not pretend otherwise: restore replaces, and says so.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { gzipSync, gunzipSync } from "node:zlib";
+import { readFile, writeFile, rm, mkdir, chmod, open as fsOpen, rename } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { openEncryptedDatabase, dbKeyPathFor } from "./sqlcipher-db.js";
+/**
+ * Write 0600, fsync, rename — and fsync the directory so the rename itself survives a power loss.
+ *
+ * Restore OVERWRITES an identity. A partially written database is the one failure that opens and is
+ * WRONG rather than failing loudly, because page 1 is enough for `sqlite_master` to read. Rename is
+ * atomic: the path is either the old file or the whole new one.
+ */
+async function writeFileDurably(path, bytes) {
+    const tmp = `${path}.restore-${randomBytes(6).toString("hex")}`;
+    const fh = await fsOpen(tmp, "wx", 0o600);
+    try {
+        await fh.write(bytes);
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmp, path);
+    const dir = await fsOpen(dirname(path), "r");
+    try {
+        await dir.sync();
+    }
+    finally {
+        await dir.close();
+    }
+}
+/** Magic + version, so a wrong file is refused by shape before anything else is attempted. */
+const MAGIC = "CELLO-BACKUP-v1";
+/**
+ * THE SENSITIVITY NOTICE. One string, used by every path that writes an archive, so a second call
+ * site cannot ship a quieter version of it.
+ */
+const SENSITIVITY = "TREAT THIS FILE LIKE A PRIVATE KEY. It contains your agent's encrypted database AND the key that " +
+    "opens it, because a backup without the key restores to something nobody can read. Anyone who has " +
+    "this file can sign as your agent and read every transcript in it. Store it where you would store " +
+    "a private key — not a shared drive, not a chat message.";
+/**
+ * Take a consistent snapshot of the live database and write a portable archive.
+ *
+ * `dbPath` is the live database. It may be open in this process; `VACUUM INTO` is safe against that
+ * and is why the snapshot goes through SQLite rather than a file copy.
+ */
+export async function createBackup(opts) {
+    const keyPath = opts.keyPath ?? dbKeyPathFor(opts.dbPath);
+    if (!existsSync(opts.dbPath)) {
+        return {
+            ok: false,
+            reason: "database_not_found",
+            guidance: `No database at ${opts.dbPath}. Start the daemon at least once before taking a backup — there is no identity to export yet.`,
+        };
+    }
+    if (!existsSync(keyPath)) {
+        // Refused rather than exported-without-key: an archive that cannot be opened is worse than no
+        // archive, because the operator stops worrying about it.
+        return {
+            ok: false,
+            reason: "key_file_not_found",
+            guidance: `The database at ${opts.dbPath} has no key file at ${keyPath}. Exporting the database without it would produce a backup nobody can ever open, so nothing was written.`,
+        };
+    }
+    if (existsSync(opts.outPath) && opts.overwrite !== true) {
+        return {
+            ok: false,
+            reason: "archive_exists",
+            guidance: `${opts.outPath} already exists. Replacing a backup silently is a way to lose an identity while believing you hold two copies of it — pass overwrite to replace it deliberately, or choose another path.`,
+        };
+    }
+    // A snapshot beside the real database, then read and discard it. `VACUUM INTO` refuses to write
+    // to an existing path, so the name is fresh per call.
+    // BESIDE THE ARCHIVE, not in the shared temp dir (review F11). On macOS `$TMPDIR` is per-user
+    // 0700, but on Linux it is `/tmp` and SQLite creates the snapshot at `0644 & ~umask`. The contents
+    // are encrypted — verified empirically, the header is ciphertext and it is unopenable without the
+    // key — so that is ciphertext exposure rather than key exposure. It is still a full copy of the
+    // database, and the `finally` below only covers throws: a SIGKILL mid-backup would leave it there.
+    const snapshot = join(dirname(opts.outPath), `.cello-backup-snapshot-${randomBytes(8).toString("hex")}.db`);
+    try {
+        const key = await readFile(keyPath);
+        const db = openEncryptedDatabase(opts.dbPath, new Uint8Array(key));
+        try {
+            db.exec(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`);
+        }
+        finally {
+            db.close();
+        }
+        const dbBytes = await readFile(snapshot);
+        const envelope = {
+            magic: MAGIC,
+            version: 1,
+            created_at: Date.now(),
+            db_sha256: createHash("sha256").update(dbBytes).digest("hex"),
+            db_b64: dbBytes.toString("base64"),
+            key_b64: key.toString("base64"),
+        };
+        const packed = gzipSync(Buffer.from(JSON.stringify(envelope), "utf8"));
+        await writeFile(opts.outPath, packed, { mode: 0o600 });
+        /**
+         * CHMOD AFTER THE WRITE, because `mode` is honoured only at `O_CREAT` — review F5, measured on
+         * this machine:
+         *
+         *     existing 0644 file + writeFile(mode 0600)  →  still 0644
+         *     existing 0666 file + writeFile(mode 0600)  →  still 0666
+         *     fresh file                                  →  0600
+         *
+         * So the `--force` path — overwriting yesterday's archive — kept whatever mode was already
+         * there. A file that arrived at 0644 (scp, a shell redirect under umask 022, an iCloud
+         * round-trip) would hold a WORLD-READABLE plaintext signing key. The comment claimed the
+         * property; only the create path enforced it.
+         */
+        await chmod(opts.outPath, 0o600);
+        opts.logger.info("agent.backup.written", {
+            path: opts.outPath,
+            bytes: packed.length,
+            impact: "the agent's identity, key shares, contacts, transcripts and seals are now exportable to another machine",
+            guidance: SENSITIVITY,
+        });
+        return { ok: true, path: opts.outPath, bytes: packed.length, guidance: SENSITIVITY };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        opts.logger.error("agent.backup.failed", { path: opts.outPath, reason });
+        return {
+            ok: false,
+            reason: "backup_failed",
+            guidance: `The backup could not be written: ${reason}. Nothing was changed on this machine.`,
+        };
+    }
+    finally {
+        await rm(snapshot, { force: true }).catch(() => { });
+    }
+}
+/** Read an archive's metadata without restoring it. */
+export async function inspectBackup(archivePath) {
+    const parsed = await parseArchive(archivePath);
+    if (!parsed.ok)
+        return { ok: false, reason: parsed.reason };
+    return {
+        ok: true,
+        createdAt: parsed.envelope.created_at,
+        hasKey: parsed.envelope.key_b64.length > 0,
+        dbBytes: parsed.dbBytes.length,
+    };
+}
+/**
+ * Parse and FULLY VALIDATE an archive in memory.
+ *
+ * Everything that can fail happens here, before `restoreBackup` touches the disk. That ordering is
+ * the whole safety property: a restore that fails must leave the machine exactly as it was.
+ */
+async function parseArchive(archivePath) {
+    if (!existsSync(archivePath))
+        return { ok: false, reason: "archive_not_found" };
+    let raw;
+    try {
+        raw = await readFile(archivePath);
+    }
+    catch (err) {
+        return { ok: false, reason: `archive_unreadable: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    let json;
+    try {
+        json = gunzipSync(raw).toString("utf8");
+    }
+    catch {
+        // A truncated file usually dies here — gzip carries its own length and CRC, which is why the
+        // container is compressed rather than raw JSON.
+        return { ok: false, reason: "archive_corrupt_or_not_a_cello_backup" };
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(json);
+    }
+    catch {
+        return { ok: false, reason: "archive_corrupt_or_not_a_cello_backup" };
+    }
+    if (envelope.magic !== MAGIC || envelope.version !== 1) {
+        return { ok: false, reason: "archive_wrong_format_or_version" };
+    }
+    if (typeof envelope.db_b64 !== "string" || typeof envelope.key_b64 !== "string") {
+        return { ok: false, reason: "archive_missing_payload" };
+    }
+    const dbBytes = Buffer.from(envelope.db_b64, "base64");
+    const keyBytes = Buffer.from(envelope.key_b64, "base64");
+    if (dbBytes.length === 0)
+        return { ok: false, reason: "archive_missing_database" };
+    if (keyBytes.length !== 32) {
+        // Without a well-formed key the restored database is unopenable — the exact failure this unit
+        // exists to prevent, so it is refused rather than restored hopefully.
+        return { ok: false, reason: "archive_missing_or_malformed_key" };
+    }
+    const actual = createHash("sha256").update(dbBytes).digest("hex");
+    if (actual !== envelope.db_sha256)
+        return { ok: false, reason: "archive_checksum_mismatch" };
+    return { ok: true, envelope, dbBytes, keyBytes };
+}
+/**
+ * Replace this machine's database and key with the archive's.
+ *
+ * OVERWRITE, not merge — merge is explicitly deferred, and pretending otherwise would silently pick
+ * a winner between two divergent histories. The caller is responsible for the daemon not holding
+ * the database open; the handler enforces that.
+ */
+export async function restoreBackup(opts) {
+    const keyPath = opts.keyPath ?? dbKeyPathFor(opts.dbPath);
+    const parsed = await parseArchive(opts.archivePath);
+    if (!parsed.ok) {
+        opts.logger.error("agent.restore.refused", {
+            archivePath: opts.archivePath,
+            reason: parsed.reason,
+            impact: "nothing was written — the agent currently on this machine is untouched",
+        });
+        return {
+            ok: false,
+            reason: parsed.reason,
+            guidance: `That file was not restored: ${parsed.reason}. NOTHING on this machine was changed — the ` +
+                `archive is validated completely before anything is written, because a restore overwrites ` +
+                `and a bad archive must never be able to destroy the agent you still have.`,
+        };
+    }
+    try {
+        // 0700, matching `resolveDbKey`'s own mkdir. On a fresh machine THIS is what creates the CELLO
+        // directory, and it holds a signing key (review F12).
+        await mkdir(dirname(opts.dbPath), { recursive: true, mode: 0o700 });
+        /**
+         * ORDER AND ATOMICITY — review F6/F7, and the previous comment here had it backwards.
+         *
+         * It said "key first, because a database without its key is the unopenable state". On a machine
+         * that ALREADY has an agent that is true but harmless — a key/db mismatch throws
+         * `db_encryption_key_mismatch`, loudly, and re-running the restore fixes it.
+         *
+         * On a FRESH machine — the actual restore use case — key-first is the dangerous order. Crash
+         * between the two writes and the key is present with NO database, so `resolveDbKey` loads the
+         * key and SQLCipher CREATES A FRESH EMPTY ONE. The daemon boots clean with zero agents and says
+         * nothing. That is the only crash state that opens, is wrong, and is silent.
+         *
+         * Worse, a crash MID-write left a truncated database whose page 1 was present, so
+         * `sqlite_master` read and the open SUCCEEDED against a partial file.
+         *
+         * Both are closed by writing to a temp sibling, fsync'ing, and renaming — rename is atomic, so
+         * the file either is the old one or is the whole new one, never half. The sidecars go first:
+         * stale WAL frames encrypted under the OLD key must not be present when the new database
+         * appears. Then the database, then the key — so the surviving crash state is db-present /
+         * key-absent, which `resolveDbKey` refuses loudly by design.
+         *
+         * The key write is fsync'd for the reason `sqlcipher-db.ts` gives where it writes the same file:
+         * "so a crash right after a fresh install can't lose the key while the encrypted DB exists".
+         * Returning ok:true with the key only in page cache re-opens that hole.
+         */
+        await rm(`${opts.dbPath}-wal`, { force: true }).catch(() => { });
+        await rm(`${opts.dbPath}-shm`, { force: true }).catch(() => { });
+        await writeFileDurably(opts.dbPath, parsed.dbBytes);
+        await writeFileDurably(keyPath, parsed.keyBytes);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        opts.logger.error("agent.restore.failed", { archivePath: opts.archivePath, reason });
+        return {
+            ok: false,
+            reason: "restore_write_failed",
+            guidance: `The restore could not complete: ${reason}. The database may be in a partial state — restore again from the same archive before starting the daemon.`,
+        };
+    }
+    // Prove it opens, here, rather than letting the daemon discover it at next boot.
+    try {
+        const db = openEncryptedDatabase(opts.dbPath, new Uint8Array(parsed.keyBytes));
+        db.close();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        opts.logger.error("agent.restore.unopenable", { dbPath: opts.dbPath, reason });
+        return {
+            ok: false,
+            reason: "restored_database_unopenable",
+            guidance: `The archive was written but the restored database could not be opened: ${reason}. This should not happen — the archive carries its own key. Keep the archive and report it.`,
+        };
+    }
+    const createdAt = new Date(parsed.envelope.created_at).toISOString();
+    opts.logger.info("agent.restore.completed", {
+        dbPath: opts.dbPath,
+        backupCreatedAt: createdAt,
+        impact: "this machine's agent database and key were REPLACED by the archive's",
+    });
+    return {
+        ok: true,
+        dbPath: opts.dbPath,
+        guidance: `Restored from a backup taken ${createdAt}. This machine's previous agent database was ` +
+            `REPLACED, not merged — anything that happened here since that backup is gone. Restart the ` +
+            `daemon (cello logout && cello login) so it opens the restored database.`,
+    };
+}
+//# sourceMappingURL=backup-restore.js.map