dofs: resolving through a symlink with a relative target throws EINVAL instead of resolving relative to the link's directory

[rajpreetcodes]

Describe the bug

@cloudflare/dofs stores relative symlink targets verbatim, as documented, but any path resolution that traverses such a link throws EINVAL "Invalid path (must be absolute)" instead of resolving the target relative to the link's directory.

The doc comments promise the opposite: packages/dofs/src/fs/symlink.ts:9-11 and packages/dofs/src/fs/filesystem.ts:122-124 both say "The target is stored verbatim; it can be relative or absolute and is allowed to dangle. resolveInode follows it transparently."

The cause: resolveParts (packages/dofs/src/fs/resolve.ts:229) follows a link by feeding the stored target straight into canonicalizePath, and canonicalizePath (packages/dofs/src/path.ts:15-17) throws for anything not starting with /.

Creation and readlink succeed, so the landmine is armed at create time and detonates on first traversal. The sync layer replays container-side symlink entries verbatim (packages/dofs/src/sync/apply.ts:286, :405), so an ordinary ln -s foo bar inside the container (or any node_modules/.bin/* entry) imports cleanly and then breaks every stat/readFile/traversal through the link on the host side.

A dangling relative link is also mapped to the wrong error code: stat on it throws EINVAL where POSIX requires ENOENT, which breaks callers doing ENOENT-tolerant probing.

Expected behavior

Per POSIX path_resolution(7) and the package's own doc comments: a relative target resolves against the directory containing the link. stat("/dir/link") with link -> target resolves /dir/target. A dangling relative target surfaces as ENOENT, not EINVAL.

Steps to reproduce

Add this test to packages/dofs (uses the existing withDB harness from src/fs/with-db.ts) and run npm test --workspace @cloudflare/dofs -- <file>:

mkdir(db, "/dir", {}, () => 0);
await writeFile(db, "/dir/target", "hello", {}, () => 0);
symlink(db, "target", "/dir/link", () => 0); // stored fine, readlink returns "target"

stat(db, "/dir/link");                 // POSIX: resolves /dir/target (file, size 5)
await readFile(db, "/dir/link", "utf8"); // POSIX: "hello"

Actual output:

WorkspaceFsError: Invalid path (must be absolute): target
 ❯ canonicalizePath src/path.ts:16:11
 ❯ resolveParts src/fs/resolve.ts:229:41
 ❯ resolveInode src/fs/resolve.ts:103:12
 ❯ statShared src/fs/stat.ts:57:16

readFile rejects with the same error. And for the dangling case, symlink(db, "nowhere", "/dangling") then stat(db, "/dangling"):

AssertionError: expected 'EINVAL' to be 'ENOENT'

Proposed fix

In the symlink branch of resolveParts (resolve.ts:223-243): when link_target does not start with /, resolve it against the already-consumed parent segments ([...parts.slice(0, i), ...targetParts]) before canonicalizing, clamping .. at root per POSIX instead of throwing. Any target that still fails to canonicalize should surface as a dangling link (return null -> ENOENT), never EINVAL. The CTE fast path (resolve.ts:101-106) already falls back to the loop for any symlink, so the loop is the single place to fix. Tests worth adding: target, ./target, ../sibling/target, dangling relative target.

Environment

• cloudflare/computer at 76d9e75 (current main), local checkout
• npm test --workspace @cloudflare/dofs baseline: 436/436 pass before adding the repro
• Node v22.18.0, npm 11.8.0, Windows 11 (bug is platform-independent; it is pure SQLite/TS path logic)

[3x3xX3N0N]

Confirmed at 76d9e75, with a patch and failing-first tests if useful.

Root cause. resolveParts feeds the stored link_target straight into canonicalizePath at packages/dofs/src/fs/resolve.ts:229, and that function's absolute-path precondition (packages/dofs/src/path.ts:15-17) throws for anything not starting with /. The precondition is correct for user input and wrong for link contents, which POSIX explicitly allows to be relative.

resolve.ts:228 is the only consumer of link_target outside the schema and SELECT lists, so it is the single fix site. The gate at :223 (!isFinal || followFinal) is why readlink and lstat still work — only a follow-resolve detonates.

Fix adds a linkTargetParts(target, baseParts) helper that joins a relative target onto the segments consumed so far, drops ., and clamps .. at root (path_resolution(7): root's .. is root). Absolute targets still restart at root. canonicalizePath is deliberately untouched — its contract is right for the user-input surface and path.test.ts pins it.

One behavior change worth flagging: a target that names nothing now returns null rather than throwing, so a dangling relative link reads as a miss. stat.ts:57-60 maps that to ENOENT, which is what stat(2) specifies — EINVAL is not among its errors for this condition. If anything depended on EINVAL as a "malformed link" signal it would need updating; I found no such caller.

Six tests added covering bare relative, ./-prefixed, ../, ..-clamped-at-root, dangling-as-miss, and a self-referential target still raising ELOOP (the follows budget is unchanged, so the cap still fires at 40). All six fail at this sha with EINVAL. Full dofs suite: 442 passing.

Branch: https://github.com/3x3xX3N0N/computer/tree/fix/dofs-relative-symlink-targets — not opening a PR, per CONTRIBUTING.md.

Related: this helper is also what #55's fix needs for relative targets, so that one stacks on this branch. I also hit a third case while here — a symlink as an intermediate component fails ENOTDIR — filed separately as #65 since it is a different function and a separable fix.