files: follow in-root symlinks via a kernel-faithful confined resolver

[Meirtz]

Why

agentix.files upload/download walked every path component with O_NOFOLLOW and refused any symlink. That is far stronger than the jail's actual invariant (the resolved target stays under $AGENTIX_UPLOAD_ROOT) and breaks legitimate filesystems: merged-usr images make /bin, /sbin, /lib symlinks to usr/*, and real repos contain symlinked sources. With the root widened to / there is nothing to escape, yet the refusal still fired.

What

The resolver now follows symlinks the way openat2(RESOLVE_IN_ROOT) does — escape is structurally impossible, not lexically checked:

• the root dir is opened once with O_NOFOLLOW and retained for the whole walk (never reopened by path), so a concurrent rename/replace of the root cannot redirect a later step outside the jail — a TOCTOU that an earlier reopen-per-restart draft was vulnerable to;
• symlink targets are pushed onto the walk queue as raw components, never lexically normalized: .. is applied by popping the open-dir stack (clamped at the root) against actually-resolved directories, so a target like inner/../victim.txt where inner -> dest/sub resolves to dest/victim.txt exactly as the kernel would, not to a lexically-wrong root file;
• absolute symlink targets re-anchor at the root (chroot semantics): a link to /etc/x reads <root>/etc/x and can never touch the host;
• a 40-hop cap (the kernel's own limit) turns cycles into PermissionError.

macOS reports ENOTDIR instead of ELOOP for the O_DIRECTORY case, so symlink detection arbitrates via readlink.

Tests

merged-usr relative links, nested link-to-link chains, ..-bearing targets (contained + escaping), absolute-target re-anchoring, a link resolving exactly to the root, and cycle refusal. Tests monkeypatch files.UPLOAD_ROOT rather than reloading the module — reload re-creates UploadResult and breaks class identity for the safepickle allowlist.

Reviewed by a second co-author (Codex, security lens) + adversarial pass. The HIGH findings — root-fd TOCTOU on restart and lexical-.. resolving the wrong file — drove the rewrite from the initial reopen-per-restart version to this retained-fd-stack resolver.

🤖 Generated with Claude Code