@kortix/agent-tunnel 0.13.15 → 0.13.17

package/README.md

@@ -63,3 +63,31 @@ locally before enabling Computer Use. The tunnel uses an existing binary from
 `CUA_DRIVER_BIN`, `~/.local/bin`, `/usr/local/bin`, or `/opt/homebrew/bin`.
 Treat that binary as trusted local code. Agent Tunnel does not verify or update
 it.
+
+### Transfer a binary file without copying base64
+
+Run the client where the source file exists. Set `TUNNEL_API_URL`, `TUNNEL_TOKEN`,
+and `TUNNEL_ID` for the target connection, then run:
+
+```sh
+agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}'
+```
+
+`fs_upload` reads bytes from `source`, computes SHA-256, and sends the bytes
+programmatically over the authenticated tunnel. It requires filesystem write
+permission. A pending approval returns `success: false` and exit code 1; retry
+only after approval. The command accepts regular files up to 3 MiB, which leaves
+room under the relay's 5 MiB message limit after base64 encoding.
+
+The connected agent checks the supplied `sha256` before modifying the destination.
+It reads the file after writing and returns its persisted `sha256` and `size`.
+The CLI succeeds only when both match the source. An older agent without checksum
+support causes verification to fail; the file may already exist. Update the agent
+before retrying.
+
+For raw `fs.write`, `sha256` is optional for compatibility. Supply it for binary
+content. Never copy an opaque base64 payload from model context. Generate the file
+on the destination when a programmatic transfer is unavailable. A matching hash
+proves byte integrity, not format validity: validate XLSX/ZIP structure and workbook
+contents at the source. File size and magic bytes are insufficient. Do not use
+public file-host relays for this workflow.

package/dist/agent-cli.js

@@ -4369,6 +4369,39 @@ function createDesktopCapability() {
 
 // src/agent/capabilities/filesystem.ts
 import { open, writeFile, readdir, stat, unlink, mkdir } from "fs/promises";
+import { createHash as createHash2 } from "node:crypto";
+
+// src/shared/filesystem-validation.ts
+function validateFilesystemParams(method, params) {
+  if (!["fs.read", "fs.write", "fs.list", "fs.stat", "fs.delete"].includes(method))
+    return null;
+  if (typeof params.path !== "string" || !params.path.trim() || params.path.includes("\x00")) {
+    return "path must be a non-empty string without null bytes";
+  }
+  if (method !== "fs.read" && method !== "fs.write")
+    return null;
+  if (params.encoding !== undefined && !["utf8", "utf-8", "base64"].includes(params.encoding)) {
+    return 'Encoding must be "utf-8" or "base64"';
+  }
+  if (method !== "fs.write")
+    return null;
+  if (typeof params.content !== "string")
+    return "Content must be a string";
+  if (params.sha256 !== undefined && (typeof params.sha256 !== "string" || !/^[a-fA-F0-9]{64}$/.test(params.sha256))) {
+    return "sha256 must be a 64-character hexadecimal SHA-256 digest";
+  }
+  if (params.encoding === "base64") {
+    const content = params.content;
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) {
+      return "Content must be canonical padded base64";
+    }
+    if (Buffer.from(content, "base64").toString("base64") !== content)
+      return "Content must be canonical padded base64";
+  }
+  return null;
+}
+
+// src/agent/capabilities/filesystem.ts
 import { join as join5, dirname as dirname3 } from "path";
 
 // src/agent/security/path-validator.ts
