@checkstack/script-packages-backend 0.2.0

package/src/blob-hash.ts

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import type { ManifestEntry } from "@checkstack/script-packages-common";
+
+/**
+ * Content hashing + verification for distributed blobs.
+ *
+ * A package's distributable blob is our gzip-tar of its Bun cache entry, NOT
+ * the upstream npm tarball — so the SRI `integrity` key (which hashes the
+ * npm tarball) does NOT cover the transported bytes. To detect corruption or
+ * tampering in transit (shared blob store on core, HTTP/WS on satellites) we
+ * additionally carry `blobSha256` (sha-256 of the blob) on each manifest
+ * entry and verify it before extracting.
+ */
+
+/** Bytes as they arrive at the hash boundary from any blob source. */
+export type BlobBytes = Uint8Array | ArrayBuffer;
+
+/**
+ * Normalize blob bytes to a `Uint8Array` at the consume boundary.
+ *
+ * Blob sources differ in what view they hand back: the central resolver and
+ * the Postgres codec yield a `Uint8Array`, but `Bun.S3File.arrayBuffer()` (and
+ * any `Response.arrayBuffer()` transport) yields a raw `ArrayBuffer`. Node's
+ * `crypto.Hash.update()` rejects a bare `ArrayBuffer`
+ * ("Received an instance of ArrayBuffer"), so we wrap it in a `Uint8Array`
+ * view here. A `Uint8Array` view over the same bytes hashes identically to the
+ * underlying buffer, so this never changes a computed content hash.
+ */
+export function toUint8Array(bytes: BlobBytes): Uint8Array {
+  return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+}
+
+/** SHA-256 (hex) of a blob's bytes. */
+export function blobSha256(bytes: BlobBytes): string {
+  return createHash("sha256").update(toUint8Array(bytes)).digest("hex");
+}
+
+/**
+ * Verify `bytes` against a manifest entry's `blobSha256`. Returns `ok: true`
+ * when the hash matches OR the entry predates the field (backward-safe: no
+ * recorded hash means nothing to verify against). Returns `ok: false` with
+ * the expected/actual hashes on a mismatch so callers can error clearly and
+ * refuse to materialize the blob.
+ */
+export function verifyBlobSha256({
+  entry,
+  bytes,
+}: {
+  entry: Pick<ManifestEntry, "blobSha256">;
+  bytes: BlobBytes;
+}): { ok: true } | { ok: false; expected: string; actual: string } {
+  if (!entry.blobSha256) return { ok: true };
+  const actual = blobSha256(bytes);
+  if (actual === entry.blobSha256) return { ok: true };
+  return { ok: false, expected: entry.blobSha256, actual };
+}

package/src/blob-store-registry.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import type { BlobStore } from "./blob-store";
+import { createBlobStoreRegistry } from "./blob-store-registry";
+
+function memStore(id: string, seed: Record<string, string> = {}): BlobStore {
+  const map = new Map<string, Uint8Array>(
+    Object.entries(seed).map(([k, v]) => [k, new TextEncoder().encode(v)]),
+  );
+  return {
+    id,
+    async put({ integrity, bytes }) {
+      map.set(integrity, bytes);
+    },
+    async get({ integrity }) {
+      return map.get(integrity);
+    },
+    async has({ integrity }) {
+      return map.has(integrity);
+    },
+    async delete({ integrity }) {
+      map.delete(integrity);
+    },
+    async list() {
+      return [...map.keys()];
+    },
+  };
+}
+
+describe("BlobStoreRegistry", () => {
+  test("registers and resolves stores by id", () => {
+    const reg = createBlobStoreRegistry();
+    reg.register(memStore("postgres"));
+    reg.register(memStore("s3"));
+    expect(reg.ids().sort()).toEqual(["postgres", "s3"]);
+    expect(reg.has("s3")).toBe(true);
+    expect(reg.get("postgres").id).toBe("postgres");
+  });
+
+  test("throws a helpful error for an unregistered backend", () => {
+    const reg = createBlobStoreRegistry();
+    reg.register(memStore("postgres"));
+    expect(() => reg.get("s3")).toThrow(/not registered.*postgres/i);
+  });
+
+  test("reads from the active backend when present", async () => {
+    const reg = createBlobStoreRegistry();
+    reg.register(memStore("postgres", { "sha-1": "from-pg" }));
+    reg.register(memStore("s3", { "sha-1": "from-s3" }));
+    const res = await reg.readWithFallback({
+      integrity: "sha-1",
+      activeBackendId: "s3",
+    });
+    expect(res?.servedBy).toBe("s3");
+    expect(new TextDecoder().decode(res?.bytes)).toBe("from-s3");
+  });
+
+  test("falls back to another backend when the active one lacks the blob", async () => {
+    const reg = createBlobStoreRegistry();
+    reg.register(memStore("postgres", { "sha-2": "only-in-pg" }));
+    reg.register(memStore("s3"));
+    const res = await reg.readWithFallback({
+      integrity: "sha-2",
+      activeBackendId: "s3",
+    });
+    expect(res?.servedBy).toBe("postgres");
+    expect(new TextDecoder().decode(res?.bytes)).toBe("only-in-pg");
+  });
+
+  test("returns undefined when no backend has the blob", async () => {
+    const reg = createBlobStoreRegistry();
+    reg.register(memStore("postgres"));
+    const res = await reg.readWithFallback({
+      integrity: "missing",
+      activeBackendId: "postgres",
+    });
+    expect(res).toBeUndefined();
+  });
+});

