@abot-ai/runtime 1.2.0 → 1.3.1

package/plugins/filesystem/source/directory-sample.ts

@@ -0,0 +1,132 @@
+import { constants, type BigIntStats } from "node:fs";
+import {
+  open,
+  opendir,
+  realpath,
+  stat,
+  type FileHandle,
+} from "node:fs/promises";
+import { relative, sep } from "node:path";
+import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
+import {
+  DirectoryAuthorityError,
+  runDirectoryAuthorityTask,
+} from "../../../src/shared/directory-authority/index.js";
+import { fail, rethrowFilesystemError } from "./errors.js";
+import { sampleDirectoryTask } from "./directory-sample-task.js";
+
+export const DIRECTORY_ENTRY_LIMIT = 160;
+
+export async function readDirectorySample(
+  target: ResolvedRuntimeToolPath,
+): Promise<Readonly<{ entries: readonly string[]; truncated: boolean }>> {
+  const entries: string[] = [];
+  let handle: FileHandle | undefined;
+  try {
+    if (
+      typeof constants.O_DIRECTORY !== "number" ||
+      typeof constants.O_NOFOLLOW !== "number"
+    ) {
+      fail(
+        "filesystem_safe_io_unsupported",
+        "This platform does not provide the no-follow directory operation required for a safe read.",
+      );
+    }
+    handle = await open(
+      target.absolutePath,
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+    );
+    const before = await handle.stat({ bigint: true });
+    if (!before.isDirectory()) {
+      fail("not_a_directory", `Expected a directory: ${target.logicalPath}`);
+    }
+    const [canonicalRoot, canonicalTarget] = await Promise.all([
+      realpath(target.rootPath),
+      realpath(target.absolutePath),
+    ]);
+    const rootRelative = relative(canonicalRoot, canonicalTarget);
+    if (
+      rootRelative === ".." ||
+      rootRelative.startsWith(`..${sep}`) ||
+      rootRelative.startsWith(sep)
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed outside its configured root: ${target.logicalPath}`,
+      );
+    }
+    const pathIdentity = await stat(canonicalTarget, { bigint: true });
+    if (
+      !pathIdentity.isDirectory() ||
+      pathIdentity.dev !== before.dev ||
+      pathIdentity.ino !== before.ino
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory changed while it was being opened: ${target.logicalPath}`,
+      );
+    }
+    if (requiresIsolatedDirectorySample()) {
+      const sample = await runDirectoryAuthorityTask({
+        directoryPath: target.absolutePath,
+        directoryFd: handle.fd,
+        input: { maxEntries: DIRECTORY_ENTRY_LIMIT },
+        task: sampleDirectoryTask,
+      });
+      await assertDirectoryStable(handle, before, target.logicalPath);
+      return sample;
+    }
+    const directory = await opendir(`/proc/self/fd/${handle.fd}`);
+    for await (const entry of directory) {
+      if (entries.length >= DIRECTORY_ENTRY_LIMIT) {
+        await assertDirectoryStable(handle, before, target.logicalPath);
+        entries.sort((left, right) => left.localeCompare(right));
+        return Object.freeze({
+          entries: Object.freeze(entries),
+          truncated: true,
+        });
+      }
+      entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
+    }
+    await assertDirectoryStable(handle, before, target.logicalPath);
+    entries.sort((left, right) => left.localeCompare(right));
+    return Object.freeze({ entries: Object.freeze(entries), truncated: false });
+  } catch (error: unknown) {
+    if (
+      error instanceof DirectoryAuthorityError &&
+      error.code.startsWith("directory_authority_")
+    ) {
+      fail(
+        "filesystem_path_changed",
+        `Directory authority was lost: ${target.logicalPath}`,
+      );
+    }
+    return rethrowFilesystemError(error, "inspect", target.logicalPath);
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+async function assertDirectoryStable(
+  handle: FileHandle,
+  before: BigIntStats,
+  logicalPath: string,
+): Promise<void> {
+  const after = await handle.stat({ bigint: true });
+  if (
+    !after.isDirectory() ||
+    after.dev !== before.dev ||
+    after.ino !== before.ino ||
+    after.mtimeNs !== before.mtimeNs ||
+    after.ctimeNs !== before.ctimeNs
+  ) {
+    fail(
+      "filesystem_read_changed",
+      `Directory changed while it was being read: ${logicalPath}`,
+    );
+  }
+}
+
+function requiresIsolatedDirectorySample(): boolean {
+  return process.platform === "darwin";
+}

package/plugins/filesystem/source/directory-write-task.ts

@@ -0,0 +1,160 @@
+export type DirectoryWriteInput = Readonly<{
+  relativePath: string;
+  content: string;
+  expectedVersion:
+    | Readonly<{ kind: "absent" }>
+    | Readonly<{
+        kind: "file";
+        device: string;
+        inode: string;
+        size: number;
+        mode: number;
+        modifiedNs: string;
+        changedNs: string;
+        digest: string;
+      }>;
+}>;
+
+/** Self-contained trusted task: serialized into an isolated Node process. */
+export async function commitDirectoryWrite(
+  input: DirectoryWriteInput,
+): Promise<void> {
+  const fs = require("node:fs/promises") as typeof import("node:fs/promises");
+  const { constants } = require("node:fs") as typeof import("node:fs");
+  const { createHash, randomUUID } =
+    require("node:crypto") as typeof import("node:crypto");
+  const expected = input.expectedVersion;
+
+  function failWrite(code: string): never {
+    throw Object.assign(new Error(code), { code });
+  }
+  function hasNodeCode(error: unknown, code: string): boolean {
+    return error instanceof Error && "code" in error && error.code === code;
+  }
+  function isSingleComponent(value: string): boolean {
+    if (!value || value === "." || value === "..") return false;
+    if (value.includes("/") || value.includes("\\")) return false;
+    return !value.includes("\0");
+  }
+  const segments = input.relativePath.split("/");
+  if (!segments.every(isSingleComponent)) failWrite("filesystem_path_changed");
+  const targetName = segments.pop()!;
+  if (Buffer.byteLength(input.content, "utf8") > 1_048_576) {
+    failWrite("filesystem_file_too_large");
+  }
+
+  async function enterChildDirectory(name: string): Promise<void> {
+    let handle: Awaited<ReturnType<typeof fs.open>>;
+    const flags =
+      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+    try {
+      handle = await fs.open(name, flags);
+    } catch (error) {
+      if (!hasNodeCode(error, "ENOENT")) throw error;
+      try {
+        await fs.mkdir(name);
+      } catch (creationError) {
+        if (!hasNodeCode(creationError, "EEXIST")) throw creationError;
+      }
+      handle = await fs.open(name, flags);
+    }
+    try {
+      const held = await handle.stat({ bigint: true });
+      if (!held.isDirectory()) failWrite("filesystem_path_changed");
+      process.chdir(name);
+      const entered = await fs.stat(".", { bigint: true });
+      if (held.dev !== entered.dev || held.ino !== entered.ino) {
+        failWrite("filesystem_path_changed");
+      }
+    } finally {
+      await handle.close();
+    }
+  }
+  for (const segment of segments) await enterChildDirectory(segment);
+
+  function hasExpectedMetadata(info: import("node:fs").BigIntStats): boolean {
+    if (expected.kind !== "file" || !info.isFile()) return false;
+    if (String(info.dev) !== expected.device) return false;
+    if (String(info.ino) !== expected.inode) return false;
+    if (Number(info.size) !== expected.size) return false;
+    if ((Number(info.mode) & 0o7777) !== expected.mode) return false;
+    if (String(info.mtimeNs) !== expected.modifiedNs) return false;
+    return String(info.ctimeNs) === expected.changedNs;
+  }
+  async function assertExpectedTarget(): Promise<void> {
+    let target: Awaited<ReturnType<typeof fs.open>>;
+    try {
+      target = await fs.open(
+        targetName,
+        constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+      );
+    } catch (error) {
+      if (hasNodeCode(error, "ENOENT") && expected.kind === "absent") return;
+      failWrite("filesystem_target_changed");
+    }
+    try {
+      const before = await target.stat({ bigint: true });
+      if (!hasExpectedMetadata(before)) failWrite("filesystem_target_changed");
+      if (expected.kind !== "file") failWrite("filesystem_target_changed");
+      const bytes = Buffer.alloc(expected.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await target.read(
+          bytes,
+          offset,
+          bytes.length - offset,
+          offset,
+        );
+        if (bytesRead <= 0) failWrite("filesystem_target_changed");
+        offset += bytesRead;
+      }
+      const after = await target.stat({ bigint: true });
+      if (!hasExpectedMetadata(after)) failWrite("filesystem_target_changed");
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (digest !== expected.digest) failWrite("filesystem_target_changed");
+    } finally {
+      await target.close();
+    }
+  }
+
+  const parent = await fs.open(
+    ".",
+    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
+  );
+  const temporaryName = `.abot-${targetName}-${randomUUID()}.tmp`;
+  let temporaryCreated = false;
+  try {
+    const temporary = await fs.open(temporaryName, "wx");
+    temporaryCreated = true;
+    try {
+      await temporary.writeFile(input.content, "utf8");
+      if (expected.kind === "file") await temporary.chmod(expected.mode);
+      await temporary.sync();
+    } finally {
+      await temporary.close();
+    }
+    await assertExpectedTarget();
+    if (expected.kind === "file") {
+      await fs.rename(temporaryName, targetName);
+      temporaryCreated = false;
+    } else {
+      try {
+        await fs.link(temporaryName, targetName);
+      } catch (error) {
+        if (hasNodeCode(error, "EEXIST"))
+          failWrite("filesystem_target_changed");
+        throw error;
+      }
+      const removed = await fs
+        .rm(temporaryName, { force: true })
+        .then(() => true)
+        .catch(() => false);
+      temporaryCreated = !removed;
+    }
+    await parent.sync().catch(() => undefined);
+  } finally {
+    if (temporaryCreated)
+      await fs.rm(temporaryName, { force: true }).catch(() => undefined);
+    await parent.close().catch(() => undefined);
+  }
+}

package/plugins/filesystem/source/mutation-parent.ts

@@ -66,6 +66,7 @@ async function openDirectory(
         `Directory changed while it was being opened: ${logicalPath}`,
       );
     }
+    if (usesIsolatedDirectoryAuthority()) return handle;
     const procPath = `/proc/self/fd/${handle.fd}`;
     const procIdentity = await stat(procPath, { bigint: true });
     if (!procIdentity.isDirectory() || !sameIdentity(opened, procIdentity)) {
@@ -162,3 +163,13 @@ export async function openMutationParent(
     throw error;
   }
 }
+
+function usesIsolatedDirectoryAuthority(): boolean {
+  return process.platform === "darwin";
+}
+
+export function openMutationRoot(
+  target: ResolvedRuntimeToolPath,
+): Promise<FileHandle> {
+  return openDirectory(target.rootPath, target.rootPath, target.logicalPath);
+}