@actagent/file-transfer 2026.6.2

package/src/node-host/path-errors.ts

@@ -0,0 +1,112 @@
+// File Transfer plugin module implements path errors behavior.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError, resolveAbsolutePathForRead } from "actagent/plugin-sdk/security-runtime";
+
+export type InvalidPathResult = {
+  ok: false;
+  code: "INVALID_PATH";
+  message: string;
+};
+
+export const SYMLINK_REJECTED_MESSAGE =
+  "path traverses a symlink; refusing because followSymlinks=false (set plugins.entries.file-transfer.config.nodes.<node>.followSymlinks=true to allow, or update allowReadPaths to the canonical path)";
+
+export type FsSafeReadErrorCode = "INVALID_PATH" | "NOT_FOUND" | "SYMLINK_REDIRECT";
+
+export function classifyFsSafeReadError(err: unknown): FsSafeReadErrorCode | undefined {
+  if (!(err instanceof FsSafeError)) {
+    return undefined;
+  }
+  if (err.code === "not-found") {
+    return "NOT_FOUND";
+  }
+  if (err.code === "symlink") {
+    return "SYMLINK_REDIRECT";
+  }
+  if (err.code === "invalid-path") {
+    return "INVALID_PATH";
+  }
+  return undefined;
+}
+
+export function readAbsolutePath(input: unknown): string | InvalidPathResult {
+  if (typeof input !== "string" || input.length === 0) {
+    return { ok: false, code: "INVALID_PATH", message: "path required" };
+  }
+  if (input.includes("\0")) {
+    return { ok: false, code: "INVALID_PATH", message: "path contains NUL byte" };
+  }
+  if (!path.isAbsolute(input)) {
+    return { ok: false, code: "INVALID_PATH", message: "path must be absolute" };
+  }
+  return input;
+}
+
+export function canonicalPathFromFsSafeError(err: unknown): string | undefined {
+  if (!(err instanceof FsSafeError) || !err.cause || typeof err.cause !== "object") {
+    return undefined;
+  }
+  return "canonicalPath" in err.cause && typeof err.cause.canonicalPath === "string"
+    ? err.cause.canonicalPath
+    : undefined;
+}
+
+export async function resolveCanonicalReadPath<Code extends string>(input: {
+  classifyError: (err: unknown) => Code;
+  followSymlinks: boolean;
+  notFoundMessage: string;
+  requestedPath: string;
+}): Promise<string | { ok: false; code: Code; message: string; canonicalPath?: string }> {
+  try {
+    return (
+      await resolveAbsolutePathForRead(input.requestedPath, {
+        symlinks: input.followSymlinks ? "follow" : "reject",
+      })
+    ).canonicalPath;
+  } catch (err) {
+    const code = input.classifyError(err);
+    const canonicalPath = canonicalPathFromFsSafeError(err);
+    return {
+      ok: false,
+      code,
+      message:
+        code === "NOT_FOUND"
+          ? input.notFoundMessage
+          : code === "SYMLINK_REDIRECT"
+            ? SYMLINK_REJECTED_MESSAGE
+            : `realpath failed: ${String(err)}`,
+      ...(canonicalPath ? { canonicalPath } : {}),
+    };
+  }
+}
+
+export async function statRequiredDirectory<Code extends string>(
+  canonicalPath: string,
+  classifyError: (err: unknown) => Code,
+): Promise<
+  { ok: true } | { ok: false; code: Code | "IS_FILE"; message: string; canonicalPath: string }
+> {
+  let stats: Awaited<ReturnType<typeof fs.stat>>;
+  try {
+    stats = await fs.stat(canonicalPath);
+  } catch (err) {
+    const code = classifyError(err);
+    return {
+      ok: false,
+      code,
+      message: `stat failed: ${String(err)}`,
+      canonicalPath,
+    };
+  }
+
+  if (!stats.isDirectory()) {
+    return {
+      ok: false,
+      code: "IS_FILE",
+      message: "path is not a directory",
+      canonicalPath,
+    };
+  }
+  return { ok: true };
+}

