pi-codex-tools 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-08-08
+
+### Fixed
+
+- Stop npm from running `node-gyp rebuild` on install. The package ships prebuilt native bindings and loads them at runtime, but npm's gypfile detection keyed off the dev-only `binding.gyp` and injected a failing `node-gyp rebuild` into the install lifecycle — breaking install on machines without a build toolchain (e.g. Linux). Set `gypfile: false` to suppress it.
+
+## [0.2.0] - 2026-08-08
+
+### Added
+
+- macOS support for `apply_patch` via a bundled `openat` / `mkdirat` / `unlinkat` N-API binding, prebuilt for Apple silicon and Intel. The TOCTOU-safe no-follow directory walk now runs on macOS with parity to Linux, so supported Codex models can use `apply_patch` on macOS (previously Linux-only).
+
+### Fixed
+
+- Keep `edit` and `write` active on platforms where `apply_patch` cannot run. The tool swap was gated solely on model grammar capability, so unsupported platforms (macOS) replaced the native file tools with `apply_patch` and then failed at execution; activation now also requires the secure filesystem to be supported.
+
 ## [0.1.3] - 2026-08-06
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ Give grammar-capable OpenAI/Codex models the Codex `apply_patch` tool in Pi with
 
 - **Raw `apply_patch`** — sends Codex's Lark grammar as an OpenAI custom tool, so patches are not JSON-wrapped.
 - **Capability-based activation** — requires `openai-codex-responses` or `openai-responses` plus `model.compat.supportsOpenAIGrammarTools === true`; model names alone are never enough.
-- **Safe local mutation** — patches are limited to 1 MiB, target files to 64 MiB, stay under Pi's current working directory, reject symlink escapes, use descriptor-anchored no-follow operations on Linux, fail closed elsewhere, preflight all hunks, and serialize writes with Pi's mutation queue.
+- **Safe local mutation** — patches are limited to 1 MiB, target files to 64 MiB, stay under Pi's current working directory, reject symlink escapes, use descriptor-anchored no-follow operations on Linux and macOS, fail closed elsewhere, preflight all hunks, and serialize writes with Pi's mutation queue.
 - **Model switching** — supported models replace Pi's `edit` and `write` tools with `apply_patch`; other active tools are preserved. Switching back restores only the file tools that were active before the switch.
 - **Sequential patch calls** — the extension marks patch execution sequential and disables provider-side parallel tool calls when the patch tool is active.
 - **Streaming progress** — while a patch is generated, the TUI shows a live, color-coded glimpse of the content being written (new-file content, or `+`/`-` lines for updates) plus a running `+added -removed` tally and a per-file roster for multi-file patches. It reuses Pi's shared diff rendering and mirrors the built-in `write`/`edit` previews; patch execution is unchanged.
@@ -25,7 +25,7 @@ pi -e /path/to/pi-mono/packages/pi-codex-tools
 
 ## Scope decisions
 
-The current Codex source does not define separate `read_file` or `write_file` tools: file inspection is normally done through shell commands and file mutation through `apply_patch`. This package keeps Pi's bounded `read` and `bash` tools, and uses `apply_patch` in place of Pi's `edit` and `write` tools for supported models. Because Pi does not provide Codex's OS-level filesystem sandbox, `apply_patch` runs only on Linux and fails closed on unsupported platforms. It also requires a Pi model runtime that advertises `compat.supportsOpenAIGrammarTools`; older runtimes leave the tool inactive.
+The current Codex source does not define separate `read_file` or `write_file` tools: file inspection is normally done through shell commands and file mutation through `apply_patch`. This package keeps Pi's bounded `read` and `bash` tools, and uses `apply_patch` in place of Pi's `edit` and `write` tools for supported models. Because Pi does not provide Codex's OS-level filesystem sandbox, `apply_patch` performs its own TOCTOU-safe, no-follow directory walk: on Linux it re-opens each component relative to a trusted fd via `/proc/self/fd`, and on macOS via a tiny bundled `openat`/`mkdirat`/`unlinkat` N-API binding (prebuilt for Apple silicon and Intel). It fails closed on platforms without that support, in which case the native `edit`/`write` tools stay active. `apply_patch` also requires a Pi model runtime that advertises `compat.supportsOpenAIGrammarTools`; older runtimes leave the tool inactive.
 
 | Codex surface | Decision |
 | --- | --- |

package/SECURITY.md

