@mostra/sdk 0.0.0-stage → 0.2.0

package/src/bundle/cache.ts

@@ -0,0 +1,375 @@
+/**
+ * The local cache of runtime bundles (RT-01): one directory per archive digest, so a bundle is
+ * found by what it is, not by what it's called. A bundle enters the cache only through
+ * {@link installPinned}: downloaded against its pin, extracted into a temporary directory, its
+ * files checked, renamed into place, its browser fetched, and only then marked ready. Concurrent
+ * installers of one bundle share a lock, so it is downloaded once; a crash leaves a temporary
+ * directory the next install removes, never a half-ready bundle.
+ */
+import { randomBytes } from "node:crypto";
+import {
+  link,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  statfs,
+  utimes,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  type BundleAsset,
+  BundleAsset as BundleAssetSchema,
+  type BundlePins,
+  type BundlePlatform,
+  bundleAssetName,
+  createDiagnostic,
+  RpcError,
+} from "@mostra/protocol";
+import { type DownloadProgress, download } from "./download.ts";
+import { extractBundle } from "./extract.ts";
+import {
+  type Bundle,
+  checkFiles,
+  type Environment,
+  offline,
+  readBundle,
+  readSetup,
+  type SetupStep,
+  setupBundle,
+} from "./setup.ts";
+
+/** Where the cache is: `MOSTRA_CACHE_DIR`, else the platform's per-user cache directory. */
+export function cacheRoot(env: Environment, platform: string = process.platform): string {
+  const override = env["MOSTRA_CACHE_DIR"];
+  if (override) return resolve(override);
+  const home = env["HOME"] || homedir();
+  if (platform === "darwin") return join(home, "Library", "Caches", "mostra");
+  const xdg = env["XDG_CACHE_HOME"];
+  return join(xdg?.startsWith("/") ? xdg : join(home, ".cache"), "mostra");
+}
+
+/** The directory a bundle with this archive digest lives in. */
+export function bundleDir(env: Environment, sha256: string): string {
+  return join(cacheRoot(env), "bundles", sha256);
+}
+
+/** What an install reports while it works. */
+export type InstallProgress =
+  | ({ readonly step: "download" } & DownloadProgress)
+  | { readonly step: "extract" | "lock" }
+  | { readonly step: SetupStep };
+
+/** Options of {@link installPinned}. */
+export interface InstallOptions {
+  /** The environment: the cache, mirror and offline variables, proxies. */
+  readonly env: Environment;
+  /** The platform whose archive to install. */
+  readonly platform: BundlePlatform;
+  /** Gives up the install; nothing partial is kept. */
+  readonly signal?: AbortSignal | undefined;
+  /** Each step, and the bytes received while downloading. */
+  readonly onProgress?: ((progress: InstallProgress) => void) | undefined;
+}
+
+/** The space an install needs beyond the archive and its files: the browser and some margin. */
+const BROWSER_ALLOWANCE = 500 * 1024 * 1024;
+
+/**
+ * The pinned bundle for this platform, ready to run: from the cache when it is there and ready,
+ * else installed. `MOSTRA_BUNDLE_MIRROR` replaces the release URL (files keep their names).
+ */
+export async function installPinned(pins: BundlePins, options: InstallOptions): Promise<Bundle> {
+  const asset = pins.assets[options.platform];
+  // Checked before any I/O: the asset's name becomes a path in the cache's scratch directory and
+  // its digest the bundle's directory (Opus review finding 8), so the asset must be well-formed
+  // and named exactly as its release's archive for this platform.
+  if (
+    asset !== undefined &&
+    (!BundleAssetSchema.safeParse(asset).success ||
+      asset.file !== bundleAssetName(pins.version, options.platform))
+  ) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+        message: `The pins name ${JSON.stringify(asset.file)} for ${options.platform}, not Mostra ${pins.version}'s archive ${bundleAssetName(pins.version, options.platform)}.`,
+      }),
+    );
+  }
+  if (asset === undefined) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", {
+        message: `Mostra ${pins.version} has no runtime bundle for ${options.platform}.`,
+      }),
+    );
+  }
+  const dir = bundleDir(options.env, asset.sha256);
+  const ready = await readyAt(dir);
+  if (ready) return ready;
+  if (offline(options.env)) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", {
+        message: `Mostra ${pins.version}'s runtime bundle isn't in the cache (${dir}), and MOSTRA_OFFLINE keeps Mostra from fetching it.`,
+      }),
+    );
+  }
+  const bundles = join(cacheRoot(options.env), "bundles");
+  await mkdir(bundles, { recursive: true, mode: 0o700 });
+  options.onProgress?.({ step: "lock" });
+  const release = await lock(join(bundles, `${asset.sha256}.lock`), options.signal);
+  try {
+    const raced = await readyAt(dir);
+    if (raced) return raced;
+    await sweep(bundles);
+    if (await exists(dir)) {
+      // A bundle whose setup didn't finish (no network for the browser, a crash). Only its own
+      // files decide whether it is downloaded afresh: a file that differs from the pins can't be
+      // repaired in place, but the browser can be fetched again, and downloading 200 MB again
+      // never changes what Playwright serves (Opus review finding 5). Anything else, such as a
+      // permission error, is thrown: it says nothing about the bundle, so nothing is deleted.
+      if (await filesIntact(dir)) return await finish(dir, { ...options, filesChecked: true });
+      await rm(dir, { recursive: true, force: true });
+    }
+    await fetchInto(pins, asset, dir, bundles, options);
+    return await finish(dir, { ...options, filesChecked: true });
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Whether the bundle at `dir` holds exactly what its `files.json` lists. `false` only for
+ * `MOSTRA_ENV_BUNDLE_INVALID` (a missing or changed file, a `bundle.json` that doesn't read);
+ * every other error is thrown.
+ */
+async function filesIntact(dir: string): Promise<boolean> {
+  try {
+    await checkFiles(await readBundle(dir));
+    return true;
+  } catch (error) {
+    if (error instanceof RpcError && error.diagnostic.code === "MOSTRA_ENV_BUNDLE_INVALID")
+      return false;
+    throw error;
+  }
+}
+
+/** The bundle at `dir` when it exists and its setup marker matches it. */
+async function readyAt(dir: string): Promise<Bundle | undefined> {
+  const bundle = await readBundle(dir).catch(() => undefined);
+  if (bundle === undefined) return undefined;
+  return (await readSetup(bundle)) ? bundle : undefined;
+}
+
+async function finish(
+  dir: string,
+  options: InstallOptions & { readonly filesChecked?: boolean },
+): Promise<Bundle> {
+  await setupBundle(dir, {
+    env: options.env,
+    signal: options.signal,
+    filesChecked: options.filesChecked,
+    onStep: (step) => options.onProgress?.({ step }),
+  });
+  return readBundle(dir);
+}
+
+/** Downloads, extracts and checks the archive, then renames it into `dir`. */
+async function fetchInto(
+  pins: BundlePins,
+  asset: BundleAsset,
+  dir: string,
+  bundles: string,
+  options: InstallOptions,
+): Promise<void> {
+  await requireSpace(bundles, asset);
+  const scratch = join(bundles, `.tmp-${process.pid}-${randomBytes(6).toString("hex")}`);
+  await mkdir(scratch, { mode: 0o700 });
+  try {
+    const archive = join(scratch, asset.file);
+    const base = options.env["MOSTRA_BUNDLE_MIRROR"] || pins.release;
+    const url = `${withoutTrailingSlashes(base)}/${encodeURIComponent(asset.file)}`;
+    await download(url, archive, asset, {
+      env: options.env,
+      signal: options.signal,
+      onProgress: (progress) => options.onProgress?.({ step: "download", ...progress }),
+    });
+    options.onProgress?.({ step: "extract" });
+    const root = join(scratch, "root");
+    await mkdir(root);
+    const top = asset.file.replace(/\.tar\.gz$/, "");
+    if (top !== bundleAssetName(pins.version, options.platform).replace(/\.tar\.gz$/, "")) {
+      throw new RpcError(
+        createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+          message: `The pinned archive ${asset.file} isn't Mostra ${pins.version}'s bundle for ${options.platform}.`,
+        }),
+      );
+    }
+    await extractBundle(archive, root, top);
+    await rm(archive, { force: true });
+    const bundle = await readBundle(root);
+    if (bundle.info.version !== pins.version || bundle.info.platform !== options.platform) {
+      throw new RpcError(
+        createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+          message: `The archive holds Mostra ${bundle.info.version} for ${bundle.info.platform}, not ${pins.version} for ${options.platform}.`,
+        }),
+      );
+    }
+    options.onProgress?.({ step: "files" });
+    await checkFiles(bundle);
+    try {
+      await rename(root, dir);
+    } catch (error) {
+      // Another installer finished first (the lock is an optimization, never what correctness
+      // rests on): its directory is used, whose files it checked before renaming them into place.
+      const code = (error as NodeJS.ErrnoException).code;
+      if (!(code === "ENOTEMPTY" || code === "EEXIST") || !(await exists(dir))) throw error;
+    }
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+/** Fails early when the cache's file system can't hold the bundle. */
+async function requireSpace(dir: string, asset: BundleAsset): Promise<void> {
+  const fs = await statfs(dir).catch(() => undefined);
+  if (fs === undefined) return;
+  const free = Number(fs.bavail) * Number(fs.bsize);
+  const needed = asset.size + asset.unpackedSize + BROWSER_ALLOWANCE;
+  if (free < needed) {
+    const gib = (bytes: number): string => `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", {
+        message: `The runtime bundle needs about ${gib(needed)} free in ${dir}, and ${gib(free)} is free (the disk is full).`,
+      }),
+    );
+  }
+}
+
+/** Removes temporary directories an interrupted install left, when their process is gone. */
+async function sweep(bundles: string): Promise<void> {
+  for (const name of await readdir(bundles).catch(() => [] as string[])) {
+    const match = /^\.tmp-(\d+)-/.exec(name);
+    if (match && !alive(Number(match[1]))) {
+      await rm(join(bundles, name), { recursive: true, force: true });
+    }
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  return stat(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** How old a lock may get before another installer takes it over whatever its owner. */
+const STALE_LOCK_MS = 60 * 60_000;
+/**
+ * How often a held lock is touched, so an install longer than {@link STALE_LOCK_MS} (a slow
+ * network, a large browser) is never taken from its live owner (Opus review of WP-12, finding 10).
+ */
+const LOCK_TOUCH_MS = 60_000;
+
+/** `url` without trailing slashes, in linear time (a regex would be quadratic on many slashes). */
+function withoutTrailingSlashes(url: string): string {
+  let end = url.length;
+  while (end > 0 && url[end - 1] === "/") end -= 1;
+  return url.slice(0, end);
+}
+
+/**
+ * Removes the lock at `path` when it is stale (its owner gone, or older than an hour) and says
+ * whether it did. The lock is read and judged through one descriptor, then moved aside, and only
+ * the file judged is removed: a fresh lock another installer took in between is put back (or,
+ * if a third took one meanwhile, left to the next round). The lock only saves a second download;
+ * the scratch directory and its rename keep the cache correct whatever happens here.
+ */
+async function takeOverIfStale(path: string): Promise<boolean> {
+  let handle: Awaited<ReturnType<typeof open>>;
+  try {
+    handle = await open(path, "r");
+  } catch {
+    return true; // gone already: try to take it
+  }
+  let judged: { ino: number; dev: number };
+  try {
+    const info = await handle.stat();
+    const owner = Number.parseInt(await handle.readFile("utf8"), 10);
+    const stale =
+      Date.now() - info.mtimeMs > STALE_LOCK_MS ||
+      (Number.isInteger(owner) && owner > 0 && !alive(owner));
+    if (!stale) return false;
+    judged = { ino: info.ino, dev: info.dev };
+  } finally {
+    await handle.close();
+  }
+  const aside = `${path}.stale-${randomBytes(6).toString("hex")}`;
+  try {
+    await rename(path, aside);
+  } catch {
+    return true; // someone else moved or removed it
+  }
+  const moved = await stat(aside).catch(() => undefined);
+  if (moved && (moved.ino !== judged.ino || moved.dev !== judged.dev)) {
+    // Not the file judged stale: a fresh lock. Put it back unless a newer one exists.
+    await link(aside, path).catch(() => undefined);
+  }
+  await rm(aside, { force: true });
+  return true;
+}
+
+/**
+ * Takes the install lock at `path`: an exclusive create holding the owner's PID. A lock whose
+ * owner is gone, or older than an hour, is taken over; otherwise the caller waits for it.
+ */
+async function lock(path: string, signal: AbortSignal | undefined): Promise<() => Promise<void>> {
+  const token = randomBytes(8).toString("hex");
+  for (;;) {
+    signal?.throwIfAborted();
+    try {
+      const handle = await open(path, "wx", 0o600);
+      await handle.writeFile(`${process.pid} ${token}\n`);
+      await handle.close();
+      const touch = setInterval(() => {
+        void readFile(path, "utf8")
+          .then((text) => {
+            if (text.includes(token)) return utimes(path, new Date(), new Date());
+            return undefined;
+          })
+          .catch(() => undefined);
+      }, LOCK_TOUCH_MS);
+      touch.unref();
+      // Released by moving it aside and removing it only if it is still this installer's own.
+      return async () => {
+        clearInterval(touch);
+        const aside = `${path}.done-${randomBytes(6).toString("hex")}`;
+        if (
+          !(await rename(path, aside).then(
+            () => true,
+            () => false,
+          ))
+        )
+          return;
+        const text = await readFile(aside, "utf8").catch(() => "");
+        if (!text.includes(token)) await link(aside, path).catch(() => undefined);
+        await rm(aside, { force: true });
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    if (await takeOverIfStale(path)) continue;
+    await new Promise((done) => setTimeout(done, 250));
+  }
+}

package/src/bundle/download.ts

@@ -0,0 +1,255 @@
+/**
+ * Fetching a pinned archive (RT-01): streamed to disk while it is hashed, never longer than the
+ * pin says, through the environment's proxy (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`), retried on
+ * failures that a retry can cure, and checked against the pin before anyone reads it.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import { createDiagnostic, RpcError } from "@mostra/protocol";
+import { EnvHttpProxyAgent, fetch } from "undici";
+
+/** What a download must match. */
+export interface Expected {
+  readonly sha256: string;
+  readonly size: number;
+}
+
+/** Progress of one download, in bytes. */
+export interface DownloadProgress {
+  /** Bytes received so far. */
+  readonly received: number;
+  /** Bytes the pin says the archive has. */
+  readonly total: number;
+}
+
+/** Options of {@link download}. */
+export interface DownloadOptions {
+  /**
+   * The environment whose proxy settings apply (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, either
+   * case): a host's own, never silently `process.env`'s. Default `process.env`.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly onProgress?: ((progress: DownloadProgress) => void) | undefined;
+  /** How long the connection may stay silent. Default 60 s. */
+  readonly stallMs?: number | undefined;
+  /** Attempts in all, for failures a retry can cure. Default 3. */
+  readonly attempts?: number | undefined;
+}
+
+/** A failure a retry won't cure (an HTTP 4xx other than 408 and 429, a wrong size or digest). */
+class Final extends Error {}
+
+/**
+ * Downloads `url` (`https:`, `http:` or `file:`) to `dest` and checks its size and SHA-256.
+ * Throws `MOSTRA_ENV_BUNDLE_INVALID` when the bytes aren't the pinned ones and
+ * `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED` otherwise; `dest` never survives a failure.
+ */
+export async function download(
+  url: string,
+  dest: string,
+  expected: Expected,
+  options: DownloadOptions = {},
+): Promise<void> {
+  const attempts = options.attempts ?? 3;
+  let last: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const actual = await once(url, dest, expected, options);
+      if (actual !== expected.sha256) {
+        throw invalid(
+          `The download from ${redactUrl(url)} has SHA-256 ${actual}, not the pinned ${expected.sha256}.`,
+        );
+      }
+      return;
+    } catch (error) {
+      await rm(dest, { force: true });
+      last = error;
+      if (error instanceof RpcError || error instanceof Final || options.signal?.aborted) break;
+      if ((error as NodeJS.ErrnoException).code === "ENOSPC") break;
+      if (attempt < attempts) await delay(1000 * 4 ** (attempt - 1), options.signal);
+    }
+  }
+  if (last instanceof RpcError) throw last;
+  if (options.signal?.aborted) throw options.signal.reason;
+  throw new RpcError(
+    createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", {
+      message: `Couldn't download ${redactUrl(url)}: ${scrubUrls(describe(last))}`,
+    }),
+  );
+}
+
+async function once(
+  url: string,
+  dest: string,
+  expected: Expected,
+  options: DownloadOptions,
+): Promise<string> {
+  const hash = createHash("sha256");
+  let received = 0;
+  const stallMs = options.stallMs ?? 60_000;
+  const controller = new AbortController();
+  const abort = (): void => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const arm = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(
+      () => controller.abort(new Error(`no data for ${stallMs / 1000} s`)),
+      stallMs,
+    );
+  };
+  try {
+    arm();
+    const body = await open(url, controller.signal, options.env ?? process.env);
+    const counter = async function* (source: AsyncIterable<Uint8Array>) {
+      for await (const chunk of source) {
+        arm();
+        received += chunk.length;
+        if (received > expected.size) {
+          throw invalid(
+            `The download from ${redactUrl(url)} is larger than the pinned ${expected.size} bytes.`,
+          );
+        }
+        hash.update(chunk);
+        options.onProgress?.({ received, total: expected.size });
+        yield chunk;
+      }
+    };
+    await pipeline(body, counter, createWriteStream(dest, { mode: 0o600 }), {
+      signal: controller.signal,
+    });
+    if (received !== expected.size) {
+      throw invalid(
+        `The download from ${redactUrl(url)} has ${received} bytes, not the pinned ${expected.size}.`,
+      );
+    }
+    return hash.digest("hex");
+  } catch (error) {
+    if (controller.signal.aborted && !(error instanceof RpcError)) {
+      const reason: unknown = controller.signal.reason;
+      throw reason instanceof Error ? reason : new Error(String(reason));
+    }
+    throw error;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    options.signal?.removeEventListener("abort", abort);
+  }
+}
+
+/** The body of `url` as a stream. */
+async function open(
+  url: string,
+  signal: AbortSignal,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<AsyncIterable<Uint8Array>> {
+  const parsed = new URL(url);
+  if (parsed.protocol === "file:") {
+    return createReadStream(fileURLToPath(parsed), { signal }) as AsyncIterable<Uint8Array>;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Final(`${parsed.protocol} URLs aren't supported`);
+  }
+  // fetch refuses a URL with credentials, so a mirror's (`https://user:pass@host/…`) travel as
+  // Basic authorization, which fetch drops on a redirect to another origin.
+  const headers: Record<string, string> = {
+    "user-agent": "mostra-sdk",
+    accept: "application/octet-stream",
+  };
+  if (parsed.username !== "" || parsed.password !== "") {
+    const user = decodeURIComponent(parsed.username);
+    const password = decodeURIComponent(parsed.password);
+    headers["authorization"] = `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+    parsed.username = "";
+    parsed.password = "";
+  }
+  const response = await fetch(parsed, {
+    dispatcher: proxyAgent(env),
+    redirect: "follow",
+    signal,
+    headers,
+  });
+  if (!response.ok || response.body === null) {
+    const status = response.status;
+    await response.body?.cancel().catch(() => undefined);
+    const message = `HTTP ${status}${response.statusText ? ` ${response.statusText}` : ""}`;
+    if (status >= 400 && status < 500 && status !== 408 && status !== 429) throw new Final(message);
+    throw new Error(message);
+  }
+  return Readable.fromWeb(response.body as import("node:stream/web").ReadableStream<Uint8Array>);
+}
+
+const agents = new Map<string, EnvHttpProxyAgent>();
+/**
+ * The agent for `env`'s `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` (lowercase first, as curl
+ * reads them), one per distinct setting. Each is passed explicitly, an empty one included, so
+ * undici never falls back to `process.env` (GPT review finding 6).
+ */
+function proxyAgent(env: Readonly<Record<string, string | undefined>>): EnvHttpProxyAgent {
+  const settings = {
+    httpProxy: env["http_proxy"] ?? env["HTTP_PROXY"] ?? "",
+    httpsProxy: env["https_proxy"] ?? env["HTTPS_PROXY"] ?? "",
+    noProxy: env["no_proxy"] ?? env["NO_PROXY"] ?? "",
+  };
+  const key = JSON.stringify(settings);
+  let agent = agents.get(key);
+  if (agent === undefined) {
+    agent = new EnvHttpProxyAgent(settings);
+    agents.set(key, agent);
+  }
+  return agent;
+}
+
+/**
+ * `text` with every URL in it reduced to {@link redactUrl}'s form: an error from the network stack
+ * repeats the URL it failed on, credentials, query and all (a mirror's or a proxy's), and a
+ * diagnostic is printed (GPT review finding 2).
+ */
+export function scrubUrls(text: string): string {
+  return text.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>()]+/gi, (url) => redactUrl(url));
+}
+
+function invalid(message: string): RpcError {
+  return new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message }));
+}
+
+/** A URL without credentials or a query, safe to print. */
+export function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return "(an invalid URL)";
+  }
+}
+
+function describe(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const cause = (error as { cause?: unknown }).cause;
+  const code = (cause as { code?: string } | undefined)?.code ?? (error as { code?: string }).code;
+  return code !== undefined && !error.message.includes(code)
+    ? `${error.message} (${code})`
+    : error.message;
+}
+
+function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((done) => {
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        done();
+      },
+      { once: true },
+    );
+  });
+}

package/src/bundle/extract.ts

@@ -0,0 +1,60 @@
+/**
+ * Unpacking a downloaded archive (RT-01). Only regular files, directories and symbolic links are
+ * accepted, all under the archive's one top directory, which is stripped. node-tar refuses
+ * absolute paths, `..` and writing through a link; it does create a link whatever its target, so
+ * setup then checks the whole tree against the bundle's file list (`checkTree`), which refuses any
+ * file or link it doesn't list and any link that leaves the bundle. A pinned archive's SHA-256 is
+ * checked before any of this.
+ */
+import { createDiagnostic, RpcError } from "@mostra/protocol";
+import { x } from "tar";
+
+const ACCEPTED = new Set(["File", "OldFile", "ContiguousFile", "Directory", "SymbolicLink"]);
+
+/** Extracts `archive` (a `.tar.gz` with one top directory `top`) into the empty directory `into`. */
+export async function extractBundle(archive: string, into: string, top: string): Promise<void> {
+  let refused: string | undefined;
+  try {
+    await x({
+      file: archive,
+      cwd: into,
+      strip: 1,
+      strict: true,
+      preservePaths: false,
+      preserveOwner: false,
+      // Owner-only directories are tightened later; files keep their 0644/0755 modes.
+      noChmod: false,
+      filter: (path, entry) => {
+        const type = "type" in entry ? String(entry.type) : "File";
+        const inside = path === `${top}/` || path === top || path.startsWith(`${top}/`);
+        if (!inside || !ACCEPTED.has(type)) {
+          refused ??= `${path} (${type})`;
+          return false;
+        }
+        return true;
+      },
+    });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    // The file system failing (a full disk, a permission) isn't the archive's fault.
+    if (typeof code === "string" && /^E[A-Z]+$/.test(code) && code !== "EOF") {
+      throw new RpcError(
+        createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", {
+          message: `The runtime bundle couldn't be written to ${into}: ${(error as Error).message}${code === "ENOSPC" ? " (the disk is full)" : ""}`,
+        }),
+      );
+    }
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+        message: `The runtime bundle's archive couldn't be read: ${(error as Error).message}`,
+      }),
+    );
+  }
+  if (refused !== undefined) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+        message: `The runtime bundle's archive holds an entry a bundle never has: ${refused}.`,
+      }),
+    );
+  }
+}