package/src/shared/audit.ts

@@ -0,0 +1,98 @@
+// Append-only audit log for file-transfer operations.
+//
+// Records every decision (allow/deny/error) at the gateway-side tool
+// layer. Lands at ~/.actagent/audit/file-transfer.jsonl. Rotation is
+// caller's responsibility — the file grows unbounded.
+//
+// Log records do NOT include file contents or hashes of secrets. They do
+// include canonical paths and sha256 of the payload, so treat the audit
+// file as sensitive.
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { appendRegularFile } from "actagent/plugin-sdk/security-runtime";
+
+export type FileTransferAuditOp = "file.fetch" | "dir.list" | "dir.fetch" | "file.write";
+
+type FileTransferAuditDecision =
+  | "allowed"
+  | "allowed:once"
+  | "allowed:always"
+  | "denied:no_policy"
+  | "denied:policy"
+  | "denied:approval"
+  | "denied:command_not_allowed"
+  | "denied:symlink_escape"
+  | "error";
+
+type FileTransferAuditRecord = {
+  timestamp: string;
+  op: FileTransferAuditOp;
+  nodeId: string;
+  nodeDisplayName?: string;
+  requestedPath: string;
+  canonicalPath?: string;
+  decision: FileTransferAuditDecision;
+  errorCode?: string;
+  errorMessage?: string;
+  sizeBytes?: number;
+  sha256?: string;
+  durationMs?: number;
+  // Tying back to the agent that initiated the op
+  requesterAgentId?: string;
+  sessionKey?: string;
+  // Reason text for denials
+  reason?: string;
+};
+
+let auditDirPromise: Promise<string> | null = null;
+
+async function ensureAuditDir(): Promise<string> {
+  if (auditDirPromise) {
+    return auditDirPromise;
+  }
+  const promise = (async () => {
+    const dir = path.join(os.homedir(), ".actagent", "audit");
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  })();
+  // If the mkdir rejects (transient permission error etc.), clear the
+  // cached singleton so the NEXT call retries instead of permanently
+  // silencing the audit log.
+  promise.catch(() => {
+    if (auditDirPromise === promise) {
+      auditDirPromise = null;
+    }
+  });
+  auditDirPromise = promise;
+  return promise;
+}
+
+function auditFilePath(dir: string): string {
+  return path.join(dir, "file-transfer.jsonl");
+}
+
+/**
+ * Append an audit record. Best-effort — failures are logged to stderr and
+ * never propagated to the caller (the caller's operation is the source of
+ * truth, not the audit write).
+ */
+export async function appendFileTransferAudit(
+  record: Omit<FileTransferAuditRecord, "timestamp">,
+): Promise<void> {
+  try {
+    const dir = await ensureAuditDir();
+    const line = `${JSON.stringify({
+      timestamp: new Date().toISOString(),
+      ...record,
+    })}\n`;
+    await appendRegularFile({
+      filePath: auditFilePath(dir),
+      content: line,
+      rejectSymlinkParents: true,
+    });
+  } catch (e) {
+    process.stderr.write(`[file-transfer:audit] append failed: ${String(e)}\n`);
+  }
+}

package/src/shared/errors.test.ts

