sealkeep 0.9.0 → 0.11.0

package/dist/src/restore.js

@@ -1,10 +1,14 @@
-import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { lstat, mkdir, realpath, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
-import { fail } from "./errors.js";
+import { fail, isSealkeepError } from "./errors.js";
 import { recordAudit } from "./audit.js";
 import { assertPhraseOpens, findArchive, readConfig, restoreRecordToFile } from "./vault.js";
+import { hashFileRange } from "../packages/sealkeep-crypto/src/index.js";
+import { readSourceBytes, resolveSourceReference } from "./source-reader.js";
+import { LEGACY_BUFFER_LIMIT_BYTES } from "./byte-stream.js";
+import { parkExistingPathNoClobber, publishTempCreateIfAbsent, restoreParkedCreateIfAbsent, validateNoFollowPath, } from "./reclaim-transaction.js";
 /**
  * Where each adapter's transcripts legitimately live. Restoring "natively" means
  * putting bytes back at the recorded original path, and only if that path is still
@@ -21,9 +25,24 @@ function within(candidate, root) {
 }
 /** Resolves the adapter-native destination, refusing anything outside the agent's roots. */
 export function nativeRestoreTarget(record, home = homedir()) {
-    const agent = record.source.agent;
+    // A record's agent tag is sticky: archive a Codex session once without
+    // naming the agent and it is "custom" forever, because re-archiving the same
+    // bytes returns the original record rather than writing a new one. The
+    // recorded path still says plainly where the file came from, so when the tag
+    // is unhelpful, ask the path. This only ever RESOLVES to a real agent root —
+    // the containment check below still refuses anything outside one.
+    let agent = record.source.agent;
     if (agent !== "codex" && agent !== "claude") {
-        fail("native_restore_unavailable", `No native restore path is defined for agent "${agent}"; pass an explicit destination`, { agent });
+        const resolved = resolve(record.source.path);
+        for (const candidate of ["codex", "claude"]) {
+            if (NATIVE_ROOTS[candidate](home).some((root) => within(resolved, root))) {
+                agent = candidate;
+                break;
+            }
+        }
+    }
+    if (agent !== "codex" && agent !== "claude") {
+        fail("native_restore_unavailable", `No native restore path is defined for agent "${record.source.agent}", and ${record.source.path} is not inside a known agent directory; pass an explicit destination`, { agent: record.source.agent });
     }
     const roots = NATIVE_ROOTS[agent](home);
     const original = resolve(record.source.path);
@@ -32,56 +51,273 @@ export function nativeRestoreTarget(record, home = homedir()) {
     }
     return original;
 }
+/**
+ * Build and verify a native transcript parent without following a symlinked
+ * `.codex`, `.claude`, sessions root, or date/project directory. The lexical
+ * target still remains the adapter's recorded path; canonicalisation here
+ * only makes platform aliases such as macOS `/var` -> `/private/var` safe to
+ * compare.
+ */
+export async function validateNativeRestoreOutput(output, home = homedir(), leaf = "missing-or-file") {
+    const lexicalHome = resolve(home);
+    const canonicalHome = await realpath(lexicalHome);
+    const suffix = output === lexicalHome ? "" : output.startsWith(lexicalHome.endsWith(sep) ? lexicalHome : `${lexicalHome}${sep}`)
+        ? output.slice(lexicalHome.length + (lexicalHome.endsWith(sep) ? 0 : 1))
+        : null;
+    if (suffix === null || suffix === "")
+        fail("path_not_permitted", `Native transcript path is outside the selected home: ${output}`);
+    const canonicalOutput = join(canonicalHome, suffix);
+    const roots = [...NATIVE_ROOTS.codex(canonicalHome), ...NATIVE_ROOTS.claude(canonicalHome)];
+    const parent = dirname(canonicalOutput);
+    const root = roots.find((candidate) => within(parent, candidate));
+    if (!root)
+        fail("path_not_permitted", `Native transcript path is outside the agent roots: ${output}`);
+    let cursor = canonicalHome;
+    for (const part of parent.slice(canonicalHome.length).split(sep).filter(Boolean)) {
+        cursor = join(cursor, part);
+        await mkdir(cursor, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        const info = await lstat(cursor);
+        if (!info.isDirectory() || info.isSymbolicLink() || await realpath(cursor) !== cursor) {
+            fail("path_not_permitted", `Native transcript parent is not a canonical directory: ${cursor}`);
+        }
+    }
+    try {
+        await validateNoFollowPath(canonicalOutput, roots, { leaf });
+    }
+    catch {
+        fail("path_not_permitted", `Native transcript path is not a regular file under its agent root: ${output}`);
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function destinationConflict(output) {
+    fail("destination_exists", `${output} already exists or changed while recovery was finishing. Its bytes were kept. Re-run after the writer stops, or choose another destination.`, { destination: output });
+}
+async function expectedFileOrNull(path) {
+    try {
+        return await hashFileRange(path);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function publishRestoreNoClobber(temp, output, expected) {
+    try {
+        await publishTempCreateIfAbsent(temp, output, expected);
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST")
+            destinationConflict(output);
+        throw error;
+    }
+}
+async function commitRestore(temp, output, expected, policy, operations) {
+    await operations?.beforeCommit?.({ output, policy });
+    if (policy === "refuse") {
+        await publishRestoreNoClobber(temp, output, expected);
+        return {};
+    }
+    const displaced = await expectedFileOrNull(output);
+    if (!displaced) {
+        await publishRestoreNoClobber(temp, output, expected);
+        return {};
+    }
+    // `replace` changes the active path, but it cannot safely unlink the old
+    // inode: another process may still have it open and append after any final
+    // stat/hash check. Keep that inode at a visible safety path, just as backup
+    // does, so every concurrent byte remains addressable.
+    const tag = policy === "backup" ? "backup" : "replaced";
+    const parkPath = `${output}.sealkeep-${tag}-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID()}`;
+    await operations?.beforePark?.({ output, parkPath, policy });
+    try {
+        await parkExistingPathNoClobber(output, parkPath, displaced);
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST") {
+            fail("destination_exists", `Recovery could not reserve ${parkPath}. Both that file and the current destination were kept; retry creates a different safety path.`, { destination: output, preservedPath: parkPath });
+        }
+        throw error;
+    }
+    await operations?.afterPark?.({ output, parkPath, policy });
+    try {
+        await publishRestoreNoClobber(temp, output, expected);
+    }
+    catch (error) {
+        // If nobody claimed the destination, put the displaced inode back. If a
+        // contender did, both it and the parked inode remain visible and untouched.
+        const rollback = await restoreParkedCreateIfAbsent(parkPath, output, displaced)
+            .then(() => "restored", () => "preserved");
+        if (rollback === "preserved") {
+            fail("destination_exists", `Recovery could not safely publish at ${output}. Any competing file was kept there, and the displaced file was kept at ${parkPath}.`, { destination: output, preservedPath: parkPath });
+        }
+        throw error;
+    }
+    return { backupPath: parkPath };
+}
 /**
  * Restores one archive atomically.
  *
- * The plaintext is streamed to a temporary file beside the destination and renamed
- * into place, so a crash never leaves a half-written transcript — and a transcript
+ * The plaintext is streamed to a temporary file beside the destination and
+ * published with create-if-absent semantics, so a crash never leaves a
+ * half-written transcript — and a transcript
  * of any size is restored without ever holding it in memory. An existing file
- * is refused by default; `backup` preserves it beside the restored copy and
- * `replace` is the only policy that discards it.
+ * is refused by default. `backup` preserves the displaced inode beside the
+ * restored copy. `replace` replaces the active destination too, but retains
+ * the displaced inode under a visible `.sealkeep-replaced-*` safety path: no
+ * portable filesystem primitive can prove that another process has stopped
+ * writing through an already-open descriptor.
  */
 export async function restoreArchive(dataDir, id, phrase, options = {}) {
     // A recipient key opens an archive it was wrapped for, without the phrase.
     // That is how an organisation reads what someone who has left sealed, and
     // how a project member reads a project they were added to.
     const key = options.privateKey;
-    const record = await findArchive(dataDir, id);
     const native = options.native === true;
     if (native && options.destination)
         fail("invalid_argument", "Choose either --native or an explicit destination, not both");
     if (!native && !options.destination)
         fail("invalid_argument", "A destination is required unless --native is used");
-    const output = native ? nativeRestoreTarget(record, options.home ?? homedir()) : resolve(options.destination);
-    const policy = options.overwrite ?? "refuse";
-    const existing = await stat(output).then(() => true).catch(() => false);
-    if (existing && policy === "refuse") {
-        fail("destination_exists", `${output} already exists. Re-run with --overwrite backup to keep it, or --overwrite replace to discard it.`, { destination: output });
-    }
-    // Proved before anything is created, because the restore itself writes as it
-    // decrypts: a wrong phrase must not leave a directory or a partial file
-    // behind. The config decides what "proved" means — unwrapping for a sealed
-    // vault, the identity check for a plain one.
-    // The phrase check proves the PHRASE opens this vault; a key holder has no
-    // phrase and the wrap itself is the proof, so the unwrap below is the gate.
-    if (!key)
-        assertPhraseOpens(await readConfig(dataDir), record, phrase);
-    await mkdir(dirname(output), { recursive: true });
-    const temp = join(dirname(output), `.${basename(output)}.${randomUUID()}.partial`);
-    let backupPath;
-    let bytes;
+    const source = options.source ?? (options.project ? await resolveSourceReference(dataDir, phrase, id, options.project, options.projectKey) : undefined);
+    if (options.source && id !== options.source.archiveId)
+        fail("invalid_argument", "archiveId must match the immutable source reference");
+    if (source?.spaceKey && native)
+        fail("native_restore_unavailable", "A Team source must be restored to an explicit destination on this device");
+    if (source?.spaceKey && options.destination && (options.overwrite ?? "refuse") === "refuse"
+        && await lstat(resolve(options.destination)).then(() => true, () => false))
+        destinationConflict(resolve(options.destination));
+    const teamRead = source ? await readSourceBytes(dataDir, phrase, source, {
+        maxWireBytes: LEGACY_BUFFER_LIMIT_BYTES, maxDecodedBytes: LEGACY_BUFFER_LIMIT_BYTES,
+        signal: AbortSignal.timeout(120_000),
+    }) : undefined;
     try {
-        ({ bytes } = await restoreRecordToFile(dataDir, record, key ? { privateKey: key } : phrase, temp));
-        if (existing && policy === "backup") {
-            backupPath = `${output}.vaultline-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-            await rename(output, backupPath);
+        const record = teamRead?.record ?? await findArchive(dataDir, id);
+        const output = native ? nativeRestoreTarget(record, options.home ?? homedir()) : resolve(options.destination);
+        const policy = options.overwrite ?? "refuse";
+        const existing = await lstat(output).then(() => true).catch(() => false);
+        // A dry run answers "what would this restore do" and stops before anything
+        // is created: no directory, no temp file, no audit row. The phrase (or the
+        // team read above) is still proven, so a wrong phrase fails here too instead
+        // of appearing to preview successfully. An existing destination is reported,
+        // not thrown — the caller asked what would happen, and this is the answer.
+        if (options.dryRun) {
+            if (!key && !teamRead)
+                assertPhraseOpens(await readConfig(dataDir), record, phrase);
+            return { record, output, bytes: record.source.bytes, native, dryRun: true, destinationExists: existing };
+        }
+        if (existing && policy === "refuse") {
+            fail("destination_exists", `${output} already exists. Re-run with --overwrite backup or replace; either keeps the displaced file at a visible safety path.`, { destination: output });
+        }
+        // Proved before anything is created, because the restore itself writes as it
+        // decrypts: a wrong phrase must not leave a directory or a partial file
+        // behind. The config decides what "proved" means — unwrapping for a sealed
+        // vault, the identity check for a plain one.
+        // The phrase check proves the PHRASE opens this vault; a key holder has no
+        // phrase and the wrap itself is the proof, so the unwrap below is the gate.
+        if (!key && !teamRead)
+            assertPhraseOpens(await readConfig(dataDir), record, phrase);
+        if (native)
+            await validateNativeRestoreOutput(output, options.home ?? homedir(), "missing-or-file");
+        else
+            await mkdir(dirname(output), { recursive: true });
+        const temp = join(dirname(output), `.${basename(output)}.${randomUUID()}.partial`);
+        let backupPath;
+        let bytes;
+        try {
+            if (teamRead) {
+                await writeFile(temp, teamRead.bytes, { mode: 0o600, flag: "wx" });
+                bytes = teamRead.bytes.length;
+                await teamRead.assertCurrent();
+            }
+            else
+                ({ bytes } = await restoreRecordToFile(dataDir, record, key ? { privateKey: key } : phrase, temp));
+            const committed = await commitRestore(temp, output, { bytes, sha256: record.source.sha256 }, policy, teamRead ? { ...options.operations, beforeCommit: async (input) => {
+                    await options.operations?.beforeCommit?.(input);
+                    await teamRead.assertCurrent();
+                } } : options.operations);
+            backupPath = committed.backupPath;
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            // Refusals are what an audit log is FOR: a revoked colleague probing an
+            // archive after removal used to leave no trace at all.
+            await recordAudit(dataDir, "archive.restore", "denied", { archiveId: id, output, reason: isSealkeepError(error) ? error.code : "error" }).catch(() => undefined);
+            throw error;
         }
-        await rename(temp, output);
+        finally {
+            teamRead?.bytes.fill(0);
+        }
+        await recordAudit(dataDir, "archive.restore", "allowed", { archiveId: id, output, bytes, native, backedUp: Boolean(backupPath) });
+        return { record, output, bytes, native, backupPath };
+    }
+    finally {
+        teamRead?.bytes.fill(0);
+    }
+}
+/**
+ * Proves an archive can produce the bytes it claims, before anything is taken.
+ *
+ * Decrypts the archive to a scratch file and hashes the result. Nothing else
+ * in this file is allowed to trash a source until this has returned true —
+ * the point is to catch a codec or storage fault while the original is still
+ * on disk, which is the only moment catching it is worth anything.
+ */
+export async function verifyArchiveReadsBack(dataDir, archiveId, phrase, expectedSha256) {
+    const { createHash } = await import("node:crypto");
+    const { Writable } = await import("node:stream");
+    const { findArchive, restoreRecordToFile } = await import("./vault.js");
+    /**
+     * Hash the plaintext as it goes past; write it nowhere.
+     *
+     * This used to restore to a scratch file and hash that, which cost as much
+     * FREE DISK as the original session — so on a full disk the proof was
+     * impossible exactly when it was needed, and `squeeze` reported the ENOSPC as
+     * "the archive did not read back", which reads as corruption. The bytes are
+     * still hashed and still compared; they simply never land.
+     */
+    const digest = createHash("sha256");
+    const sink = new Writable({ write(chunk, _enc, done) { digest.update(chunk); done(); } });
+    try {
+        const record = await findArchive(dataDir, archiveId);
+        await restoreRecordToFile(dataDir, record, phrase, sink);
+        return digest.digest("hex") === expectedSha256;
     }
     catch (error) {
-        await rm(temp, { force: true });
-        throw error;
+        // A delta chain or a plain-mode vault rebuilds through real files. Those
+        // fall back to the scratch-file proof, which is correct where there is room.
+        const { isSealkeepError } = await import("./errors.js");
+        if (isSealkeepError(error) && error.code === "invalid_argument")
+            return verifyViaScratchFile(dataDir, archiveId, phrase, expectedSha256);
+        return false;
+    }
+}
+/** The original proof: restore to a scratch file and hash it. Needs room for the whole session. */
+async function verifyViaScratchFile(dataDir, archiveId, phrase, expectedSha256) {
+    const { mkdtemp, rm: removeFile } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join: joinPath } = await import("node:path");
+    const { createReadStream } = await import("node:fs");
+    const { createHash } = await import("node:crypto");
+    const { pipeline } = await import("node:stream/promises");
+    const scratch = await mkdtemp(joinPath(tmpdir(), "sealkeep-verify-"));
+    const probe = joinPath(scratch, "readback");
+    try {
+        await restoreArchive(dataDir, archiveId, phrase, { destination: probe, overwrite: "replace" });
+        const digest = createHash("sha256");
+        await pipeline(createReadStream(probe), digest);
+        return digest.digest("hex") === expectedSha256;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await removeFile(scratch, { recursive: true, force: true });
     }
-    await recordAudit(dataDir, "archive.restore", "allowed", { archiveId: id, output, bytes, native, backedUp: Boolean(backupPath) });
-    return { record, output, bytes, native, backupPath };
 }

package/dist/src/resume-stub.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A stable, model-visible marker.  It deliberately lives in an ordinary Codex
+ * message rather than in a made-up rollout record type: old and new Codex
+ * builds may ignore fields they do not know, but the conversation loader has
+ * always understood user/assistant messages.
+ */
+export declare const CODEX_RESUME_STUB_MARKER = "sealkeep://codex-resume-stub/v1";
+export type CodexResumeStub = {
+    version: 1;
+    archiveId: string;
+    sessionId: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+export type PreparedCodexResumeStub = CodexResumeStub & {
+    tempPath: string;
+    atime: Date;
+    mtime: Date;
+};
+/**
+ * Only real, non-symlinked native Codex rollout locations participate.
+ *
+ * Lexical containment is insufficient here: a symlinked `sessions` directory
+ * can make a path spell `~/.codex/sessions/...` while naming an unrelated file
+ * elsewhere. Check every user-controlled path component with lstat, then check
+ * canonical containment as a second independent condition.
+ */
+export declare function isNativeCodexSessionPath(path: string, home?: string): Promise<boolean>;
+/** Canonical no-follow validation shared by reclaim and crash reconciliation. */
+export declare function validateNativeCodexSessionPath(path: string, home?: string, leaf?: "file" | "missing-or-file"): Promise<string>;
+/** The native filename, not a parent directory or a longer hex token, owns the session id. */
+export declare function codexSessionIdMatchesFilename(path: string, sessionId: string): boolean;
+/** Validates that replacing this exact native rollout with a pointer is supported. */
+export declare function assertCodexResumePointerSupported(path: string, home?: string): Promise<void>;
+/**
+ * Re-validates a staged original against its logical native filename.
+ * Crash reconciliation uses this after upgrades: staging lives inside the
+ * vault, but the rollout UUID contract still belongs to the original path.
+ */
+export declare function assertCodexResumePointerMetadataSupported(contentsPath: string, logicalNativePath: string): Promise<void>;
+/**
+ * A reclaim journal may outlive the binary that wrote it. Do not let such a
+ * journal turn an arbitrary neighbouring file into a replacement temp: only
+ * the private basename generated by prepareCodexResumeStub is eligible.
+ */
+export declare function assertCodexResumePointerTempPath(tempPath: string): void;
+/**
+ * Return true only when an existing pathname is the exact journaled pointer
+ * and its structured contents bind it to this native session and archive.
+ * A missing or fingerprint-mismatched pathname returns false because generic
+ * reconciliation already retains it. A matching-but-invalid pathname throws:
+ * deleting or publishing it based only on a journal-supplied hash would let a
+ * corrupt journal target an unrelated neighbouring file.
+ */
+export declare function validateCodexResumePointerBinding(contentsPath: string, logicalNativePath: string, archiveId: string, expected: {
+    bytes: number;
+    sha256: string;
+}): Promise<boolean>;
+/** Own and validated parent IDs that may identify a live Codex process. */
+export declare function codexSessionProcessIds(path: string): Promise<string[]>;
+/** IDs plus project cwd used when a live Codex process has no UUID in argv. */
+export declare function codexSessionProcessIdentity(path: string): Promise<{
+    ids: string[];
+    cwd: string;
+}>;
+/**
+ * Builds the replacement beside the source, while the original is still
+ * present and fully verified. The caller transaction-stages the original first
+ * and then publishes this prepared file into its native path without
+ * overwriting a path the agent recreated in the meantime.
+ *
+ * The original session-meta line is kept byte-for-byte.  It is the format
+ * contract of the installed Codex build and carries the stable id, cwd, git
+ * project, source kind and original timestamp.  Even a large modern metadata
+ * line is tiny beside a multi-GB rollout and avoids guessing at vendor fields.
+ */
+export declare function prepareCodexResumeStub(sourcePath: string, archiveId: string, options?: {
+    home?: string;
+    project?: string | null;
+    /** Test seam; production fsyncs the complete pointer inode after utimes. */
+    syncPreparedFile?: (path: string) => Promise<void>;
+}): Promise<PreparedCodexResumeStub | null>;
+/** Installs an already-prepared pointer without clobbering a recreated path. */
+export declare function installCodexResumeStub(stub: PreparedCodexResumeStub): Promise<void>;
+export declare function discardCodexResumeStub(stub: PreparedCodexResumeStub | null): Promise<void>;
+/**
+ * Recognises only the complete, untouched pointer format.  Once Codex appends
+ * a new turn there are more than the three expected lines, so the worker
+ * archives that new work normally instead of permanently excluding the file.
+ */
+export declare function readUntouchedCodexResumeStub(path: string): Promise<CodexResumeStub | null>;