@actagent/file-transfer 2026.6.2

package/src/node-host/dir-fetch.ts

@@ -0,0 +1,363 @@
+// File Transfer plugin module implements dir fetch behavior.
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import path from "node:path";
+import { root as fsRoot } from "actagent/plugin-sdk/security-runtime";
+import {
+  classifyFsSafeReadError,
+  readAbsolutePath,
+  resolveCanonicalReadPath,
+  statRequiredDirectory,
+} from "./path-errors.js";
+
+const DIR_FETCH_HARD_MAX_BYTES = 16 * 1024 * 1024;
+const DIR_FETCH_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+
+type DirFetchParams = {
+  path?: unknown;
+  maxBytes?: unknown;
+  includeDotfiles?: unknown;
+  followSymlinks?: unknown;
+  preflightOnly?: unknown;
+};
+
+type DirFetchOk = {
+  ok: true;
+  path: string;
+  tarBase64: string;
+  tarBytes: number;
+  sha256: string;
+  fileCount: number;
+  entries?: string[];
+  preflightOnly?: boolean;
+};
+
+type DirFetchErrCode =
+  | "INVALID_PATH"
+  | "NOT_FOUND"
+  | "IS_FILE"
+  | "TREE_TOO_LARGE"
+  | "SYMLINK_REDIRECT"
+  | "READ_ERROR";
+
+type DirFetchErr = {
+  ok: false;
+  code: DirFetchErrCode;
+  message: string;
+  canonicalPath?: string;
+};
+
+type DirFetchResult = DirFetchOk | DirFetchErr;
+
+function clampMaxBytes(input: unknown): number {
+  if (typeof input !== "number" || !Number.isFinite(input) || input <= 0) {
+    return DIR_FETCH_DEFAULT_MAX_BYTES;
+  }
+  return Math.min(Math.floor(input), DIR_FETCH_HARD_MAX_BYTES);
+}
+
+function classifyFsError(err: unknown): DirFetchErrCode {
+  const safeCode = classifyFsSafeReadError(err);
+  if (safeCode) {
+    return safeCode;
+  }
+  const code = (err as { code?: string } | null)?.code;
+  if (code === "ENOENT") {
+    return "NOT_FOUND";
+  }
+  return "READ_ERROR";
+}
+
+async function preflightDu(dirPath: string, maxBytes: number): Promise<boolean> {
+  // du -sk gives size in 1KB blocks (512-byte blocks on macOS with -k)
+  // We use maxBytes * 4 as the rough heuristic ceiling (generous, gzip compresses)
+  const heuristicKb = Math.ceil((maxBytes * 4) / 1024);
+  return new Promise((resolve) => {
+    const du = spawn("du", ["-sk", dirPath], { stdio: ["ignore", "pipe", "ignore"] });
+    let output = "";
+    du.stdout.on("data", (chunk: Buffer) => {
+      output += chunk.toString();
+    });
+    du.on("close", (code) => {
+      if (code !== 0) {
+        // du failed; be permissive and let tar catch the overflow
+        resolve(true);
+        return;
+      }
+      const match = /^(\d+)/.exec(output.trim());
+      if (!match) {
+        resolve(true);
+        return;
+      }
+      const sizeKb = Number.parseInt(match[1], 10);
+      resolve(sizeKb <= heuristicKb);
+    });
+    du.on("error", () => {
+      // du not available; skip preflight
+      resolve(true);
+    });
+  });
+}
+
+async function listTarEntries(tarBuffer: Buffer): Promise<string[]> {
+  // Async spawn so a slow `tar -tzf` doesn't park the node-host event
+  // loop for up to 10s. Other in-flight requests continue to be served.
+  return new Promise<string[]>((resolve) => {
+    const child = spawn("tar", ["-tzf", "-"], { stdio: ["pipe", "pipe", "ignore"] });
+    let stdoutBuf = "";
+    let aborted = false;
+    const watchdog = setTimeout(() => {
+      aborted = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* gone */
+      }
+      resolve([]);
+    }, 10_000);
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString();
+      // Bound buffer growth — pathological archives shouldn't OOM us.
+      if (stdoutBuf.length > 32 * 1024 * 1024) {
+        aborted = true;
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          /* gone */
+        }
+        clearTimeout(watchdog);
+        resolve([]);
+      }
+    });
+    child.on("close", (code) => {
+      clearTimeout(watchdog);
+      if (aborted) {
+        return;
+      }
+      if (code !== 0) {
+        resolve([]);
+        return;
+      }
+      const lines = stdoutBuf
+        .split("\n")
+        .map((line) => line.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/$/u, ""))
+        .filter((line) => line.length > 0);
+      resolve(lines);
+    });
+    child.on("error", () => {
+      clearTimeout(watchdog);
+      if (!aborted) {
+        resolve([]);
+      }
+    });
+    child.stdin.end(tarBuffer);
+  });
+}
+
+async function listTreeEntries(root: string, maxEntries: number): Promise<string[] | "TOO_MANY"> {
+  const results: string[] = [];
+  const rootHandle = await fsRoot(root);
+  async function visit(relativeDir: string): Promise<boolean> {
+    const entries = await rootHandle.list(relativeDir, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const rel = path.posix.join(relativeDir === "." ? "" : relativeDir, entry.name);
+      results.push(rel);
+      if (results.length > maxEntries) {
+        return false;
+      }
+      if (entry.isDirectory) {
+        const ok = await visit(rel);
+        if (!ok) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  return (await visit(".")) ? results : "TOO_MANY";
+}
+
+export async function handleDirFetch(params: DirFetchParams): Promise<DirFetchResult> {
+  const requestedPath = readAbsolutePath(params.path);
+  if (typeof requestedPath !== "string") {
+    return requestedPath;
+  }
+
+  const maxBytes = clampMaxBytes(params.maxBytes);
+  const includeDotfiles = params.includeDotfiles === true;
+  const followSymlinks = params.followSymlinks === true;
+  const preflightOnly = params.preflightOnly === true;
+
+  const canonical = await resolveCanonicalReadPath({
+    requestedPath,
+    followSymlinks,
+    classifyError: classifyFsError,
+    notFoundMessage: "directory not found",
+  });
+  if (typeof canonical !== "string") {
+    return canonical;
+  }
+
+  const directory = await statRequiredDirectory(canonical, classifyFsError);
+  if (!directory.ok) {
+    return directory;
+  }
+
+  if (preflightOnly) {
+    try {
+      const entries = await listTreeEntries(canonical, 5000);
+      if (entries === "TOO_MANY") {
+        return {
+          ok: false,
+          code: "TREE_TOO_LARGE",
+          message: "directory tree exceeds 5000 entries during preflight",
+          canonicalPath: canonical,
+        };
+      }
+      return {
+        ok: true,
+        path: canonical,
+        tarBase64: "",
+        tarBytes: 0,
+        sha256: "",
+        fileCount: entries.length,
+        entries,
+        preflightOnly: true,
+      };
+    } catch (err) {
+      const code = classifyFsError(err);
+      return {
+        ok: false,
+        code,
+        message: `preflight readdir failed: ${String(err)}`,
+        canonicalPath: canonical,
+      };
+    }
+  }
+
+  // Preflight size check using du
+  const withinBudget = await preflightDu(canonical, maxBytes);
+  if (!withinBudget) {
+    return {
+      ok: false,
+      code: "TREE_TOO_LARGE",
+      message: `directory tree exceeds estimated size limit (${maxBytes} bytes raw)`,
+      canonicalPath: canonical,
+    };
+  }
+
+  // Build tar args. Shell out to /usr/bin/tar for portability.
+  // -cz: create + gzip
+  // -C <dir>: change to directory so paths in archive are relative
+  // .: include everything from that directory
+  // v1: includeDotfiles is accepted in the API but not enforced. BSD tar's
+  // --exclude pattern matching is unreliable for dotfiles (every plausible
+  // pattern except "*/.*" collapses the archive on macOS). Reliable filtering
+  // requires a `find ! -name '.*' | tar -T -` pipeline; deferred to v2.
+  // For now we always archive everything in the directory.
+  void includeDotfiles;
+  const tarArgs: string[] = ["-czf", "-", "-C", canonical, "."];
+
+  // Capture tar output with a hard byte cap and a wall-clock timeout.
+  // SIGTERM if the byte cap is exceeded; SIGKILL if the timeout fires
+  // (covers tar hanging on a slow filesystem or symlink loop).
+  const TAR_HARD_TIMEOUT_MS = 60_000;
+  const tarBuffer = await new Promise<Buffer | "TOO_LARGE" | "TIMEOUT" | "ERROR">((resolve) => {
+    const tarBin = process.platform !== "win32" ? "/usr/bin/tar" : "tar";
+    const child = spawn(tarBin, tarArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+    let aborted = false;
+
+    const watchdog = setTimeout(() => {
+      if (aborted) {
+        return;
+      }
+      aborted = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+      resolve("TIMEOUT");
+    }, TAR_HARD_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (aborted) {
+        return;
+      }
+      totalBytes += chunk.byteLength;
+      if (totalBytes > maxBytes) {
+        aborted = true;
+        clearTimeout(watchdog);
+        child.kill("SIGTERM");
+        resolve("TOO_LARGE");
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(watchdog);
+      if (aborted) {
+        return;
+      }
+      if (code !== 0) {
+        resolve("ERROR");
+        return;
+      }
+      resolve(Buffer.concat(chunks));
+    });
+
+    child.on("error", () => {
+      clearTimeout(watchdog);
+      if (!aborted) {
+        resolve("ERROR");
+      }
+    });
+  });
+
+  if (tarBuffer === "TOO_LARGE") {
+    return {
+      ok: false,
+      code: "TREE_TOO_LARGE",
+      message: `tarball exceeded ${maxBytes} byte limit mid-stream`,
+      canonicalPath: canonical,
+    };
+  }
+  if (tarBuffer === "TIMEOUT") {
+    return {
+      ok: false,
+      code: "READ_ERROR",
+      message: "tar command exceeded 60s wall-clock timeout (slow filesystem or symlink loop?)",
+      canonicalPath: canonical,
+    };
+  }
+  if (tarBuffer === "ERROR") {
+    return {
+      ok: false,
+      code: "READ_ERROR",
+      message: "tar command failed",
+      canonicalPath: canonical,
+    };
+  }
+
+  const sha256 = crypto.createHash("sha256").update(tarBuffer).digest("hex");
+  const tarBase64 = tarBuffer.toString("base64");
+  const tarBytes = tarBuffer.byteLength;
+  const entries = await listTarEntries(tarBuffer);
+
+  return {
+    ok: true,
+    path: canonical,
+    tarBase64,
+    tarBytes,
+    sha256,
+    fileCount: entries.length,
+    entries,
+  };
+}

package/src/node-host/dir-list.test.ts

@@ -0,0 +1,169 @@
+// File Transfer tests cover dir list plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  DIR_LIST_DEFAULT_MAX_ENTRIES,
+  DIR_LIST_HARD_MAX_ENTRIES,
+  handleDirList,
+} from "./dir-list.js";
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+  // realpath: see file-fetch.test.ts for the macOS symlinked-tmpdir reason.
+  tmpRoot = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "dir-list-test-")));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+async function expectDirListError(
+  input: Parameters<typeof handleDirList>[0],
+  code: "INVALID_PATH" | "IS_FILE" | "NOT_FOUND",
+) {
+  const result = await handleDirList(input);
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.code).toBe(code);
+  }
+}
+
+describe("handleDirList — input validation", () => {
+  it("rejects empty / non-string path", async () => {
+    await expectDirListError({ path: "" }, "INVALID_PATH");
+    await expectDirListError({ path: undefined }, "INVALID_PATH");
+  });
+
+  it("rejects relative paths", async () => {
+    await expectDirListError({ path: "relative" }, "INVALID_PATH");
+  });
+
+  it("rejects paths with NUL bytes", async () => {
+    await expectDirListError({ path: "/tmp/foo\0bar" }, "INVALID_PATH");
+  });
+});
+
+describe("handleDirList — fs errors", () => {
+  it("returns NOT_FOUND for a missing directory", async () => {
+    await expectDirListError({ path: path.join(tmpRoot, "does-not-exist") }, "NOT_FOUND");
+  });
+
+  it("returns IS_FILE when path resolves to a regular file", async () => {
+    const f = path.join(tmpRoot, "f.txt");
+    await fs.writeFile(f, "x");
+    await expectDirListError({ path: f }, "IS_FILE");
+  });
+});
+
+describe("handleDirList — happy path", () => {
+  it("lists files and subdirs with metadata, sorted by name", async () => {
+    await fs.writeFile(path.join(tmpRoot, "z.txt"), "Z");
+    await fs.writeFile(path.join(tmpRoot, "a.png"), "PNG-bytes");
+    await fs.mkdir(path.join(tmpRoot, "subdir"));
+
+    const r = await handleDirList({ path: tmpRoot });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.entries.map((e) => e.name)).toEqual(["a.png", "subdir", "z.txt"]);
+
+    const a = r.entries.find((e) => e.name === "a.png")!;
+    expect(a.isDir).toBe(false);
+    expect(a.size).toBeGreaterThan(0);
+    expect(a.mimeType).toBe("image/png");
+
+    const sub = r.entries.find((e) => e.name === "subdir")!;
+    expect(sub.isDir).toBe(true);
+    expect(sub.size).toBe(0);
+    expect(sub.mimeType).toBe("inode/directory");
+
+    expect(r.truncated).toBe(false);
+    expect(r.nextPageToken).toBeUndefined();
+  });
+
+  it("includes dotfiles in the listing", async () => {
+    await fs.writeFile(path.join(tmpRoot, ".hidden"), "x");
+    await fs.writeFile(path.join(tmpRoot, "visible"), "x");
+
+    const r = await handleDirList({ path: tmpRoot });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.entries.map((e) => e.name)).toEqual([".hidden", "visible"]);
+  });
+
+  it("paginates via pageToken (offset-based)", async () => {
+    for (let i = 0; i < 7; i++) {
+      // zero-pad so localeCompare-stable sort matches creation order
+      await fs.writeFile(path.join(tmpRoot, `f-${i}.txt`), "x");
+    }
+
+    const page1 = await handleDirList({ path: tmpRoot, maxEntries: 3 });
+    if (!page1.ok) {
+      throw new Error("page1");
+    }
+    expect(page1.entries.map((e) => e.name)).toEqual(["f-0.txt", "f-1.txt", "f-2.txt"]);
+    expect(page1.truncated).toBe(true);
+    expect(page1.nextPageToken).toBe("3");
+
+    const page2 = await handleDirList({
+      path: tmpRoot,
+      maxEntries: 3,
+      pageToken: page1.nextPageToken,
+    });
+    if (!page2.ok) {
+      throw new Error("page2");
+    }
+    expect(page2.entries.map((e) => e.name)).toEqual(["f-3.txt", "f-4.txt", "f-5.txt"]);
+    expect(page2.truncated).toBe(true);
+
+    const page3 = await handleDirList({
+      path: tmpRoot,
+      maxEntries: 3,
+      pageToken: page2.nextPageToken,
+    });
+    if (!page3.ok) {
+      throw new Error("page3");
+    }
+    expect(page3.entries.map((e) => e.name)).toEqual(["f-6.txt"]);
+    expect(page3.truncated).toBe(false);
+    expect(page3.nextPageToken).toBeUndefined();
+  });
+
+  it("does not coerce partial page tokens", async () => {
+    for (let i = 0; i < 3; i++) {
+      await fs.writeFile(path.join(tmpRoot, `f-${i}.txt`), "x");
+    }
+
+    const r = await handleDirList({ path: tmpRoot, maxEntries: 1, pageToken: "1next" });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.entries.map((e) => e.name)).toEqual(["f-0.txt"]);
+    expect(r.nextPageToken).toBe("1");
+  });
+
+  it("accepts plus-signed page tokens", async () => {
+    for (let i = 0; i < 3; i++) {
+      await fs.writeFile(path.join(tmpRoot, `f-${i}.txt`), "x");
+    }
+
+    const r = await handleDirList({ path: tmpRoot, maxEntries: 1, pageToken: "+01" });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.entries.map((e) => e.name)).toEqual(["f-1.txt"]);
+    expect(r.nextPageToken).toBe("2");
+  });
+});
+
+describe("handleDirList — limits", () => {
+  it("clamps maxEntries to the hard ceiling and uses the default for invalid values", () => {
+    expect(DIR_LIST_DEFAULT_MAX_ENTRIES).toBe(200);
+    expect(DIR_LIST_HARD_MAX_ENTRIES).toBe(5000);
+    expect(DIR_LIST_DEFAULT_MAX_ENTRIES).toBeLessThan(DIR_LIST_HARD_MAX_ENTRIES);
+  });
+});

