@crewhaus/checkpoint-store 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/checkpoint-store",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "File-backed checkpoint store for graph-engine — save/load/list/branch over per-graph-run JSON files",
   "main": "src/index.ts",
@@ -12,13 +12,14 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/errors": "0.1.3",
+    "@crewhaus/tenancy": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +31,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -3,9 +3,15 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { RuntimeError } from "@crewhaus/errors";
+import { TenancyError, buildTenant, withTenant } from "@crewhaus/tenancy";
 import {
+  type Checkpoint,
   type CheckpointStore,
+  type CheckpointStoreAdapter,
   CheckpointStoreError,
+  type GraphRunId,
+  type GraphRunMeta,
+  type ListOptions,
   createCheckpointStore,
   newCheckpointId,
   newGraphRunId,
@@ -206,3 +212,190 @@ describe("stress (T7-lite)", () => {
     expect(list[499]?.state).toEqual({ i: 499 });
   }, 15_000);
 });
+
+describe("cross-tenant fencing (CWE-1230)", () => {
+  test("inside tenantA, a store rooted under tenantB fails closed", async () => {
+    const tenantsRoot = mkdtempSync(join(tmpdir(), "checkpoint-tenants-"));
+    try {
+      const tenantA = buildTenant("tenant-a", { tenantsRoot });
+      const tenantB = buildTenant("tenant-b", { tenantsRoot });
+      // Store rooted under tenantB while tenantA is active — every resolved
+      // graph-run directory escapes tenantA's sessionRoot, so it fails closed.
+      const fenced = createCheckpointStore({ rootDir: tenantB.sessionRoot });
+      await withTenant(tenantA, async () => {
+        const grun = newGraphRunId();
+        await expect(fenced.save({ graphRunId: grun, nodeName: "a", state: 1 })).rejects.toThrow(
+          TenancyError,
+        );
+        await expect(fenced.load(grun)).rejects.toThrow(/cross-tenant access denied/);
+      });
+    } finally {
+      rmSync(tenantsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("inside tenantA, a store rooted under tenantA round-trips", async () => {
+    const tenantsRoot = mkdtempSync(join(tmpdir(), "checkpoint-tenants-"));
+    try {
+      const tenantA = buildTenant("tenant-a", { tenantsRoot });
+      const ok = createCheckpointStore({ rootDir: tenantA.sessionRoot });
+      await withTenant(tenantA, async () => {
+        const grun = newGraphRunId();
+        const cp = await ok.save({ graphRunId: grun, nodeName: "a", state: { x: 1 } });
+        const loaded = await ok.load(grun, cp.id);
+        expect(loaded?.id).toBe(cp.id);
+      });
+    } finally {
+      rmSync(tenantsRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("no active tenant — behaviour is unchanged (no fencing)", async () => {
+    const grun = newGraphRunId();
+    const cp = await store.save({ graphRunId: grun, nodeName: "a", state: { x: 1 } });
+    const loaded = await store.load(grun, cp.id);
+    expect(loaded?.id).toBe(cp.id);
+  });
+});
+
+describe("list: since filter", () => {
+  // A controllable clock keeps checkpoint timestamps deterministic so the
+  // `since` boundary is exercised without depending on the real wall clock.
+  test("skips checkpoints created strictly before `since`", async () => {
+    const clock = { ms: Date.parse("2026-01-01T00:00:00.000Z") };
+    const clocked = createCheckpointStore({
+      rootDir: tmp,
+      now: () => new Date(clock.ms),
+    });
+    const grun = newGraphRunId();
+
+    const older = await clocked.save({ graphRunId: grun, nodeName: "old", state: 1 });
+    clock.ms += 60_000; // advance one minute
+    const newer = await clocked.save({ graphRunId: grun, nodeName: "new", state: 2 });
+
+    // `since` lands between the two checkpoints: the older one is filtered out
+    // (the `continue` branch), the newer one is kept.
+    const cutoff = new Date(clock.ms - 30_000).toISOString();
+    const list = await clocked.list(grun, { since: cutoff });
+    expect(list.map((c) => c.id)).toEqual([newer.id]);
+    expect(list.map((c) => c.id)).not.toContain(older.id);
+  });
+
+  test("`since` in the future drops everything", async () => {
+    const grun = newGraphRunId();
+    await store.save({ graphRunId: grun, nodeName: "a", state: 1 });
+    const list = await store.list(grun, { since: "2999-01-01T00:00:00.000Z" });
+    expect(list).toEqual([]);
+  });
+});
+
+describe("save: parentCheckpointId validation", () => {
+  test("rejects a malformed parentCheckpointId before any write", async () => {
+    const grun = newGraphRunId();
+    await expect(
+      store.save({ graphRunId: grun, nodeName: "a", state: 1, parentCheckpointId: "../../bad" }),
+    ).rejects.toBeInstanceOf(RuntimeError);
+    // Nothing was persisted for this run.
+    expect(await store.meta(grun)).toBeUndefined();
+  });
+});
+
+describe("pluggable adapter", () => {
+  // A minimal in-memory adapter proves `createCheckpointStore({ adapter })`
+  // wires a non-filesystem backend through every public method, and lets us
+  // reach states the file-backed adapter never produces on its own.
+  function makeMemoryAdapter(): {
+    adapter: CheckpointStoreAdapter;
+    checkpoints: Map<string, Checkpoint>;
+    metas: Map<GraphRunId, GraphRunMeta>;
+  } {
+    const checkpoints = new Map<string, Checkpoint>();
+    const metas = new Map<GraphRunId, GraphRunMeta>();
+    const key = (g: GraphRunId, c: string): string => `${g}/${c}`;
+    const adapter: CheckpointStoreAdapter = {
+      async save(c: Checkpoint): Promise<void> {
+        checkpoints.set(key(c.graphRunId, c.id), c);
+      },
+      async load(g: GraphRunId, c: string): Promise<Checkpoint | undefined> {
+        return checkpoints.get(key(g, c));
+      },
+      async list(g: GraphRunId, _opts: ListOptions): Promise<ReadonlyArray<Checkpoint>> {
+        return [...checkpoints.values()].filter((c) => c.graphRunId === g);
+      },
+      async loadMeta(g: GraphRunId): Promise<GraphRunMeta | undefined> {
+        return metas.get(g);
+      },
+      async saveMeta(m: GraphRunMeta): Promise<void> {
+        metas.set(m.graphRunId, m);
+      },
+      async drop(g: GraphRunId): Promise<void> {
+        metas.delete(g);
+        for (const k of [...checkpoints.keys()]) {
+          if (k.startsWith(`${g}/`)) checkpoints.delete(k);
+        }
+      },
+    };
+    return { adapter, checkpoints, metas };
+  }
+
+  test("save → load → branch → drop all route through the custom adapter", async () => {
+    const { adapter, checkpoints, metas } = makeMemoryAdapter();
+    const custom = createCheckpointStore({ adapter });
+
+    const grun = newGraphRunId();
+    const cp = await custom.save({ graphRunId: grun, nodeName: "plan", state: { a: 1 } });
+    expect(checkpoints.get(`${grun}/${cp.id}`)?.nodeName).toBe("plan");
+    expect(metas.get(grun)?.head).toBe(cp.id);
+
+    expect((await custom.load(grun, cp.id))?.id).toBe(cp.id);
+    expect((await custom.load(grun))?.id).toBe(cp.id);
+
+    const { newGraphRunId: child, head } = await custom.branch(grun, cp.id);
+    expect(metas.get(child)?.branchedFrom).toEqual({ graphRunId: grun, checkpointId: cp.id });
+    expect(head.state).toEqual({ a: 1 });
+
+    await custom.drop(grun);
+    expect(metas.has(grun)).toBe(false);
+    expect(await custom.load(grun, cp.id)).toBeUndefined();
+  });
+
+  test("load without checkpointId returns undefined when meta has no head", async () => {
+    const { adapter, metas } = makeMemoryAdapter();
+    const custom = createCheckpointStore({ adapter });
+    const grun = newGraphRunId();
+    // Seed a meta with no head — a state a freshly-created run can hold before
+    // its first commit. `load(grun)` must short-circuit to undefined.
+    metas.set(grun, { version: 1, graphRunId: grun, createdAt: new Date(0).toISOString() });
+    expect(await custom.load(grun)).toBeUndefined();
+  });
+
+  test("save preserves an existing meta's branchedFrom when advancing head", async () => {
+    const { adapter, metas } = makeMemoryAdapter();
+    const custom = createCheckpointStore({ adapter });
+    const grun = newGraphRunId();
+    const branchedFrom = { graphRunId: newGraphRunId(), checkpointId: newCheckpointId() };
+    // Pre-seed a branched-run meta (head absent), then commit: ensureMeta must
+    // reuse the existing meta so branchedFrom survives the head update.
+    metas.set(grun, {
+      version: 1,
+      graphRunId: grun,
+      createdAt: new Date(0).toISOString(),
+      branchedFrom,
+    });
+    const cp = await custom.save({ graphRunId: grun, nodeName: "n", state: 1 });
+    expect(metas.get(grun)?.head).toBe(cp.id);
+    expect(metas.get(grun)?.branchedFrom).toEqual(branchedFrom);
+  });
+});
+
+describe("CheckpointStoreError", () => {
+  test("carries the config code and serializes its cause chain", () => {
+    const root = new Error("disk gone");
+    const err = new CheckpointStoreError("save failed", root);
+    expect(err).toBeInstanceOf(CheckpointStoreError);
+    expect(err.code).toBe("config");
+    expect(err.name).toBe("CheckpointStoreError");
+    const json = err.toJSON();
+    expect(json.cause).toEqual({ name: "Error", message: "disk gone" });
+  });
+});

package/src/index.ts

@@ -38,8 +38,9 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { CrewhausError, RuntimeError } from "@crewhaus/errors";
+import { assertSamePath, currentTenantContext, requireTenant } from "@crewhaus/tenancy";
 
 export const DEFAULT_ROOT_DIR = ".crewhaus/graphs";
 
@@ -160,7 +161,16 @@ class FileSystemAdapter implements CheckpointStoreAdapter {
 
   private dir(graphRunId: GraphRunId): string {
     validateGraphRunId(graphRunId);
-    return join(this.rootDir, graphRunId);
+    const dir = join(this.rootDir, graphRunId);
+    // When a tenant context is active, fail closed on a resolved path that
+    // escapes the tenant's sessionRoot (CWE-1230). Every checkpoint/meta path
+    // is built under this directory, so fencing here covers every read/write.
+    // Outside a tenant scope (the common CLI case) this is a no-op so
+    // non-tenant behaviour is unchanged.
+    if (currentTenantContext() !== undefined) {
+      assertSamePath(resolve(dir), requireTenant().sessionRoot);
+    }
+    return dir;
   }
 
   private metaPath(graphRunId: GraphRunId): string {