@@ -0,0 +1,63 @@
+// File Transfer tests cover errors plugin behavior.
+import { describe, expect, it } from "vitest";
+import { classifyFsError, err, throwFromNodePayload } from "./errors.js";
+
+describe("err", () => {
+  it("returns an error envelope without canonicalPath when omitted", () => {
+    const e = err("INVALID_PATH", "path required");
+    expect(e).toEqual({ ok: false, code: "INVALID_PATH", message: "path required" });
+    expect("canonicalPath" in e).toBe(false);
+  });
+
+  it("includes canonicalPath only when provided non-empty", () => {
+    const withPath = err("NOT_FOUND", "missing", "/tmp/x");
+    expect(withPath.canonicalPath).toBe("/tmp/x");
+
+    const blankPath = err("NOT_FOUND", "missing", "");
+    expect("canonicalPath" in blankPath).toBe(false);
+  });
+});
+
+describe("classifyFsError", () => {
+  it("maps ENOENT to NOT_FOUND", () => {
+    expect(classifyFsError({ code: "ENOENT" })).toBe("NOT_FOUND");
+  });
+
+  it("maps EACCES and EPERM to PERMISSION_DENIED", () => {
+    expect(classifyFsError({ code: "EACCES" })).toBe("PERMISSION_DENIED");
+    expect(classifyFsError({ code: "EPERM" })).toBe("PERMISSION_DENIED");
+  });
+
+  it("maps EISDIR to IS_DIRECTORY", () => {
+    expect(classifyFsError({ code: "EISDIR" })).toBe("IS_DIRECTORY");
+  });
+
+  it("falls back to READ_ERROR for unknown / null / non-object input", () => {
+    expect(classifyFsError({ code: "EUNKNOWN" })).toBe("READ_ERROR");
+    expect(classifyFsError(null)).toBe("READ_ERROR");
+    expect(classifyFsError(undefined)).toBe("READ_ERROR");
+    expect(classifyFsError("nope")).toBe("READ_ERROR");
+  });
+});
+
+describe("throwFromNodePayload", () => {
+  it("preserves code and message in the thrown Error", () => {
+    expect(() =>
+      throwFromNodePayload("file.fetch", { code: "NOT_FOUND", message: "file not found" }),
+    ).toThrow(/file\.fetch NOT_FOUND: file not found/);
+  });
+
+  it("appends canonicalPath when present", () => {
+    expect(() =>
+      throwFromNodePayload("file.fetch", {
+        code: "POLICY_DENIED",
+        message: "blocked",
+        canonicalPath: "/tmp/x",
+      }),
+    ).toThrow(/canonical=\/tmp\/x/);
+  });
+
+  it("falls back to ERROR / generic message when fields are missing", () => {
+    expect(() => throwFromNodePayload("dir.list", {})).toThrow(/dir\.list ERROR: dir\.list failed/);
+  });
+});

package/src/shared/errors.ts

@@ -0,0 +1,68 @@
+// Shared error code surface across the four file-transfer tools/handlers.
+// Every tool returns the same { ok: false, code, message, canonicalPath? }
+// shape so the model can reason about errors uniformly.
+
+type FileTransferErrCode =
+  // Path-shape errors (caller's fault)
+  | "INVALID_PATH"
+  | "INVALID_BASE64"
+  | "INVALID_PARAMS"
+  // Filesystem errors (file/dir layer)
+  | "NOT_FOUND"
+  | "PERMISSION_DENIED"
+  | "IS_DIRECTORY"
+  | "IS_FILE"
+  | "PARENT_NOT_FOUND"
+  | "EXISTS_NO_OVERWRITE"
+  | "READ_ERROR"
+  | "WRITE_ERROR"
+  // Size/limit errors
+  | "FILE_TOO_LARGE"
+  | "TREE_TOO_LARGE"
+  // Safety errors
+  | "PATH_TRAVERSAL"
+  | "SYMLINK_TARGET_DENIED"
+  | "INTEGRITY_FAILURE"
+  // Policy errors (gateway-side)
+  | "POLICY_DENIED"
+  | "NO_POLICY";
+
+type FileTransferErr = {
+  ok: false;
+  code: FileTransferErrCode;
+  message: string;
+  canonicalPath?: string;
+};
+
+export function err(
+  code: FileTransferErrCode,
+  message: string,
+  canonicalPath?: string,
+): FileTransferErr {
+  return { ok: false, code, message, ...(canonicalPath ? { canonicalPath } : {}) };
+}
+
+// Translate a node-side fs error to a public error code.
+export function classifyFsError(e: unknown): FileTransferErrCode {
+  const code = (e as { code?: string } | null)?.code;
+  if (code === "ENOENT") {
+    return "NOT_FOUND";
+  }
+  if (code === "EACCES" || code === "EPERM") {
+    return "PERMISSION_DENIED";
+  }
+  if (code === "EISDIR") {
+    return "IS_DIRECTORY";
+  }
+  return "READ_ERROR";
+}
+
+// Convert a node-host error payload to a thrown Error for agent-tool consumption.
+// The agent-tool surfaces these as failed tool results uniformly.
+export function throwFromNodePayload(operation: string, payload: Record<string, unknown>): never {
+  const code = typeof payload.code === "string" ? payload.code : "ERROR";
+  const message = typeof payload.message === "string" ? payload.message : `${operation} failed`;
+  const canonical =
+    typeof payload.canonicalPath === "string" ? ` (canonical=${payload.canonicalPath})` : "";
+  throw new Error(`${operation} ${code}: ${message}${canonical}`);
+}