@@ -4377,7 +4410,7 @@ import { realpathSync as realpathSync2 } from "fs";
 function resolveExistingRoot(path) {
   const normalized = normalize(resolve(path));
   try {
-    return realpathSync2(normalized);
+    return resolvePathForValidation(normalized);
   } catch {
     return normalized;
   }
@@ -4427,22 +4460,7 @@ function validatePath(path, allowedPaths, blockedPaths = []) {
   return resolved;
 }
 function validateWritePath(path, allowedPaths, blockedPaths = []) {
-  const resolved = validatePath(path, allowedPaths, blockedPaths);
-  let parent = dirname2(normalize(resolve(path)));
-  while (parent && parent !== dirname2(parent)) {
-    try {
-      const resolvedParent = realpathSync2(parent);
-      assertAllowedResolvedPath(path, resolvedParent, allowedPaths, blockedPaths);
-      return resolved;
-    } catch (err) {
-      const code = err.code;
-      if (code !== "ENOENT") {
-        throw new Error(`Access denied: cannot resolve parent for "${path}" (${code})`);
-      }
-      parent = dirname2(parent);
-    }
-  }
-  throw new Error(`Access denied: cannot resolve parent for "${path}"`);
+  return validatePath(path, allowedPaths, blockedPaths);
 }
 
 // src/agent/capabilities/filesystem.ts
@@ -4522,6 +4540,9 @@ function createFilesystemCapability(config) {
   });
   methods.set("fs.write", async (params) => {
     assertFilesystemOperation(params, "fs.write");
+    const validationError = validateFilesystemParams("fs.write", params);
+    if (validationError)
+      throw new Error(validationError);
     const path = params.path;
     const content = params.content;
     const encoding = parseEncoding(params.encoding);
@@ -4534,15 +4555,29 @@ function createFilesystemCapability(config) {
     if (contentBytes > maxFileSize) {
       throw new Error(`Content exceeds max size (${contentBytes} > ${maxFileSize})`);
     }
+    const bytes = Buffer.from(content, encoding);
+    const expectedHash = createHash2("sha256").update(bytes).digest("hex");
+    if (params.sha256 !== undefined && params.sha256.toLowerCase() !== expectedHash) {
+      throw new Error("SHA-256 mismatch: content differs from the source; destination was not modified");
+    }
     await mkdir(dirname3(path), { recursive: true });
     validateFilesystemPath(path, config, params, true);
-    await writeFile(path, content, { encoding });
+    await writeFile(path, bytes);
     validateFilesystemPath(path, config, params);
-    const stats = await stat(path);
-    return {
-      size: stats.size,
-      path
-    };
+    const handle = await open(path, "r");
+    try {
+      const stats = await handle.stat();
+      const persistedHash = createHash2("sha256").update(await handle.readFile()).digest("hex");
+      if (persistedHash !== expectedHash)
+        throw new Error("SHA-256 mismatch after write; destination verification failed");
+      return {
+        sha256: persistedHash,
+        size: stats.size,
+        path
+      };
+    } finally {
+      await handle.close();
+    }
   });
   methods.set("fs.list", async (params) => {
     assertFilesystemOperation(params, "fs.list");

package/dist/client-cli.js

@@ -2,6 +2,8 @@
 
 // src/client/cli.ts
 import { readFileSync } from "fs";
+import { open } from "node:fs/promises";
+import { createHash } from "node:crypto";
 
 // src/client/tunnel-client.ts
 function trimTrailingSlashes(value) {
@@ -205,6 +207,7 @@ var ALL_COMMANDS = [
   "status",
   "fs_read",
   "fs_write",
+  "fs_upload",
   "fs_list",
   "shell",
   "cua_ensure",
@@ -317,12 +320,44 @@ async function fsWrite(args) {
   const result = await call("fs.write", {
     path: args.path,
     content: args.content,
+    sha256: args.sha256,
     encoding: args.encoding || "utf-8"
   });
   if (result === null)
     return;
   const data = result;
-  out({ success: true, path: data.path, size: data.size });
+  out({ success: true, path: data.path, size: data.size, sha256: data.sha256 });
+}
+async function fsUpload(args) {
+  if (typeof args.source !== "string" || !args.source)
+    return fail("source is required");
+  if (typeof args.path !== "string" || !args.path)
+    return fail("path is required");
+  const handle = await open(args.source, "r");
+  let bytes;
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile())
+      return fail("source must be a regular file");
+    if (stats.size > 3 * 1024 * 1024)
+      return fail("source exceeds the 3 MiB upload limit");
+    bytes = await handle.readFile();
+    if (bytes.length > 3 * 1024 * 1024)
+      return fail("source exceeds the 3 MiB upload limit");
+  } finally {
+    await handle.close();
+  }
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const result = await call("fs.write", { path: args.path, content: bytes.toString("base64"), encoding: "base64", sha256 });
+  if (result === null) {
+    process.exitCode = 1;
+    return;
+  }
+  const data = result;
+  if (data.sha256 !== sha256 || data.size !== bytes.length) {
+    return fail("Destination verification failed. Update the connected agent if its response has no sha256. The file may have been written.");
+  }
+  out({ success: true, path: data.path, size: data.size, sha256 });
 }
 async function fsList(args) {
   const result = await call("fs.list", {
@@ -403,6 +438,9 @@ try {
     case "fs_write":
       await fsWrite(args);
       break;
+    case "fs_upload":
+      await fsUpload(args);
+      break;
     case "fs_list":
       await fsList(args);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.13.15",
+  "version": "0.13.17",
   "private": false,
   "type": "module",
   "description": "Tunnel relay between cloud AI agents and local machines — server relay, local agent, client SDK, JSON-RPC, HMAC signing",

package/src/agent/capabilities/filesystem-integrity.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createFilesystemCapability } from './filesystem';
+import type { TunnelConfig } from '../config';
+
+const roots: string[] = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map(path => rm(path, { recursive: true, force: true }))); });
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), 'tunnel-integrity-'));
+  roots.push(root);
+  const config: TunnelConfig = {
+    token: '', tunnelId: '', apiUrl: 'http://localhost', wsPath: '/ws',
+    maxFileSize: 1024 * 1024, allowedPaths: [root], blockedPaths: [],
+    allowedCommands: [], blockedCommands: [], workingDir: root,
+    shellTimeout: 1000, shellMaxTimeout: 1000, shellMaxOutputSize: 1024, shellEnvPassthrough: [],
+  };
+  return { path: join(root, 'artifact.xlsx'), write: createFilesystemCapability(config).methods.get('fs.write')!,
+    __permission: { permissionId: 'test', capability: 'filesystem', scope: { paths: [root], operations: ['write'] } } };
+}
+const sha256 = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex');
+
+test('binary write returns the persisted SHA-256 and preserves every byte', async () => {
+  const { write, ...params } = await fixture();
+  const bytes = Buffer.from(Array.from({ length: 65536 }, (_, i) => i % 256));
+  const result = await write({ ...params, content: bytes.toString('base64'), encoding: 'base64', sha256: sha256(bytes) });
+  expect(result).toMatchObject({ size: bytes.length, sha256: sha256(bytes) });
+  expect(await readFile(params.path)).toEqual(bytes);
+});
+
+test('same-length corruption fails before overwriting an existing destination', async () => {
+  const { write, ...params } = await fixture();
+  await writeFile(params.path, 'preserve me');
+  const source = Buffer.from('PK valid-looking archive');
+  const corrupt = Buffer.from(source); corrupt[10] ^= 1;
+  await expect(write({ ...params, content: corrupt.toString('base64'), encoding: 'base64', sha256: sha256(source) })).rejects.toThrow('SHA-256 mismatch');
+  expect(await readFile(params.path, 'utf8')).toBe('preserve me');
+});
+
+test('malformed base64 fails before writing', async () => {
+  const { write, ...params } = await fixture();
+  await expect(write({ ...params, content: 'aGVsbG8=!', encoding: 'base64' })).rejects.toThrow('base64');
+  expect(await Bun.file(params.path).exists()).toBe(false);
+});
+
+test('an exact-file approval permits that file and rejects its sibling', async () => {
+  const { write, ...params } = await fixture();
+  params.__permission.scope.paths = [params.path];
+  await write({ ...params, content: 'approved' });
+  expect(await readFile(params.path, 'utf8')).toBe('approved');
+  await expect(write({ ...params, path: params.path + '.other', content: 'denied' })).rejects.toThrow('outside allowed directories');
+});
+
+test('an allowed directory symlink cannot redirect a write outside the local ceiling', async () => {
+  const { symlink } = await import('node:fs/promises');
+  const { write, ...params } = await fixture();
+  const other = await fixture();
+  const link = params.path + '.link';
+  await symlink(dirname(other.path), link);
+  await expect(write({ ...params, path: join(link, 'escape.xlsx'), content: 'denied' })).rejects.toThrow('outside allowed directories');
+  expect(await Bun.file(dirname(other.path) + '/escape.xlsx').exists()).toBe(false);
+});

