Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ If applicable, paste terminal output or screenshots to help explain your problem
- OS: [e.g. Windows, macOS, Ubuntu]
- OS version: [e.g. Windows 11 (x64)]
- Node.js: [e.g. v22.11.0]
- TailClass version: [e.g. 1.0.0]
- TailClass version: [e.g. 1.0.2]
- Tailwind CSS version: [e.g. v3.4 / v4.0]
- Framework (if relevant): [e.g. Plain HTML, React/Next.js, Vue, Svelte, Astro]

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Publish Package 📦 to npm (Trusted Publishing OIDC)

# Triggered by pushing a release tag (e.g. `git push origin v1.0.1`).
# Triggered by pushing a release tag (e.g. `git push origin v1.0.2`).
# The tag must be created on a commit that is already on `main`, otherwise the
# `build_and_test` job fails before anything is published.
on:
Expand Down
72 changes: 72 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,78 @@ All notable changes to **TailClass** are documented here. The format loosely
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.2] — 2026-11-09

Security release. Fixes two escape hatches found during follow-up testing of the
1.0.1 hardening. Upgrading is recommended for anyone running TailClass against
repositories they did not author (including CI jobs on pull requests).

### Security

- **Symlink path traversal (High).** `outputCss`, `dictionaryFile` and
`manifestFile` were confined by a lexical `path.resolve()` check only. A
repository containing a directory symlink (for example `assets -> ../../.ssh`)
could therefore make `apply`/`list` write — or `revert --clean` delete — files
outside the project root even though the configured string never left it.
Config-derived paths are now checked component by component with
`lstat`/`realpath` against the **real** project root; a TailClass output file
may not be a symlink, and symlinks that resolve outside the root are rejected
before any write or deletion. Writes use `O_NOFOLLOW`, re-validate after
creating parent directories, and never follow a symlink for the final
component. Backups under `.tailclass-backup/` and the auto-discovered
dictionary are covered as well. Symlinked **directories** whose real path
stays inside the root keep working.
- **`revert --clean` arbitrary deletion (High).** `--clean` used to delete
whatever `outputCss`/`manifestFile` pointed at, without verifying ownership —
a hand-written stylesheet, an unrelated JSON file, or a file outside the root
reachable through a symlink. It now removes only files positively identified
as TailClass output (the generated header, or `@apply` rules matching an owned
manifest), and never a scanned source file, symlink or directory. Unowned
files are left in place and reported through `cleanupSkipped` plus a stderr
warning. `--force` never relaxes this rule.

### Added

- `src/fs-safety.js` — realpath-based confinement plus `writeFileNoFollow()` and
`unlinkRegularFile()` helpers.
- `writeResolvedFile()` / `unlinkResolvedFile()` in `src/config.js`: every output
write and every `--clean` deletion goes through the checked resolver.
- Generated manifests now carry `generator: "TailClass"` and `manifestPath`, so
`--clean` can still locate the files TailClass owns after a config change.
- `revertProject()` returns `cleanedFiles` and `cleanupSkipped`.
- Tests: `test/path-safety.test.js` (symlink escapes, ownership checks,
markerless `--no-comments` CSS, scanned-source protection, explicit CLI paths).

### Changed

- **Behavior change (symlinked output files).** In 1.0.1 a symlink at an output
path (for example `tailclass.css -> src/styles/generated.css`) was followed:
`apply`/`list` wrote through it and `revert --clean` removed the link. The
final component of every output path must now be a **regular file**. A
symlinked output file is rejected **even when its target is inside the
project root**, even with `--force`, and even when the path was supplied on the
command line; `--clean` also never deletes a symlink, wherever it points.
TailClass fails with `Refusing to write ... the target is a symlink ...`.
To migrate, replace the link with a regular file, or point `outputCss` /
`dictionaryFile` / `manifestFile` at the real file. Symlinked *directories*
in the middle of a path are unaffected as long as they resolve inside the
root (for example `outputCss: "styles/generated.css"` with
`styles -> ./src/styles`).
- `revert --clean` reports the files it removed and warns on stderr about any
file it deliberately left untouched.
- The error for a symlinked output file now says explicitly that the target must
be a regular file and how to migrate; it no longer suggests `--output`, which
is also rejected for symlinked output files. `--help` carries the same note.
- Configuration schema, README and SECURITY.md document that config-supplied
paths may not traverse symlinks and that `--clean` only deletes owned files.

