@crewhaus/tool-document-ingest 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-document-ingest",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "M4.3 — IngestDocument tool. Reads .txt/.md/.csv/.json/.yaml inline; PDF/docx/xlsx via pluggable parsers (deferred to operator-provided handlers).",
   "main": "src/index.ts",
@@ -12,16 +12,16 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1",
-    "@crewhaus/tool-builder": "0.1.1",
-    "@crewhaus/tool-catalog": "0.1.1",
+    "@crewhaus/errors": "0.1.3",
+    "@crewhaus/tool-builder": "0.1.3",
+    "@crewhaus/tool-catalog": "0.1.3",
     "zod": "^3.23.8"
   },
   "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",
@@ -33,12 +33,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,34 +1,48 @@
 /**
  * Tests for tool-document-ingest. Built-in handling for plain text /
- * structured / tabular formats, plus operator-registered parsers.
+ * structured / tabular formats, operator-registered parsers, and
+ * workspace path containment (mirrors tool-fs's traversal-rejection
+ * cases).
+ *
+ * The harness chdirs into a temp workspace because IngestDocument is
+ * sandboxed to `process.cwd()` — tests address files by workspace-
+ * relative path.
  */
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
 import {
   DocumentIngestError,
+  ToolPermissionError,
   clearDocumentParsers,
   ingestDocument,
   registerDocumentParser,
 } from "./index";
 
 let tmp: string;
+let originalCwd: string;
 
 beforeEach(() => {
-  tmp = mkdtempSync(join(tmpdir(), "doc-ingest-"));
+  originalCwd = process.cwd();
+  // realpath so absolute-path-inside-workspace assertions hold on macOS,
+  // where tmpdir() lives behind the /var → /private/var symlink.
+  tmp = realpathSync(mkdtempSync(join(tmpdir(), "doc-ingest-")));
+  process.chdir(tmp);
   clearDocumentParsers();
 });
 
 afterEach(() => {
+  process.chdir(originalCwd);
   rmSync(tmp, { recursive: true, force: true });
   clearDocumentParsers();
 });
 
