@homeflare/alchemy 0.23.0 → 0.24.0

package/src/release/binary-pins.ts

@@ -0,0 +1,95 @@
+/**
+ * `pinProblems` — everything wrong with a declaration's pins alone, as plain strings, checked
+ * before a plan resolves a directory or a host is asked anything. Split out of binary-form.ts
+ * 2026-09-23 to keep that file under the house's 250-line cap (it was 229, heading for ~250 once
+ * `archive.root` needed its own validation and JSDoc). binary-form.ts re-exports `pinProblems` and
+ * `MAX_ARCHIVE`, so nothing that imported them moves.
+ */
+import type { ReleaseArchive } from './binary-form.ts';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+export const MAX_ARCHIVE = 1 << 30;
+// ⛔ Strict on purpose: each is written into a URL or a path. GitHub's own owner and name alphabet.
+const REPO = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/;
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+// ★ ONLY WHAT THE READER HANDLES: a gzipped tar. A `.zip` or a bare binary is a new capability
+//   with its own walk-down, not a name this should accept and then fail to unpack.
+const TARBALL = /\.(tar\.gz|tgz)$/;
+
+/** A single path segment that cannot climb, hide or name the directory itself. */
+const segmentProblem = (what: string, value: string): string | undefined =>
+  !SEGMENT.test(value) || value === '.' || value === '..'
+    ? `${what} must be one path segment of letters, digits, '.', '_' or '-': ${JSON.stringify(value)}`
+    : undefined;
+
+/** Everything wrong with the pins alone — plain strings in any declaration, resolved or not. */
+export const pinProblems = (props: {
+  readonly archive?: Partial<ReleaseArchive>;
+  readonly member?: unknown;
+  readonly sha256?: unknown;
+  readonly name?: unknown;
+}): string[] => {
+  const archive = props.archive ?? {};
+  const found: string[] = [];
+  const text = (what: string, value: unknown): string | undefined => {
+    if (typeof value === 'string') return value;
+    found.push(`${what} is required, as a plain string`);
+    return undefined;
+  };
+  const repo = text('archive.repo', archive.repo);
+  // ⚠️ `owner/..` passes the alphabet, and a URL parser normalises it away: the request would go
+  //   to `github.com/releases/…`, somewhere nobody pinned. Refused by name.
+  const repoName = repo?.slice(repo.indexOf('/') + 1);
+  if (repo !== undefined && (!REPO.test(repo) || repoName === '.' || repoName === '..'))
+    found.push(`archive.repo must be "owner/name": ${JSON.stringify(repo)}`);
+  for (const [what, value] of [
+    ['archive.tag', archive.tag],
+    ['name', props.name],
+  ] as const) {
+    const given = text(what, value);
+    const problem = given === undefined ? undefined : segmentProblem(what, given);
+    if (problem !== undefined) found.push(problem);
+  }
+  const asset = text('archive.asset', archive.asset);
+  if (asset !== undefined) {
+    const problem = segmentProblem('archive.asset', asset);
+    if (problem !== undefined) found.push(problem);
+    else if (!TARBALL.test(asset))
+      found.push(`archive.asset must be a .tar.gz or .tgz: "${asset}"`);
+  }
+  // ★ ONE DECLARED DIRECTORY, NEVER DERIVED. Optional: most archives (Victoria, OpenBao) are flat.
+  //   Where given, it is the vendor's own wrapper (measured, not guessed — tar.ts's header comment)
+  //   and must be exactly one safe segment, the same alphabet as a tag or an asset name.
+  if (archive.root !== undefined) {
+    if (typeof archive.root !== 'string') {
+      found.push('archive.root must be a plain string when given');
+    } else {
+      const problem = segmentProblem('archive.root', archive.root);
+      if (problem !== undefined) found.push(problem);
+    }
+  }
+  // ⛔ THE SIZE IS ALLOCATED UP FRONT (download.ts fills one buffer of exactly this many bytes), so
+  //   a typo'd size is a memory bomb in the deploying process. vmutils, the largest archive pinned,
+  //   is 123.6 MB; a gibibyte is a ceiling nothing single-binary should reach.
+  const size = archive.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0 || size > MAX_ARCHIVE) {
+    found.push(`archive.size must be the asset's byte count, 1 to ${String(MAX_ARCHIVE)}`);
+  }
+  for (const [what, value] of [
+    ['archive.sha256', archive.sha256],
+    ['sha256', props.sha256],
+  ] as const) {
+    const given = text(what, value);
+    if (given !== undefined && !HEX64.test(given))
+      found.push(`${what} must be 64 lower-case hex digits`);
+  }
+  const member = text('member', props.member);
+  // ⛔ The tar reader refuses these entries anyway; asking for one is a mistake to name at plan.
+  if (
+    member !== undefined &&
+    (member === '' || member.startsWith('/') || member.split('/').includes('..'))
+  ) {
+    found.push(`member must be a relative name inside the archive: ${JSON.stringify(member)}`);
+  }
+  return found;
+};