package/src/shared/lazy-node-invoke-policy.test.ts

@@ -0,0 +1,102 @@
+// File Transfer tests cover lazy node invoke policy plugin behavior.
+import type {
+  ACTAgentPluginNodeInvokePolicy,
+  ACTAgentPluginNodeInvokePolicyContext,
+} from "actagent/plugin-sdk/plugin-entry";
+import { describe, expect, it, vi } from "vitest";
+import { createLazyFileTransferNodeInvokePolicy } from "./lazy-node-invoke-policy.js";
+
+function createPolicyContext(
+  overrides: Partial<ACTAgentPluginNodeInvokePolicyContext> = {},
+): ACTAgentPluginNodeInvokePolicyContext {
+  return {
+    nodeId: "node-1",
+    command: "file.fetch",
+    params: { path: "/tmp/a.txt" },
+    config: {} as never,
+    pluginConfig: {},
+    node: {
+      nodeId: "node-1",
+      displayName: "Test Node",
+      commands: ["file.fetch"],
+    },
+    client: null,
+    invokeNode: vi.fn<ACTAgentPluginNodeInvokePolicyContext["invokeNode"]>(async () => ({
+      ok: true,
+      payload: { ok: true },
+      payloadJSON: null,
+    })),
+    ...overrides,
+  };
+}
+
+describe("lazy file-transfer node invoke policy", () => {
+  it("exposes command metadata without loading the delegate", () => {
+    const loadPolicy = vi.fn<() => Promise<ACTAgentPluginNodeInvokePolicy>>();
+
+    const policy = createLazyFileTransferNodeInvokePolicy(loadPolicy);
+
+    expect(policy.commands).toEqual(["file.fetch", "dir.list", "dir.fetch", "file.write"]);
+    expect(loadPolicy).not.toHaveBeenCalled();
+  });
+
+  it("loads and caches the delegate on first handle", async () => {
+    const invokeNode = vi.fn<ACTAgentPluginNodeInvokePolicyContext["invokeNode"]>(async () => ({
+      ok: true,
+      payload: { ok: true },
+      payloadJSON: null,
+    }));
+    const delegateHandle = vi.fn<ACTAgentPluginNodeInvokePolicy["handle"]>(async (ctx) => {
+      await ctx.invokeNode();
+      return { ok: true, payload: { delegated: true } };
+    });
+    const loadPolicy = vi.fn<() => Promise<ACTAgentPluginNodeInvokePolicy>>(async () => ({
+      commands: ["file.fetch"],
+      handle: delegateHandle,
+    }));
+    const policy = createLazyFileTransferNodeInvokePolicy(loadPolicy);
+
+    await expect(policy.handle(createPolicyContext({ invokeNode }))).resolves.toEqual({
+      ok: true,
+      payload: { delegated: true },
+    });
+    await expect(policy.handle(createPolicyContext({ invokeNode }))).resolves.toEqual({
+      ok: true,
+      payload: { delegated: true },
+    });
+
+    expect(loadPolicy).toHaveBeenCalledTimes(1);
+    expect(delegateHandle).toHaveBeenCalledTimes(2);
+    expect(invokeNode).toHaveBeenCalledTimes(2);
+  });
+
+  it("fails closed when the delegate cannot load", async () => {
+    const invokeNode = vi.fn<ACTAgentPluginNodeInvokePolicyContext["invokeNode"]>(async () => ({
+      ok: true,
+      payload: { ok: true },
+      payloadJSON: null,
+    }));
+    const policy = createLazyFileTransferNodeInvokePolicy(async () => {
+      throw new Error("load failed");
+    });
+
+    await expect(policy.handle(createPolicyContext({ invokeNode }))).resolves.toMatchObject({
+      ok: false,
+      code: "PLUGIN_POLICY_UNAVAILABLE",
+      unavailable: true,
+    });
+    expect(invokeNode).not.toHaveBeenCalled();
+  });
+
+  it("does not rewrite delegate failures as load failures", async () => {
+    const delegateError = new Error("delegate failed");
+    const policy = createLazyFileTransferNodeInvokePolicy(async () => ({
+      commands: ["file.fetch"],
+      handle: async () => {
+        throw delegateError;
+      },
+    }));
+
+    await expect(policy.handle(createPolicyContext())).rejects.toBe(delegateError);
+  });
+});