+/** Write `content` into the temp workspace; returns the workspace-relative path. */
 function writeFile(name: string, content: string): string {
-  const path = join(tmp, name);
-  writeFileSync(path, content);
-  return path;
+  writeFileSync(join(tmp, name), content);
+  return name;
 }
 
 describe("ingestDocument — basics", () => {
@@ -39,7 +53,7 @@ describe("ingestDocument — basics", () => {
   });
 
   test("throws when file does not exist", async () => {
-    await expect(ingestDocument.execute({ path: "/does/not/exist.txt" })).rejects.toThrow(
+    await expect(ingestDocument.execute({ path: "does/not/exist.txt" })).rejects.toThrow(
       DocumentIngestError,
     );
   });
@@ -61,6 +75,62 @@ describe("ingestDocument — basics", () => {
   });
 });
 
+describe("ingestDocument — path containment", () => {
+  test("ToolPermissionError is a CrewhausError with code 'tool'", () => {
+    const err = new ToolPermissionError("IngestDocument", "../../escape");
+    expect(err).toBeInstanceOf(CrewhausError);
+    expect(err.code).toBe("tool");
+    expect(err.toolName).toBe("IngestDocument");
+    expect(err.path).toBe("../../escape");
+    expect(err.message).toContain("escapes the workspace root");
+  });
+
+  test("rejects parent-directory traversal", async () => {
+    await expect(ingestDocument.execute({ path: "../../../etc/passwd" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+
+  test("rejects absolute path outside workspace", async () => {
+    await expect(ingestDocument.execute({ path: "/etc/passwd" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+
+  test("rejects subdir-then-traversal", async () => {
+    mkdirSync(join(tmp, "sub"));
+    await expect(ingestDocument.execute({ path: "sub/../../escape.txt" })).rejects.toBeInstanceOf(
+      ToolPermissionError,
+    );
+  });
+
+  test("rejects an in-root symlink whose target escapes the workspace", async () => {
+    const outside = mkdtempSync(join(tmpdir(), "doc-ingest-outside-"));
+    try {
+      writeFileSync(join(outside, "secret.txt"), "top secret");
+      symlinkSync(join(outside, "secret.txt"), join(tmp, "link.txt"));
+      await expect(ingestDocument.execute({ path: "link.txt" })).rejects.toBeInstanceOf(
+        ToolPermissionError,
+      );
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
+  test("allows an absolute path inside the workspace", async () => {
+    writeFile("inside.txt", "in-root content");
+    const result = await ingestDocument.execute({ path: join(tmp, "inside.txt") });
+    expect(result).toContain("in-root content");
+  });
+
+  test("allows an in-root symlink to an in-root file (no over-blocking)", async () => {
+    writeFile("real.txt", "linked content");
+    symlinkSync(join(tmp, "real.txt"), join(tmp, "good-link.txt"));
+    const result = await ingestDocument.execute({ path: "good-link.txt" });
+    expect(result).toContain("linked content");
+  });
+});
+
 describe("ingestDocument — tabular formats", () => {
   test("counts rows + columns in CSV", async () => {
     const path = writeFile("data.csv", "a,b,c\n1,2,3\n4,5,6\n");

package/src/index.ts

@@ -20,15 +20,27 @@
  * can register their own parser via `registerDocumentParser`; the
  * tool's contract stays the same.
  *
- * Security note: the path is a Bun.file() read of a user-controlled
- * string. The runtime should classify the OUTPUT via boundary-classifier
- * with origin "user" — files in the user's host are developer-trusted,
- * but the contents may contain anything (e.g. a prompt-injecting PDF).
- * Pillar 3 compliance is satisfied by the existing `tool` origin
- * classifier in runtime-core.
+ * Security note: the path is user-controlled (the model supplies it, and
+ * the model may be steered by injected content). Two defenses apply:
+ *   1. Containment — the path is resolved against `process.cwd()` and
+ *      rejected if it escapes the workspace root, lexically (`..` or
+ *      absolute escapes) or via an in-root symlink whose real target
+ *      lies outside (CWE-59). See `resolveSafe` below.
+ *   2. Output classification — the runtime classifies the OUTPUT via
+ *      boundary-classifier with the existing `tool` origin (Pillar 3);
+ *      file contents may contain anything (e.g. a prompt-injecting PDF).
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, extname, resolve } from "node:path";
+import {
+  closeSync,
+  existsSync,
+  constants as fsConstants,
+  fstatSync,
+  openSync,
+  readSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { CrewhausError } from "@crewhaus/errors";
 import { buildTool } from "@crewhaus/tool-builder";
 import type { RegisteredTool } from "@crewhaus/tool-catalog";
@@ -49,6 +61,95 @@ export class DocumentIngestError extends CrewhausError {
   }
 }
 
+export class ToolPermissionError extends CrewhausError {
+  override readonly name = "ToolPermissionError";
+  readonly toolName: string;
+  readonly path: string;
+
+  constructor(toolName: string, attemptedPath: string) {
+    super(
+      "tool",
+      `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`,
+    );
+    this.toolName = toolName;
+    this.path = attemptedPath;
+  }
+}
+
+/**
+ * Resolve `rel` against the workspace root and reject anything that escapes.
+ * Mirrors `tool-fs`'s `resolveSafe` — duplicated here (like `tool-image`)
+ * rather than extracted to a shared package; keep the copies in sync.
+ */
+function resolveSafe(toolName: string, rel: string, root: string = process.cwd()): string {
+  const rootResolved = resolve(root);
+  const abs = resolve(rootResolved, rel);
+  // 1) Lexical containment — fast path; rejects `..` and absolute escapes.
+  //    The trailing `sep` avoids the `/root` vs `/root-sibling` pitfall.
+  if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${sep}`)) {
+    throw new ToolPermissionError(toolName, rel);
+  }
+  // 2) Symlink-aware containment (CWE-59). The lexical check above is fooled
+  //    by an in-root symlink that points outside the workspace, so re-check
+  //    the REAL path. The leaf may not exist (the file-not-found error comes
+  //    after containment so escaping paths never leak existence info), so
+  //    resolve the deepest existing ancestor and re-append the missing tail.
+  //    Fails closed if realpath errors for any reason other than the walk.
+  let real: string;
+  try {
+    const rootReal = realpathSync(rootResolved);
+    let probe = abs;
+    const tail: string[] = [];
+    while (!existsSync(probe)) {
+      tail.unshift(basename(probe));
+      const parent = dirname(probe);
+      if (parent === probe) break; // reached the filesystem root
+      probe = parent;
+    }
+    real = tail.length > 0 ? join(realpathSync(probe), ...tail) : realpathSync(probe);
+    if (real !== rootReal && !real.startsWith(`${rootReal}${sep}`)) {
+      throw new ToolPermissionError(toolName, rel);
+    }
+  } catch (err) {
+    if (err instanceof ToolPermissionError) throw err;
+    throw new ToolPermissionError(toolName, rel);
+  }
+  // Return the validated REAL path; the read below opens it with O_NOFOLLOW so a
+  // leaf swapped to a symlink after this check (TOCTOU/CWE-367) is rejected.
+  return real;
+}
+
+/**
+ * Read a resolveSafe-validated text file with O_NOFOLLOW so a leaf swapped to a
+ * symlink after the containment check is rejected rather than followed out of
+ * the workspace. (Custom parsers read the resolved realpath themselves and are
+ * out of this guard's scope.)
+ */
+function readTextNoFollow(absPath: string): string {
+  let fd: number;
+  try {
+    fd = openSync(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ELOOP") {
+      throw new ToolPermissionError("IngestDocument", absPath);
+    }
+    throw err;
+  }
+  try {
+    const { size } = fstatSync(fd);
+    const b = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < size) {
+      const n = readSync(fd, b, offset, size - offset, offset);
+      if (n === 0) break;
+      offset += n;
+    }
+    return b.toString("utf-8", 0, offset);
+  } finally {
+    closeSync(fd);
+  }
+}
+
 const TEXT_EXTENSIONS = new Set([".txt", ".md", ".mdx", ".log", ".out", ".rst"]);
 const TABULAR_EXTENSIONS = new Set([".csv", ".tsv"]);
 const STRUCTURED_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
@@ -84,7 +185,10 @@ export function clearDocumentParsers(): void {
 }
 
 const inputSchema = z.object({
-  path: z.string().min(1).describe("Absolute or cwd-relative path to the file."),
+  path: z
+    .string()
+    .min(1)
+    .describe("Workspace-relative path to the file. Paths escaping the workspace are rejected."),
   maxBytes: z
     .number()
     .int()
@@ -99,12 +203,12 @@ const DEFAULT_MAX_BYTES = 1_000_000;
 export const ingestDocument: RegisteredTool = buildTool({
   name: "IngestDocument",
   description:
-    "Read a file from the host filesystem and return its content with structured metadata. Supports plain text, CSV/TSV, JSON, YAML out of the box; PDF/docx/xlsx need an operator-registered parser.",
+    "Read a file inside the workspace and return its content with structured metadata. Paths escaping the workspace root are rejected. Supports plain text, CSV/TSV, JSON, YAML out of the box; PDF/docx/xlsx need an operator-registered parser.",
   inputSchema,
   readOnly: true,
   destructive: false,
   execute: async (input) => {
-    const abs = resolve(input.path);
+    const abs = resolveSafe("IngestDocument", input.path);
     if (!existsSync(abs)) {
       throw new DocumentIngestError(`file not found: ${abs}`);
     }
@@ -139,7 +243,7 @@ export const ingestDocument: RegisteredTool = buildTool({
       STRUCTURED_EXTENSIONS.has(ext) ||
       ext === ""
     ) {
-      const raw = readFileSync(abs, "utf-8");
+      const raw = readTextNoFollow(abs);
       const metadata: Record<string, unknown> = {
         ext: ext || "(none)",
         size: stat.size,