package/src/agent/capabilities/filesystem.ts

@@ -6,6 +6,8 @@
  */
 
 import { open, writeFile, readdir, stat, unlink, mkdir } from 'fs/promises';
+import { createHash } from 'node:crypto';
+import { validateFilesystemParams } from '../../shared/filesystem-validation';
 import { join, dirname } from 'path';
 import type { Capability, RpcHandler } from './index';
 import { validatePath, validateWritePath } from '../security/path-validator';
@@ -131,6 +133,8 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
 
   methods.set('fs.write', async (params) => {
     assertFilesystemOperation(params, 'fs.write');
+    const validationError = validateFilesystemParams('fs.write', params);
+    if (validationError) throw new Error(validationError);
     const path = params.path as string;
     const content = params.content as string;
     const encoding = parseEncoding(params.encoding);
@@ -148,17 +152,31 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
       throw new Error(`Content exceeds max size (${contentBytes} > ${maxFileSize})`);
     }
 
+    const bytes = Buffer.from(content, encoding);
+    const expectedHash = createHash('sha256').update(bytes).digest('hex');
+    if (params.sha256 !== undefined && (params.sha256 as string).toLowerCase() !== expectedHash) {
+      throw new Error('SHA-256 mismatch: content differs from the source; destination was not modified');
+    }
+
     await mkdir(dirname(path), { recursive: true });
     validateFilesystemPath(path, config, params, true);
 
-    await writeFile(path, content, { encoding });
+    await writeFile(path, bytes);
     validateFilesystemPath(path, config, params);
-    const stats = await stat(path);
+    const handle = await open(path, 'r');
+    try {
+      const stats = await handle.stat();
+      const persistedHash = createHash('sha256').update(await handle.readFile()).digest('hex');
+      if (persistedHash !== expectedHash) throw new Error('SHA-256 mismatch after write; destination verification failed');
 
-    return {
-      size: stats.size,
-      path,
-    };
+      return {
+        sha256: persistedHash,
+        size: stats.size,
+        path,
+      };
+    } finally {
+      await handle.close();
+    }
   });
 
   methods.set('fs.list', async (params) => {

package/src/agent/security/path-validator.ts

@@ -14,7 +14,7 @@ import { realpathSync } from 'fs';
 function resolveExistingRoot(path: string): string {
   const normalized = normalize(resolve(path));
   try {
-    return realpathSync(normalized);
+    return resolvePathForValidation(normalized);
   } catch {
     return normalized;
   }
@@ -86,22 +86,8 @@ export function validateWritePath(
   allowedPaths: string[],
   blockedPaths: string[] = [],
 ): string {
-  const resolved = validatePath(path, allowedPaths, blockedPaths);
-
-  let parent = dirname(normalize(resolve(path)));
-  while (parent && parent !== dirname(parent)) {
-    try {
-      const resolvedParent = realpathSync(parent);
-      assertAllowedResolvedPath(path, resolvedParent, allowedPaths, blockedPaths);
-      return resolved;
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== 'ENOENT') {
-        throw new Error(`Access denied: cannot resolve parent for "${path}" (${code})`);
-      }
-      parent = dirname(parent);
-    }
-  }
-
-  throw new Error(`Access denied: cannot resolve parent for "${path}"`);
+  // Resolve the complete destination through its nearest existing ancestor.
+  // Checking the parent against an exact-file allowlist would reject the file
+  // that the user approved. validatePath also resolves missing allowlist roots.
+  return validatePath(path, allowedPaths, blockedPaths);
 }

package/src/client/cli.test.ts

@@ -184,6 +184,20 @@ describe('Agent Tunnel CLI', () => {
     expect(r.json!.size).toBe(11);
   });
 
+  test('fs_upload refuses an older agent response without checksum proof', async () => {
+    const source = resolve(import.meta.dir, '../../../../tests/fixtures/tunnel-integrity.xlsx');
+    const r = await runCli('fs_upload', JSON.stringify({ source, path: '/tmp/report.xlsx' }));
+    expect(r.exitCode).toBe(1);
+    expect(r.json?.success).toBe(false);
+    expect(r.json?.error).toContain('Destination verification failed');
+  });
+
+  test('fs_upload rejects a missing source before calling the server', async () => {
+    const r = await runCli('fs_upload', JSON.stringify({ path: '/tmp/report.xlsx' }));
+    expect(r.exitCode).toBe(1);
+    expect(r.json?.error).toBe('source is required');
+  });
+
   test('fs_list returns entries', async () => {
     const r = await runCli('fs_list', '{"path":"/tmp"}');
     expect(r.exitCode).toBe(0);

package/src/client/cli.ts

@@ -5,6 +5,8 @@
  */
 
 import { readFileSync } from 'fs';
+import { open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { TunnelClient, TunnelClientError } from './tunnel-client';
 
 const S6_ENV_DIR = process.env.S6_ENV_DIR || '/run/s6/container_environment';
@@ -14,6 +16,7 @@ const ALL_COMMANDS = [
   'status',
   'fs_read',
   'fs_write',
+  'fs_upload',
   'fs_list',
   'shell',
   'cua_ensure',
@@ -144,11 +147,38 @@ async function fsWrite(args: Record<string, unknown>) {
   const result = await call('fs.write', {
     path: args.path,
     content: args.content,
+    sha256: args.sha256,
     encoding: (args.encoding as string) || 'utf-8',
   });
   if (result === null) return;
   const data = result as Record<string, unknown>;
-  out({ success: true, path: data.path, size: data.size });
+  out({ success: true, path: data.path, size: data.size, sha256: data.sha256 });
+}
+
+/** Read bytes locally: opaque payloads never pass through model output. */
+async function fsUpload(args: Record<string, unknown>) {
+  if (typeof args.source !== 'string' || !args.source) return fail('source is required');
+  if (typeof args.path !== 'string' || !args.path) return fail('path is required');
+  const handle = await open(args.source, 'r');
+  let bytes: Buffer;
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) return fail('source must be a regular file');
+    // The relay and agent cap frames at 5 MiB. Leave room for base64 and RPC metadata.
+    if (stats.size > 3 * 1024 * 1024) return fail('source exceeds the 3 MiB upload limit');
+    bytes = await handle.readFile();
+    if (bytes.length > 3 * 1024 * 1024) return fail('source exceeds the 3 MiB upload limit');
+  } finally {
+    await handle.close();
+  }
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  const result = await call('fs.write', { path: args.path, content: bytes.toString('base64'), encoding: 'base64', sha256 });
+  if (result === null) { process.exitCode = 1; return; }
+  const data = result as Record<string, unknown>;
+  if (data.sha256 !== sha256 || data.size !== bytes.length) {
+    return fail('Destination verification failed. Update the connected agent if its response has no sha256. The file may have been written.');
+  }
+  out({ success: true, path: data.path, size: data.size, sha256 });
 }
 
 async function fsList(args: Record<string, unknown>) {
@@ -238,6 +268,9 @@ try {
     case 'fs_write':
       await fsWrite(args);
       break;
+    case 'fs_upload':
+      await fsUpload(args);
+      break;
     case 'fs_list':
       await fsList(args);
       break;

package/src/client/tools.ts

@@ -88,22 +88,24 @@ export function createTunnelTools(client: TunnelClient): TunnelToolDefinition[]
     },
     {
       name: 'tunnel_fs_write',
-      description: `Write a file to a connected computer via Agent Tunnel. Creates parent directories if needed. Requires filesystem write permission.`,
+      description: `Write a file to a connected computer via Agent Tunnel. Creates parent directories if needed. Requires filesystem write permission. Never transcribe binary base64; use agent-tunnel-cli fs_upload with source and path, or generate on the destination.`,
       parameters: {
         tunnel_id: tunnelIdParam,
         path: { type: 'string', description: 'Absolute path for the file on the connected computer', required: true },
         content: { type: 'string', description: 'File content to write', required: true },
+        sha256: { type: 'string', description: 'Source SHA-256; mismatch rejects the write before changing the destination', required: false },
         encoding: { type: 'string', description: 'File encoding (default: utf-8)', required: false },
       },
       async execute(args) {
         const result = await client.rpcWithPermissionFlow('fs.write', {
           path: args.path,
           content: args.content,
+          sha256: args.sha256,
           encoding: (args.encoding as string) || 'utf-8',
         });
         if (typeof result === 'string') return result;
         const data = result as Record<string, unknown>;
-        return `File written: ${data.path} (${data.size} bytes)`;
+        return `File written: ${data.path} (${data.size} bytes), SHA-256: ${data.sha256}`;
       },
     },
     {

package/src/index.ts

@@ -13,6 +13,7 @@ export {
   isTunnelCapability,
   operationForMethod,
   validateTunnelPermissionScope,
+  validateFilesystemParams,
 } from './shared';
 
 export type {

package/src/shared/filesystem-validation.ts

@@ -0,0 +1,24 @@
+/** Validate file arguments before requesting permission or touching the destination. */
+export function validateFilesystemParams(method: string, params: Record<string, unknown>): string | null {
+  if (!['fs.read', 'fs.write', 'fs.list', 'fs.stat', 'fs.delete'].includes(method)) return null;
+  if (typeof params.path !== 'string' || !params.path.trim() || params.path.includes('\0')) {
+    return 'path must be a non-empty string without null bytes';
+  }
+  if (method !== 'fs.read' && method !== 'fs.write') return null;
+  if (params.encoding !== undefined && !['utf8', 'utf-8', 'base64'].includes(params.encoding as string)) {
+    return 'Encoding must be "utf-8" or "base64"';
+  }
+  if (method !== 'fs.write') return null;
+  if (typeof params.content !== 'string') return 'Content must be a string';
+  if (params.sha256 !== undefined && (typeof params.sha256 !== 'string' || !/^[a-fA-F0-9]{64}$/.test(params.sha256))) {
+    return 'sha256 must be a 64-character hexadecimal SHA-256 digest';
+  }
+  if (params.encoding === 'base64') {
+    const content = params.content;
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content)) {
+      return 'Content must be canonical padded base64';
+    }
+    if (Buffer.from(content, 'base64').toString('base64') !== content) return 'Content must be canonical padded base64';
+  }
+  return null;
+}

package/src/shared/index.ts

@@ -41,3 +41,5 @@ export {
   validateTunnelPermissionScope,
 } from './permissions';
 export type { PermissionScopeValidationResult } from './permissions';
+
+export { validateFilesystemParams } from './filesystem-validation';