@cello-protocol/client 0.0.2

package/dist/backup-key-derivation.js

@@ -0,0 +1,48 @@
+/**
+ * backup-key-derivation.ts — HKDF derivation of the cloud backup encryption key.
+ *
+ * PERSIST-011: backup_key = HKDF-SHA256(ikm=identity_key, salt=none,
+ *              info='backup-key' || agent_id, length=32)
+ *
+ * Security invariants (PERSIST-011 SI-001):
+ *   - identity_key is passed in by the caller; it is NEVER stored here.
+ *   - The returned backup_key is NEVER logged or persisted by this function.
+ *   - This function has no side effects — pure transformation only.
+ *
+ * Key independence (AC-001):
+ *   - backup_key and db_key use distinct info strings:
+ *       db_key:     info = 'local-db-key\x00' + agentId
+ *       backup_key: info = 'backup-key\x00' + agentId
+ *   - For the same identity_key and agentId, backup_key != db_key.
+ *   - Losing one key does not compromise the other.
+ *
+ * RFC reference: RFC 5869 (HKDF). Node.js implementation: crypto.hkdfSync.
+ */
+import { hkdfSync } from "node:crypto";
+/**
+ * Derive a 32-byte cloud backup encryption key from the agent's identity_key.
+ *
+ * @param identityKey - The agent's long-term root key (32 bytes). Never stored or logged.
+ * @param agentId     - The stable agent identifier. Binds the key to a specific agent.
+ * @returns           - A 32-byte Uint8Array suitable for use as an AES-256-GCM key.
+ *
+ * Security: The backup_key is deterministic — same inputs always produce the same output.
+ * This is intentional: the client must re-derive the key on every backup/restore without
+ * storing it, using only the identity_key (which is stored separately, protected
+ * by the OS keychain or equivalent).
+ *
+ * The null-byte separator between the literal and agentId prevents prefix-collision
+ * attacks where two different (literal, agentId) pairs produce the same concatenation.
+ */
+export function deriveBackupKey(identityKey, agentId) {
+    // info = 'backup-key' || NUL || agentId (UTF-8 encoded).
+    // Distinct from db_key info string ('local-db-key\x00' + agentId) — same identity_key
+    // cannot produce the same output for both keys.
+    const infoStr = `backup-key\x00${agentId}`;
+    const info = Buffer.from(infoStr, "utf8");
+    // HKDF-SHA256: salt=none (empty Buffer), length=32 bytes
+    // RFC 5869 §2.2: when salt is not provided, a string of HashLen zeros is used.
+    const derived = hkdfSync("sha256", identityKey, Buffer.alloc(0), info, 32);
+    return new Uint8Array(derived);
+}
+//# sourceMappingURL=backup-key-derivation.js.map

package/dist/backup-key-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-key-derivation.js","sourceRoot":"","sources":["../src/backup-key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,WAAuB,EAAE,OAAe;IACtE,yDAAyD;IACzD,sFAAsF;IACtF,gDAAgD;IAChD,MAAM,OAAO,GAAG,iBAAiB,OAAO,EAAE,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE1C,yDAAyD;IACzD,+EAA+E;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAE3E,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/client-backup.d.ts