package/src/blob-store-registry.ts

@@ -0,0 +1,75 @@
+import type { BlobStore } from "./blob-store";
+
+/**
+ * Collects every registered {@link BlobStore} (one per store plugin) and
+ * resolves the active one by id. Also offers a read-with-fallback used
+ * during a storage migration: when the active backend doesn't yet hold a
+ * blob, fall back to the other registered backends so script execution
+ * never breaks mid-migration.
+ */
+export interface BlobStoreRegistry {
+  register(store: BlobStore): void;
+  /** All registered store ids (for the admin backend selector). */
+  ids(): string[];
+  has(id: string): boolean;
+  /** Resolve a specific store by id. Throws if not registered. */
+  get(id: string): BlobStore;
+  /**
+   * Read a blob from `activeBackendId`, falling back across the other
+   * registered backends if the active one lacks it. Returns the bytes +
+   * the id of the backend that served them, or undefined if none have it.
+   */
+  readWithFallback(input: {
+    integrity: string;
+    activeBackendId: string;
+  }): Promise<{ bytes: Uint8Array; servedBy: string } | undefined>;
+}
+
+export function createBlobStoreRegistry(): BlobStoreRegistry {
+  const stores = new Map<string, BlobStore>();
+
+  return {
+    register(store) {
+      stores.set(store.id, store);
+    },
+
+    ids() {
+      return [...stores.keys()];
+    },
+
+    has(id) {
+      return stores.has(id);
+    },
+
+    get(id) {
+      const store = stores.get(id);
+      if (!store) {
+        throw new Error(
+          `Blob store backend "${id}" is not registered. Available: ${
+            [...stores.keys()].join(", ") || "(none)"
+          }`,
+        );
+      }
+      return store;
+    },
+
+    async readWithFallback({ integrity, activeBackendId }) {
+      const active = stores.get(activeBackendId);
+      if (active) {
+        const bytes = await active.get({ integrity });
+        if (bytes !== undefined) {
+          return { bytes, servedBy: activeBackendId };
+        }
+      }
+      // Fallback across the rest (migration in flight, partial state).
+      for (const [id, store] of stores) {
+        if (id === activeBackendId) continue;
+        const bytes = await store.get({ integrity });
+        if (bytes !== undefined) {
+          return { bytes, servedBy: id };
+        }
+      }
+      return;
+    },
+  };
+}

package/src/blob-store.ts