package/src/shared/lazy-node-invoke-policy.ts

@@ -0,0 +1,36 @@
+// File Transfer plugin module implements lazy node invoke policy behavior.
+import type { ACTAgentPluginNodeInvokePolicy } from "actagent/plugin-sdk/plugin-entry";
+import { FILE_TRANSFER_NODE_INVOKE_COMMANDS } from "./node-invoke-policy-commands.js";
+
+type LoadFileTransferNodeInvokePolicy = () => Promise<ACTAgentPluginNodeInvokePolicy>;
+
+const loadFileTransferNodeInvokePolicy: LoadFileTransferNodeInvokePolicy = async () => {
+  const { createFileTransferNodeInvokePolicy } = await import("./node-invoke-policy.js");
+  return createFileTransferNodeInvokePolicy();
+};
+
+export function createLazyFileTransferNodeInvokePolicy(
+  loadPolicy: LoadFileTransferNodeInvokePolicy = loadFileTransferNodeInvokePolicy,
+): ACTAgentPluginNodeInvokePolicy {
+  let policyPromise: Promise<ACTAgentPluginNodeInvokePolicy> | undefined;
+
+  return {
+    commands: [...FILE_TRANSFER_NODE_INVOKE_COMMANDS],
+    async handle(ctx) {
+      let policy: ACTAgentPluginNodeInvokePolicy;
+      try {
+        policyPromise ??= loadPolicy();
+        policy = await policyPromise;
+      } catch (error) {
+        const message = error instanceof Error && error.message ? error.message : String(error);
+        return {
+          ok: false,
+          code: "PLUGIN_POLICY_UNAVAILABLE",
+          message: `file-transfer PLUGIN_POLICY_UNAVAILABLE: node.invoke policy unavailable: ${message}`,
+          unavailable: true,
+        };
+      }
+      return await policy.handle(ctx);
+    },
+  };
+}

package/src/shared/mime.test.ts

