feat(client): symlink-refusing filesystem primitives

[XieX]

Stacked PR 2 of 7 — merge bottom-up into xie/agent-skills-feature-ac9ac7.

1. feat(client): Agent Skills value types #29 — value types
2. feat(client): symlink-refusing filesystem primitives #30 — symlink-refusing filesystem primitives ← you are here
3. feat(client): Agent Skills store seam, verification, and accessors #31 — store seam, verification, accessors
4. test(client): integrity verification and the accessor telemetry sweep #32 — integrity + telemetry tests
5. feat(client): writeSkills materialization and the abuse matrix #33 — writeSkills + abuse matrix
6. test(client): the rest of the writeSkills suite #34 — remaining writeSkills tests
7. docs(client): document Agent Skills #35 — docs

Each PR targets the one below it, so GitHub already shows only this PR's own diff.

---

Second of seven. The filesystem primitives the skills materialization layer is built on, landed separately because they know nothing about skills and can be reviewed without any of it. Nothing is exported from the package root — this is internal machinery.

What's here

• atomicWrite creates its temp file exclusively (O_EXCL) in the target's own directory, so the rename is same-filesystem and can't be redirected through a staging area an attacker controls. It fsyncs the file, renames at mode 0644, then fsyncs the directory.
• openDirectoryNoFollow opens with O_NOFOLLOW | O_DIRECTORY, so a symlinked directory is refused by the kernel rather than by a check that could be raced.
• unlinkNoFollow is the single managed-file delete.

Both destructive calls route through the fsOps record so exactly those two operations, and nothing else, are interceptable from a test.

The write primitives take data: Uint8Array rather than Buffer (a Buffer is a Uint8Array, so this is a pure widening): skill content is opaque bytes end to end, and the layer that writes it should not demand a Node-specific subtype.

The TOCTOU limitation, stated plainly

Node exposes no *at() family — no renameat, unlinkat, or openat, and no rename on FileHandle — so a destructive operation cannot be addressed relative to a pinned directory descriptor. SUPPORTS_DIR_FD is a real feature probe of that family, and it is false here.

What narrows the window instead is a (dev, ino) re-check against the pinned handle immediately before each destructive step, on top of the O_NOFOLLOW opens and the exclusive same-directory temp file. That does not close the window. An attacker who already has write permission on the managed root can still win the race. The two swap-race cases that would prove otherwise are skipped off the same probe the implementation gates on, and written out in full so they become live the moment the probe flips.

This is recorded at SUPPORTS_DIR_FD rather than papered over.

Why the (dev, ino) re-check is tested here

On this runtime it is the whole defense against a directory swapped between validation and a path-based rename or unlink — and it is invisible from the layer above. It could be deleted outright with every higher-level test still green. So it's staged here at the primitive layer: pin the handle, swap the directory underneath it, invoke the primitive.

The checks here are also deliberately redundant with the ones the materialization layer will apply — a symlinked skill directory gets refused twice. Exercising each layer on its own is what keeps that redundancy from rotting into a single point of failure.

Verification

Client package 342 → 355 tests. typecheck and biome clean.

🤖 Generated with Claude Code

---

Note

Overview
Adds internal safe-fs helpers the skills materialization stack will use: atomicWrite / atomicWriteIn (exclusive same-directory temps, fsync, rename at 0644), openDirectoryNoFollow / openOrCreateDirectory (O_NOFOLLOW, symlink-aware mkdir), and unlinkNoFollow. Destructive rename / unlink go through an fsOps seam for tests; writes accept Uint8Array.

SUPPORTS_DIR_FD probes Node for descriptor-relative *at() APIs (currently false) and documents the remaining TOCTOU gap. assertUnswapped re-checks (dev, ino) on the pinned directory handle immediately before each destructive step.

safe-fs.test.ts covers open flags, O_EXCL retry on temp collisions (mocked open), cleanup, and staged directory-swap races for write and unlink.

^{Reviewed by Cursor Bugbot for commit 3db4993. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3db4993. Configure here.}