@@ -19,7 +19,7 @@ Report privately through [GitHub Security Advisories](https://github.com/jvm/pi-
 
 Pi extensions execute with the same permissions as the local user running Pi. Review installed extensions and only install packages from sources you trust.
 
-`apply_patch` does not access the network or credential APIs. It can read credential-containing files when a patch targets them. It validates paths beneath the current working directory, rejects symlink paths and symlinked parents, limits patch input to 1 MiB and target-file reads to 64 MiB, preflights file changes before writing, and uses root-anchored descriptor-based no-follow operations on Linux. It fails closed on unsupported platforms because Pi does not provide Codex's OS-level filesystem sandbox. A failure during a multi-file write can still leave earlier files changed; callers should use version control and review the resulting diff.
+`apply_patch` does not access the network or credential APIs. It can read credential-containing files when a patch targets them. It validates paths beneath the current working directory, rejects symlink paths and symlinked parents, limits patch input to 1 MiB and target-file reads to 64 MiB, preflights file changes before writing, and performs a root-anchored descriptor-based no-follow directory walk so a path component swapped to a symlink between check and use cannot escape. On Linux the walk re-opens each component via `/proc/self/fd`; on macOS it uses a bundled `openat`/`mkdirat`/`unlinkat` N-API binding (committed prebuilds for `darwin-arm64` and `darwin-x64`, loaded via `node-gyp-build`) because Node does not expose `openat` and macOS lacks procfs. The binding is darwin-only, exposes only those three POSIX calls, and is loaded best-effort: on platforms without it `apply_patch` fails closed and Pi keeps its native `edit`/`write` tools. A failure during a multi-file write can still leave earlier files changed; callers should use version control and review the resulting diff.
 
 The package reads the current provider/model capability flags only to select tools. It does not log prompts, patches, file contents, credentials, auth headers, or provider responses.
 

package/extensions/index.ts

@@ -2,7 +2,7 @@ import { Container, Text } from "@earendil-works/pi-tui";
 import type { Component } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { reportInstallTelemetry } from "../src/install-telemetry.js";
-import { applyPatch, APPLY_PATCH_GRAMMAR, MAX_PATCH_BYTES } from "../src/apply-patch.js";
+import { applyPatch, APPLY_PATCH_GRAMMAR, MAX_PATCH_BYTES, secureFilesystemSupported } from "../src/apply-patch.js";
 import { createFreeformInputSchema, createOpenAILarkSampling, type OpenAIGrammarSampling } from "../src/grammar.js";
 import { supportsOpenAIGrammarTools } from "../src/model-support.js";
 import { formatApplyPatchCallText, formatApplyPatchResultText } from "../src/patch-preview.js";
@@ -94,7 +94,7 @@ export default function piCodexTools(pi: ExtensionAPI): void {
     if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
 
     const active = new Set(pi.getActiveTools());
-    if (supportsOpenAIGrammarTools(ctx.model)) {
+    if (supportsOpenAIGrammarTools(ctx.model) && secureFilesystemSupported()) {
       if (replacedToolsWasActive === undefined) {
         replacedToolsWasActive = {
           edit: active.has(EDIT),

package/native/addon.c

@@ -0,0 +1,161 @@
+// Native POSIX *at bindings for descriptor-relative filesystem walks.
+// Used by apply_patch on platforms without /proc/self/fd (macOS) to keep the
+// same TOCTOU-safe, no-follow directory walk that Linux gets via procfs.
+#include <node_api.h>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <string.h>
+
+static napi_value throw_errno(napi_env env, int err) {
+  const char *code = NULL;
+  switch (err) {
+    case ENOENT: code = "ENOENT"; break;
+    case EEXIST: code = "EEXIST"; break;
+    case ELOOP: code = "ELOOP"; break;
+    case ENOTDIR: code = "ENOTDIR"; break;
+    case EACCES: code = "EACCES"; break;
+    case EISDIR: code = "EISDIR"; break;
+    case ENAMETOOLONG: code = "ENAMETOOLONG"; break;
+    case EINVAL: code = "EINVAL"; break;
+  }
+  napi_value msg, errv;
+  if (napi_create_string_utf8(env, strerror(err), NAPI_AUTO_LENGTH, &msg) != napi_ok ||
+      napi_create_error(env, NULL, msg, &errv) != napi_ok) {
+    napi_throw_error(env, NULL, strerror(err));
+    return NULL;
+  }
+  if (code) {
+    napi_value codev;
+    napi_create_string_utf8(env, code, NAPI_AUTO_LENGTH, &codev);
+    napi_set_named_property(env, errv, "code", codev);
+  }
+  napi_value enov;
+  napi_create_int32(env, err, &enov);
+  napi_set_named_property(env, errv, "errno", enov);
+  napi_throw(env, errv);
+  return NULL;
+}
+
+static char *get_string(napi_env env, napi_value v) {
+  size_t len = 0;
+  if (napi_get_value_string_utf8(env, v, NULL, 0, &len) != napi_ok) return NULL;
+  char *buf = (char *)malloc(len + 1);
+  if (!buf) return NULL;
+  size_t written = 0;
+  if (napi_get_value_string_utf8(env, v, buf, len + 1, &written) != napi_ok) { free(buf); return NULL; }
+  return buf;
+}
+
+static napi_value OpenAt(napi_env env, napi_callback_info info) {
+  size_t argc = 4;
+  napi_value args[4];
+  if (napi_get_cb_info(env, info, &argc, args, NULL, NULL) != napi_ok || argc < 3) {
+    napi_throw_type_error(env, NULL, "openat(dirfd, path, flags[, mode]) requires (dirfd, path, flags)");
+    return NULL;
+  }
+  int dirfd = 0, flags = 0, mode = 0;
+  if (napi_get_value_int32(env, args[0], &dirfd) != napi_ok ||
+      napi_get_value_int32(env, args[2], &flags) != napi_ok) {
+    napi_throw_type_error(env, NULL, "dirfd and flags must be integers");
+    return NULL;
+  }
+  char *path = get_string(env, args[1]);
+  if (!path) { napi_throw_type_error(env, NULL, "path must be a string"); return NULL; }
+  if (argc >= 4 && napi_get_value_int32(env, args[3], &mode) != napi_ok) {
+    free(path); napi_throw_type_error(env, NULL, "mode must be an integer"); return NULL;
+  }
+  int fd = openat(dirfd, path, flags, (mode_t)mode);
+  int saved_errno = errno;
+  free(path);
+  if (fd < 0) return throw_errno(env, saved_errno);
+  napi_value result;
+  napi_create_int32(env, fd, &result);
+  return result;
+}
+
+static napi_value MkdirAt(napi_env env, napi_callback_info info) {
+  size_t argc = 3;
+  napi_value args[3];
+  if (napi_get_cb_info(env, info, &argc, args, NULL, NULL) != napi_ok || argc < 2) {
+    napi_throw_type_error(env, NULL, "mkdirat(dirfd, path[, mode]) requires (dirfd, path)");
+    return NULL;
+  }
+  int dirfd = 0, mode = 0777;
+  if (napi_get_value_int32(env, args[0], &dirfd) != napi_ok) { napi_throw_type_error(env, NULL, "dirfd must be an integer"); return NULL; }
+  char *path = get_string(env, args[1]);
+  if (!path) { napi_throw_type_error(env, NULL, "path must be a string"); return NULL; }
+  if (argc >= 3 && napi_get_value_int32(env, args[2], &mode) != napi_ok) { free(path); napi_throw_type_error(env, NULL, "mode must be an integer"); return NULL; }
+  int rc = mkdirat(dirfd, path, (mode_t)mode);
+  int saved_errno = errno;
+  free(path);
+  if (rc < 0) return throw_errno(env, saved_errno);
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+static napi_value UnlinkAt(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value args[2];
+  if (napi_get_cb_info(env, info, &argc, args, NULL, NULL) != napi_ok || argc < 2) {
+    napi_throw_type_error(env, NULL, "unlinkat(dirfd, path) requires (dirfd, path)");
+    return NULL;
+  }
+  int dirfd = 0;
+  if (napi_get_value_int32(env, args[0], &dirfd) != napi_ok) { napi_throw_type_error(env, NULL, "dirfd must be an integer"); return NULL; }
+  char *path = get_string(env, args[1]);
+  if (!path) { napi_throw_type_error(env, NULL, "path must be a string"); return NULL; }
+  int rc = unlinkat(dirfd, path, 0);
+  int saved_errno = errno;
+  free(path);
+  if (rc < 0) return throw_errno(env, saved_errno);
+  napi_value undef;
+  napi_get_undefined(env, &undef);
+  return undef;
+}
+
+static napi_value LstatAt(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value args[2];
+  if (napi_get_cb_info(env, info, &argc, args, NULL, NULL) != napi_ok || argc < 2) {
+    napi_throw_type_error(env, NULL, "lstatAt(dirfd, path) requires (dirfd, path)");
+    return NULL;
+  }
+  int dirfd = 0;
+  if (napi_get_value_int32(env, args[0], &dirfd) != napi_ok) {
+    napi_throw_type_error(env, NULL, "dirfd must be an integer");
+    return NULL;
+  }
+  char *path = get_string(env, args[1]);
+  if (!path) {
+    napi_throw_type_error(env, NULL, "path must be a string");
+    return NULL;
+  }
+  struct stat st;
+  int rc = fstatat(dirfd, path, &st, AT_SYMLINK_NOFOLLOW);
+  int saved_errno = errno;
+  free(path);
+  if (rc < 0) return throw_errno(env, saved_errno);
+  napi_value obj, v;
+  napi_create_object(env, &obj);
+  napi_get_boolean(env, S_ISREG(st.st_mode), &v); napi_set_named_property(env, obj, "isFile", v);
+  napi_get_boolean(env, S_ISDIR(st.st_mode), &v); napi_set_named_property(env, obj, "isDirectory", v);
+  napi_get_boolean(env, S_ISLNK(st.st_mode), &v); napi_set_named_property(env, obj, "isSymbolicLink", v);
+  return obj;
+}
+
+static napi_value Init(napi_env env, napi_value exports) {
+  const napi_property_descriptor props[] = {
+    { "openat", NULL, OpenAt, NULL, NULL, NULL, napi_default, NULL },
+    { "mkdirat", NULL, MkdirAt, NULL, NULL, NULL, napi_default, NULL },
+    { "unlinkat", NULL, UnlinkAt, NULL, NULL, NULL, napi_default, NULL },
+    { "lstatAt", NULL, LstatAt, NULL, NULL, NULL, napi_default, NULL },
+  };
+  napi_define_properties(env, exports, 4, props);
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-tools",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Codex-compatible apply_patch tooling for Pi's grammar-capable OpenAI models.",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,6 +35,8 @@
     "index.ts",
     "extensions",
     "src",
+    "native",
+    "prebuilds",
     "README.md",
     "NOTICE",
     "LICENSE",
@@ -43,10 +45,13 @@
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md"
   ],
+  "gypfile": false,
   "scripts": {
     "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test tests/*.test.mjs",
+    "build:native": "node-gyp configure build",
+    "prebuild:native": "prebuildify --napi --arch arm64 && prebuildify --napi --arch x64",
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
@@ -60,6 +65,7 @@
     "@earendil-works/pi-coding-agent": "^0.82.1",
     "@earendil-works/pi-tui": "^0.82.1",
     "@types/node": "^26.1.2",
+    "prebuildify": "^6.0.1",
     "tsx": "^4.23.1",
     "typebox": "^1.3.8",
     "typescript": "^7.0.2"
@@ -71,6 +77,7 @@
     "node": ">=20.6.0"
   },
   "dependencies": {
-    "@mocito/install-telemetry": "0.1.1"
+    "@mocito/install-telemetry": "0.1.1",
+    "node-gyp-build": "^4.8.4"
   }
 }

package/src/apply-patch.ts

@@ -1,9 +1,10 @@
 // Adapted from OpenAI Codex apply-patch grammar/parser behavior; see NOTICE.
-import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
-import type { FileHandle } from "node:fs/promises";
+import { constants, open as openCb, fstat as fstatCb, read as readCb, write as writeCb, close as closeCb, mkdir as mkdirCb, unlink as unlinkCb } from "node:fs";
+import type { Stats } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { getOpenAtBindings } from "./native.js";
 
 export const MAX_PATCH_BYTES = 1_048_576;
 export const MAX_PATCH_HUNKS = 1_000;
@@ -11,7 +12,74 @@ export const MAX_TARGET_FILE_BYTES = 64 * 1024 * 1024;
 
 const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
 const SECURE_FD_DIRECTORY = process.platform === "linux" ? "/proc/self/fd" : undefined;
-const SECURE_FILESYSTEM_SUPPORTED = SECURE_FD_DIRECTORY !== undefined && O_NOFOLLOW !== 0;
+const OPENAT_BINDINGS = getOpenAtBindings();
+const BASE_SECURE_FILESYSTEM_SUPPORTED =
+  (process.platform === "linux" && SECURE_FD_DIRECTORY !== undefined && O_NOFOLLOW !== 0) ||
+  (process.platform === "darwin" && OPENAT_BINDINGS !== null && O_NOFOLLOW !== 0);
+let secureFilesystemSupportedOverride: boolean | undefined;
+
+/** Whether apply_patch can safely execute against this platform's filesystem. */
+export function secureFilesystemSupported(): boolean {
+  return secureFilesystemSupportedOverride ?? BASE_SECURE_FILESYSTEM_SUPPORTED;
+}
+
+/** @internal Force the support flag so the activation path can be tested on any host platform. */
+export function setSecureFilesystemSupportedForTest(value: boolean | undefined): void {
+  secureFilesystemSupportedOverride = value;
+}
+
+const openFd = (path: string, flags: number, mode: number): Promise<number> =>
+  new Promise((resolveP, rejectP) => openCb(path, flags, mode, (error, fd) => (error ? rejectP(error) : resolveP(fd))));
+const fstatFd = (fd: number): Promise<Stats> =>
+  new Promise((resolveP, rejectP) => fstatCb(fd, (error, stats) => (error ? rejectP(error) : resolveP(stats))));
+const readFd = (fd: number, buffer: Buffer, offset: number, length: number, position: number | null): Promise<number> =>
+  new Promise((resolveP, rejectP) => readCb(fd, buffer, offset, length, position, (error, bytesRead) => (error ? rejectP(error) : resolveP(bytesRead))));
+const writeFd = (fd: number, buffer: Buffer, offset: number, length: number, position: number | null): Promise<number> =>
+  new Promise((resolveP, rejectP) => writeCb(fd, buffer, offset, length, position, (error, written) => (error ? rejectP(error) : resolveP(written))));
+const closeFd = (fd: number): Promise<void> =>
+  new Promise((resolveP, rejectP) => closeCb(fd, (error) => (error ? rejectP(error) : resolveP())));
+const mkdirPath = (path: string, mode: number): Promise<void> =>
+  new Promise((resolveP, rejectP) => mkdirCb(path, mode, (error) => (error ? rejectP(error) : resolveP())));
+const unlinkPath = (path: string): Promise<void> =>
+  new Promise((resolveP, rejectP) => unlinkCb(path, (error) => (error ? rejectP(error) : resolveP())));
+
+// Open `child` relative to a trusted open directory descriptor, never following the final component.
+async function openChildRelative(parentFd: number, child: string, flags: number, mode: number): Promise<number> {
+  if (OPENAT_BINDINGS) return OPENAT_BINDINGS.openat(parentFd, child, flags, mode);
+  return openFd(join(SECURE_FD_DIRECTORY as string, String(parentFd), child), flags, mode);
+}
+
+async function mkdirChildRelative(parentFd: number, child: string, mode: number): Promise<void> {
+  if (OPENAT_BINDINGS) {
+    OPENAT_BINDINGS.mkdirat(parentFd, child, mode);
+    return;
+  }
+  await mkdirPath(join(SECURE_FD_DIRECTORY as string, String(parentFd), child), mode);
+}
+
+async function unlinkChildRelative(parentFd: number, child: string): Promise<void> {
+  if (OPENAT_BINDINGS) {
+    OPENAT_BINDINGS.unlinkat(parentFd, child);
+    return;
+  }
+  await unlinkPath(join(SECURE_FD_DIRECTORY as string, String(parentFd), child));
+}
+
+// No-follow stat of `child` relative to a trusted descriptor, without opening it
+// (so unreadable files can still be inspected for symlink/directory rejection).
+async function lstatChildRelative(parentFd: number, child: string): Promise<{ isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }> {
+  if (OPENAT_BINDINGS) return OPENAT_BINDINGS.lstatAt(parentFd, child);
+  const stats = await lstat(join(SECURE_FD_DIRECTORY as string, String(parentFd), child));
+  return { isFile: stats.isFile(), isDirectory: stats.isDirectory(), isSymbolicLink: stats.isSymbolicLink() };
+}
+
+async function writeAllFd(fd: number, data: string): Promise<void> {
+  const buffer = Buffer.from(data, "utf8");
+  let written = 0;
+  while (written < buffer.length) {
+    written += await writeFd(fd, buffer, written, buffer.length - written, written);
+  }
+}
 const SECURE_DIRECTORY_FLAGS = constants.O_RDONLY | O_NOFOLLOW | (constants.O_DIRECTORY ?? 0) | (constants.O_NONBLOCK ?? 0);
 const SECURE_READ_FLAGS = constants.O_RDONLY | O_NOFOLLOW | (constants.O_NONBLOCK ?? 0);
 const SECURE_UPDATE_FLAGS = constants.O_WRONLY | O_NOFOLLOW | constants.O_TRUNC | (constants.O_NONBLOCK ?? 0);
@@ -238,22 +306,22 @@ export async function applyPatch(input: string, options: ApplyPatchOptions): Pro
   });
 
   return withMutationLocks(lockPaths, async () => {
-    const rootHandle = await openSecureRoot(root, options.signal);
+    const rootFd = await openSecureRoot(root, options.signal);
     try {
-      const operations = await planOperations(hunks, root, rootHandle, options.signal);
+      const operations = await planOperations(hunks, root, rootFd, options.signal);
       throwIfAborted(options.signal);
       // ponytail: preflight catches parse/match errors before writes; cross-process failures can still leave a partial multi-file patch.
       for (const operation of operations) {
         throwIfAborted(options.signal);
         if (operation.kind === "add") {
-          await writeSecureFile(rootHandle, root, operation.path, operation.content, true, options.signal);
+          await writeSecureFile(rootFd, root, operation.path, operation.content, true, options.signal);
         } else if (operation.kind === "delete") {
-          await removeSecureFile(rootHandle, root, operation.path, options.signal);
+          await removeSecureFile(rootFd, root, operation.path, options.signal);
         } else if (operation.moveTo) {
-          await writeSecureFile(rootHandle, root, operation.moveTo, operation.content, true, options.signal);
-          await removeSecureFile(rootHandle, root, operation.path, options.signal);
+          await writeSecureFile(rootFd, root, operation.moveTo, operation.content, true, options.signal);
+          await removeSecureFile(rootFd, root, operation.path, options.signal);
         } else {
-          await writeSecureFile(rootHandle, root, operation.path, operation.content, false, options.signal);
+          await writeSecureFile(rootFd, root, operation.path, operation.content, false, options.signal);
         }
       }
 
@@ -265,12 +333,12 @@ export async function applyPatch(input: string, options: ApplyPatchOptions): Pro
         })),
       };
     } finally {
-      await rootHandle.close();
+      await closeFd(rootFd);
     }
   });
 }
 
