Skip to content

Fix symlink path traversal and unsafe revert --clean deletions (v1.0.2) - #5

Merged
johanbeytell1 merged 2 commits into
mainfrom
arena/b7269fc5-tailclass
Nov 9, 2026
Merged

johanbeytell1 merged 2 commits into
mainfrom
arena/b7269fc5-tailclass

Conversation

@johanbeytell1

Copy link
Copy Markdown
Member

Summary

Security release v1.0.2. Fixes the two vulnerabilities reported during follow-up testing of the 1.0.1 hardening:

  1. Configured output paths could escape through directory symlinks (High). outputCss, dictionaryFile and manifestFile were confined by a lexical path.resolve() check only. A cloned repo containing e.g. assets -> ../../outside could make apply/list write — or revert --clean delete — files outside the project root.
  2. revert --clean could delete non-TailClass files (High). --clean unconditionally deleted whatever the configured CSS/manifest paths pointed at, including hand-written stylesheets, unrelated JSON, source files, and outside files reachable via a symlink.

What changed

Physical path confinement

  • New src/fs-safety.js: every existing component of an output path is lstated and resolved with realpath against the real project root. Symlinks that leave the root (or are broken) are rejected; writes use O_NOFOLLOW, re-validate after creating parent directories, and deletions only ever remove regular files.
  • src/config.js: resolveWritablePath() now defaults to treating an unspecified path source as untrusted, and gained writeResolvedFile() / unlinkResolvedFile() so all output writes and --clean deletions go through the checked resolver. validateOutputPath() applies the same physical check at config load time.
  • Covered: generated CSS, revert manifest, dictionary, reports, .tailclass-backup/, the auto-discovered dictionary, source rewrites and init. Explicit CLI paths outside the root are still honoured.

revert --clean ownership

  • Only files positively identified as TailClass output are deleted: the versioned generated CSS header, or (for --no-comments CSS) @apply rules matching an owned revert manifest. Manifests must carry TailClass markers and a plausible mappings record.
  • Scanned source files, foreign files, symlinks and directories are left untouched and reported via cleanupSkipped plus a stderr warning (also in --json mode). --force never relaxes this.
  • Generated manifests now include generator: "TailClass" and manifestPath, so clean can still find real output after a config change.
  • revertProject() returns cleanedFiles and cleanupSkipped.

Behavior change (documented explicitly)

  • An output path's final component must now be a regular file, not a symlink — even when the link points inside the project root, even with --force, and even for an explicit CLI path. 1.0.1 followed such links on write and unlinked them on --clean. Symlinked directories that resolve inside the root remain supported.
  • Migration: replace the symlink with a regular file, or point outputCss / dictionaryFile / manifestFile at the real file. Documented in CHANGELOG.md, README.md, SECURITY.md, the config JSON schema, types/index.d.ts, CLI --help and the runtime error itself (which no longer suggests the invalid --output workaround).

Version & docs

  • package.json and src/version.js → 1.0.2; changelog, security policy (new guarantees + supported-version table), README examples, schema descriptions, TS declarations, CLI help and release-workflow example updated.
  • No v1.0.2 tag was created, so the publish workflow has not been triggered.

Verification

  • npm run check → lint passes, 66/66 tests (16 new regression tests in test/path-safety.test.js: symlink escapes, inside-root symlink rejection, ownership checks, markerless CSS, scanned-source protection, CLI paths, version pinning).
  • npm run demo passes.
  • npm pack --dry-run produces tailclass-1.0.2.tgz and includes src/fs-safety.js.

Review notes

  • The public API gains two result fields (cleanedFiles, cleanupSkipped); existing callers are unaffected.
  • Config-derived paths that traverse symlinks out of the root now fail in resolveConfig (so even scan rejects them), matching the existing behavior for ../ traversal.

johanbeytell1 and others added 2 commits November 9, 2026 11:36
- Confine config-derived output paths physically via lstat/realpath against the real project root; reject symlinked output files and directory symlinks that escape the root; write with O_NOFOLLOW and re-validate after mkdir.
- revert --clean now deletes only files verified as TailClass output; foreign files, scanned sources, symlinks and directories are preserved and reported via cleanupSkipped/stderr.
- Add src/fs-safety.js, regression tests in test/path-safety.test.js, docs/schema/type updates, and bump version to 1.0.2.

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
- Explicitly distinguish allowed directory symlinks (inside root) from symlinked output files, which are now rejected even when the link points inside the root, even with --force or a CLI path.
- Clarify CHANGELOG, README, SECURITY.md, config schema, TS types and CLI --help; make runtime errors say how to migrate and stop suggesting --output for this case.
- Add regression tests for the inside-root symlink case and for --clean never unlinking a symlink.

Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
@johanbeytell1
johanbeytell1 merged commit 3907b29 into main Nov 9, 2026
3 checks passed
@johanbeytell1
johanbeytell1 deleted the arena/b7269fc5-tailclass branch November 9, 2026 11:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant