@actagent/file-transfer 2026.6.2

package/src/node-host/file-fetch.test.ts

@@ -0,0 +1,254 @@
+// File Transfer tests cover file fetch plugin behavior.
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  FILE_FETCH_DEFAULT_MAX_BYTES,
+  FILE_FETCH_HARD_MAX_BYTES,
+  handleFileFetch,
+} from "./file-fetch.js";
+
+let tmpRoot: string;
+
+type FileFetchResult = Awaited<ReturnType<typeof handleFileFetch>>;
+type FileFetchSuccess = Extract<FileFetchResult, { ok: true }>;
+type FileFetchFailure = Extract<FileFetchResult, { ok: false }>;
+
+function expectFailureCode(
+  result: FileFetchResult,
+  code: string,
+): asserts result is FileFetchFailure {
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    throw new Error(`expected failure ${code}`);
+  }
+  expect(result.code).toBe(code);
+}
+
+function expectSuccess(result: FileFetchResult): asserts result is FileFetchSuccess {
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    throw new Error(`expected ok, got ${result.code}: ${result.message}`);
+  }
+}
+
+beforeEach(async () => {
+  // realpath the mkdtemp result — on macOS /tmp/foo and /var/folders/... are
+  // symlinks to /private/{tmp,var/folders}, and the new SYMLINK_REDIRECT
+  // default would otherwise refuse every test path. Tests want to exercise
+  // the happy path with canonical paths; symlink-specific assertions create
+  // explicit symlinks inside tmpRoot.
+  tmpRoot = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "file-fetch-test-")));
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe("handleFileFetch — input validation", () => {
+  it("returns INVALID_PATH for empty / non-string path", async () => {
+    expectFailureCode(await handleFileFetch({ path: "" }), "INVALID_PATH");
+    expectFailureCode(await handleFileFetch({ path: undefined }), "INVALID_PATH");
+    expectFailureCode(await handleFileFetch({ path: 42 as unknown }), "INVALID_PATH");
+  });
+
+  it("rejects relative paths", async () => {
+    const r = await handleFileFetch({ path: "relative/file.txt" });
+    expectFailureCode(r, "INVALID_PATH");
+    expect(r.ok ? "" : r.message).toMatch(/absolute/);
+  });
+
+  it("rejects paths with NUL bytes", async () => {
+    const r = await handleFileFetch({ path: "/tmp/foo\0bar" });
+    expectFailureCode(r, "INVALID_PATH");
+    expect(r.ok ? "" : r.message).toMatch(/NUL/);
+  });
+});
+
+describe("handleFileFetch — fs errors", () => {
+  it("returns NOT_FOUND for a missing file", async () => {
+    const target = path.join(tmpRoot, "missing.txt");
+    expectFailureCode(await handleFileFetch({ path: target }), "NOT_FOUND");
+  });
+
+  it("returns IS_DIRECTORY when the path resolves to a directory", async () => {
+    const r = await handleFileFetch({ path: tmpRoot });
+    expectFailureCode(r, "IS_DIRECTORY");
+    // canonical path is reported back so the caller can re-check policy
+    if (r.ok) {
+      throw new Error("expected directory fetch to fail");
+    }
+    expect(r.canonicalPath).toBe(tmpRoot);
+  });
+});
+
+describe("handleFileFetch — zero-byte round-trip", () => {
+  it("fetches an empty file with size=0 and base64=''", async () => {
+    const target = path.join(tmpRoot, "empty.bin");
+    await fs.writeFile(target, "");
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}: ${r.message}`);
+    }
+    expect(r.size).toBe(0);
+    expect(r.base64).toBe("");
+    // SHA-256 of empty input.
+    expect(r.sha256).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+  });
+});
+
+describe("handleFileFetch — happy path", () => {
+  it("reads a small file and returns size + sha256 + base64", async () => {
+    const target = path.join(tmpRoot, "hello.txt");
+    const contents = "hello world\n";
+    await fs.writeFile(target, contents);
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}: ${r.message}`);
+    }
+
+    expect(r.size).toBe(contents.length);
+    expect(Buffer.from(r.base64, "base64").toString("utf-8")).toBe(contents);
+    const expectedSha = crypto.createHash("sha256").update(contents).digest("hex");
+    expect(r.sha256).toBe(expectedSha);
+    // canonicalized path may differ from input on macOS (/tmp -> /private/tmp)
+    expect(path.basename(r.path)).toBe("hello.txt");
+  });
+
+  it("preflights canonical path and size without reading bytes", async () => {
+    const target = path.join(tmpRoot, "hello.txt");
+    await fs.writeFile(target, "hello world\n");
+    const readFileSpy = vi.spyOn(fs, "readFile");
+
+    const r = await handleFileFetch({ path: target, preflightOnly: true });
+
+    expectSuccess(r);
+    expect(r.path).toBe(target);
+    expect(r.size).toBe(12);
+    expect(r.base64).toBe("");
+    expect(r.sha256).toBe("");
+    expect(r.preflightOnly).toBe(true);
+    expect(readFileSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns a sensible mime type for known extensions", async () => {
+    const target = path.join(tmpRoot, "readme.md");
+    await fs.writeFile(target, "# heading\n");
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    // libmagic ("file" cli) typically reports text/plain or text/markdown for
+    // a one-line markdown file; the extension fallback yields text/markdown.
+    // Accept either.
+    expect(r.mimeType).toMatch(/^text\/(plain|markdown)$/);
+  });
+
+  it("detects extensionless plain text as text/plain", async () => {
+    const target = path.join(tmpRoot, "LICENSE");
+    const contents = "Permission is hereby granted\n";
+    await fs.writeFile(target, contents);
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+
+    expect(r.mimeType).toBe("text/plain");
+    expect(Buffer.from(r.base64, "base64").toString("utf-8")).toBe(contents);
+  });
+
+  it("does not classify extensionless binary content as text/plain", async () => {
+    const target = path.join(tmpRoot, "opaque");
+    await fs.writeFile(target, Buffer.from([0x00, 0x01, 0x02, 0xff]));
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+
+    expect(r.mimeType).toBe("application/octet-stream");
+  });
+
+  it("sniffs binary content instead of trusting a misleading extension", async () => {
+    const target = path.join(tmpRoot, "image.txt");
+    await fs.writeFile(
+      target,
+      Buffer.from([
+        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+        0x52,
+      ]),
+    );
+
+    const r = await handleFileFetch({ path: target });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.mimeType).toBe("image/png");
+  });
+});
+
+describe("handleFileFetch — size enforcement", () => {
+  it("returns FILE_TOO_LARGE when stat size exceeds the cap", async () => {
+    const target = path.join(tmpRoot, "big.bin");
+    const data = Buffer.alloc(2048, 0xab);
+    await fs.writeFile(target, data);
+
+    const r = await handleFileFetch({ path: target, maxBytes: 1024 });
+    expectFailureCode(r, "FILE_TOO_LARGE");
+  });
+
+  it("clamps maxBytes to the hard ceiling", async () => {
+    expect(FILE_FETCH_HARD_MAX_BYTES).toBe(16 * 1024 * 1024);
+    expect(FILE_FETCH_DEFAULT_MAX_BYTES).toBeLessThanOrEqual(FILE_FETCH_HARD_MAX_BYTES);
+
+    // A request asking for a maxBytes well above the hard ceiling should
+    // still be honored for a small file (no error).
+    const target = path.join(tmpRoot, "tiny.bin");
+    await fs.writeFile(target, Buffer.from([0x01, 0x02, 0x03]));
+    const r = await handleFileFetch({ path: target, maxBytes: Number.MAX_SAFE_INTEGER });
+    expect(r.ok).toBe(true);
+  });
+
+  it("uses default cap when maxBytes is not finite or non-positive", async () => {
+    const target = path.join(tmpRoot, "small.bin");
+    await fs.writeFile(target, Buffer.from([0xff]));
+    expectSuccess(await handleFileFetch({ path: target, maxBytes: -1 }));
+    expectSuccess(await handleFileFetch({ path: target, maxBytes: Number.NaN }));
+    expectSuccess(await handleFileFetch({ path: target, maxBytes: "8" as unknown }));
+  });
+});
+
+describe("handleFileFetch — symlink handling", () => {
+  it("refuses to follow a symlink by default (SYMLINK_REDIRECT)", async () => {
+    const real = path.join(tmpRoot, "real.txt");
+    const link = path.join(tmpRoot, "link.txt");
+    await fs.writeFile(real, "data");
+    await fs.symlink(real, link);
+
+    const r = await handleFileFetch({ path: link });
+    expectFailureCode(r, "SYMLINK_REDIRECT");
+    // Caller learns the canonical target so the operator can update the
+    // allowlist or set followSymlinks=true.
+    expect(r.ok ? null : r.canonicalPath).toBe(real);
+  });
+
+  it("follows symlinks and returns the canonical path when followSymlinks=true", async () => {
+    const real = path.join(tmpRoot, "real.txt");
+    const link = path.join(tmpRoot, "link.txt");
+    await fs.writeFile(real, "data");
+    await fs.symlink(real, link);
+
+    const r = await handleFileFetch({ path: link, followSymlinks: true });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}`);
+    }
+    expect(path.basename(r.path)).toBe("real.txt");
+  });
+});

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

@@ -0,0 +1,203 @@
+// File Transfer plugin module implements file fetch behavior.
+import crypto from "node:crypto";
+import path from "node:path";
+import { detectMime } from "actagent/plugin-sdk/media-mime";
+import { root } from "actagent/plugin-sdk/security-runtime";
+import {
+  classifyFsSafeReadError,
+  readAbsolutePath,
+  resolveCanonicalReadPath,
+} from "./path-errors.js";
+
+export const FILE_FETCH_HARD_MAX_BYTES = 16 * 1024 * 1024;
+export const FILE_FETCH_DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const TEXT_SNIFF_MAX_BYTES = 8192;
+
+type FileFetchParams = {
+  path?: unknown;
+  maxBytes?: unknown;
+  followSymlinks?: unknown;
+  preflightOnly?: unknown;
+};
+
+type FileFetchOk = {
+  ok: true;
+  path: string;
+  size: number;
+  mimeType: string;
+  base64: string;
+  sha256: string;
+  preflightOnly?: boolean;
+};
+
+type FileFetchErrCode =
+  | "INVALID_PATH"
+  | "NOT_FOUND"
+  | "PERMISSION_DENIED"
+  | "IS_DIRECTORY"
+  | "FILE_TOO_LARGE"
+  | "PATH_TRAVERSAL"
+  | "SYMLINK_REDIRECT"
+  | "READ_ERROR";
+
+type FileFetchErr = {
+  ok: false;
+  code: FileFetchErrCode;
+  message: string;
+  canonicalPath?: string;
+};
+
+type FileFetchResult = FileFetchOk | FileFetchErr;
+
+function clampMaxBytes(input: unknown): number {
+  if (typeof input !== "number" || !Number.isFinite(input) || input <= 0) {
+    return FILE_FETCH_DEFAULT_MAX_BYTES;
+  }
+  return Math.min(Math.floor(input), FILE_FETCH_HARD_MAX_BYTES);
+}
+
+function classifyFsError(err: unknown): FileFetchErrCode {
+  const safeCode = classifyFsSafeReadError(err);
+  if (safeCode) {
+    return safeCode;
+  }
+  const code = (err as { code?: string } | null)?.code;
+  if (code === "not-file") {
+    return "IS_DIRECTORY";
+  }
+  if (code === "ENOENT") {
+    return "NOT_FOUND";
+  }
+  if (code === "EACCES" || code === "EPERM") {
+    return "PERMISSION_DENIED";
+  }
+  if (code === "EISDIR") {
+    return "IS_DIRECTORY";
+  }
+  return "READ_ERROR";
+}
+
+function isLikelyPlainText(buffer: Buffer): boolean {
+  if (buffer.byteLength === 0) {
+    return true;
+  }
+  const sample = buffer.subarray(0, TEXT_SNIFF_MAX_BYTES);
+  if (sample.includes(0)) {
+    return false;
+  }
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(sample);
+  } catch {
+    return false;
+  }
+  let controlBytes = 0;
+  for (const byte of sample) {
+    if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d) {
+      controlBytes += 1;
+    }
+  }
+  return controlBytes / sample.byteLength < 0.01;
+}
+
+async function detectFetchedFileMime(params: {
+  buffer: Buffer;
+  filePath: string;
+}): Promise<string> {
+  const detected = await detectMime(params);
+  if (detected) {
+    return detected;
+  }
+  return isLikelyPlainText(params.buffer) ? "text/plain" : "application/octet-stream";
+}
+
+export async function handleFileFetch(params: FileFetchParams): Promise<FileFetchResult> {
+  const requestedPath = readAbsolutePath(params.path);
+  if (typeof requestedPath !== "string") {
+    return requestedPath;
+  }
+
+  const maxBytes = clampMaxBytes(params.maxBytes);
+  const followSymlinks = params.followSymlinks === true;
+  const preflightOnly = params.preflightOnly === true;
+
+  const canonical = await resolveCanonicalReadPath({
+    requestedPath,
+    followSymlinks,
+    classifyError: classifyFsError,
+    notFoundMessage: "file not found",
+  });
+  if (typeof canonical !== "string") {
+    return canonical;
+  }
+
+  let opened: Awaited<ReturnType<Awaited<ReturnType<typeof root>>["open"]>>;
+  try {
+    const parentRoot = await root(path.dirname(canonical));
+    opened = await parentRoot.open(path.basename(canonical));
+  } catch (err) {
+    const code = classifyFsError(err);
+    return {
+      ok: false,
+      code,
+      message: code === "IS_DIRECTORY" ? "path is a directory" : `open failed: ${String(err)}`,
+      canonicalPath: canonical,
+    };
+  }
+
+  try {
+    const stats = opened.stat;
+    if (stats.size > maxBytes) {
+      return {
+        ok: false,
+        code: "FILE_TOO_LARGE",
+        message: `file size ${stats.size} exceeds limit ${maxBytes}`,
+        canonicalPath: opened.realPath,
+      };
+    }
+
+    if (preflightOnly) {
+      return {
+        ok: true,
+        path: opened.realPath,
+        size: stats.size,
+        mimeType: "",
+        base64: "",
+        sha256: "",
+        preflightOnly: true,
+      };
+    }
+
+    const buffer = await opened.handle.readFile();
+    if (buffer.byteLength > maxBytes) {
+      return {
+        ok: false,
+        code: "FILE_TOO_LARGE",
+        message: `read ${buffer.byteLength} bytes exceeds limit ${maxBytes}`,
+        canonicalPath: opened.realPath,
+      };
+    }
+
+    const sha256 = crypto.createHash("sha256").update(buffer).digest("hex");
+    const base64 = buffer.toString("base64");
+    const mimeType = await detectFetchedFileMime({ buffer, filePath: opened.realPath });
+
+    return {
+      ok: true,
+      path: opened.realPath,
+      size: buffer.byteLength,
+      mimeType,
+      base64,
+      sha256,
+    };
+  } catch (err) {
+    const code = classifyFsError(err);
+    return {
+      ok: false,
+      code,
+      message: `read failed: ${String(err)}`,
+      canonicalPath: opened.realPath,
+    };
+  } finally {
+    await opened.handle.close().catch(() => undefined);
+  }
+}