### Fixed

- `apply` no longer reads the auto-discovered dictionary through an unchecked
path, and `--backup` writes are confined to the project root.
- `init` and source rewrites also refuse to follow a symlink at the final path
component.

## [1.0.1] — 2026-11-09

Security & robustness hardening. All items are covered by regression tests. Upgrading from
Expand Down
26 changes: 20 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Don't want automatic names on certain patterns? Run **Class List Mode** (`tailcl
**Centralized `tailclass.css` (edit once to restyle everywhere):**

```css
/* Generated by TailClass v1.0.1 — https://github.com/Infinitode/TailClass */
/* Generated by TailClass v1.0.2 — https://github.com/Infinitode/TailClass */
/* Centralized Tailwind component classes. Edit rules here to update styles site-wide. */

@layer components {
Expand Down Expand Up @@ -188,7 +188,7 @@ This prints a full breakdown in your terminal and generates **`tailclass.map.jso
```json
{
"$schema": "https://raw.githubusercontent.com/Infinitode/TailClass/main/schema/tailclass.map.schema.json",
"version": "1.0.1",
"version": "1.0.2",
"summary": {
"filesScanned": 12,
"filesWithClasses": 11,
Expand Down Expand Up @@ -312,8 +312,22 @@ untrusted input:

- `outputCss`, `dictionaryFile` and `manifestFile` **must stay inside the project root**
when they come from the config file (use `-o`/`--dict` on the command line for
deliberate out-of-root targets). `apply` additionally refuses to overwrite a scanned
source file, or a stylesheet/manifest that it does not own, unless `--force` is used.
deliberate out-of-root targets). This is a **physical** check: every existing path
component is resolved with `lstat`/`realpath` against the real project root, so a
directory symlink cannot redirect a write outside the project. Symlinked
*directories* that resolve inside the root still work. `apply` additionally refuses
to overwrite a scanned source file, or a stylesheet/manifest that it does not own,
unless `--force` is used.
- **Behavior change in v1.0.2:** an output path's final component must be a regular
file, **not a symlink** — even when the link points to a file inside the project
root, even with `--force`, and even for an explicit CLI path. 1.0.1 wrote through
such links; 1.0.2 fails with `Refusing to write ... the target is a symlink ...`,
and `revert --clean` never deletes a symlink. Replace the link with a regular file
or point `outputCss`/`dictionaryFile`/`manifestFile` at the real file. Intermediate
directory symlinks are unaffected.
- `revert --clean` only deletes files TailClass can verify it generated; a foreign
stylesheet, an unrelated JSON file, a scanned source file or a symlink is left
untouched and reported as a warning. `--force` does not override this.
- Invalid values fail loudly with the offending key (`Invalid exclude[1]: expected a
string, received null`); unknown keys are reported as warnings on stderr.
- Class tokens containing `;`, `{`, `}` or comment terminators are never emitted into
Expand Down Expand Up @@ -360,7 +374,7 @@ tailclass <command> [directory] [options]
| `--strict-dict` | Only extract patterns explicitly present in `--dict`. |
| `-d, --dry-run` | Preview edits and generated CSS without writing to disk. |
| `--backup` | Back up original modified files into `.tailclass-backup/`. |
| `--force` | Overwrite a stylesheet/manifest that does not look like TailClass output. |
| `--force` | Overwrite a stylesheet/manifest that does not look like TailClass output on `apply`. Never permits `--clean` to delete foreign files. |
| `-a, --all` | Include non-repeated / 1-off patterns in `list` mode. |
| `--report <file>` | Export Markdown (`.md`) or CSV (`.csv`) audit report in `list` mode. |
| `--format <mode>` | CSS format: `tailwind-v3` (default), `tailwind-v4`, or `plain`. |
Expand All @@ -377,7 +391,7 @@ tailclass <command> [directory] [options]
| `--include-classes <globs>` | Restrict extraction to matching utility globs. |
| `--ignore-tags <tags>` | Comma-separated HTML/JSX tags to ignore. |
| `--only-tags <tags>` | Restrict auto-classing to specific HTML/JSX tags. |
| `--clean` | Remove `tailclass.css` and `.tailclass-manifest.json` after `revert`. |
| `--clean` | After `revert`, remove only the stylesheet/manifest TailClass generated (foreign files are kept with a warning). |
| `--json` | Output structured JSON for CI pipelines and editor integrations. |

---
Expand Down
24 changes: 22 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,27 @@ repository you clone.
configuration file must resolve inside the scanned project root; paths that escape it
are rejected before anything is written or deleted. Paths supplied explicitly on the
command line (`--output`, `--dict`, `--report`) are honoured as-is.
- **Physical path confinement.** The root check is not merely lexical (`../`):
every existing component of an output path is `lstat`ed and resolved with
`realpath` against the real project root. A directory symlink planted in a cloned
repository can no longer redirect a write, read, backup or `revert --clean`
deletion outside the project. Writes use `O_NOFOLLOW` and re-validate after
creating parent directories. Symlinked *directories* whose real path stays inside
the root are still allowed.
- **Output files must be regular files (behavior change in 1.0.2).** The final
component of any output path may not be a symlink, even if the link points to a
file inside the root, even with `--force`, and even for an explicit CLI path;
`revert --clean` likewise never unlinks a symlink. 1.0.1 followed such links.
Point the output at the real file instead. This prevents a symlink from being
used to clobber, read or delete a file TailClass did not intend to touch.
- **No clobbering.** `apply` refuses to overwrite a scanned source file, or a
stylesheet/manifest that does not look like TailClass output, unless `--force` is
given.
- **No arbitrary deletion.** `revert --clean` deletes only regular files TailClass
can positively identify as its own (generated CSS header, or `@apply` rules
matching an owned revert manifest). Foreign stylesheets, foreign JSON files,
scanned source files, symlinks and directories are left untouched and reported
via `cleanupSkipped`/stderr. `--force` does not override this.
- **CSS payload validation.** Class tokens containing `;`, `{`, `}`, control characters
or comment terminators are kept inline on the element and never emitted into
`@apply`; selectors, comments and dictionary metadata are validated on output.
Expand All @@ -28,7 +46,8 @@ repository you clone.

| Version | Supported |
|---------|-----------|
| 1.0.1+ | ✅ |
| 1.0.2+ | ✅ |
| 1.0.1 | ❌ superseded — upgrade for the v1.0.2 symlink / `--clean` fixes |
| 1.0.0 | ❌ superseded — upgrade for the v1.0.1 security fixes |
| < 1.0 | ❌ |

Expand All @@ -54,7 +73,8 @@ window to ship a fix before any public disclosure.

In scope:

- arbitrary file overwrite or path traversal outside the target project root caused by crafted configuration or dictionary files;
- arbitrary file overwrite, deletion or path traversal outside the target project root caused by crafted configuration, dictionary or manifest files — including symlink-based traversal;
- deletion of non-TailClass files by `revert --clean`;
- catastrophic backtracking (ReDoS) or denial of service in the markup scanner, glob matcher, or Tailwind token parser;
- CSS injection or source corruption triggered by unsanitized dictionary values;
- supply-chain issues in the repository's build or release workflows.
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "tailclass",
"version": "1.0.1",
"version": "1.0.2",
"description": "An open-source Tailwind CSS auto-classer that scans sites for repeated utility layouts, assigns smart semantic component names, supports custom mapping dictionaries, and generates a centralized stylesheet.",
"keywords": [
"tailwindcss",
Expand Down
6 changes: 3 additions & 3 deletions schema/tailclass.config.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,17 @@
"outputCss": {
"type": "string",
"default": "tailclass.css",
"description": "Output path for the generated centralized Tailwind CSS file. Must stay inside the scanned project root when set from a configuration file."
"description": "Output path for the generated centralized Tailwind CSS file. Must stay inside the scanned project root when set from a configuration file, including when path components are symlinks. The target must be a regular file, not a symlink (even a symlink pointing inside the root); symlinked directories that resolve inside the root are allowed."
},
"dictionaryFile": {
"type": "string",
"default": "tailclass.map.json",
"description": "Path for Class List Mode dictionary output and lookup. Must stay inside the scanned project root when set from a configuration file."
"description": "Path for Class List Mode dictionary output and lookup. Must stay inside the scanned project root when set from a configuration file, including when path components are symlinks. The target must be a regular file, not a symlink (even a symlink pointing inside the root); symlinked directories that resolve inside the root are allowed."
},
"manifestFile": {
"type": "string",
"default": ".tailclass-manifest.json",
"description": "Path for the revert manifest generated during apply. Must stay inside the scanned project root when set from a configuration file."
"description": "Path for the revert manifest generated during apply. Must stay inside the scanned project root when set from a configuration file, including when path components are symlinks. The target must be a regular file, not a symlink (even a symlink pointing inside the root); symlinked directories that resolve inside the root are allowed. revert --clean only deletes manifests TailClass can verify it generated and never deletes a symlink."
},
"cssFormat": {
"type": "string",
Expand Down
27 changes: 24 additions & 3 deletions src/cli.js
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ function formatHelpText(c) {
` --strict-dict Only extract patterns explicitly listed in --dict`,
` -d, --dry-run Preview CSS & file changes without touching disk`,
` --backup Save original modified files under .tailclass-backup/`,
` --force Overwrite a stylesheet/manifest TailClass does not own`,
` --force Overwrite a non-TailClass stylesheet/manifest on "apply"`,
` -a, --all Include 1-off / non-repeated patterns in "list" mode`,
` --report <file> Also export a .md or .csv report in "list" mode`,
` --format <mode> CSS output format: tailwind-v3 | tailwind-v4 | plain`,
Expand All @@ -304,11 +304,15 @@ function formatHelpText(c) {
` --include-classes <globs> Only extract utilities matching these globs`,
` --ignore-tags <tags> HTML/JSX tags to skip (e.g. "svg,code")`,
` --only-tags <tags> Only auto-class specific tags (e.g. "nav,button,div")`,
` --clean Delete tailclass.css and manifest after "revert"`,
` --clean After "revert", delete only TailClass-owned output files`,
` --json Emit machine-readable JSON output`,
` -h, --help Display this help message`,
` -v, --version Display version number`,
"",
`${c.bold("NOTE")}`,
` Output paths must be regular files: a symlinked output file is rejected even`,
` when the link points inside the project (v1.0.2). Directory symlinks are OK.`,
"",
`${c.bold("EXAMPLES")}`,
` tailclass scan ./src`,
` tailclass list ./src --report class-report.md`,
Expand Down Expand Up @@ -673,6 +677,13 @@ function runCli(argv, io = {}) {
force: Boolean(flags.force),
});
printConfigWarnings(writeErr, c, res.config);
// Surface skipped deletions on stderr in every mode, including `--json`
// (where stdout must stay machine-readable).
if (flags.clean && !res.dryRun) {
for (const note of res.cleanupSkipped || []) {
writeErr(c.yellow(`Warning: ${note}. --clean only removes files TailClass owns.`));
}
}

if (flags.json) {
write(JSON.stringify(res, null, 2));
Expand All @@ -687,7 +698,17 @@ function runCli(argv, io = {}) {
)} file(s).`
);
if (flags.clean && !res.dryRun) {
write(`${c.green("✔")} Removed centralized stylesheet and manifest.`);
const removed = res.cleanedFiles || [];
const skipped = res.cleanupSkipped || [];
if (removed.length === 2 && skipped.length === 0) {
write(`${c.green("✔")} Removed centralized stylesheet and manifest.`);
} else if (removed.length > 0) {
write(
`${c.green("✔")} Removed ${removed.length} TailClass-generated file${
removed.length === 1 ? "" : "s"
} (${removed.map((f) => path.basename(f)).join(", ")}).`
);
}
}
return 0;
}
Expand Down
Loading
Loading