doc: more clarity in security warning

isaacs · isaacs · commit 35a1ffe73eb4 · 2026-03-17T11:57:57.000-07:00
diff --git a/README.md b/README.md
@@ -32,19 +32,38 @@ implementation. (Note that most of these are disabled if
   is set, or the extraction is run as root.
 - File and directory modes in the archive are ignored, unless
   the `chmod: true` option is set.
-
-**However**, care must still be taken when dealing with data from
-unknown sources, especially when extracting files, with this or
-any library, no matter how hardened it may be.
+- A path-reservation system is used to ensure that even when
+  multiple entries are being extracted in parallel, subsequent
+  entries with the same filename will not interfere with one
+  another (for example, exchanging a file with a symbolic link
+  while it is being written to).
+- Unicode characters in path names are fully normalized, to
+  prevent evading these protections with unicode equivalences.
+
+It is frankly unlikely that any tar implementation in JavaScript
+is going to be as secure as this one, unless a similar amount of
+work is put into it, putting it to the test over many years of
+intensive use and scrutiny. You can vibe-code a tar extractor in
+an afternoon, but you'll regret it.
+
+> [!WARNING]
+>
+> **However**, all that being said, _care must still be taken_
+> when dealing with data from unknown sources, especially when
+> extracting files, with this or any library, no matter how
+> hardened it may be. It is _your_ responsibility to use this
+> library safely.
 
 1. **NEVER** extract tarball data into a folder that could be
    potentially controlled by an unknown actor. A clever attacker
    can swap out the target of an extracted file with a symbolic
    link to some location of their choosing, resulting in writing
    files outside the target folder. There is no reasonable way to
    harden against this category of attack, and security reports
-   about it will be closed. TOCTOU exposure is unavoidable when
-   creating files based on entries in an archive file.
+   about it will be closed.
+   [TOCTOU](https://cwe.mitre.org/data/definitions/367.html)
+   exposure is unavoidable when creating files based on entries
+   in an archive file.
 2. If you are unpacking tarballs that may come from an unknown
    source, it is **highly recommended** that you use a filter
    function that rejects all hardlinks and symbolic links. Link
diff --git a/src/unpack.ts b/src/unpack.ts
@@ -303,7 +303,7 @@ export class Unpack extends Parser {
         // tar paths, not a filesystem.
         const entryDir = path.posix.dirname(entry.path)
         const resolved = path.posix.normalize(
-          path.posix.join(entryDir, parts.join('/'))
+          path.posix.join(entryDir, parts.join('/')),
         )
         // If the resolved path escapes (starts with ..), reject it
         if (resolved.startsWith('../') || resolved === '..') {
diff --git a/test/ghsa-8qq5-rm4j-mr97.ts b/test/ghsa-8qq5-rm4j-mr97.ts
@@ -14,8 +14,11 @@ const absoluteWithDotDot = '/../a/target'
 const secretLinkpath = resolve(t.testdirName, 'secret.txt')
 
 t.formatSnapshot = (o: unknown): unknown =>
-  typeof o === 'string' ? o.replace(
-    /^ENOENT: no such file or directory, link .*? -> .*?$/, 'ENOENT: no such file or directory, link')
+  typeof o === 'string' ?
+    o.replace(
+      /^ENOENT: no such file or directory, link .*? -> .*?$/,
+      'ENOENT: no such file or directory, link',
+    )
   : Array.isArray(o) ? o.map(o => t.formatSnapshot?.(o))
   : o
 

Original file line number	Diff line number	Diff line change
`@@ -303,7 +303,7 @@ export class Unpack extends Parser {`
`303`	`303`	`// tar paths, not a filesystem.`
`304`	`304`	`const entryDir = path.posix.dirname(entry.path)`
`305`	`305`	`const resolved = path.posix.normalize(`
`306`		`- path.posix.join(entryDir, parts.join('/'))`
	`306`	`+ path.posix.join(entryDir, parts.join('/')),`
`307`	`307`	`)`
`308`	`308`	`// If the resolved path escapes (starts with ..), reject it`
`309`	`309`	`if (resolved.startsWith('../') \|\| resolved === '..') {`