@@ -0,0 +1,51 @@
+import { createExtensionPoint } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+
+/**
+ * Pluggable, content-addressed blob persistence for script-package
+ * artifacts. Blobs are keyed by their integrity hash (the npm tarball /
+ * Bun-cache entry per `name@version`), so the integrity is the stable
+ * identity across backends - only the locator differs.
+ *
+ * Two built-ins ship as plugins: `script-packages-store-postgres` (the
+ * default, Postgres large-objects, zero extra infra) and
+ * `script-packages-store-s3` (preferred when configured). Adding a third
+ * later is just another plugin implementing this interface; no schema
+ * change.
+ *
+ * Implementations MUST be content-addressed and idempotent: `put` of an
+ * already-present integrity is a no-op (or overwrite with identical bytes).
+ */
+export interface BlobStore {
+  /** Stable backend id recorded in `script_package_blob.backend`. */
+  readonly id: string;
+
+  /** Store the (already-compressed) bytes for `integrity`. Idempotent. */
+  put(input: { integrity: string; bytes: Uint8Array }): Promise<void>;
+
+  /** Fetch the bytes for `integrity`, or undefined if this backend lacks it. */
+  get(input: { integrity: string }): Promise<Uint8Array | undefined>;
+
+  /** Whether this backend holds `integrity`. */
+  has(input: { integrity: string }): Promise<boolean>;
+
+  /** Delete the blob for `integrity` (GC / post-migration cleanup). Idempotent. */
+  delete(input: { integrity: string }): Promise<void>;
+
+  /** Every integrity this backend currently holds (for migration / GC). */
+  list(): Promise<string[]>;
+}
+
+/**
+ * Extension point a blob-store plugin registers its implementation with.
+ * The active backend is selected via `script_package_storage_config`; the
+ * backend resolves the registered store by id.
+ */
+export interface BlobStoreExtensionPoint {
+  registerBlobStore(store: BlobStore, metadata: PluginMetadata): void;
+}
+
+export const blobStoreExtensionPoint =
+  createExtensionPoint<BlobStoreExtensionPoint>(
+    "script-packages.blobStoreExtensionPoint",
+  );

