@actagent/file-transfer 2026.6.2

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

@@ -0,0 +1,378 @@
+// File Transfer tests cover file write 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 } from "vitest";
+import { handleFileWrite } from "./file-write.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(), "file-write-test-")));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+function b64(s: string): string {
+  return Buffer.from(s, "utf-8").toString("base64");
+}
+
+function expectFailure(result: Awaited<ReturnType<typeof handleFileWrite>>, code: string) {
+  expect(result.ok).toBe(false);
+  if (result.ok) {
+    throw new Error("expected file write failure");
+  }
+  expect(result.code).toBe(code);
+}
+
+function expectSuccessFields(
+  result: Awaited<ReturnType<typeof handleFileWrite>>,
+  fields: Record<string, unknown>,
+) {
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    throw new Error(`expected ok, got ${result.code}: ${result.message}`);
+  }
+  for (const [key, value] of Object.entries(fields)) {
+    expect(result[key as keyof typeof result]).toEqual(value);
+  }
+}
+
+async function expectAccessMissing(target: string) {
+  try {
+    await fs.access(target);
+  } catch (error) {
+    expect((error as NodeJS.ErrnoException).code).toBe("ENOENT");
+    return;
+  }
+  throw new Error(`expected ${target} to be missing`);
+}
+
+describe("handleFileWrite — input validation", () => {
+  it("rejects empty / non-string path", async () => {
+    expectFailure(await handleFileWrite({ path: "", contentBase64: b64("x") }), "INVALID_PATH");
+  });
+
+  it("rejects relative paths", async () => {
+    const r = await handleFileWrite({ path: "relative.txt", contentBase64: b64("x") });
+    expectFailure(r, "INVALID_PATH");
+  });
+
+  it("rejects paths with NUL bytes", async () => {
+    const r = await handleFileWrite({ path: "/tmp/foo\0bar", contentBase64: b64("x") });
+    expectFailure(r, "INVALID_PATH");
+  });
+
+  it("requires contentBase64 but allows an empty encoded payload", async () => {
+    const missing = await handleFileWrite({ path: path.join(tmpRoot, "missing.bin") });
+    expectFailure(missing, "INVALID_BASE64");
+
+    const target = path.join(tmpRoot, "empty.bin");
+    const empty = await handleFileWrite({ path: target, contentBase64: "" });
+    expectSuccessFields(empty, {
+      size: 0,
+      sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    });
+    expect(await fs.readFile(target)).toHaveLength(0);
+  });
+});
+
+describe("handleFileWrite — happy path", () => {
+  it("writes a new file and returns size + sha256 + overwritten=false", async () => {
+    const target = path.join(tmpRoot, "out.txt");
+    const contents = "hello write\n";
+    const r = await handleFileWrite({ path: target, contentBase64: b64(contents) });
+    if (!r.ok) {
+      throw new Error(`expected ok, got ${r.code}: ${r.message}`);
+    }
+    expect(r.size).toBe(contents.length);
+    expect(r.overwritten).toBe(false);
+    const expectedSha = crypto.createHash("sha256").update(contents).digest("hex");
+    expect(r.sha256).toBe(expectedSha);
+
+    const onDisk = await fs.readFile(target, "utf-8");
+    expect(onDisk).toBe(contents);
+  });
+
+  it("does not leave .tmp files behind on success", async () => {
+    const target = path.join(tmpRoot, "atomic.txt");
+    const r = await handleFileWrite({ path: target, contentBase64: b64("body") });
+    expect(r.ok).toBe(true);
+
+    const entries = await fs.readdir(tmpRoot);
+    const tmpFiles = entries.filter((n) => n.includes(".tmp"));
+    expect(tmpFiles).toStrictEqual([]);
+  });
+});
+
+describe("handleFileWrite — overwrite policy", () => {
+  it("refuses to overwrite an existing file when overwrite=false", async () => {
+    const target = path.join(tmpRoot, "exists.txt");
+    await fs.writeFile(target, "before");
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("after"),
+      overwrite: false,
+    });
+    expectFailure(r, "EXISTS_NO_OVERWRITE");
+    expect(await fs.readFile(target, "utf-8")).toBe("before");
+  });
+
+  it("overwrites and reports overwritten=true when overwrite=true", async () => {
+    const target = path.join(tmpRoot, "exists.txt");
+    await fs.writeFile(target, "before");
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("after"),
+      overwrite: true,
+    });
+    if (!r.ok) {
+      throw new Error("expected ok");
+    }
+    expect(r.overwritten).toBe(true);
+    expect(await fs.readFile(target, "utf-8")).toBe("after");
+  });
+});
+
+describe("handleFileWrite — parent directory handling", () => {
+  it("returns PARENT_NOT_FOUND when parent is missing and createParents=false", async () => {
+    const target = path.join(tmpRoot, "nested", "child.txt");
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("x"),
+      createParents: false,
+    });
+    expectFailure(r, "PARENT_NOT_FOUND");
+  });
+
+  it("creates missing parents when createParents=true", async () => {
+    const target = path.join(tmpRoot, "deep", "nested", "child.txt");
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("x"),
+      createParents: true,
+    });
+    expect(r.ok).toBe(true);
+    expect(await fs.readFile(target, "utf-8")).toBe("x");
+  });
+});
+
+describe("handleFileWrite — symlink protection", () => {
+  it("refuses to write through an existing symlink (lstat)", async () => {
+    const real = path.join(tmpRoot, "real.txt");
+    const link = path.join(tmpRoot, "link.txt");
+    await fs.writeFile(real, "untouched");
+    await fs.symlink(real, link);
+
+    const r = await handleFileWrite({
+      path: link,
+      contentBase64: b64("evil"),
+      overwrite: true,
+    });
+    expectFailure(r, "SYMLINK_TARGET_DENIED");
+    // The original file must be unchanged.
+    expect(await fs.readFile(real, "utf-8")).toBe("untouched");
+  });
+
+  it("refuses to write through a symlink in a parent directory by default", async () => {
+    // realDir is the actual victim; sentinel is a pre-existing file in it.
+    const realDir = path.join(tmpRoot, "real-dir");
+    await fs.mkdir(realDir);
+    const sentinel = path.join(realDir, "sentinel.txt");
+    await fs.writeFile(sentinel, "DO_NOT_TOUCH");
+
+    // /tmpRoot/allowed -> /tmpRoot/real-dir (symlink in a parent segment).
+    const allowed = path.join(tmpRoot, "allowed");
+    await fs.symlink(realDir, allowed);
+
+    // Asking to write to .../allowed/new-file.txt — the lexical parent
+    // (.../allowed) resolves through a symlink to .../real-dir. Refuse.
+    const r = await handleFileWrite({
+      path: path.join(allowed, "new-file.txt"),
+      contentBase64: b64("payload"),
+    });
+    expectFailure(r, "SYMLINK_REDIRECT");
+    // The error includes the canonical target so the operator can
+    // either update allowWritePaths or set followSymlinks=true.
+    expect(r.ok ? null : r.canonicalPath).toBe(path.join(realDir, "new-file.txt"));
+    // No file was created at the canonical target.
+    await expectAccessMissing(path.join(realDir, "new-file.txt"));
+    // Sentinel must be untouched.
+    expect(await fs.readFile(sentinel, "utf-8")).toBe("DO_NOT_TOUCH");
+  });
+
+  it("checks symlinked parents before recursive mkdir", async () => {
+    const realDir = path.join(tmpRoot, "real-dir");
+    await fs.mkdir(realDir);
+    const allowed = path.join(tmpRoot, "allowed");
+    await fs.symlink(realDir, allowed);
+
+    const r = await handleFileWrite({
+      path: path.join(allowed, "new", "child.txt"),
+      contentBase64: b64("payload"),
+      createParents: true,
+    });
+
+    expectFailure(r, "SYMLINK_REDIRECT");
+    expect(r.ok ? null : r.canonicalPath).toBe(path.join(realDir, "new", "child.txt"));
+    await expectAccessMissing(path.join(realDir, "new"));
+  });
+
+  it("follows the parent symlink when followSymlinks=true", async () => {
+    const realDir = path.join(tmpRoot, "real-dir");
+    await fs.mkdir(realDir);
+    const allowed = path.join(tmpRoot, "allowed");
+    await fs.symlink(realDir, allowed);
+
+    const r = await handleFileWrite({
+      path: path.join(allowed, "new-file.txt"),
+      contentBase64: b64("payload"),
+      followSymlinks: true,
+    });
+    expect(r.ok).toBe(true);
+    // The file landed in the canonical (real) directory.
+    expect(await fs.readFile(path.join(realDir, "new-file.txt"), "utf-8")).toBe("payload");
+  });
+
+  it("preflights canonical write targets without creating files or parents", async () => {
+    const realDir = path.join(tmpRoot, "real-dir");
+    await fs.mkdir(realDir);
+    const allowed = path.join(tmpRoot, "allowed");
+    await fs.symlink(realDir, allowed);
+
+    const r = await handleFileWrite({
+      path: path.join(allowed, "new", "child.txt"),
+      contentBase64: b64("payload"),
+      createParents: true,
+      followSymlinks: true,
+      preflightOnly: true,
+    });
+
+    expectSuccessFields(r, {
+      path: path.join(realDir, "new", "child.txt"),
+      size: "payload".length,
+    });
+    await expectAccessMissing(path.join(realDir, "new"));
+  });
+
+  it("refuses to overwrite a directory", async () => {
+    const target = path.join(tmpRoot, "is-a-dir");
+    await fs.mkdir(target);
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("x"),
+      overwrite: true,
+    });
+    expectFailure(r, "IS_DIRECTORY");
+  });
+});
+
+describe("handleFileWrite — integrity check", () => {
+  it("returns INTEGRITY_FAILURE before writing when expectedSha256 mismatches", async () => {
+    const target = path.join(tmpRoot, "checked.txt");
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("real-content"),
+      expectedSha256: "0".repeat(64),
+    });
+    expectFailure(r, "INTEGRITY_FAILURE");
+    // The file must never be created on a mismatch.
+    await expectAccessMissing(target);
+  });
+
+  it("does NOT replace or delete an existing file when overwrite=true and expectedSha256 mismatches", async () => {
+    const target = path.join(tmpRoot, "victim.txt");
+    await fs.writeFile(target, "ORIGINAL_CONTENT_DO_NOT_TOUCH");
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64("attacker-content"),
+      overwrite: true,
+      expectedSha256: "0".repeat(64),
+    });
+    expectFailure(r, "INTEGRITY_FAILURE");
+    // Critical: the original must survive. A bad caller hash must not
+    // be a primitive for replacing-then-deleting an existing file.
+    expect(await fs.readFile(target, "utf-8")).toBe("ORIGINAL_CONTENT_DO_NOT_TOUCH");
+  });
+
+  it("accepts a matching expectedSha256 and keeps the file", async () => {
+    const target = path.join(tmpRoot, "checked.txt");
+    const contents = "real-content";
+    const sha = crypto.createHash("sha256").update(contents).digest("hex");
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64(contents),
+      expectedSha256: sha,
+    });
+    expect(r.ok).toBe(true);
+    expect(await fs.readFile(target, "utf-8")).toBe(contents);
+  });
+
+  it("treats expectedSha256 as case-insensitive", async () => {
+    const target = path.join(tmpRoot, "checked.txt");
+    const contents = "abc";
+    const sha = crypto.createHash("sha256").update(contents).digest("hex").toUpperCase();
+
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: b64(contents),
+      expectedSha256: sha,
+    });
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("handleFileWrite — base64 round-trip validation", () => {
+  it("rejects malformed base64 that silently drops characters", async () => {
+    const target = path.join(tmpRoot, "bad.bin");
+    // "@" is not in the base64 alphabet — Buffer.from would silently drop
+    // it and decode "AAA" instead of failing.
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: "AAA@@@",
+    });
+    expectFailure(r, "INVALID_BASE64");
+    await expectAccessMissing(target);
+  });
+
+  it("accepts standard base64 with and without padding", async () => {
+    const target = path.join(tmpRoot, "padded.bin");
+    // Buffer.from("hi") -> "aGk=" with padding, "aGk" without.
+    const r1 = await handleFileWrite({ path: target, contentBase64: "aGk=" });
+    expect(r1.ok).toBe(true);
+
+    const target2 = path.join(tmpRoot, "unpadded.bin");
+    const r2 = await handleFileWrite({ path: target2, contentBase64: "aGk" });
+    expect(r2.ok).toBe(true);
+  });
+
+  it("accepts base64url variant (-_ instead of +/)", async () => {
+    const target = path.join(tmpRoot, "url.bin");
+    // Buffer.from([0xfb, 0xff]) -> "+/8=" standard, "-_8=" url
+    const r = await handleFileWrite({ path: target, contentBase64: "-_8=" });
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("handleFileWrite — size cap", () => {
+  it("rejects content larger than the 16MB cap", async () => {
+    const target = path.join(tmpRoot, "big.bin");
+    // 17MB of zero-bytes — base64 inflates by ~4/3 but we're checking the
+    // decoded buffer length so this is fine.
+    const big = Buffer.alloc(17 * 1024 * 1024, 0);
+    const r = await handleFileWrite({
+      path: target,
+      contentBase64: big.toString("base64"),
+    });
+    expectFailure(r, "FILE_TOO_LARGE");
+  });
+});

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

@@ -0,0 +1,280 @@
+// File Transfer plugin module implements file write behavior.
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  canonicalPathFromExistingAncestor,
+  FsSafeError,
+  resolveAbsolutePathForWrite,
+  root,
+} from "actagent/plugin-sdk/security-runtime";
+
+const MAX_CONTENT_BYTES = 16 * 1024 * 1024; // 16 MB
+
+type FileWriteParams = {
+  path: string;
+  contentBase64: string;
+  overwrite: boolean;
+  createParents: boolean;
+  expectedSha256?: string;
+  followSymlinks?: boolean;
+  preflightOnly?: boolean;
+};
+
+type FileWriteSuccess = {
+  ok: true;
+  path: string;
+  size: number;
+  sha256: string;
+  overwritten: boolean;
+};
+
+type FileWriteError = {
+  ok: false;
+  code: string;
+  message: string;
+  canonicalPath?: string;
+};
+
+type FileWriteResult = FileWriteSuccess | FileWriteError;
+
+function sha256Hex(buf: Buffer): string {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+function err(code: string, message: string, canonicalPath?: string): FileWriteError {
+  return { ok: false, code, message, ...(canonicalPath ? { canonicalPath } : {}) };
+}
+
+function symlinkRedirectError(error: FsSafeError): FileWriteError {
+  const canonicalTarget =
+    error.cause &&
+    typeof error.cause === "object" &&
+    "canonicalPath" in error.cause &&
+    typeof error.cause.canonicalPath === "string"
+      ? error.cause.canonicalPath
+      : undefined;
+  return err(
+    "SYMLINK_REDIRECT",
+    "path traverses a symlink; refusing because followSymlinks=false (set plugins.entries.file-transfer.config.nodes.<node>.followSymlinks=true to allow, or update allowWritePaths to the canonical path)",
+    canonicalTarget,
+  );
+}
+
+function writeFsSafeError(error: FsSafeError, targetPath: string): FileWriteError {
+  if (error.code === "symlink") {
+    return err(
+      "SYMLINK_TARGET_DENIED",
+      `path is a symlink; refusing to write through it: ${targetPath}`,
+    );
+  }
+  if (error.code === "not-file") {
+    return err("IS_DIRECTORY", `path resolves to a directory: ${targetPath}`);
+  }
+  if (error.code === "already-exists") {
+    return err("EXISTS_NO_OVERWRITE", `file already exists and overwrite is false: ${targetPath}`);
+  }
+  return err("WRITE_ERROR", error.message, targetPath);
+}
+
+export async function handleFileWrite(
+  params: Partial<FileWriteParams> & Record<string, unknown>,
+): Promise<FileWriteResult> {
+  const rawPath = typeof params?.path === "string" ? params.path : "";
+  const hasContentBase64 = typeof params?.contentBase64 === "string";
+  const contentBase64 = hasContentBase64 ? (params.contentBase64 as string) : "";
+  const overwrite = params?.overwrite === true;
+  const createParents = params?.createParents === true;
+  const expectedSha256 =
+    typeof params?.expectedSha256 === "string" ? params.expectedSha256 : undefined;
+  const followSymlinks = params?.followSymlinks === true;
+  const preflightOnly = params?.preflightOnly === true;
+
+  // 1. Validate path: must be absolute, non-empty, no NUL byte
+  if (!rawPath) {
+    return err("INVALID_PATH", "path is required");
+  }
+  if (rawPath.includes("\0")) {
+    return err("INVALID_PATH", "path must not contain NUL bytes");
+  }
+  if (!path.isAbsolute(rawPath)) {
+    return err("INVALID_PATH", "path must be absolute");
+  }
+  if (!hasContentBase64) {
+    return err("INVALID_BASE64", "contentBase64 is required");
+  }
+
+  // 2. Decode base64 → Buffer.
+  //    Buffer.from(s, "base64") in Node never throws — it silently drops
+  //    non-base64 characters and returns whatever it could decode. That
+  //    means a typo or truncated input would land garbage on disk if we
+  //    accepted whatever decoded. Defense: round-trip the decoded buffer
+  //    back to base64 and compare against the input modulo padding/url
+  //    variants. A mismatch means characters were silently dropped.
+  const buf = Buffer.from(contentBase64, "base64");
+  const reEncoded = buf.toString("base64");
+  // Normalize: drop padding and convert base64url chars to standard so the
+  // comparison tolerates both "=" / no-"=" inputs and "-_" base64url.
+  const normalize = (s: string): string =>
+    s.replace(/=+$/u, "").replace(/-/gu, "+").replace(/_/gu, "/");
+  if (normalize(reEncoded) !== normalize(contentBase64)) {
+    return err("INVALID_BASE64", "contentBase64 is not valid base64");
+  }
+
+  if (buf.length > MAX_CONTENT_BYTES) {
+    return err(
+      "FILE_TOO_LARGE",
+      `decoded content is ${buf.length} bytes; maximum is ${MAX_CONTENT_BYTES} bytes (16 MB)`,
+    );
+  }
+
+  let targetPath: string;
+  let parentDir: string;
+  let parentExists: boolean;
+  try {
+    const resolved = await resolveAbsolutePathForWrite(rawPath, {
+      symlinks: followSymlinks ? "follow" : "reject",
+    });
+    targetPath = resolved.path;
+    parentDir = resolved.parentDir;
+    parentExists = resolved.parentExists;
+  } catch (error) {
+    if (error instanceof FsSafeError && error.code === "symlink") {
+      return symlinkRedirectError(error);
+    }
+    throw error;
+  }
+
+  if (!parentExists) {
+    if (!createParents) {
+      return err("PARENT_NOT_FOUND", `parent directory does not exist: ${parentDir}`);
+    }
+    if (preflightOnly) {
+      const computedSha256 = sha256Hex(buf);
+      if (expectedSha256 && expectedSha256.toLowerCase() !== computedSha256) {
+        return err(
+          "INTEGRITY_FAILURE",
+          `sha256 mismatch: expected ${expectedSha256.toLowerCase()}, got ${computedSha256}`,
+          targetPath,
+        );
+      }
+      return {
+        ok: true,
+        path: await canonicalPathFromExistingAncestor(targetPath),
+        size: buf.length,
+        sha256: computedSha256,
+        overwritten: false,
+      };
+    }
+    try {
+      await fs.mkdir(parentDir, { recursive: true });
+    } catch (mkdirErr) {
+      const message = mkdirErr instanceof Error ? mkdirErr.message : String(mkdirErr);
+      return err("WRITE_ERROR", `failed to create parent directories: ${message}`);
+    }
+  }
+
+  try {
+    await resolveAbsolutePathForWrite(targetPath, {
+      symlinks: followSymlinks ? "follow" : "reject",
+    });
+  } catch (error) {
+    if (error instanceof FsSafeError && error.code === "symlink") {
+      return symlinkRedirectError(error);
+    }
+    throw error;
+  }
+
+  const targetFileName = path.basename(targetPath);
+  const parentRoot = await root(parentDir);
+  let overwritten = false;
+  try {
+    const existingLStat = await fs.lstat(targetPath);
+    if (existingLStat.isSymbolicLink()) {
+      return err(
+        "SYMLINK_TARGET_DENIED",
+        `path is a symlink; refusing to write through it: ${targetPath}`,
+      );
+    }
+    if (existingLStat.isDirectory()) {
+      return err("IS_DIRECTORY", `path resolves to a directory: ${targetPath}`);
+    }
+    if (!overwrite) {
+      return err(
+        "EXISTS_NO_OVERWRITE",
+        `file already exists and overwrite is false: ${targetPath}`,
+      );
+    }
+    overwritten = true;
+  } catch (statErr: unknown) {
+    const statErrorCode =
+      statErr instanceof FsSafeError ? statErr.code : (statErr as NodeJS.ErrnoException).code;
+    if (statErrorCode !== "not-found" && statErrorCode !== "ENOENT") {
+      const message = statErr instanceof Error ? statErr.message : String(statErr);
+      if (message.toLowerCase().includes("permission")) {
+        return err("PERMISSION_DENIED", `permission denied: ${targetPath}`);
+      }
+      return err("WRITE_ERROR", `unexpected stat error: ${message}`);
+    }
+  }
+
+  // 5. Hash the decoded buffer BEFORE touching disk. If the caller
+  //    supplied expectedSha256 and it doesn't match, refuse outright so
+  //    a bad caller hash with overwrite=true can't replace + delete the
+  //    original. Computing from the buffer (not a re-read) is the right
+  //    source of truth — the caller asked us to write THESE bytes.
+  const computedSha256 = sha256Hex(buf);
+  if (expectedSha256 && expectedSha256.toLowerCase() !== computedSha256) {
+    return err(
+      "INTEGRITY_FAILURE",
+      `sha256 mismatch: expected ${expectedSha256.toLowerCase()}, got ${computedSha256}`,
+      targetPath,
+    );
+  }
+
+  if (preflightOnly) {
+    return {
+      ok: true,
+      path: await canonicalPathFromExistingAncestor(targetPath),
+      size: buf.length,
+      sha256: computedSha256,
+      overwritten,
+    };
+  }
+
+  try {
+    if (overwrite) {
+      await parentRoot.write(targetFileName, buf);
+    } else {
+      await parentRoot.create(targetFileName, buf);
+    }
+  } catch (writeErr) {
+    if (writeErr instanceof FsSafeError) {
+      return writeFsSafeError(writeErr, targetPath);
+    }
+    const message = writeErr instanceof Error ? writeErr.message : String(writeErr);
+    if (message.toLowerCase().includes("permission") || message.toLowerCase().includes("access")) {
+      return err("PERMISSION_DENIED", `permission denied writing to: ${parentDir}`);
+    }
+    return err("WRITE_ERROR", `failed to write file: ${message}`);
+  }
+
+  let canonicalPath = targetPath;
+  try {
+    const opened = await parentRoot.open(targetFileName);
+    canonicalPath = opened.realPath;
+    await opened.handle.close().catch(() => undefined);
+  } catch (openErr) {
+    if (openErr instanceof FsSafeError) {
+      return writeFsSafeError(openErr, targetPath);
+    }
+  }
+
+  return {
+    ok: true,
+    path: canonicalPath,
+    size: buf.length,
+    sha256: computedSha256,
+    overwritten,
+  };
+}