@@ -0,0 +1,144 @@
+/**
+ * client-backup.ts — Encrypted cloud backup for the CELLO client.
+ *
+ * PERSIST-011: Encrypts the local SQLCipher database file with AES-256-GCM
+ * using a backup_key derived from identity_key via HKDF, and uploads the
+ * ciphertext to the configured CloudStorageProvider.
+ *
+ * Security invariants:
+ *   SI-001: backup_key is NEVER uploaded to cloud storage, stored in backup
+ *           metadata, or included in any log event.
+ *   SI-002: AES-256-GCM with a fresh random 96-bit nonce per backup.
+ *           Nonce reuse with GCM leaks both the key and plaintext.
+ *   SI-003: Restore writes the decrypted plaintext to a temporary file first.
+ *           The live database is replaced only after checksum verification
+ *           passes (atomic rename). Corrupt downloads are discarded.
+ *
+ * Key derivation (RFC 5869 HKDF, NIST SP 800-38D AES-GCM):
+ *   backup_key = HKDF-SHA256(ikm=identity_key, salt=none,
+ *                             info='backup-key' || NUL || agent_id, length=32)
+ *
+ * Ciphertext wire format:
+ *   [nonce(12)] [auth_tag(16)] [encrypted_plaintext]
+ *
+ * Backup object key (cloud storage path):
+ *   backups/<agentId>/<timestamp>.enc  (timestamp = Date.now() at backup initiation)
+ *
+ * Backup metadata (stored in ClientStore under 'backup:metadata'):
+ *   { timestamp: number, destinationUrl: string, checksum: string }
+ *   where checksum = SHA-256 hex of the full ciphertext blob (nonce+tag+ciphertext).
+ */
+import type { CloudStorageProvider, Logger } from "@cello-protocol/interfaces";
+/**
+ * AC-007: Operator-facing warning about data that cannot be reconstructed.
+ * This constant is exported so the composition root can surface it in operator runbooks
+ * and configuration screens. The story requires it to be present in operator-facing
+ * documentation, not just in code comments.
+ */
+export declare const BACKUP_WARNING: string;
+/** Options for constructing a ClientBackup instance. */
+export interface ClientBackupOptions {
+    /** Stable agent identifier — used in log events and storage key derivation. */
+    agentId: string;
+    /**
+     * The agent's long-term identity_key (32 bytes).
+     * backup_key and db_key are both derived from this.
+     * NEVER stored, NEVER logged (SI-001).
+     */
+    identityKey: Uint8Array;
+    /** Absolute path to the local SQLCipher database file. */
+    dbPath: string;
+    /**
+     * Cloud storage adapter. If null, backup operations are skipped with a WARN log.
+     * Null models the case where the operator has not configured cloud storage (AC-005).
+     */
+    cloudStorage: CloudStorageProvider | null;
+    /** Structured logger injected from the composition root. */
+    logger: Logger;
+    /**
+     * Optional: read backup metadata from the local store.
+     * Defaults to no-op returning undefined if not provided (useful for pure encryption tests).
+     */
+    getMetadata?: (key: string) => Promise<Uint8Array | undefined>;
+    /**
+     * Optional: write backup metadata to the local store.
+     * Defaults to no-op if not provided.
+     */
+    setMetadata?: (key: string, value: Uint8Array) => Promise<void>;
+    /**
+     * Optional: verify the restored database is readable after restore completes.
+     * AC-003: After writing the decrypted file, restore() calls this callback
+     * to open the database with db_key and verify records are readable before
+     * declaring restore complete. If this callback throws, restore fails.
+     * Defaults to no-op if not provided (useful for pure encryption tests).
+     */
+    verifyRestored?: (dbPath: string) => Promise<void>;
+    /**
+     * PERSIST-022: Storage destination type for observability.
+     * Set by the composition root to "local" or "s3" depending on which
+     * CloudStorageProvider is wired in. Logged in client.backup.completed.
+     * Defaults to "local" for backward compatibility with M4 LocalCloudStorageProvider usage.
+     */
+    destinationType?: "local" | "s3";
+}
+/**
+ * Manages encrypted cloud backup and restore for the CELLO client database.
+ *
+ * Lifecycle: construct → backup() | restore() (may be called multiple times).
+ */
+export declare class ClientBackup {
+    #private;
+    constructor(options: ClientBackupOptions);
+    /**
+     * Encrypt the local SQLCipher database and upload it to cloud storage.
+     *
+     * On upload failure: logs client.backup.upload.failed and returns without throwing.
+     * On no cloud storage configured: logs client.backup.not.configured (WARN) and returns.
+     * On success: logs client.backup.completed and stores backup metadata.
+     *
+     * Pseudocode:
+     *   1. If no cloudStorage → warn client.backup.not.configured, return.
+     *   2. Derive backup_key via HKDF (RFC 5869).
+     *   3. Read plaintext DB file.
+     *   4. Generate fresh random 12-byte nonce (SI-002).
+     *   5. Encrypt with AES-256-GCM (NIST SP 800-38D).
+     *      Wire: [nonce(12)] [tag(16)] [ciphertext]
+     *   6. Compute SHA-256 of the full blob.
+     *   7. Upload blob to cloudStorage.
+     *   8. On failure: log client.backup.upload.failed, return { ok: false, reason }.
+     *   9. Store metadata { timestamp, destinationUrl, checksum } in local store.
+     *  10. Log client.backup.completed.
+     *  11. Return { ok: true }.
+     */
+    backup(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Download and decrypt the backup, replacing the local database file.
+     *
+     * On checksum mismatch: logs client.backup.restore.failed with reason 'checksum_mismatch',
+     * discards the corrupt download, does NOT overwrite the local DB, and throws.
+     *
+     * On decrypt failure: logs client.backup.restore.failed with reason 'decrypt_failed',
+     * does NOT overwrite the local DB, and throws.
+     *
+     * On success: logs client.backup.restore.completed.
+     *
+     * Pseudocode:
+     *   1. Derive backup_key via HKDF.
+     *   2. Download ciphertext blob from cloudStorage.
+     *   3. Read stored checksum from metadata.
+     *   4. Compute SHA-256 of downloaded blob.
+     *   5. If mismatch → log client.backup.restore.failed (checksum_mismatch), throw (SI-003).
+     *   6. Decrypt with AES-256-GCM.
+     *   7. Write plaintext to temp path: dbPath + '.restore-tmp' (SI-003).
+     *   8. Atomic rename temp → dbPath.
+     *   9. Call verifyRestored callback to open DB with db_key and verify readable (AC-003).
+     *  10. Log client.backup.restore.completed.
+     */
+    restore(): Promise<void>;
+}
+//# sourceMappingURL=client-backup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-backup.d.ts","sourceRoot":"","sources":["../src/client-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAQ/E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAGW,CAAC;AAiBvC,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,EAAE,UAAU,CAAC;IACxB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1C,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAC/D;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAID;;;;GAIG;AACH,qBAAa,YAAY;;gBAWX,OAAO,EAAE,mBAAmB;IAYxC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAmErE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkH/B"}

package/dist/client-backup.js

@@ -0,0 +1,273 @@
+/**
+ * client-backup.ts — Encrypted cloud backup for the CELLO client.
+ *
+ * PERSIST-011: Encrypts the local SQLCipher database file with AES-256-GCM
+ * using a backup_key derived from identity_key via HKDF, and uploads the
+ * ciphertext to the configured CloudStorageProvider.
+ *
+ * Security invariants:
+ *   SI-001: backup_key is NEVER uploaded to cloud storage, stored in backup
+ *           metadata, or included in any log event.
+ *   SI-002: AES-256-GCM with a fresh random 96-bit nonce per backup.
+ *           Nonce reuse with GCM leaks both the key and plaintext.
+ *   SI-003: Restore writes the decrypted plaintext to a temporary file first.
+ *           The live database is replaced only after checksum verification
+ *           passes (atomic rename). Corrupt downloads are discarded.
+ *
+ * Key derivation (RFC 5869 HKDF, NIST SP 800-38D AES-GCM):
+ *   backup_key = HKDF-SHA256(ikm=identity_key, salt=none,
+ *                             info='backup-key' || NUL || agent_id, length=32)
+ *
+ * Ciphertext wire format:
+ *   [nonce(12)] [auth_tag(16)] [encrypted_plaintext]
+ *
+ * Backup object key (cloud storage path):
+ *   backups/<agentId>/<timestamp>.enc  (timestamp = Date.now() at backup initiation)
+ *
+ * Backup metadata (stored in ClientStore under 'backup:metadata'):
+ *   { timestamp: number, destinationUrl: string, checksum: string }
+ *   where checksum = SHA-256 hex of the full ciphertext blob (nonce+tag+ciphertext).
+ */
+import { randomBytes, createCipheriv, createDecipheriv, createHash } from "node:crypto";
+import { readFile, writeFile, rename, unlink } from "node:fs/promises";
+import { deriveBackupKey } from "./backup-key-derivation.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const NONCE_BYTES = 12; // 96-bit nonce for AES-256-GCM (NIST SP 800-38D)
+const TAG_BYTES = 16; // 128-bit authentication tag
+/**
+ * AC-007: Operator-facing warning about data that cannot be reconstructed.
+ * This constant is exported so the composition root can surface it in operator runbooks
+ * and configuration screens. The story requires it to be present in operator-facing
+ * documentation, not just in code comments.
+ */
+export const BACKUP_WARNING = "Conversation Merkle trees are the only data that cannot be reconstructed from the directory. " +
+    "If you lose your local database and have no backup, you lose the ability to substantiate any " +
+    "dispute about those conversations.";
+// ─── ClientBackup ─────────────────────────────────────────────────────────────
+/**
+ * Manages encrypted cloud backup and restore for the CELLO client database.
+ *
+ * Lifecycle: construct → backup() | restore() (may be called multiple times).
+ */
+export class ClientBackup {
+    #agentId;
+    #identityKey;
+    #dbPath;
+    #cloudStorage;
+    #logger;
+    #getMetadata;
+    #setMetadata;
+    #verifyRestored;
+    #destinationType;
+    constructor(options) {
+        this.#agentId = options.agentId;
+        this.#identityKey = options.identityKey;
+        this.#dbPath = options.dbPath;
+        this.#cloudStorage = options.cloudStorage;
+        this.#logger = options.logger;
+        this.#getMetadata = options.getMetadata ?? (() => Promise.resolve(undefined));
+        this.#setMetadata = options.setMetadata ?? (() => Promise.resolve());
+        this.#verifyRestored = options.verifyRestored ?? (() => Promise.resolve());
+        this.#destinationType = options.destinationType ?? "local";
+    }
+    /**
+     * Encrypt the local SQLCipher database and upload it to cloud storage.
+     *
+     * On upload failure: logs client.backup.upload.failed and returns without throwing.
+     * On no cloud storage configured: logs client.backup.not.configured (WARN) and returns.
+     * On success: logs client.backup.completed and stores backup metadata.
+     *
+     * Pseudocode:
+     *   1. If no cloudStorage → warn client.backup.not.configured, return.
+     *   2. Derive backup_key via HKDF (RFC 5869).
+     *   3. Read plaintext DB file.
+     *   4. Generate fresh random 12-byte nonce (SI-002).
+     *   5. Encrypt with AES-256-GCM (NIST SP 800-38D).
+     *      Wire: [nonce(12)] [tag(16)] [ciphertext]
+     *   6. Compute SHA-256 of the full blob.
+     *   7. Upload blob to cloudStorage.
+     *   8. On failure: log client.backup.upload.failed, return { ok: false, reason }.
+     *   9. Store metadata { timestamp, destinationUrl, checksum } in local store.
+     *  10. Log client.backup.completed.
+     *  11. Return { ok: true }.
+     */
+    async backup() {
+        // AC-005: no cloud storage destination configured
+        if (this.#cloudStorage === null) {
+            this.#logger.warn("client.backup.not.configured", { agentId: this.#agentId });
+            return { ok: true }; // Not configured is not a failure — warn is sufficient
+        }
+        const startMs = Date.now();
+        // Derive backup_key — never stored, never logged (SI-001)
+        const backupKey = deriveBackupKey(this.#identityKey, this.#agentId);
+        // Read the plaintext database file
+        const plaintext = await readFile(this.#dbPath);
+        // Generate fresh random nonce per backup (SI-002 — never reuse nonce with GCM)
+        const nonce = randomBytes(NONCE_BYTES);
+        // Encrypt with AES-256-GCM (NIST SP 800-38D)
+        const cipher = createCipheriv("aes-256-gcm", backupKey, nonce);
+        const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        // Wire format: [nonce(12)] [tag(16)] [encrypted_plaintext]
+        const blob = Buffer.concat([nonce, tag, encrypted]);
+        // Zero backup_key immediately after use — it must not linger in memory (SI-001)
+        backupKey.fill(0);
+        // Compute SHA-256 checksum of the full blob (nonce+tag+ciphertext)
+        const checksum = createHash("sha256").update(blob).digest("hex");
+        // AC-002: key includes timestamp for uniqueness — backups/{agentId}/{timestamp}.enc
+        const storageKey = `backups/${this.#agentId}/${startMs}.enc`;
+        const destinationUrl = storageKey;
+        // Upload to cloud storage
+        try {
+            await this.#cloudStorage.upload(storageKey, new Uint8Array(blob));
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            // SI-001: context contains only { reason, agentId } — no key material
+            this.#logger.error("client.backup.upload.failed", { reason, agentId: this.#agentId });
+            return { ok: false, reason }; // local DB is unaffected; next triggered backup retries the full upload
+        }
+        // Store backup metadata in the local store
+        const metadata = {
+            timestamp: Date.now(),
+            destinationUrl,
+            checksum,
+        };
+        const metaBytes = Buffer.from(JSON.stringify(metadata), "utf8");
+        await this.#setMetadata("backup:metadata", new Uint8Array(metaBytes));
+        const durationMs = Date.now() - startMs;
+        this.#logger.info("client.backup.completed", {
+            agentId: this.#agentId,
+            destinationType: this.#destinationType,
+            ciphertextBytes: blob.length,
+            durationMs,
+        });
+        return { ok: true };
+    }
+    /**
+     * Download and decrypt the backup, replacing the local database file.
+     *
+     * On checksum mismatch: logs client.backup.restore.failed with reason 'checksum_mismatch',
+     * discards the corrupt download, does NOT overwrite the local DB, and throws.
+     *
+     * On decrypt failure: logs client.backup.restore.failed with reason 'decrypt_failed',
+     * does NOT overwrite the local DB, and throws.
+     *
+     * On success: logs client.backup.restore.completed.
+     *
+     * Pseudocode:
+     *   1. Derive backup_key via HKDF.
+     *   2. Download ciphertext blob from cloudStorage.
+     *   3. Read stored checksum from metadata.
+     *   4. Compute SHA-256 of downloaded blob.
+     *   5. If mismatch → log client.backup.restore.failed (checksum_mismatch), throw (SI-003).
+     *   6. Decrypt with AES-256-GCM.
+     *   7. Write plaintext to temp path: dbPath + '.restore-tmp' (SI-003).
+     *   8. Atomic rename temp → dbPath.
+     *   9. Call verifyRestored callback to open DB with db_key and verify readable (AC-003).
+     *  10. Log client.backup.restore.completed.
+     */
+    async restore() {
+        // AC-005: no cloud storage destination configured
+        if (this.#cloudStorage === null) {
+            this.#logger.warn("client.backup.not.configured", { agentId: this.#agentId });
+            throw new Error("Cloud storage not configured; cannot restore backup");
+        }
+        const startMs = Date.now();
+        const tempPath = this.#dbPath + ".restore-tmp";
+        // Derive backup_key — never stored, never logged (SI-001)
+        const backupKey = deriveBackupKey(this.#identityKey, this.#agentId);
+        let alreadyLogged = false;
+        try {
+            // Read stored metadata to get the storage key (destinationUrl).
+            // The storage key is timestamp-based (backups/{agentId}/{timestamp}.enc),
+            // so we must read it from metadata rather than reconstruct it.
+            const storedMeta = await this.#readMetadata();
+            // Without stored metadata we cannot verify the checksum — fail immediately.
+            if (storedMeta === undefined) {
+                this.#logger.error("client.backup.restore.failed", {
+                    reason: "no_backup_metadata",
+                    agentId: this.#agentId,
+                });
+                alreadyLogged = true;
+                throw new Error("no_backup_metadata");
+            }
+            const storageKey = storedMeta.destinationUrl;
+            // Download and verify
+            const downloaded = await this.#cloudStorage.download(storageKey);
+            if (downloaded === undefined) {
+                const reason = "backup_not_found";
+                this.#logger.error("client.backup.restore.failed", { reason, agentId: this.#agentId });
+                alreadyLogged = true;
+                throw new Error(`Backup not found at ${storageKey}`);
+            }
+            const blob = downloaded;
+            // Verify checksum against stored metadata (SI-003)
+            const actualChecksum = createHash("sha256").update(blob).digest("hex");
+            if (storedMeta.checksum !== actualChecksum) {
+                // SI-001: no key material in error context
+                this.#logger.error("client.backup.restore.failed", {
+                    reason: "checksum_mismatch",
+                    agentId: this.#agentId,
+                });
+                alreadyLogged = true;
+                // SI-003: temp file was not written yet; local DB untouched
+                throw new Error("checksum_mismatch");
+            }
+            // Decrypt with AES-256-GCM
+            // Wire format: [nonce(12)] [tag(16)] [encrypted_plaintext]
+            const buf = Buffer.from(blob);
+            const nonce = buf.subarray(0, NONCE_BYTES);
+            const tag = buf.subarray(NONCE_BYTES, NONCE_BYTES + TAG_BYTES);
+            const encryptedBody = buf.subarray(NONCE_BYTES + TAG_BYTES);
+            const decipher = createDecipheriv("aes-256-gcm", backupKey, nonce);
+            decipher.setAuthTag(tag);
+            const plaintext = Buffer.concat([decipher.update(encryptedBody), decipher.final()]);
+            // SI-003: write to temp path first, then atomically rename
+            // If write fails mid-way, the live DB is untouched
+            await writeFile(tempPath, plaintext);
+            await rename(tempPath, this.#dbPath);
+            // AC-003: After writing the restored file, open the database with db_key
+            // and verify it is readable before declaring restore complete.
+            // If verification throws, the error propagates and restore fails.
+            await this.#verifyRestored(this.#dbPath);
+            const durationMs = Date.now() - startMs;
+            this.#logger.info("client.backup.restore.completed", {
+                agentId: this.#agentId,
+                sourceUrl: storageKey,
+                durationMs,
+            });
+        }
+        catch (err) {
+            // Log errors if not already logged
+            if (!alreadyLogged) {
+                const reason = err instanceof Error ? err.message : String(err);
+                this.#logger.error("client.backup.restore.failed", {
+                    reason,
+                    agentId: this.#agentId,
+                });
+            }
+            // Attempt to clean up the temp file if it exists (ignore if already gone)
+            await unlink(tempPath).catch(() => { });
+            throw err;
+        }
+        finally {
+            // Zero backup_key on all paths (SI-001)
+            backupKey.fill(0);
+        }
+    }
+    // ─── Private helpers ─────────────────────────────────────────────────────────
+    /** Read and parse backup metadata from the local store. Returns undefined if not found. */
+    async #readMetadata() {
+        const raw = await this.#getMetadata("backup:metadata");
+        if (raw === undefined)
+            return undefined;
+        try {
+            return JSON.parse(Buffer.from(raw).toString("utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=client-backup.js.map

package/dist/client-backup.js.map

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