@hanamesh/dsh-app-host 0.2.0-rc.2

package/dist/provision/archive.d.ts

@@ -0,0 +1,28 @@
+/** Common archive entry shape shared by the tar.gz and zip readers. */
+export type EntryKind = 'file' | 'dir' | 'symlink' | 'hardlink';
+export interface ArchiveEntry {
+    kind: EntryKind;
+    /** Raw entry name as stored in the archive (unsafe until checked). */
+    name: string;
+    /** POSIX mode bits; 0 when the archive has none. */
+    mode: number;
+    size: number;
+    /** Symlink / hardlink target as stored. */
+    linkTarget?: string;
+    /** File body. Must be fully consumed before the next entry is requested. */
+    body: AsyncIterable<Uint8Array>;
+}
+/** Pull exact byte counts out of a chunk stream (used by the tar reader). */
+export declare class ByteReader {
+    private readonly it;
+    private buffered;
+    private bufferedLength;
+    private done;
+    constructor(source: AsyncIterable<Uint8Array>);
+    private fill;
+    /** Read exactly `n` bytes; returns fewer only at EOF. */
+    read(n: number): Promise<Uint8Array>;
+    /** Yield exactly `n` bytes as chunks. Throws on premature EOF. */
+    stream(n: number): AsyncGenerator<Uint8Array>;
+    skip(n: number): Promise<void>;
+}

package/dist/provision/archive.js

@@ -0,0 +1,66 @@
+/** Pull exact byte counts out of a chunk stream (used by the tar reader). */
+export class ByteReader {
+    it;
+    buffered = [];
+    bufferedLength = 0;
+    done = false;
+    constructor(source) {
+        this.it = source[Symbol.asyncIterator]();
+    }
+    async fill() {
+        if (this.done)
+            return false;
+        const step = await this.it.next();
+        if (step.done) {
+            this.done = true;
+            return false;
+        }
+        if (step.value.length > 0) {
+            this.buffered.push(step.value);
+            this.bufferedLength += step.value.length;
+        }
+        return true;
+    }
+    /** Read exactly `n` bytes; returns fewer only at EOF. */
+    async read(n) {
+        while (this.bufferedLength < n && (await this.fill()))
+            ;
+        const out = new Uint8Array(Math.min(n, this.bufferedLength));
+        let off = 0;
+        while (off < out.length) {
+            const head = this.buffered[0];
+            const take = Math.min(head.length, out.length - off);
+            out.set(head.subarray(0, take), off);
+            off += take;
+            if (take === head.length)
+                this.buffered.shift();
+            else
+                this.buffered[0] = head.subarray(take);
+            this.bufferedLength -= take;
+        }
+        return out;
+    }
+    /** Yield exactly `n` bytes as chunks. Throws on premature EOF. */
+    async *stream(n) {
+        let remaining = n;
+        while (remaining > 0) {
+            if (this.bufferedLength === 0 && !(await this.fill()))
+                throw new Error('unexpected end of archive');
+            const head = this.buffered[0];
+            const take = Math.min(head.length, remaining);
+            const chunk = head.subarray(0, take);
+            if (take === head.length)
+                this.buffered.shift();
+            else
+                this.buffered[0] = head.subarray(take);
+            this.bufferedLength -= take;
+            remaining -= take;
+            yield chunk;
+        }
+    }
+    async skip(n) {
+        for await (const _ of this.stream(n)) {
+            /* discard */
+        }
+    }
+}

package/dist/provision/check.d.ts

@@ -0,0 +1,10 @@
+import type { VerifySpec } from './types.js';
+/**
+ * Run `verify.exec` from the freshly extracted tree with an isolated environment:
+ * PATH is empty, so nothing on the host can be picked up by accident, and the
+ * executable is addressed by absolute path inside the staging tree.
+ */
+export declare function runCheck(tree: string, spec: VerifySpec, item: string): Promise<{
+    stdout: string;
+    stderr: string;
+}>;