package/src/cache-archive.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { spawn } from "bun";
+import {
+  mkdtemp,
+  mkdir,
+  writeFile,
+  readFile,
+  rm,
+  readdir,
+  symlink,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { packDir, unpackInto } from "./cache-archive";
+
+/** Build a gzip tar whose single entry is `entryName` (allowing `..`/abs). */
+async function makeArchiveWithEntry(
+  cwd: string,
+  entryName: string,
+): Promise<Uint8Array> {
+  // `-P`/`--absolute-names` lets us store traversing or absolute names that
+  // tar would otherwise strip — exactly the malicious shape we defend against.
+  const proc = spawn({
+    cmd: ["tar", "-czf", "-", "-P", entryName],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [bytes, exitCode] = await Promise.all([
+    new Response(proc.stdout).bytes(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) throw new Error("failed to build malicious archive");
+  return bytes;
+}
+
+describe("cache-archive pack/unpack", () => {
+  let work: string;
+
+  beforeEach(async () => {
+    work = await mkdtemp(path.join(tmpdir(), "cs-archive-"));
+  });
+  afterEach(async () => {
+    await rm(work, { recursive: true, force: true });
+  });
+
+  test("round-trips a directory tree through tar+gzip", async () => {
+    const src = path.join(work, "src");
+    const entry = "pkg@1.0.0";
+    const entryDir = path.join(src, entry);
+    await mkdir(path.join(entryDir, "sub"), { recursive: true });
+    await writeFile(path.join(entryDir, "index.js"), "module.exports = 1;\n");
+    await writeFile(path.join(entryDir, "sub", "x.txt"), "deep\n");
+
+    const blob = await packDir({ parentDir: src, entryName: entry });
+    expect(blob.byteLength).toBeGreaterThan(0);
+
+    const dest = path.join(work, "dest");
+    await mkdir(dest, { recursive: true });
+    await unpackInto({ targetDir: dest, bytes: blob });
+
+    expect(await readFile(path.join(dest, entry, "index.js"), "utf8")).toBe(
+      "module.exports = 1;\n",
+    );
+    expect(await readFile(path.join(dest, entry, "sub", "x.txt"), "utf8")).toBe(
+      "deep\n",
+    );
+  });
+
+  test("throws on a corrupt archive", async () => {
+    const dest = path.join(work, "dest");
+    await mkdir(dest, { recursive: true });
+    await expect(
+      unpackInto({ targetDir: dest, bytes: new Uint8Array([1, 2, 3, 4]) }),
+    ).rejects.toThrow(/tar extract failed/i);
+  });
+
+  test("refuses an archive entry that traverses out with ..", async () => {
+    // Build an archive whose entry NAME is `../escape`. tar resolves the
+    // name relative to its cwd, so the file lives one level up from cwd.
+    const base = path.join(work, "base");
+    const cwd = path.join(base, "inner");
+    await mkdir(cwd, { recursive: true });
+    await writeFile(path.join(base, "escape"), "pwned\n");
+    const blob = await makeArchiveWithEntry(cwd, "../escape");
+
+    const dest = path.join(work, "dest");
+    await mkdir(dest, { recursive: true });
+
+    await expect(
+      unpackInto({ targetDir: dest, bytes: blob }),
+    ).rejects.toThrow(/unsafe archive entry/i);
+
+    // Nothing was written outside dest (the sibling "escape" must not appear).
+    const siblings = await readdir(work);
+    expect(siblings).not.toContain("escape");
+  });
+
+  test("refuses a symlink entry with a safe name but an escaping target", async () => {
+    // A symlink entry whose NAME is harmless (`evil`, no `..`/abs) but whose
+    // TARGET escapes (`-> /etc`). The old name-only listing pass let it
+    // through, then a later regular-file entry could write THROUGH the link
+    // and escape targetDir. unpackInto must reject any symlink entry outright.
+    const src = path.join(work, "linksrc");
+    await mkdir(src, { recursive: true });
+    await symlink("/etc", path.join(src, "evil"));
+    const blob = await packDir({ parentDir: work, entryName: "linksrc" });
+
+    const dest = path.join(work, "dest");
+    await mkdir(dest, { recursive: true });
+    await expect(
+      unpackInto({ targetDir: dest, bytes: blob }),
+    ).rejects.toThrow(/symlink|link/i);
+
+    // Nothing materialized: the link must not exist under dest.
+    expect(
+      await readdir(dest).catch(() => []),
+    ).not.toContain("linksrc");
+  });
+
+  test("refuses a relative symlink target that traverses with ..", async () => {
+    const src = path.join(work, "linksrc2");
+    await mkdir(src, { recursive: true });
+    await symlink("../../../escape", path.join(src, "ln"));
+    const blob = await packDir({ parentDir: work, entryName: "linksrc2" });
+
+    const dest = path.join(work, "dest2");
+    await mkdir(dest, { recursive: true });
+    await expect(
+      unpackInto({ targetDir: dest, bytes: blob }),
+    ).rejects.toThrow(/symlink|link/i);
+  });
+
+  test("still round-trips a plain (link-free) directory after the link guard", async () => {
+    const src = path.join(work, "plainsrc");
+    await mkdir(path.join(src, "pkg@1.0.0"), { recursive: true });
+    await writeFile(
+      path.join(src, "pkg@1.0.0", "index.js"),
+      "module.exports = 2;\n",
+    );
+    const blob = await packDir({ parentDir: src, entryName: "pkg@1.0.0" });
+    const dest = path.join(work, "plaindest");
+    await mkdir(dest, { recursive: true });
+    await unpackInto({ targetDir: dest, bytes: blob });
+    expect(
+      await readFile(path.join(dest, "pkg@1.0.0", "index.js"), "utf8"),
+    ).toBe("module.exports = 2;\n");
+  });
+
+  test("refuses an archive entry with an absolute path", async () => {
+    const payloadDir = path.join(work, "payload2");
+    await mkdir(payloadDir, { recursive: true });
+    await writeFile(path.join(payloadDir, "abs.txt"), "x\n");
+    // Absolute entry name (e.g. /tmp/.../abs.txt).
+    const absName = path.join(payloadDir, "abs.txt");
+    const blob = await makeArchiveWithEntry("/", absName);
+
+    const dest = path.join(work, "dest");
+    await mkdir(dest, { recursive: true });
+    await expect(
+      unpackInto({ targetDir: dest, bytes: blob }),
+    ).rejects.toThrow(/unsafe archive entry/i);
+  });
+});

package/src/cache-archive.ts

@@ -0,0 +1,192 @@
+import { spawn } from "bun";
+
+/**
+ * Archive helpers for the content-addressed distribution unit.
+ *
+ * The distributable blob for each `name@version` is a gzip-compressed tar
+ * of that package's Bun cache entry directory. On reconcile a host extracts
+ * every needed blob back into its `BUN_INSTALL_CACHE_DIR`, then runs
+ * `bun install --offline` which reconstructs `node_modules` with zero
+ * network (empirically verified). Bun does the hoisting, so we never have
+ * to reconstruct the flat tree ourselves - this keeps the model
+ * Bun-version-tolerant while preserving per-package delta sync.
+ *
+ * We shell to POSIX `tar` (universal on Linux/macOS containers) and use
+ * gzip (via tar's `-z`) rather than zstd so there's no external `zstd`
+ * binary dependency. The plan named zstd; gzip is the portable substitute.
+ */
+
+async function runTar(args: string[], cwd?: string): Promise<Uint8Array> {
+  const proc = spawn({
+    cmd: ["tar", ...args],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).bytes(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`tar failed (exit ${exitCode}): ${stderr.slice(0, 500)}`);
+  }
+  return stdout;
+}
+
+/**
+ * Pack a single directory entry (`entryName`) located under `parentDir`
+ * into a gzip-compressed tar streamed to stdout. The archive stores the
+ * entry by its relative name so it extracts back to the same layout.
+ */
+export async function packDir({
+  parentDir,
+  entryName,
+}: {
+  parentDir: string;
+  entryName: string;
+}): Promise<Uint8Array> {
+  return runTar(["-czf", "-", entryName], parentDir);
+}
+
+/**
+ * Reject an archive entry path that would escape the extraction directory
+ * (zip-slip): an absolute path or any `..` path component. Returns the
+ * offending reason, or `undefined` when the path is safe + confined.
+ */
+function unsafeArchivePath(entryPath: string): string | undefined {
+  const trimmed = entryPath.trim();
+  if (trimmed === "") return undefined; // tar can emit a trailing blank line
+  // Absolute (POSIX or Windows-style) — would extract outside targetDir.
+  if (trimmed.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(trimmed)) {
+    return `absolute path "${trimmed}"`;
+  }
+  // Any `..` segment (handle both / and \ separators) — path traversal.
+  const segments = trimmed.split(/[\\/]/);
+  if (segments.includes("..")) {
+    return `parent-directory traversal in "${trimmed}"`;
+  }
+  return undefined;
+}
+
+/**
+ * Reject any archive entry that is NOT a plain file or directory.
+ *
+ * Path-only validation ({@link unsafeArchivePath}) is blind to LINK TARGETS:
+ * a symlink with a harmless NAME (e.g. `evil`, no `..`/abs) but an escaping
+ * TARGET (`-> /etc`, `-> ../../..`) passes the name check, then a later
+ * regular-file entry can be written THROUGH the link and escape `targetDir`.
+ * Reconstructed Bun-cache trees are plain files + dirs, so we reject every
+ * symlink/hardlink/device/fifo entry outright (defence in depth, independent
+ * of any tar extraction flag).
+ *
+ * `line` is one row of `tar -tzvf` verbose output; its first character is the
+ * POSIX type flag (`-` file, `d` dir, `l` symlink, `h` hardlink, etc.) on
+ * both GNU and BSD/libarchive tar. Returns the offending reason, or
+ * `undefined` for a safe (file/dir) entry or a blank line.
+ */
+function unsafeArchiveEntryType(line: string): string | undefined {
+  const trimmed = line.trimEnd();
+  if (trimmed.trim() === "") return undefined; // trailing blank line
+  const typeFlag = trimmed[0];
+  if (typeFlag === "-" || typeFlag === "d") return undefined; // file or dir
+  if (typeFlag === "l" || typeFlag === "h") {
+    return `link entry (type "${typeFlag}") in "${trimmed}"`;
+  }
+  // Anything else (block/char device "b"/"c", fifo "p", socket "s", …) is
+  // never part of a package cache tree → reject.
+  return `non-regular entry (type "${typeFlag}") in "${trimmed}"`;
+}
+
+/**
+ * Extract a gzip-compressed tar blob into `targetDir`.
+ *
+ * Hardened against zip-slip on two axes, both checked BEFORE any bytes are
+ * written (a violation aborts the whole extract, materializing nothing):
+ *
+ *   1. Entry PATHS must be relative and free of `..` components — a
+ *      traversing / absolute name would write outside `targetDir`.
+ *   2. Entry TYPES must be plain file or directory — a symlink/hardlink with
+ *      a harmless name but an escaping target would let a later file write
+ *      THROUGH it and escape `targetDir`. Reconstructed Bun-cache trees never
+ *      contain links, so any link/device/fifo entry is rejected.
+ *
+ * We validate explicitly (rather than relying on a tar flag) so the behaviour
+ * is identical across GNU and BSD/libarchive tar. The verbose listing
+ * (`-tzvf`) carries both the type flag (column 0) and the path, so a single
+ * listing pass covers both checks.
+ */
+export async function unpackInto({
+  targetDir,
+  bytes,
+}: {
+  targetDir: string;
+  bytes: Uint8Array;
+}): Promise<void> {
+  // 1. List entries (verbose: type flag + path) and validate BEFORE extract.
+  //    `-tzvf` rows look like `lrwxr-xr-x 0 user grp 0 <date> name -> target`;
+  //    the path/name portion is what `-tzf` would print, so we run the plain
+  //    listing for the path check and the verbose listing for the type check.
+  const [pathListing, typeListing] = await Promise.all([
+    runTarCapture(["-tzf", "-"], bytes),
+    runTarCapture(["-tzvf", "-"], bytes),
+  ]);
+  for (const line of pathListing.split("\n")) {
+    const reason = unsafeArchivePath(line);
+    if (reason) {
+      throw new Error(`refusing to extract unsafe archive entry: ${reason}`);
+    }
+  }
+  for (const line of typeListing.split("\n")) {
+    const reason = unsafeArchiveEntryType(line);
+    if (reason) {
+      throw new Error(`refusing to extract unsafe archive entry: ${reason}`);
+    }
+  }
+
+  // 2. Extract. `--no-same-owner` avoids surprising ownership; paths + types
+  // are already proven relative + confined + link-free above.
+  const proc = spawn({
+    cmd: ["tar", "-xzf", "-", "-C", targetDir],
+    stdin: bytes,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stderr, exitCode] = await Promise.all([
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(
+      `tar extract failed (exit ${exitCode}): ${stderr.slice(0, 500)}`,
+    );
+  }
+}
+
+/**
+ * Run `tar` with the blob piped to stdin and return stdout as text. Shared
+ * by the listing pass in {@link unpackInto}; throws on a non-zero exit (e.g.
+ * a corrupt archive) so callers surface a clear error.
+ */
+async function runTarCapture(
+  args: string[],
+  stdin: Uint8Array,
+): Promise<string> {
+  const proc = spawn({
+    cmd: ["tar", ...args],
+    stdin,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(
+      `tar extract failed (exit ${exitCode}): ${stderr.slice(0, 500)}`,
+    );
+  }
+  return stdout;
+}

package/src/cache-layout.ts

@@ -0,0 +1,64 @@
+import { readdir } from "node:fs/promises";
+
+/**
+ * Map manifest entries to their on-disk Bun cache entry directory names.
+ *
+ * Bun extracts each package into `<cacheDir>/<name>@<version>@@@<n>` (the
+ * `@@@<n>` suffix is an internal dedupe counter). We discover the actual
+ * entry dir by listing the cache and matching the `<name>@<version>`
+ * prefix, rather than hardcoding the suffix - keeping us tolerant of Bun's
+ * internal counter. Scoped packages (`@scope/name`) live under a `@scope/`
+ * subdir in the cache.
+ */
+
+export interface CacheEntryLocation {
+  /** Directory the entry sits *under* (its parent), for tar's cwd. */
+  parentDir: string;
+  /** The entry dir name relative to `parentDir`. */
+  entryName: string;
+}
+
+function specPrefix(name: string, version: string): string {
+  return `${name}@${version}@@@`;
+}
+
+/**
+ * Find the cache entry dir for `name@version`. Returns undefined if the
+ * cache doesn't contain it (caller treats as a resolve error).
+ */
+export async function findCacheEntry({
+  cacheDir,
+  name,
+  version,
+}: {
+  cacheDir: string;
+  name: string;
+  version: string;
+}): Promise<CacheEntryLocation | undefined> {
+  if (name.startsWith("@")) {
+    // Scoped: `<cacheDir>/@scope/name@version@@@n`
+    const [scope, bare] = name.split("/");
+    const scopeDir = `${cacheDir}/${scope}`;
+    const prefix = `${bare}@${version}@@@`;
+    const match = await firstMatch(scopeDir, prefix);
+    if (!match) return;
+    return { parentDir: scopeDir, entryName: match };
+  }
+  const prefix = specPrefix(name, version);
+  const match = await firstMatch(cacheDir, prefix);
+  if (!match) return;
+  return { parentDir: cacheDir, entryName: match };
+}
+
+async function firstMatch(
+  dir: string,
+  prefix: string,
+): Promise<string | undefined> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  return names.find((n) => n.startsWith(prefix));
+}