package/src/release/binary-root.test.ts

@@ -0,0 +1,122 @@
+/**
+ * `Release.Binary` end to end, through Alchemy's own Plan and Apply (openbao/fake-stack.ts), for a
+ * synthetic archive shaped like the Prometheus family: every entry wrapped in one directory
+ * (tar.ts's header comment, measured 2026-09-23). `archive.root` installs it; the same declaration
+ * without `root` refuses, exactly as tar-root.test.ts shows at the reader alone.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { type HostRunner, hostRunnerLayer } from '../launchd/runner.ts';
+import { HostDirectory, HostDirectoryProvider } from '../linux/directory.ts';
+import { fakeLinuxHost } from '../linux/fake-linux-host.ts';
+import { fakeStack } from '../openbao/fake-stack.ts';
+import { releaseUrl } from './binary-form.ts';
+import { ReleaseBinary, makeReleaseBinaryProvider } from './binary.ts';
+import type { PinnedBinary } from './catalog.ts';
+import { bytesOf, gzip, tarOf } from './fake-release.ts';
+
+const ROOT = '/opt/example/bin';
+const DIR = `${ROOT}/alertmanager-0.33.1`;
+const WRAPPED = 'alertmanager-0.33.1.darwin-arm64';
+const BYTES = bytesOf('#!fake alertmanager 0.33.1\n');
+const ARCHIVE = gzip(
+  tarOf([
+    { name: `${WRAPPED}/`, type: '5' },
+    { bytes: BYTES, name: `${WRAPPED}/alertmanager` },
+  ]),
+);
+const ASSET = 'alertmanager-0.33.1.darwin-arm64.tar.gz';
+const REPO = 'prometheus/alertmanager';
+const TAG = 'v0.33.1';
+const URL = releaseUrl(REPO, TAG, ASSET);
+const PATH = `${DIR}/alertmanager`;
+
+/** The pinned props, with or without the declared root — everything else identical. */
+const pins = (root?: string): PinnedBinary => ({
+  archive: {
+    asset: ASSET,
+    repo: REPO,
+    sha256: sha256Hex(ARCHIVE),
+    size: ARCHIVE.length,
+    tag: TAG,
+    ...(root === undefined ? {} : { root }),
+  },
+  member: 'alertmanager',
+  name: 'alertmanager',
+  sha256: sha256Hex(BYTES),
+});
+
+/** One fake host and one fake server; `events` is every host write and request, in order. */
+const harness = () => {
+  // ★ SEED THE PARENT, NOT `DIR` ITSELF: `HostDirectory` below creates `DIR` fresh, as
+  //   plan.test.ts's harness does — a directory pre-seeded at the declared path would instead be
+  //   an adoption question, which is not what this file is testing.
+  const fake = fakeLinuxHost({ dirs: { [ROOT]: 0 }, euid: 0 });
+  const events: string[] = [];
+  const runner: HostRunner = {
+    ...fake.runner,
+    writeFileAtomic: (path, bytes, options) => {
+      events.push(`write ${path}`);
+      return fake.runner.writeFileAtomic(path, bytes, options);
+    },
+  };
+  const client = HttpClient.make((request, url) => {
+    events.push(`GET ${url.toString()}`);
+    const body = url.toString() === URL ? new Blob([ARCHIVE.slice()]) : null;
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, new Response(body, { status: body ? 200 : 404 })),
+    );
+  });
+  const providers = Layer.mergeAll(makeReleaseBinaryProvider(), HostDirectoryProvider()).pipe(
+    Layer.provide(
+      Layer.mergeAll(hostRunnerLayer(runner), Layer.succeed(HttpClient.HttpClient, client)),
+    ),
+  );
+  const stack = fakeStack(providers, {}, 'RootBinaryStack');
+  const declare = (binary: PinnedBinary) =>
+    Effect.gen(function* () {
+      const dir = yield* HostDirectory('alertmanager-dir', { mode: 0o755, path: DIR });
+      yield* ReleaseBinary('alertmanager', { ...binary, directory: dir.path });
+    });
+  return { declare, events, fake, stack };
+};
+
+describe('a directory-wrapped archive, declared with root', () => {
+  test('installs, reads back and re-hashes to the pinned member digest', async () => {
+    const h = harness();
+    const planned = await h.stack.deploy(h.declare(pins(WRAPPED)));
+    expect(planned).toEqual({ alertmanager: 'create', 'alertmanager-dir': 'create' });
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BYTES);
+    expect(sha256Hex(h.fake.files.get(PATH)?.bytes ?? new Uint8Array())).toBe(sha256Hex(BYTES));
+  });
+
+  test('a second deploy of the same declaration reads the file back; nothing downloaded again', async () => {
+    const h = harness();
+    await h.stack.deploy(h.declare(pins(WRAPPED)));
+    h.events.length = 0;
+    await h.stack.deploy(h.declare(pins(WRAPPED)));
+    expect(h.events).toEqual([]);
+    expect(h.fake.files.get(PATH)?.bytes).toEqual(BYTES);
+  });
+
+  test('the same declaration without root refuses, writes nothing, leaves no file at the path', async () => {
+    const h = harness();
+    await expect(h.stack.deploy(h.declare(pins()))).rejects.toThrow('is a directory');
+    expect(h.fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('pinProblems refuses an unsafe root, before any host write or network call', () => {
+  test.each(['', '.', '..', 'a/b', './a'])('root %j', async (root) => {
+    const h = harness();
+    await expect(h.stack.deploy(h.declare(pins(root)))).rejects.toThrow('archive.root must be');
+    expect(h.fake.files.has(PATH)).toBe(false);
+    // ★ mkdir is not instrumented (it goes through `exec`, not `writeFileAtomic`), so HostDirectory
+    //   creating DIR is expected here; nothing about ReleaseBinary's own pin is.
+    expect(h.events.filter((e) => e.startsWith('GET') || e.startsWith('write'))).toEqual([]);
+  });
+});

package/src/release/catalog.ts

@@ -191,9 +191,17 @@ export const catalogBinary = (catalog: ReleaseCatalog, request: CatalogRequest):
       message: `Release.Binary ${request.binary}: ${problems.join('; ')}. Nothing was fetched.`,
     });
   }
-  const { asset, repo, sha256: archiveSha256, size, tag } = archive;
+  const { asset, repo, root, sha256: archiveSha256, size, tag } = archive;
   return {
-    archive: { asset, repo, sha256: archiveSha256, size, tag },
+    // ⚠️ exactOptionalPropertyTypes: a conditional spread, never `root: undefined` spelled out.
+    archive: {
+      asset,
+      repo,
+      sha256: archiveSha256,
+      size,
+      tag,
+      ...(root === undefined ? {} : { root }),
+    },
     member,
     name: request.binary,
     sha256,

package/src/release/tar-root.test.ts

@@ -0,0 +1,114 @@
+/**
+ * `tarReader(wanted, root)` — the declared-root mode measured against the Prometheus-family shape
+ * (tar.ts's header comment, 2026-09-23): one directory entry wraps every other entry, stripped
+ * before a name is matched, listed or checked for a duplicate. Everything tar.test.ts already
+ * refuses keeps refusing; this file is only what `root` adds or changes.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bytesOf, tarOf } from './fake-release.ts';
+import { ArchiveRefused } from './refused.ts';
+import { tarReader } from './tar.ts';
+
+const ROOT = 'alertmanager-0.33.1.darwin-arm64';
+const wrapper = { name: `${ROOT}/`, type: '5' } as const;
+const binary = { bytes: bytesOf('#!binary\n'), name: `${ROOT}/alertmanager` } as const;
+
+const read = (tar: Uint8Array, wanted: readonly string[], root?: string) => {
+  const reader = tarReader(new Set(wanted), root);
+  reader.push(tar);
+  return reader.finish();
+};
+
+const refusal = (run: () => unknown): string => {
+  try {
+    run();
+  } catch (cause) {
+    expect(cause).toBeInstanceOf(ArchiveRefused);
+    return (cause as ArchiveRefused).message;
+  }
+  throw new Error('expected a refusal');
+};
+
+describe('a declared root strips exactly one leading directory', () => {
+  test('the member comes back under its stripped name; the root entry is not one of the names', () => {
+    const tar = tarOf([wrapper, binary]);
+    const { members, names } = read(tar, ['alertmanager'], ROOT);
+    expect(new TextDecoder().decode(members.get('alertmanager'))).toBe('#!binary\n');
+    expect(names).toEqual(['alertmanager']);
+  });
+
+  test('a sibling regular file under root is listed, stripped, but not fetched unless asked for', () => {
+    const notice = { bytes: bytesOf('legal text'), name: `${ROOT}/NOTICE` };
+    const { members, names } = read(tarOf([wrapper, binary, notice]), ['alertmanager'], ROOT);
+    expect(names).toEqual(['alertmanager', 'NOTICE']);
+    expect(members.has('NOTICE')).toBe(false);
+  });
+
+  test('THE SAME ARCHIVE, root omitted: still refused "is a directory" — origin/main\'s behaviour', () => {
+    const tar = tarOf([wrapper, binary]);
+    expect(refusal(() => read(tar, ['alertmanager']))).toContain('is a directory');
+  });
+
+  test('a root declared but never present in the archive is refused', () => {
+    expect(refusal(() => read(tarOf([binary]), ['alertmanager'], ROOT))).toContain('never appears');
+  });
+
+  // 🔴 ADVERSARIAL REVIEW, 2026-09-23 (before merge): a stripped name was never re-checked by
+  //   `nameProblem`, so `<root>//x` — not absolute as a whole raw name, but stripping to `/x` —
+  //   parsed to completion as a second, distinct, un-refused entry `/x` beside `x`. Fixed in
+  //   tar.ts by running `nameProblem` on the STRIPPED name too, not only the raw one.
+  test('stripping cannot uncover an absolute name the reader would otherwise refuse', () => {
+    // `<root>//alertmanager` is not absolute AS A WHOLE NAME, so it passes nameProblem before
+    // stripping; only after `<root>/` is removed does it become the absolute name `/alertmanager`.
+    const evil = { bytes: bytesOf('evil'), name: `${ROOT}//alertmanager` };
+    expect(refusal(() => read(tarOf([wrapper, binary, evil]), ['alertmanager'], ROOT))).toContain(
+      'strips to "/alertmanager"',
+    );
+  });
+});
+
+describe('everything a declared root still refuses, whole archive', () => {
+  test.each([
+    ['a second directory entry (the root, twice)', [wrapper, wrapper, binary], 'appearing twice'],
+    [
+      'an entry named <root>-evil/x: a segment match, not a string prefix',
+      [wrapper, binary, { name: `${ROOT}-evil/x` }],
+      'outside the declared root',
+    ],
+    [
+      'a regular file at archive top level beside root',
+      [wrapper, binary, { name: 'README' }],
+      'outside the declared root',
+    ],
+    ['<root>/../x climbs out through the root', [wrapper, { name: `${ROOT}/../x` }], 'climbs out'],
+    [
+      'a PAX x header inside root',
+      [wrapper, binary, { name: `${ROOT}/PaxHeader`, type: 'x' }],
+      'PAX extended',
+    ],
+    [
+      'a GNU L header inside root',
+      [wrapper, binary, { name: `${ROOT}/@LongLink`, type: 'L' }],
+      'GNU long-name',
+    ],
+    ['a symlink inside root', [wrapper, binary, { name: `${ROOT}/link`, type: '2' }], 'a symlink'],
+    [
+      'the root entry with size > 0',
+      [{ ...wrapper, bytes: bytesOf('x') }, binary],
+      'not an empty directory',
+    ],
+    [
+      'the root entry as typeflag 1 (a hard link), not a directory',
+      [{ name: `${ROOT}/`, type: '1' }],
+      'not an empty directory',
+    ],
+    [
+      'the root entry as typeflag 2 (a symlink), not a directory',
+      [{ name: `${ROOT}/`, type: '2' }],
+      'not an empty directory',
+    ],
+    ['a duplicate name after stripping', [wrapper, binary, binary], 'appears twice'],
+  ] as const)('%s', (_, entries, message) => {
+    expect(refusal(() => read(tarOf(entries), ['alertmanager'], ROOT))).toContain(message);
+  });
+});

package/src/release/tar.ts

@@ -15,10 +15,25 @@
  *   non-zero bytes after the end marker; an archive that stops before it.
  * ★ GNU LONG NAMES ('L', 'K') AND PAX HEADERS ('x', 'g') ARE REFUSED, NOT INTERPRETED. Each renames
  *   the entry after it: a reader that honours them must get them exactly right to match exactly,
- *   and one that skips them matches under the wrong name. The four pinned archives use neither
- *   (measured 2026-09-22 with `tar -tvzf` on each: every entry a root-level regular file with a
- *   short name), so refusing costs nothing today, and a vendor format change becomes a refusal that
- *   says what changed instead of a silent mis-read.
+ *   and one that skips them matches under the wrong name. Refusing costs nothing for an archive
+ *   that carries neither, and a vendor format change becomes a refusal that says what changed
+ *   instead of a silent mis-read.
+ * ★ AN OPTIONAL `root`: ONE DECLARED LEADING DIRECTORY, STRIPPED, NEVER GUESSED. Measured
+ *   2026-09-23: `gh api repos/<o>/<r>/releases/tags/<tag>` for each asset URL and digest, the
+ *   archive downloaded into a scratch directory (never executed), re-hashed against GitHub's
+ *   `digest`, then read by THIS reader (a driver script importing `tarReader`) both before and
+ *   after this change — refused whole either way without `root`, and, with it, parsed to
+ *   completion: `alertmanager-0.33.1.darwin-arm64.tar.gz` (37,247,168 B),
+ *   `blackbox_exporter-0.28.0.darwin-arm64.tar.gz` (15,705,022 B),
+ *   `node_exporter-1.12.1.darwin-arm64.tar.gz` (5,368,643 B) and
+ *   `postgres_exporter-0.20.1.darwin-arm64.tar.gz` (10,072,235 B) each recompute to GitHub's own
+ *   `digest`, and each wraps every entry in exactly one directory (typeflag '5', size 0, first)
+ *   named `<binary>-<version>.darwin-arm64/`, holding only root-level regular files (the binary,
+ *   `LICENSE`, `NOTICE`, and for alertmanager also `amtool` and `alertmanager.yml`) — no PAX or
+ *   GNU long-name entries, so this reader's refusal of both stays exactly as costly as before.
+ *   Without `root`, EVERY refusal above still holds byte-for-byte: a directory entry — the wrapper
+ *   included — is refused the same way it always was (docs/release-binary-catalogs.md,
+ *   docs/release-binary-upstream.md gap 11).
  */
 import { ArchiveRefused } from './refused.ts';
 
@@ -101,8 +116,15 @@ export type TarContents = {
   readonly names: readonly string[];
 };
 
-/** A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw. */
-export const tarReader = (wanted: ReadonlySet<string>) => {
+/**
+ * A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw.
+ *
+ * @param root When given, exactly one typeflag-'5' entry named `<root>/`, size 0, is accepted and
+ *   dropped rather than refused as a directory; every OTHER entry name must begin with the SEGMENT
+ *   `<root>/` (a `<root>-evil/x` sibling does not) and is reported, matched and kept under that
+ *   prefix stripped off. Omitted, behaviour is byte-identical to a reader with no root at all.
+ */
+export const tarReader = (wanted: ReadonlySet<string>, root?: string) => {
   const header = new Uint8Array(BLOCK);
   const members = new Map<string, Uint8Array>();
   const names: string[] = [];
@@ -114,6 +136,8 @@ export const tarReader = (wanted: ReadonlySet<string>) => {
   let zeros = 0;
   let name = '';
   let parts: Uint8Array[] | undefined;
+  let rootSeen = false;
+  const rootPrefix = root === undefined ? undefined : `${root}/`;
 
   const endEntry = () => {
     if (parts !== undefined) members.set(name, concatBytes(parts));
@@ -134,18 +158,57 @@ export const tarReader = (wanted: ReadonlySet<string>) => {
     if (!posix && magic !== 'ustar  \u0000')
       throw refuse('an entry header is neither ustar nor GNU');
     const prefix = posix ? text(header, 345, 155) : '';
-    name = prefix === '' ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
-    const problem = nameProblem(name);
-    if (problem !== undefined) throw refuse(`entry ${JSON.stringify(name)} ${problem}`);
+    const rawName = prefix === '' ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
+    const problem = nameProblem(rawName);
+    if (problem !== undefined) throw refuse(`entry ${JSON.stringify(rawName)} ${problem}`);
+    // ★ THE DECLARED ROOT IS RECOGNISED BEFORE THE GENERAL TYPE CHECK, and only by exact name: a
+    //   directory entry under any other name — nested, or a second copy of the root itself — still
+    //   falls through to that check below and is refused as a directory, same as with no root.
+    if (rootPrefix !== undefined && rawName === rootPrefix) {
+      if (rootSeen) {
+        // ⚠️ Whatever type THIS entry is, its name is already taken: refused for reusing the
+        //   root's name, not necessarily for being a second directory (it need not be one).
+        throw refuse(`entry "${rawName}" reuses the declared root's own name, appearing twice`);
+      }
+      const type = String.fromCharCode(header[156] ?? 0);
+      const size = octal(header, 124, 12, `entry "${rawName}"'s size`);
+      if (type !== '5' || size !== 0) {
+        throw refuse(`entry "${rawName}" is the declared root but is not an empty directory`);
+      }
+      rootSeen = true;
+      phase = 'header';
+      return;
+    }
+    let stripped = rawName;
+    if (rootPrefix !== undefined) {
+      if (!rawName.startsWith(rootPrefix)) {
+        throw refuse(`entry "${rawName}" is outside the declared root "${rootPrefix}"`);
+      }
+      // ⛔ THE STRIPPED NAME GETS THE SAME SAFETY CHECK AS A RAW ONE. `rawName` already passed
+      //   `nameProblem` above, but stripping a prefix can UNCOVER a `/` or `..` that was hiding
+      //   past it: `<root>//x` is not absolute as a whole name, but strips to `/x`, which is —
+      //   the exact thing this reader refuses a plain (rootless) archive for. MEASURED: without
+      //   this check, `<root>//x` beside `<root>/x` parsed to completion as two distinct entries,
+      //   `x` and `/x`, neither refused. `stripped` can never be empty here: the one raw name that
+      //   strips to '' is `rootPrefix` itself, handled above.
+      stripped = rawName.slice(rootPrefix.length);
+      const strippedProblem = nameProblem(stripped);
+      if (strippedProblem !== undefined) {
+        throw refuse(
+          `entry "${rawName}" strips to ${JSON.stringify(stripped)}, which ${strippedProblem}`,
+        );
+      }
+    }
+    name = stripped;
     const type = String.fromCharCode(header[156] ?? 0);
     if (type !== '0' && type !== '\0') {
       const kind = KINDS[type] ?? `of unknown type ${JSON.stringify(type)}`;
-      throw refuse(`entry "${name}" is ${kind}; only regular files are accepted`);
+      throw refuse(`entry "${rawName}" is ${kind}; only regular files are accepted`);
     }
-    if (seen.has(name)) throw refuse(`entry "${name}" appears twice`);
+    if (seen.has(name)) throw refuse(`entry "${rawName}" appears twice`);
     seen.add(name);
     names.push(name);
-    remaining = octal(header, 124, 12, `entry "${name}"'s size`);
+    remaining = octal(header, 124, 12, `entry "${rawName}"'s size`);
     padding = (BLOCK - (remaining % BLOCK)) % BLOCK;
     parts = wanted.has(name) ? [] : undefined;
     phase = 'data';
@@ -188,6 +251,9 @@ export const tarReader = (wanted: ReadonlySet<string>) => {
 
   const finish = (): TarContents => {
     if (phase !== 'end') throw refuse('the archive stops before its end-of-archive marker');
+    if (rootPrefix !== undefined && !rootSeen) {
+      throw refuse(`the declared root "${rootPrefix}" never appears in the archive`);
+    }
     return { members, names };
   };