-async function planOperations(hunks: ApplyPatchHunk[], root: string, rootHandle: FileHandle, signal?: AbortSignal): Promise<PlannedOperation[]> {
+async function planOperations(hunks: ApplyPatchHunk[], root: string, rootFd: number, signal?: AbortSignal): Promise<PlannedOperation[]> {
   const operations: PlannedOperation[] = [];
   const virtualFiles = new Map<string, VirtualFile>();
 
@@ -290,7 +358,7 @@ async function planOperations(hunks: ApplyPatchHunk[], root: string, rootHandle:
 
   const getVirtualContent = async (absolute: string, file: VirtualFile): Promise<string> => {
     if (!file.exists || !file.isFile) throw new Error(`Cannot read non-file '${absolute}'.`);
-    if (file.content === undefined) file.content = await readSecureFile(rootHandle, root, absolute, signal);
+    if (file.content === undefined) file.content = await readSecureFile(rootFd, root, absolute, signal);
     return file.content;
   };
 
@@ -420,47 +488,42 @@ async function safePath(rawPath: string, root: string, signal?: AbortSignal): Pr
 }
 
 function requireSecureFilesystem(): void {
-  if (!SECURE_FILESYSTEM_SUPPORTED) {
+  if (!secureFilesystemSupported()) {
     throw new Error("apply_patch requires a POSIX filesystem with descriptor-based no-follow support.");
   }
 }
 
-function secureChildPath(parent: FileHandle, child: string): string {
-  if (!SECURE_FD_DIRECTORY) throw new Error("Secure filesystem operations are unavailable on this platform.");
-  return join(SECURE_FD_DIRECTORY, String(parent.fd), child);
-}
-
-async function openSecureRoot(root: string, signal?: AbortSignal): Promise<FileHandle> {
+async function openSecureRoot(root: string, signal?: AbortSignal): Promise<number> {
   requireSecureFilesystem();
-  let current = await open(sep, SECURE_DIRECTORY_FLAGS);
+  let current = await openFd(sep, SECURE_DIRECTORY_FLAGS, 0);
   try {
     for (const component of root.split(sep).filter(Boolean)) {
       throwIfAborted(signal);
       const next = await openSecureDirectoryChild(current, component);
-      await current.close();
+      await closeFd(current);
       current = next;
     }
     return current;
   } catch (error) {
-    await current.close().catch(() => undefined);
+    await closeFd(current).catch(() => undefined);
     throw error;
   }
 }
 
-async function openSecureDirectoryChild(parent: FileHandle, component: string): Promise<FileHandle> {
-  const handle = await open(secureChildPath(parent, component), SECURE_DIRECTORY_FLAGS);
+async function openSecureDirectoryChild(parentFd: number, component: string): Promise<number> {
+  const fd = await openChildRelative(parentFd, component, SECURE_DIRECTORY_FLAGS, 0);
   try {
-    if (!(await handle.stat()).isDirectory()) throw new Error(`Secure path component is not a directory: ${component}`);
-    return handle;
+    if (!(await fstatFd(fd)).isDirectory()) throw new Error(`Secure path component is not a directory: ${component}`);
+    return fd;
   } catch (error) {
-    await handle.close().catch(() => undefined);
+    await closeFd(fd).catch(() => undefined);
     throw error;
   }
 }
 
-type SecureParent = { handle: FileHandle; owned: boolean };
+type SecureParent = { handle: number; owned: boolean };
 
-async function openSecureParentDirectory(rootHandle: FileHandle, root: string, absolute: string, createParents: boolean, signal?: AbortSignal): Promise<SecureParent> {
+async function openSecureParentDirectory(rootFd: number, root: string, absolute: string, createParents: boolean, signal?: AbortSignal): Promise<SecureParent> {
   const parentPath = dirname(absolute);
   const relativeParent = relative(root, parentPath);
   const components = relativeParent ? relativeParent.split(sep) : [];
@@ -468,58 +531,58 @@ async function openSecureParentDirectory(rootHandle: FileHandle, root: string, a
     throw new Error(`Patch path must stay inside the current working directory: ${absolute}`);
   }
 
-  let current = rootHandle;
+  let current = rootFd;
   let owned = false;
   try {
     for (const component of components) {
       throwIfAborted(signal);
-      let next: FileHandle;
+      let next: number;
       try {
         next = await openSecureDirectoryChild(current, component);
       } catch (error) {
         if (!createParents || !isNoEntryError(error)) throw error;
         try {
-          await mkdir(secureChildPath(current, component));
+          await mkdirChildRelative(current, component, 0o777);
         } catch (mkdirError) {
           if (!isAlreadyExistsError(mkdirError)) throw mkdirError;
         }
         next = await openSecureDirectoryChild(current, component);
       }
-      if (owned) await current.close();
+      if (owned) await closeFd(current);
       current = next;
       owned = true;
     }
     return { handle: current, owned };
   } catch (error) {
-    if (owned) await current.close().catch(() => undefined);
+    if (owned) await closeFd(current).catch(() => undefined);
     throw error;
   }
 }
 
 async function withSecureFile<T>(
-  rootHandle: FileHandle,
+  rootFd: number,
   root: string,
   absolute: string,
   flags: number,
   createParents: boolean,
-  callback: (file: FileHandle, size: number) => Promise<T>,
+  callback: (fd: number, size: number) => Promise<T>,
   signal?: AbortSignal,
 ): Promise<T> {
-  const parent = await openSecureParentDirectory(rootHandle, root, absolute, createParents, signal);
-  let file: FileHandle | undefined;
+  const parent = await openSecureParentDirectory(rootFd, root, absolute, createParents, signal);
+  let fd: number | undefined;
   try {
-    file = await open(secureChildPath(parent.handle, basename(absolute)), flags, 0o666);
-    const stats = await file.stat();
+    fd = await openChildRelative(parent.handle, basename(absolute), flags, 0o666);
+    const stats = await fstatFd(fd);
     if (!stats.isFile()) throw new Error(`Patch target is not a regular file: ${absolute}`);
-    return await callback(file, stats.size);
+    return await callback(fd, stats.size);
   } finally {
-    await file?.close().catch(() => undefined);
-    if (parent.owned) await parent.handle.close().catch(() => undefined);
+    if (fd !== undefined) await closeFd(fd).catch(() => undefined);
+    if (parent.owned) await closeFd(parent.handle).catch(() => undefined);
   }
 }
 
-async function readSecureFile(rootHandle: FileHandle, root: string, absolute: string, signal?: AbortSignal): Promise<string> {
-  return withSecureFile(rootHandle, root, absolute, SECURE_READ_FLAGS, false, async (file, size) => {
+async function readSecureFile(rootFd: number, root: string, absolute: string, signal?: AbortSignal): Promise<string> {
+  return withSecureFile(rootFd, root, absolute, SECURE_READ_FLAGS, false, async (fd, size) => {
     if (size > MAX_TARGET_FILE_BYTES) {
       throw new Error(`Patch target exceeds the ${MAX_TARGET_FILE_BYTES}-byte limit: ${absolute}`);
     }
@@ -529,7 +592,7 @@ async function readSecureFile(rootHandle: FileHandle, root: string, absolute: st
     while (true) {
       throwIfAborted(signal);
       const buffer = Buffer.alloc(Math.min(FILE_READ_CHUNK_BYTES, MAX_TARGET_FILE_BYTES + 1 - total));
-      const { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+      const bytesRead = await readFd(fd, buffer, 0, buffer.length, null);
       if (bytesRead === 0) break;
       total += bytesRead;
       chunks.push(buffer.subarray(0, bytesRead));
@@ -541,23 +604,25 @@ async function readSecureFile(rootHandle: FileHandle, root: string, absolute: st
   }, signal);
 }
 
-async function writeSecureFile(rootHandle: FileHandle, root: string, absolute: string, content: string, createParents: boolean, signal?: AbortSignal): Promise<void> {
+async function writeSecureFile(rootFd: number, root: string, absolute: string, content: string, createParents: boolean, signal?: AbortSignal): Promise<void> {
   const flags = createParents ? SECURE_CREATE_FLAGS : SECURE_UPDATE_FLAGS;
-  await withSecureFile(rootHandle, root, absolute, flags, createParents, async (file) => {
-    await file.writeFile(content, "utf8");
+  await withSecureFile(rootFd, root, absolute, flags, createParents, async (fd) => {
+    await writeAllFd(fd, content);
   }, signal);
 }
 
-async function removeSecureFile(rootHandle: FileHandle, root: string, absolute: string, signal?: AbortSignal): Promise<void> {
-  const parent = await openSecureParentDirectory(rootHandle, root, absolute, false, signal);
+async function removeSecureFile(rootFd: number, root: string, absolute: string, signal?: AbortSignal): Promise<void> {
+  const parent = await openSecureParentDirectory(rootFd, root, absolute, false, signal);
   try {
-    const target = secureChildPath(parent.handle, basename(absolute));
-    const stats = await lstat(target);
-    if (stats.isSymbolicLink()) throw new Error(`Symlink paths are not allowed in apply_patch: ${absolute}`);
-    if (stats.isDirectory()) throw new Error(`Cannot delete directory '${absolute}'.`);
-    await unlink(target);
+    throwIfAborted(signal);
+    // No-follow stat without opening the target, so unreadable (mode-000) files can still be deleted;
+    // unlink only requires write permission on the parent directory, never on the file itself.
+    const stats = await lstatChildRelative(parent.handle, basename(absolute));
+    if (stats.isSymbolicLink) throw new Error(`Symlink paths are not allowed in apply_patch: ${absolute}`);
+    if (stats.isDirectory) throw new Error(`Cannot delete directory '${absolute}'.`);
+    await unlinkChildRelative(parent.handle, basename(absolute));
   } finally {
-    if (parent.owned) await parent.handle.close().catch(() => undefined);
+    if (parent.owned) await closeFd(parent.handle).catch(() => undefined);
   }
 }
 

package/src/native.ts

@@ -0,0 +1,40 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * POSIX *at bindings for descriptor-relative filesystem walks. macOS has no
+ * procfs, so the TOCTOU-safe walk used by apply_patch (open each directory
+ * component relative to a trusted parent fd with O_NOFOLLOW) needs openat /
+ * mkdirat / unlinkat. Node does not expose these, so a tiny N-API addon
+ * provides them on darwin. Linux keeps its /proc/self/fd path and never loads
+ * this binding.
+ */
+export interface OpenAtBindings {
+  openat(dirfd: number, path: string, flags: number, mode: number): number;
+  mkdirat(dirfd: number, path: string, mode: number): void;
+  unlinkat(dirfd: number, path: string): void;
+  lstatAt(dirfd: number, path: string): { isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean };
+}
+
+let cached: OpenAtBindings | null | undefined;
+
+/** Returns the native *at bindings on darwin, or null on any other platform / load failure. */
+export function getOpenAtBindings(): OpenAtBindings | null {
+  if (cached !== undefined) return cached;
+  if (process.platform !== "darwin") {
+    cached = null;
+    return null;
+  }
+  try {
+    const require = createRequire(import.meta.url);
+    const resolveBinding = require("node-gyp-build") as (dir: string) => unknown;
+    // native.ts lives in src/; the binding (build/ or prebuilds/) ships at the package root.
+    const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const addon = resolveBinding(packageRoot) as OpenAtBindings;
+    cached = typeof addon?.openat === "function" ? addon : null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}