feat(nfs): handle-table bound, exclusive create, and set-group-ID inheritance

[pi0x]

Three items off .agents/roadmap.md, all of them NFS, plus the one rule that had
to leave src/nfs/ to be stated once (src/ownership.ts).

Bound the file handle table with an LRU (f01bf33)

Neither NFS version has a FORGET, so nothing on the wire ever tells the server
a client is done with a handle. Half of that was already closed — an entry whose
last path is detached is dropped — and what was left was one entry per path a
client currently has a name for, held for the life of the server however long ago
it looked. maxHandles caps that, least recently used first.

The decision behind it: the default is still no cap, which is what this
server has always done. Recency is stamped everywhere a handle is used —
decode(), at(), pathOf(), every bind/remap attach — so the entries a
client is working through are the last ones considered, and the LRU order is
#byId's own insertion order, so nothing can fall out of step with
#byPath/#byKey. Eviction is safe by construction: #nextId only counts up,
so a handle whose entry went away answers ESTALE, never somebody else's file.
But it is not free. It costs an NFSv3 client one round trip, and an NFSv4.1
client that had the file open rather more — v4/session.ts keys open and
lock state by entry id, so the re-lookup is a different file as far as share
reservations are concerned. That asymmetry is why the number is opt-in rather
than defaulted. The root is never a victim (PUTROOTFH/PUTPUBFH/MNT encode
it from a field, not from a lookup), and neither is the entry being bound.

Exclusive create on v3 CREATE and v4.1 OPEN (6615c3c)

CREATE with EXCLUSIVE answered NFS3ERR_NOTSUPP and OPEN with
EXCLUSIVE4/EXCLUSIVE4_1 answered NFS4ERR_INVAL, because there is nowhere in
FsDriver to commit a verifier to.

There does not have to be. What EXCLUSIVE actually asks for is that a
retransmission recognise its own creation, so the verifier lives in an
ExclusiveCreates table on the shared state (src/nfs/util.ts) — one table,
so a create over v3 and a retry over v4 are one server answering once (RFC 1813
§3.3.8, RFC 5661 §18.16.3). It is bounded twice: a 120 s window, because that is
how long the original request can still plausibly be in flight, and 256 entries,
oldest insertion evicted first. Both edges fail the same safe way — the retry
stops being recognised and gets EXIST, never a wrong file — and a restart
loses the table entirely, which the class doc states rather than implying
otherwise.

Same verifier returns the existing object, a different one is EXIST, and the
entry is dropped by REMOVE, by both sides of a RENAME, and by the SETATTR
that §3.3.8 treats as the client's commit. v3's arm carries no sattr3 so it
applies no attributes; EXCLUSIVE4_1's cva_attrs go through the same
#settableOrRefuse/#applyAttrs/attrset path UNCHECKED4 does.

Set-group-ID inheritance for new entries (dfc88ef)

A driver creates everything as the server process, so each session hands the
result to its caller afterwards. The group half of that was wrong: it gave every
new entry the caller's gid, where a set-group-ID parent means the entry takes the
parent's group and a new directory takes the bit as well.

The decision was to make that one rule rather than two session patches:
src/ownership.ts is a transcription of inode_init_owner() (fs/inode.c) —
the place the kernel makes this decision for every local filesystem and makes for
no userspace one — with POSIX mkdir(2)/open(2) declining to pick between the
two arms and inode(7) stating the choice. It also clears S_ISGID on a new
group-executable whose creator is in neither the effective nor the supplementary
group the AUTH_SYS credential carried, reading CAP_FSETID as uid 0, which is
all a userspace server can see of a remote caller's capabilities.

No new stat: v3 already read the parent for wcc_data (#preOp is split so
the stat can be kept) and v4 already read it for change_info4 and the NOTDIR
check. The only added driver call is the chmod a new directory needs, and it
runs after the lchown because chown(2) clears set-group-ID in the other
order. Rename is untouched — the rule is about creation. 9P needed nothing; its
client computes both halves (v9fs_get_fsgid_for_create()) and they arrive on
the wire, so its #claim comment now says that instead of claiming to match NFS
character for character.

Deliberately left open

All four are written into .agents/roadmap.md:

• A default for maxHandles. "It is opt-in because an eviction costs an
  NFSv4.1 client more than a re-LOOKUP: src/nfs/v4/session.ts keys open and
  lock state by entry id, so evicting a handle a client has open costs it an
  OPEN as well. Pinning entries with live v4 state — and only then picking a
  default — is what is left." A directly constructed Nfs3Session/Nfs4Session
  also builds its own table and ignores the option; every public path goes
  through the router, so that is the tests and the CLI only.
• suppattr_exclcreat (75) is still unadvertised in src/nfs/v4/attr.ts's
  SUPPORTED_ATTRS. "Exclusive create shipped, and its verifier lives beside the
  file rather than in an attribute, so the honest value is now the full settable
  set — the attribute's 'deliberately absent, it is the OPEN step's call' note
  predates the OPEN step having made it."
• Set-gid inheritance on the FUSE session. "FUSE is the gap, and
  #claim in src/fuse/session.ts says why it was not simply mirrored: the NFS
  sessions read the parent anyway (for wcc_data and change_info4) while
  nothing on the FUSE path does, so the rule would add an lstat to every create
  for every caller — including the daemon-is-the-caller case that currently costs
  no driver call at all — and the membership half needs FUSE_CREATE_SUPP_GROUP
  (7.38), which src/fuse/init.ts does not ask for. Both are decisions to take
  deliberately, not omissions."
• Per-call caller credentials in FsDriver: considered, and not the answer.
  Three things against it, and they compound: "node:fs/promises has no
  credential parameter and the POSIX way to get one — setfsuid(2)/setfsgid(2)
  — is per-thread state Node does not expose and the threadpool would scramble,
  so node-fs could never implement it and unstorage/S3 have no ownership to
  implement it with; the memory driver, the only one that could, enforces no
  permissions at all, so the sole observable effect of a credential inside it is
  the initial owner and group, which src/ownership.ts now gets right; and
  invariant 5 means every session must keep the lchown path anyway for drivers
  without the extension, so the whole surface buys one driver's atomicity at the
  price of two permanent code paths." What would reopen it is a driver that
  enforces permissions itself.

Testing

pnpm test is green — lint, typecheck, and the Tier-0/Tier-1 suites, 2940 tests.
New coverage lands in test/nfs/handles.test.ts (the LRU: recency stamping, root
and bound-entry exemption, ESTALE after eviction), test/nfs/v3/session.test.ts
and test/nfs/v4/session.test.ts (both exclusive-create arms, the same-verifier
replay, the drops on REMOVE/RENAME/SETATTR, and set-gid inheritance through
both sessions), test/nfs/session.test.ts and test/nfs/server.test.ts (the
shared table across versions), and test/index.test.ts (src/ownership.ts
directly).

The Tier-2 real-mount suites were not run. pnpm test:root,
pnpm test:mount, pnpm test:nfs:mount and pnpm test:pjdfstest need sudo and
were not executed for this branch, so nothing here has been exercised against a
real kernel client. The pjdfstest numbers in .agents/pjdfstest-results.md were
not re-measured either — the note there says so, and set-gid inheritance is not
something pjdfstest covers.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mountx	Ready	Preview	Jul 31, 2026 8:22pm