package/src/node-host/dir-list.ts

@@ -0,0 +1,155 @@
+// File Transfer plugin module implements dir list behavior.
+import path from "node:path";
+import { parseStrictNonNegativeInteger } from "actagent/plugin-sdk/number-runtime";
+import { root } from "actagent/plugin-sdk/security-runtime";
+import { mimeFromExtension } from "../shared/mime.js";
+import {
+  classifyFsSafeReadError,
+  readAbsolutePath,
+  resolveCanonicalReadPath,
+  statRequiredDirectory,
+} from "./path-errors.js";
+
+export const DIR_LIST_DEFAULT_MAX_ENTRIES = 200;
+export const DIR_LIST_HARD_MAX_ENTRIES = 5000;
+
+type DirListParams = {
+  path?: unknown;
+  pageToken?: unknown;
+  maxEntries?: unknown;
+  followSymlinks?: unknown;
+};
+
+type DirListEntry = {
+  name: string;
+  path: string;
+  size: number;
+  mimeType: string;
+  isDir: boolean;
+  mtime: number;
+};
+
+type DirListOk = {
+  ok: true;
+  path: string;
+  entries: DirListEntry[];
+  nextPageToken?: string;
+  truncated: boolean;
+};
+
+type DirListErrCode =
+  | "INVALID_PATH"
+  | "NOT_FOUND"
+  | "PERMISSION_DENIED"
+  | "IS_FILE"
+  | "SYMLINK_REDIRECT"
+  | "READ_ERROR";
+
+type DirListErr = {
+  ok: false;
+  code: DirListErrCode;
+  message: string;
+  canonicalPath?: string;
+};
+
+type DirListResult = DirListOk | DirListErr;
+
+function clampMaxEntries(input: unknown): number {
+  if (typeof input !== "number" || !Number.isFinite(input) || input <= 0) {
+    return DIR_LIST_DEFAULT_MAX_ENTRIES;
+  }
+  return Math.min(Math.floor(input), DIR_LIST_HARD_MAX_ENTRIES);
+}
+
+function parsePageOffset(input: unknown): number {
+  if (typeof input !== "string") {
+    return 0;
+  }
+  return parseStrictNonNegativeInteger(input) ?? 0;
+}
+
+function classifyFsError(err: unknown): DirListErrCode {
+  const safeCode = classifyFsSafeReadError(err);
+  if (safeCode) {
+    return safeCode;
+  }
+  const code = (err as { code?: string } | null)?.code;
+  if (code === "ENOENT") {
+    return "NOT_FOUND";
+  }
+  if (code === "EACCES" || code === "EPERM") {
+    return "PERMISSION_DENIED";
+  }
+  return "READ_ERROR";
+}
+
+export async function handleDirList(params: DirListParams): Promise<DirListResult> {
+  const requestedPath = readAbsolutePath(params.path);
+  if (typeof requestedPath !== "string") {
+    return requestedPath;
+  }
+
+  const maxEntries = clampMaxEntries(params.maxEntries);
+  const offset = parsePageOffset(params.pageToken);
+
+  const followSymlinks = params.followSymlinks === true;
+
+  const canonical = await resolveCanonicalReadPath({
+    requestedPath,
+    followSymlinks,
+    classifyError: classifyFsError,
+    notFoundMessage: "path not found",
+  });
+  if (typeof canonical !== "string") {
+    return canonical;
+  }
+
+  const directory = await statRequiredDirectory(canonical, classifyFsError);
+  if (!directory.ok) {
+    return directory;
+  }
+
+  let listedEntries: { name: string; isDirectory: boolean; size: number; mtimeMs: number }[];
+  try {
+    const dirRoot = await root(canonical);
+    listedEntries = await dirRoot.list(".", { withFileTypes: true });
+  } catch (err) {
+    const code = classifyFsError(err);
+    return {
+      ok: false,
+      code,
+      message: `list failed: ${String(err)}`,
+      canonicalPath: canonical,
+    };
+  }
+
+  listedEntries.sort((a, b) => a.name.localeCompare(b.name));
+
+  const total = listedEntries.length;
+  const page = listedEntries.slice(offset, offset + maxEntries);
+  const truncated = offset + maxEntries < total;
+  const nextPageToken = truncated ? String(offset + maxEntries) : undefined;
+
+  const entries: DirListEntry[] = [];
+  for (const entry of page) {
+    const entryPath = path.join(canonical, entry.name);
+    const isDir = entry.isDirectory;
+
+    entries.push({
+      name: entry.name,
+      path: entryPath,
+      size: isDir ? 0 : entry.size,
+      mimeType: isDir ? "inode/directory" : mimeFromExtension(entry.name),
+      isDir,
+      mtime: entry.mtimeMs,
+    });
+  }
+
+  return {
+    ok: true,
+    path: canonical,
+    entries,
+    nextPageToken,
+    truncated,
+  };
+}