@crewhaus/citation-tracker 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/citation-tracker",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Per-research-run citation persistence + URL dedup (Section 23 RES)",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.0.0"
+    "@crewhaus/errors": "0.1.2"
   },
   "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 +30,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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { appendFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CitationTrackerError, createCitationTracker, newRunId } from "./index.js";
@@ -136,4 +136,155 @@ describe("createCitationTracker", () => {
       rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test("malformed jsonl in citations.jsonl surfaces as a CitationTrackerError", () => {
+    const root = newRoot();
+    const runId = newRunId();
+    const path = join(root, runId, "citations.jsonl");
+    try {
+      const t = createCitationTracker({ runId, rootDir: root });
+      t.recordCitation({ url: "u", snippet: "s" });
+      appendFileSync(path, "{not valid json\n");
+      expect(() => createCitationTracker({ runId, rootDir: root })).toThrow(CitationTrackerError);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("getFetchRecord returns metadata for a known URL and undefined otherwise", () => {
+    const root = newRoot();
+    try {
+      const t = createCitationTracker({ rootDir: root });
+      expect(t.getFetchRecord("missing")).toBeUndefined();
+      const rec = t.recordFetch({ url: "u", content: "the body", branchId: "b7" });
+      const got = t.getFetchRecord("u");
+      expect(got).toEqual(rec);
+      expect(got?.sha256).toMatch(/^[0-9a-f]{64}$/);
+      expect(got?.contentBytes).toBe(Buffer.byteLength("the body", "utf8"));
+      expect(got?.branchId).toBe("b7");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("getFetchedContent returns undefined for an unknown URL", () => {
+    const root = newRoot();
+    try {
+      const t = createCitationTracker({ rootDir: root });
+      expect(t.getFetchedContent("never-fetched")).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("listFetches returns all fetch records in append order", () => {
+    const root = newRoot();
+    try {
+      const t = createCitationTracker({ rootDir: root });
+      expect(t.listFetches()).toEqual([]);
+      t.recordFetch({ url: "first", content: "1" });
+      t.recordFetch({ url: "second", content: "2" });
+      // Idempotent re-record must NOT add a second entry.
+      t.recordFetch({ url: "first", content: "1-again" });
+      const urls = t.listFetches().map((r) => r.url);
+      expect(urls).toEqual(["first", "second"]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("listFetches survives kill-and-resume in append order", () => {
+    const root = newRoot();
+    const runId = newRunId();
+    try {
+      const t1 = createCitationTracker({ runId, rootDir: root });
+      t1.recordFetch({ url: "a", content: "ka" });
+      t1.recordFetch({ url: "b", content: "kb" });
+      const t2 = createCitationTracker({ runId, rootDir: root });
+      expect(t2.listFetches().map((r) => r.url)).toEqual(["a", "b"]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("recordCitation carries branchId and supportingClaim through to disk", () => {
+    const root = newRoot();
+    const runId = newRunId();
+    try {
+      const t = createCitationTracker({ runId, rootDir: root });
+      const c = t.recordCitation({
+        url: "u",
+        snippet: "s",
+        branchId: "branch-9",
+        supportingClaim: "supports: target shapes list",
+      });
+      expect(c.branchId).toBe("branch-9");
+      expect(c.supportingClaim).toBe("supports: target shapes list");
+
+      // Round-trips verbatim through the JSONL on resume.
+      const reopened = createCitationTracker({ runId, rootDir: root });
+      const persisted = reopened.listCitationsOrdered()[0];
+      expect(persisted?.branchId).toBe("branch-9");
+      expect(persisted?.supportingClaim).toBe("supports: target shapes list");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("now() injection makes retrievedAt deterministic", () => {
+    const root = newRoot();
+    try {
+      const fixed = new Date("2030-01-02T03:04:05.000Z");
+      const t = createCitationTracker({ rootDir: root, now: () => fixed });
+      const f = t.recordFetch({ url: "u", content: "x" });
+      expect(f.retrievedAt).toBe("2030-01-02T03:04:05.000Z");
+      // Citation with no prior fetch also stamps via now().
+      const c = t.recordCitation({ url: "other", snippet: "s" });
+      expect(c.retrievedAt).toBe("2030-01-02T03:04:05.000Z");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("newRunId produces well-formed, accepted run ids", () => {
+    const root = newRoot();
+    try {
+      const id = newRunId();
+      expect(id).toMatch(/^run_[0-9a-f]{16}$/);
+      // A freshly-minted id must be accepted by the validator.
+      const t = createCitationTracker({ runId: id, rootDir: root });
+      expect(t.runId).toBe(id);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("security: a tampered sha256 in fetches.jsonl cannot traverse out of the cache dir", () => {
+    const root = newRoot();
+    const runId = newRunId();
+    try {
+      // Boot once to create the run dir, then overwrite fetches.jsonl with a
+      // record whose sha256 is a path-traversal payload. A secret file lives
+      // two levels up (the runId dir) at a guessable name.
+      createCitationTracker({ runId, rootDir: root });
+      const secretPath = join(root, runId, "stolen.txt");
+      writeFileSync(secretPath, "TOP SECRET CONTENTS");
+      // cache/<sha256>.txt -> cache/../stolen.txt resolves to the secret file.
+      const evilRecord = {
+        version: 1,
+        url: "https://victim.example/x",
+        retrievedAt: "2030-01-01T00:00:00.000Z",
+        sha256: "../stolen",
+        contentBytes: 19,
+      };
+      writeFileSync(join(root, runId, "fetches.jsonl"), `${JSON.stringify(evilRecord)}\n`);
+
+      const t = createCitationTracker({ runId, rootDir: root });
+      expect(t.hasFetched("https://victim.example/x")).toBe(true);
+      // The guard must refuse the malformed sha256 rather than read the secret.
+      expect(t.getFetchedContent("https://victim.example/x")).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });

package/src/index.ts

@@ -35,6 +35,14 @@ import { CrewhausError, RuntimeError } from "@crewhaus/errors";
 
 export const DEFAULT_ROOT_DIR = ".crewhaus/research";
 const RUN_ID_RE = /^run_[0-9a-f]{16}$/;
+/**
+ * A sha256 digest is always exactly 64 lowercase hex chars. We re-validate it
+ * before interpolating into the cache file path because the value can originate
+ * from a JSONL line read off disk (boot-time replay), and a corrupted or
+ * tampered `fetches.jsonl` must not be able to steer a read outside `cache/`
+ * (e.g. a `sha256` of "../../../etc/passwd"). Legitimate records always match.
+ */
+const SHA256_RE = /^[0-9a-f]{64}$/;
 
 export type RunId = string;
 
@@ -170,6 +178,9 @@ export function createCitationTracker(opts: CreateCitationTrackerOptions = {}):
   }
 
   function tryReadCache(rec: FetchRecord): string | undefined {
+    // Defend the cache read against a tampered fetches.jsonl: a sha256 that is
+    // not a clean 64-hex digest could otherwise traverse out of cache/.
+    if (typeof rec.sha256 !== "string" || !SHA256_RE.test(rec.sha256)) return undefined;
     const p = cachePathFor(rec.sha256);
     if (!existsSync(p)) return undefined;
     return readFileSync(p, "utf8");