package/dist/provision/check.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { ProvisionError } from './errors.js';
+import { isInside } from './paths.js';
+/**
+ * Run `verify.exec` from the freshly extracted tree with an isolated environment:
+ * PATH is empty, so nothing on the host can be picked up by accident, and the
+ * executable is addressed by absolute path inside the staging tree.
+ */
+export async function runCheck(tree, spec, item) {
+    const exe = path.join(tree, ...spec.exec.split('/'));
+    if (!isInside(tree, exe))
+        throw new ProvisionError('E_VERIFY', `verify.exec escapes the tree: ${spec.exec}`, { item });
+    const env = { PATH: '' };
+    if (process.platform === 'win32') {
+        // A Windows process cannot start without SystemRoot; nothing else is inherited.
+        for (const k of ['SystemRoot', 'SYSTEMROOT', 'windir', 'TEMP', 'TMP']) {
+            const v = process.env[k];
+            if (v !== undefined)
+                env[k] = v;
+        }
+    }
+    const timeoutMs = spec.timeoutMs ?? 60_000;
+    return new Promise((resolve, reject) => {
+        const child = spawn(exe, spec.args ?? [], { env, cwd: tree, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new ProvisionError('E_VERIFY', `verify.exec timed out after ${timeoutMs}ms: ${spec.exec}`, { item }));
+        }, timeoutMs);
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(new ProvisionError('E_VERIFY', `verify.exec could not start (${spec.exec}): ${err.message}`, { item, cause: err }));
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new ProvisionError('E_VERIFY', `verify.exec exited ${code ?? signal}: ${spec.exec}; stderr: ${stderr.trim().slice(0, 500)}`, { item }));
+                return;
+            }
+            if (spec.expect !== undefined && stdout.trim() !== spec.expect) {
+                reject(new ProvisionError('E_VERIFY', `verify.exec output ${JSON.stringify(stdout.trim().slice(0, 200))} != expected ${JSON.stringify(spec.expect)}`, { item }));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}

package/dist/provision/checkpoints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Crash-injection checkpoints for consistency tests (CONSISTENCY.md X02/X03).
+ *
+ * Set `HANAMESH_PROVISION_KILL_AT=<name>` to SIGKILL the current process the
+ * first time that checkpoint is reached, or `download@<bytes>` to kill once the
+ * download has written at least that many bytes. Every checkpoint sits *after*
+ * the durability point of the step it names (file closed / fsync'd / rename returned),
+ * never after a merely resolved promise.
+ */
+export type CheckpointName = 'after-download' | 'after-sha256' | 'after-extract' | 'after-check' | 'after-manifest-temp' | 'after-trash' | 'after-manifest' | 'after-rename' | 'after-ledger';
+export declare function checkpoint(name: CheckpointName): void;
+export declare function downloadCheckpoint(bytes: number): void;

package/dist/provision/checkpoints.js

@@ -0,0 +1,23 @@
+const ENV = 'HANAMESH_PROVISION_KILL_AT';
+export function checkpoint(name) {
+    const want = process.env[ENV];
+    if (want === undefined || want !== name)
+        return;
+    killSelf(name);
+}
+export function downloadCheckpoint(bytes) {
+    const want = process.env[ENV];
+    if (want === undefined || !want.startsWith('download@'))
+        return;
+    const threshold = Number(want.slice('download@'.length));
+    if (Number.isFinite(threshold) && bytes >= threshold)
+        killSelf(want);
+}
+function killSelf(name) {
+    process.stderr.write(`[hanamesh-provision] kill injected at ${name}\n`);
+    process.kill(process.pid, 'SIGKILL');
+    // SIGKILL is not deliverable to ourselves synchronously on every platform; block until it lands.
+    for (;;) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
+    }
+}