@@ -0,0 +1,61 @@
+// File Transfer tests cover mime plugin behavior.
+import { describe, expect, it } from "vitest";
+import {
+  IMAGE_MIME_INLINE_SET,
+  TEXT_INLINE_MAX_BYTES,
+  TEXT_INLINE_MIME_SET,
+  mimeFromExtension,
+} from "./mime.js";
+
+describe("mimeFromExtension", () => {
+  it("returns the mapped mime for known extensions", () => {
+    expect(mimeFromExtension("foo.png")).toBe("image/png");
+    expect(mimeFromExtension("/abs/path/bar.JPG")).toBe("image/jpeg");
+    expect(mimeFromExtension("doc.pdf")).toBe("application/pdf");
+    expect(mimeFromExtension("notes.md")).toBe("text/markdown");
+    expect(mimeFromExtension("trace.log")).toBe("text/plain");
+    expect(mimeFromExtension("bitmap.bmp")).toBe("image/bmp");
+  });
+
+  it("falls back to application/octet-stream for unknown extensions", () => {
+    expect(mimeFromExtension("blob.xyz")).toBe("application/octet-stream");
+    expect(mimeFromExtension("Makefile")).toBe("application/octet-stream");
+  });
+
+  it("is case-insensitive on the extension", () => {
+    expect(mimeFromExtension("foo.PNG")).toBe("image/png");
+    expect(mimeFromExtension("foo.WeBp")).toBe("image/webp");
+  });
+});
+
+describe("MIME constants", () => {
+  it("EXTENSION_MIME includes the v1 image set", () => {
+    expect(mimeFromExtension("image.png")).toBe("image/png");
+    expect(mimeFromExtension("image.jpg")).toBe("image/jpeg");
+    expect(mimeFromExtension("image.jpeg")).toBe("image/jpeg");
+    expect(mimeFromExtension("image.webp")).toBe("image/webp");
+    expect(mimeFromExtension("image.gif")).toBe("image/gif");
+  });
+
+  it("IMAGE_MIME_INLINE_SET is the inline-renderable image set", () => {
+    expect(IMAGE_MIME_INLINE_SET.has("image/png")).toBe(true);
+    expect(IMAGE_MIME_INLINE_SET.has("image/jpeg")).toBe(true);
+    expect(IMAGE_MIME_INLINE_SET.has("image/webp")).toBe(true);
+    expect(IMAGE_MIME_INLINE_SET.has("image/gif")).toBe(true);
+    // heic/heif intentionally excluded
+    expect(IMAGE_MIME_INLINE_SET.has("image/heic")).toBe(false);
+    expect(IMAGE_MIME_INLINE_SET.has("image/heif")).toBe(false);
+  });
+
+  it("TEXT_INLINE_MIME_SET covers small-text inlining types", () => {
+    expect(TEXT_INLINE_MIME_SET.has("text/plain")).toBe(true);
+    expect(TEXT_INLINE_MIME_SET.has("text/markdown")).toBe(true);
+    expect(TEXT_INLINE_MIME_SET.has("application/json")).toBe(true);
+    expect(TEXT_INLINE_MIME_SET.has("text/csv")).toBe(true);
+    expect(TEXT_INLINE_MIME_SET.has("text/xml")).toBe(true);
+  });
+
+  it("TEXT_INLINE_MAX_BYTES is the documented 8KB cap", () => {
+    expect(TEXT_INLINE_MAX_BYTES).toBe(8 * 1024);
+  });
+});

package/src/shared/mime.ts

@@ -0,0 +1,30 @@
+// File Transfer plugin module implements mime behavior.
+import { mimeTypeFromFilePath } from "actagent/plugin-sdk/media-mime";
+
+// MIME types we treat as inline-displayable images for vision-capable models.
+// Note: heic/heif are detectable but not all providers can render them, so we
+// leave them out of the inline-image set and let them flow as text+saved-path.
+export const IMAGE_MIME_INLINE_SET = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+// Plain-text MIME types where inlining the content into a text block is more
+// useful than a "saved at <path>" stub for small files (under TEXT_INLINE_MAX).
+export const TEXT_INLINE_MIME_SET = new Set([
+  "text/plain",
+  "text/markdown",
+  "text/csv",
+  "text/html",
+  "application/json",
+  "application/xml",
+  "text/xml",
+]);
+
+export const TEXT_INLINE_MAX_BYTES = 8 * 1024;
+
+export function mimeFromExtension(filePath: string): string {
+  return mimeTypeFromFilePath(filePath) ?? "application/octet-stream";
+}

package/src/shared/node-invoke-policy-commands.ts

@@ -0,0 +1,9 @@
+// File Transfer plugin module implements node invoke policy commands behavior.
+export const FILE_TRANSFER_NODE_INVOKE_COMMANDS = [
+  "file.fetch",
+  "dir.list",
+  "dir.fetch",
+  "file.write",
+] as const;
+
+export type FileTransferNodeInvokeCommand = (typeof FILE_TRANSFER_NODE_INVOKE_COMMANDS)[number];