package/dist/provision/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/dist/provision/cli.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isProvisionError } from './errors.js';
+import { platformKey } from './platform.js';
+import { plan, provision, remove, verify } from './provision.js';
+const USAGE = `hanamesh-provision — put a large file on this machine safely (no guessing, no PATH)
+
+  hanamesh-provision plan    <manifest.json> --root <dir> [--platform <key>] [--only <item>]...
+  hanamesh-provision install <manifest.json> --root <dir> [--source <id>]... [--only <item>]... [--force] [--platform <key>]
+  hanamesh-provision remove  <item> --root <dir>
+  hanamesh-provision verify  --root <dir>
+  hanamesh-provision platform
+
+Progress goes to stderr, the JSON result to stdout. Exit code 0 only when everything was done.
+`;
+class UsageError extends Error {
+}
+function parseArgs(argv) {
+    const out = { command: argv[0], positional: [], flags: new Map(), bools: new Set() };
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--force' || a === '--help' || a === '-h' || a === '--quiet') {
+            out.bools.add(a.replace(/^-+/, ''));
+            continue;
+        }
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+            const val = eq === -1 ? argv[++i] : a.slice(eq + 1);
+            if (val === undefined)
+                throw new UsageError(`missing value for --${key}`);
+            const list = out.flags.get(key) ?? [];
+            list.push(val);
+            out.flags.set(key, list);
+            continue;
+        }
+        out.positional.push(a);
+    }
+    return out;
+}
+function need(p, key) {
+    const v = p.flags.get(key)?.at(-1);
+    if (v === undefined)
+        throw new UsageError(`--${key} is required`);
+    return v;
+}
+function progressPrinter(quiet) {
+    let lastLine = '';
+    let lastTick = 0;
+    let lastPct = -1;
+    return (e) => {
+        if (quiet)
+            return;
+        let line = `[${e.item}] ${e.phase}`;
+        if (e.source !== undefined)
+            line += ` via ${e.source}`;
+        const isByteTick = e.phase === 'download' && e.bytes !== undefined && e.note === undefined;
+        if (isByteTick) {
+            // Throttle byte progress: at most every 500 ms or on a whole-percent change.
+            const pct = e.total !== undefined && e.total > 0 ? Math.floor((e.bytes / e.total) * 100) : -1;
+            const now = Date.now();
+            if (now - lastTick < 500 && pct === lastPct)
+                return;
+            lastTick = now;
+            lastPct = pct;
+            line += e.total !== undefined ? ` ${e.bytes}/${e.total} (${pct}%)` : ` ${e.bytes} bytes`;
+        }
+        else if (e.phase === 'extract' && e.bytes !== undefined) {
+            return; // per-entry ticks are noise on a terminal
+        }
+        if (e.note !== undefined)
+            line += ` — ${e.note}`;
+        if (line === lastLine)
+            return;
+        lastLine = line;
+        process.stderr.write(line + '\n');
+    };
+}
+export async function main(argv) {
+    let p;
+    try {
+        p = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (p.command === undefined || p.bools.has('help') || p.command === 'help') {
+        process.stdout.write(USAGE);
+        return p.command === undefined ? 2 : 0;
+    }
+    const quiet = p.bools.has('quiet');
+    try {
+        switch (p.command) {
+            case 'platform': {
+                process.stdout.write(JSON.stringify({ platform: platformKey() }) + '\n');
+                return 0;
+            }
+            case 'plan': {
+                const manifest = await readManifest(p.positional[0]);
+                const root = need(p, 'root');
+                const opts = { root };
+                const platform = p.flags.get('platform')?.at(-1);
+                if (platform !== undefined)
+                    opts.platform = platform;
+                const only = p.flags.get('only');
+                if (only !== undefined)
+                    opts.only = only;
+                const result = await plan(manifest, opts);
+                process.stdout.write(JSON.stringify({ root: path.resolve(root), platform: platform ?? platformKey(), plan: result }, null, 2) + '\n');
+                return 0;
+            }
+            case 'install': {
+                const manifest = await readManifest(p.positional[0]);
+                const root = need(p, 'root');
+                const opts = { root, onProgress: progressPrinter(quiet) };
+                const platform = p.flags.get('platform')?.at(-1);
+                if (platform !== undefined)
+                    opts.platform = platform;
+                const only = p.flags.get('only');
+                if (only !== undefined)
+                    opts.only = only;
+                const sources = p.flags.get('source');
+                if (sources !== undefined)
+                    opts.sourceOrder = sources;
+                if (p.bools.has('force'))
+                    opts.force = true;
+                const result = await provision(manifest, opts);
+                process.stdout.write(JSON.stringify({ root: path.resolve(root), platform: platform ?? platformKey(), results: result }, null, 2) + '\n');
+                return 0;
+            }
+            case 'remove': {
+                const item = p.positional[0];
+                if (item === undefined)
+                    throw new UsageError('remove needs an <item>');
+                const result = await remove(item, { root: need(p, 'root') });
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+                return 0;
+            }
+            case 'verify': {
+                const result = await verify({ root: need(p, 'root') });
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+                return result.ok ? 0 : 1;
+            }
+            default:
+                process.stderr.write(`unknown command "${p.command}"\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`${err.message}\n${USAGE}`);
+            return 2;
+        }
+        if (isProvisionError(err)) {
+            process.stderr.write(`error ${err.code}${err.item !== undefined ? ` [${err.item}]` : ''}: ${err.message}\n`);
+            process.stdout.write(JSON.stringify({ error: { code: err.code, item: err.item ?? null, message: err.message } }) + '\n');
+            return 1;
+        }
+        process.stderr.write(`error: ${err.message}\n`);
+        process.stdout.write(JSON.stringify({ error: { code: 'E_INTERNAL', message: err.message } }) + '\n');
+        return 1;
+    }
+}
+async function readManifest(file) {
+    if (file === undefined)
+        throw new UsageError('a <manifest.json> path is required');
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+}

package/dist/provision/download.d.ts

@@ -0,0 +1,21 @@
+import type { ProgressEvent } from './types.js';
+export interface DownloadCandidate {
+    source: string;
+    kind: 'https' | 'file';
+    url: URL;
+}
+export interface DownloadOptions {
+    item: string;
+    /** Final path of the archive (inside staging). `.part` / `.part.json` live next to it. */
+    file: string;
+    expectedSha256: string;
+    expectedSize?: number | undefined;
+    onProgress?: ((e: ProgressEvent) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Try each candidate in order until one yields a file whose sha256 equals `expectedSha256`.
+ * A transport failure keeps the `.part` for a later resume; a digest mismatch deletes the file.
+ * Returns the source id that succeeded.
+ */
+export declare function downloadVerified(candidates: DownloadCandidate[], opts: DownloadOptions): Promise<string>;

package/dist/provision/download.js

@@ -0,0 +1,242 @@
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkpoint, downloadCheckpoint } from './checkpoints.js';
+import { ProvisionError } from './errors.js';
+import { exists, fsyncDir, readJson, sha256File, writeFileAtomic } from './fsutil.js';
+import { redactUrl } from './paths.js';
+const MAX_REDIRECTS = 10;
+function abortError(item) {
+    return new ProvisionError('E_ABORTED', 'aborted by caller', { item });
+}
+/**
+ * Try each candidate in order until one yields a file whose sha256 equals `expectedSha256`.
+ * A transport failure keeps the `.part` for a later resume; a digest mismatch deletes the file.
+ * Returns the source id that succeeded.
+ */
+export async function downloadVerified(candidates, opts) {
+    const { item, file, expectedSha256, onProgress } = opts;
+    let lastError;
+    if (await exists(file)) {
+        // A fully downloaded archive from an earlier run; trust it only if the digest matches.
+        if ((await sha256File(file)) === expectedSha256) {
+            onProgress?.({ item, phase: 'verify', note: 'reused' });
+            const meta = await readJson(file + '.json');
+            return meta?.url !== undefined ? candidates.find((c) => redactUrl(c.url.toString()) === meta.url)?.source ?? 'cached' : 'cached';
+        }
+        await fs.rm(file, { force: true });
+    }
+    for (const candidate of candidates) {
+        if (opts.signal?.aborted)
+            throw abortError(item);
+        try {
+            await downloadOne(candidate, opts);
+        }
+        catch (err) {
+            if (err instanceof ProvisionError && err.code === 'E_ABORTED')
+                throw err;
+            lastError = err instanceof ProvisionError ? err : new ProvisionError('E_DOWNLOAD', `download failed from ${candidate.source}: ${err.message}`, { item, cause: err });
+            onProgress?.({ item, phase: 'download', source: candidate.source, note: `source-failed: ${lastError.message}` });
+            continue;
+        }
+        onProgress?.({ item, phase: 'verify', source: candidate.source });
+        const actual = await sha256File(file);
+        /* MUTATION:sha256-compare */
+        if (actual !== expectedSha256) {
+            await fs.rm(file, { force: true });
+            await fs.rm(file + '.json', { force: true });
+            lastError = new ProvisionError('E_SHA256', `sha256 mismatch from source ${candidate.source}: expected ${expectedSha256}, got ${actual}`, { item });
+            onProgress?.({ item, phase: 'verify', source: candidate.source, note: 'sha256-mismatch' });
+            continue;
+        }
+        checkpoint('after-sha256');
+        return candidate.source;
+    }
+    throw lastError ?? new ProvisionError('E_SOURCE', 'no download candidates', { item });
+}
+async function downloadOne(candidate, opts) {
+    const { item, file, onProgress } = opts;
+    const part = file + '.part';
+    const metaFile = file + '.part.json';
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const cleanUrl = redactUrl(candidate.url.toString());
+    if (candidate.kind === 'file') {
+        await copyFromFileUrl(candidate, part, opts);
+    }
+    else {
+        await fetchHttps(candidate, part, metaFile, opts);
+    }
+    // Durability point of the download: bytes on disk, then the atomic rename to the final name.
+    const h = await fs.open(part, 'r+');
+    try {
+        await h.sync();
+    }
+    finally {
+        await h.close();
+    }
+    await fs.rename(part, file);
+    await writeFileAtomic(file + '.json', JSON.stringify({ url: cleanUrl, source: candidate.source }));
+    await fs.rm(metaFile, { force: true });
+    await fsyncDir(path.dirname(file));
+    checkpoint('after-download');
+    onProgress?.({ item, phase: 'download', source: candidate.source, note: 'complete' });
+}
+async function copyFromFileUrl(candidate, part, opts) {
+    const { item, onProgress, signal } = opts;
+    const src = fileURLToPath(candidate.url);
+    let total;
+    try {
+        total = (await fs.stat(src)).size;
+    }
+    catch (err) {
+        throw new ProvisionError('E_DOWNLOAD', `file source unreadable: ${redactUrl(candidate.url.toString())}`, { item, cause: err });
+    }
+    const out = await fs.open(part, 'w');
+    let bytes = 0;
+    try {
+        for await (const chunk of createReadStream(src, { highWaterMark: 1 << 20 })) {
+            if (signal?.aborted)
+                throw abortError(item);
+            await out.write(chunk);
+            bytes += chunk.length;
+            onProgress?.({ item, phase: 'download', source: candidate.source, bytes, total });
+            downloadCheckpoint(bytes);
+        }
+    }
+    finally {
+        await out.close();
+    }
+}
+async function fetchHttps(candidate, part, metaFile, opts) {
+    const { item, onProgress, signal } = opts;
+    const cleanUrl = redactUrl(candidate.url.toString());
+    let offset = 0;
+    let meta = await readJson(metaFile);
+    if (meta !== undefined && meta.url === cleanUrl && (await exists(part))) {
+        offset = (await fs.stat(part)).size;
+    }
+    else {
+        meta = undefined;
+        await fs.rm(part, { force: true });
+        await fs.rm(metaFile, { force: true });
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const headers = { 'user-agent': 'hanamesh-provision/0.1', accept: '*/*' };
+        if (offset > 0) {
+            headers['range'] = `bytes=${offset}-`;
+            if (meta?.etag !== undefined)
+                headers['if-range'] = meta.etag;
+        }
+        const res = await followRedirects(candidate.url, headers, signal, item);
+        if (res.status === 416) {
+            // Server says our offset is past the end: our part is unusable.
+            await res.body?.cancel();
+            await fs.rm(part, { force: true });
+            await fs.rm(metaFile, { force: true });
+            offset = 0;
+            meta = undefined;
+            continue;
+        }
+        if (res.status !== 200 && res.status !== 206) {
+            await res.body?.cancel();
+            throw new ProvisionError('E_DOWNLOAD', `HTTP ${res.status} from ${cleanUrl}`, { item });
+        }
+        const etag = res.headers.get('etag') ?? undefined;
+        let total;
+        if (res.status === 206) {
+            const cr = /^bytes (\d+)-(\d+)\/(\d+|\*)$/.exec(res.headers.get('content-range') ?? '');
+            if (cr === null || Number(cr[1]) !== offset) {
+                await res.body?.cancel();
+                throw new ProvisionError('E_DOWNLOAD', `unexpected Content-Range for resume from ${cleanUrl}`, { item });
+            }
+            if (cr[3] !== '*')
+                total = Number(cr[3]);
+            onProgress?.({ item, phase: 'download', source: candidate.source, bytes: offset, total, note: `resume@${offset}` });
+        }
+        else {
+            // Server ignored Range (or fresh start): begin from zero.
+            if (offset > 0)
+                onProgress?.({ item, phase: 'download', source: candidate.source, note: 'range-unsupported' });
+            offset = 0;
+            const len = res.headers.get('content-length');
+            if (len !== null)
+                total = Number(len);
+        }
+        if (total === undefined)
+            total = opts.expectedSize;
+        const newMeta = { url: cleanUrl };
+        if (etag !== undefined)
+            newMeta.etag = etag;
+        if (total !== undefined)
+            newMeta.total = total;
+        await writeFileAtomic(metaFile, JSON.stringify(newMeta));
+        meta = newMeta;
+        if (res.body === null)
+            throw new ProvisionError('E_DOWNLOAD', `empty body from ${cleanUrl}`, { item });
+        const out = await fs.open(part, offset > 0 ? 'r+' : 'w');
+        let bytes = offset;
+        try {
+            if (offset > 0)
+                await out.truncate(offset);
+            const reader = res.body.getReader();
+            for (;;) {
+                if (signal?.aborted) {
+                    await reader.cancel().catch(() => undefined);
+                    throw abortError(item);
+                }
+                let step;
+                try {
+                    step = await reader.read();
+                }
+                catch (err) {
+                    if (signal?.aborted)
+                        throw abortError(item);
+                    throw new ProvisionError('E_DOWNLOAD', `connection lost at byte ${bytes} from ${cleanUrl}`, { item, cause: err });
+                }
+                if (step.done)
+                    break;
+                await out.write(step.value, 0, step.value.length, bytes);
+                bytes += step.value.length;
+                onProgress?.({ item, phase: 'download', source: candidate.source, bytes, total });
+                downloadCheckpoint(bytes);
+            }
+        }
+        finally {
+            await out.close();
+        }
+        if (total !== undefined && bytes !== total) {
+            throw new ProvisionError('E_DOWNLOAD', `short read: got ${bytes} of ${total} bytes from ${cleanUrl}`, { item });
+        }
+        return;
+    }
+    throw new ProvisionError('E_DOWNLOAD', `could not establish a download from ${cleanUrl}`, { item });
+}
+async function followRedirects(start, headers, signal, item) {
+    let url = start;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (url.protocol !== 'https:') {
+            /* MUTATION:https-only */
+            throw new ProvisionError('E_SOURCE', `refusing non-https URL ${redactUrl(url.toString())}`, { item });
+        }
+        let res;
+        try {
+            res = await fetch(url, { headers, redirect: 'manual', signal: signal ?? null });
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw abortError(item);
+            throw new ProvisionError('E_DOWNLOAD', `network error for ${redactUrl(url.toString())}: ${err.message}`, { item, cause: err });
+        }
+        if ([301, 302, 303, 307, 308].includes(res.status)) {
+            const loc = res.headers.get('location');
+            await res.body?.cancel();
+            if (loc === null)
+                throw new ProvisionError('E_DOWNLOAD', `redirect without Location from ${redactUrl(url.toString())}`, { item });
+            url = new URL(loc, url);
+            continue;
+        }
+        return res;
+    }
+    throw new ProvisionError('E_DOWNLOAD', `too many redirects from ${redactUrl(start.toString())}`, { item });
+}

package/dist/provision/errors.d.ts

@@ -0,0 +1,11 @@
+export type ProvisionErrorCode = 'E_MANIFEST' | 'E_SOURCE' | 'E_DOWNLOAD' | 'E_SHA256' | 'E_ARCHIVE' | 'E_UNSAFE_PATH' | 'E_VERIFY' | 'E_PROMOTE' | 'E_LEDGER' | 'E_NOT_INSTALLED' | 'E_ABORTED' | 'E_UNSUPPORTED';
+export declare class ProvisionError extends Error {
+    readonly name = "ProvisionError";
+    readonly code: ProvisionErrorCode;
+    readonly item: string | undefined;
+    constructor(code: ProvisionErrorCode, message: string, options?: {
+        item?: string;
+        cause?: unknown;
+    });
+}
+export declare function isProvisionError(err: unknown): err is ProvisionError;

package/dist/provision/errors.js

@@ -0,0 +1,13 @@
+export class ProvisionError extends Error {
+    name = 'ProvisionError';
+    code;
+    item;
+    constructor(code, message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.item = options?.item;
+    }
+}
+export function isProvisionError(err) {
+    return err instanceof ProvisionError;
+}

package/dist/provision/extract.d.ts

@@ -0,0 +1,17 @@
+import type { ArchiveKind, OwnedFile, OwnedSymlink, ProgressEvent } from './types.js';
+export interface ExtractOptions {
+    item: string;
+    strip?: number | undefined;
+    onProgress?: ((e: ProgressEvent) => void) | undefined;
+}
+export interface ExtractedTree {
+    files: OwnedFile[];
+    dirs: string[];
+    symlinks: OwnedSymlink[];
+}
+/**
+ * Extract an archive into `dest` (which must be empty or absent). Every entry is checked
+ * before anything touches the disk: no absolute paths, no `..`, no symlink that resolves
+ * outside `dest`, no write through a symlinked ancestor. Returns the ownership lists.
+ */
+export declare function extractArchive(kind: ArchiveKind, archive: string, dest: string, opts: ExtractOptions): Promise<ExtractedTree>;