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

package/dist/provision/extract.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ProvisionError } from './errors.js';
+import { fsyncDir, sha256File } from './fsutil.js';
+import { isInside, safeEntrySegments, safeLinkTarget } from './paths.js';
+import { readTarGz } from './tar.js';
+import { readZip } from './zip.js';
+function unsafe(item, what, name) {
+    return new ProvisionError('E_UNSAFE_PATH', `refusing archive entry (${what}): ${JSON.stringify(name)}`, { item });
+}
+/**
+ * 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 async function extractArchive(kind, archive, dest, opts) {
+    const { item } = opts;
+    const strip = opts.strip ?? 0;
+    const destAbs = path.resolve(dest);
+    await fs.mkdir(destAbs, { recursive: true });
+    const files = [];
+    const dirs = new Set();
+    const symlinks = [];
+    const symlinkPaths = new Set();
+    const filePaths = new Map(); // rel -> abs (for hardlinks)
+    let entries = 0;
+    const entryStream = kind === 'tar.gz' ? readTarGz(archive, item) : readZip(archive, item);
+    const ensureNoSymlinkAncestor = (segments, name) => {
+        for (let i = 1; i < segments.length; i++) {
+            if (symlinkPaths.has(segments.slice(0, i).join('/')))
+                throw unsafe(item, 'write through symlink', name);
+        }
+    };
+    const resolveDest = (segments, name) => {
+        const abs = path.join(destAbs, ...segments);
+        if (!isInside(destAbs, abs) || abs === destAbs)
+            throw unsafe(item, 'escapes destination', name);
+        return abs;
+    };
+    for await (const entry of entryStream) {
+        entries++;
+        const rawSegments = safeEntrySegments(entry.name);
+        if (rawSegments === null)
+            throw unsafe(item, 'absolute or traversal path', entry.name);
+        if (rawSegments.length <= strip) {
+            // Stripped away entirely (e.g. the top-level directory). Body drained by the reader.
+            for await (const _ of entry.body) {
+                /* drain */
+            }
+            continue;
+        }
+        const segments = rawSegments.slice(strip);
+        const rel = segments.join('/');
+        ensureNoSymlinkAncestor(segments, entry.name);
+        const abs = resolveDest(segments, entry.name);
+        switch (entry.kind) {
+            case 'dir': {
+                await fs.mkdir(abs, { recursive: true });
+                dirs.add(rel);
+                break;
+            }
+            case 'file': {
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                for (let i = 1; i < segments.length; i++)
+                    dirs.add(segments.slice(0, i).join('/'));
+                const mode = (entry.mode & 0o777) || 0o644;
+                const handle = await fs.open(abs, 'wx', mode);
+                const hash = createHash('sha256');
+                let size = 0;
+                try {
+                    for await (const chunk of entry.body) {
+                        hash.update(chunk);
+                        await handle.write(chunk);
+                        size += chunk.length;
+                    }
+                    // No per-file fsync: it costs ~20 s for a Node tree on APFS and buys nothing against
+                    // process termination (the level X02 proves). Power-loss corruption is caught by
+                    // `verify` through the per-file digests in the ownership manifest.
+                }
+                finally {
+                    await handle.close();
+                }
+                if (process.platform !== 'win32')
+                    await fs.chmod(abs, mode);
+                files.push({ path: rel, size, sha256: hash.digest('hex'), mode });
+                filePaths.set(rel, abs);
+                break;
+            }
+            case 'symlink': {
+                const target = entry.linkTarget ?? '';
+                const resolved = safeLinkTarget(segments, target);
+                /* MUTATION:symlink-escape */
+                if (resolved === null)
+                    throw unsafe(item, `symlink escapes destination (-> ${target})`, entry.name);
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                for (let i = 1; i < segments.length; i++)
+                    dirs.add(segments.slice(0, i).join('/'));
+                await fs.symlink(target.split(/[\\/]+/).join(path.sep), abs);
+                symlinks.push({ path: rel, target });
+                symlinkPaths.add(rel);
+                break;
+            }
+            case 'hardlink': {
+                const targetSegments = safeEntrySegments(entry.linkTarget ?? '');
+                if (targetSegments === null || targetSegments.length <= strip)
+                    throw unsafe(item, 'hardlink target', entry.name);
+                const targetRel = targetSegments.slice(strip).join('/');
+                const src = filePaths.get(targetRel);
+                if (src === undefined)
+                    throw unsafe(item, 'hardlink to unknown file', entry.name);
+                await fs.mkdir(path.dirname(abs), { recursive: true });
+                await fs.copyFile(src, abs);
+                const st = await fs.stat(abs);
+                files.push({ path: rel, size: st.size, sha256: await sha256File(abs), mode: st.mode & 0o777 });
+                filePaths.set(rel, abs);
+                break;
+            }
+        }
+        opts.onProgress?.({ item, phase: 'extract', bytes: entries });
+    }
+    await fsyncDir(destAbs);
+    return { files, dirs: [...dirs].sort(), symlinks };
+}

package/dist/provision/fsutil.d.ts

@@ -0,0 +1,8 @@
+export declare function sha256File(file: string): Promise<string>;
+/** temp + fsync + rename. The data is durable and the path is never observed half-written. */
+export declare function writeFileAtomic(file: string, data: string | Uint8Array, mode?: number): Promise<void>;
+/** Best-effort directory fsync (no-op where the platform refuses to open directories). */
+export declare function fsyncDir(dir: string): Promise<void>;
+export declare function exists(p: string): Promise<boolean>;
+export declare function readJson<T>(file: string): Promise<T | undefined>;
+export declare function rmrf(p: string): Promise<void>;

package/dist/provision/fsutil.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+export async function sha256File(file) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(file), hash);
+    return hash.digest('hex');
+}
+/** temp + fsync + rename. The data is durable and the path is never observed half-written. */
+export async function writeFileAtomic(file, data, mode) {
+    const dir = path.dirname(file);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now().toString(36)}.tmp`);
+    const handle = await fs.open(tmp, 'w', mode ?? 0o644);
+    try {
+        await handle.writeFile(data);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(tmp, file);
+    await fsyncDir(dir);
+}
+/** Best-effort directory fsync (no-op where the platform refuses to open directories). */
+export async function fsyncDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    let handle;
+    try {
+        handle = await fs.open(dir, 'r');
+    }
+    catch {
+        return;
+    }
+    try {
+        await handle.sync();
+    }
+    catch {
+        /* some filesystems reject fsync on directories; the rename itself is still atomic */
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function exists(p) {
+    try {
+        await fs.lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readJson(file) {
+    let text;
+    try {
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    return JSON.parse(text);
+}
+export async function rmrf(p) {
+    await fs.rm(p, { recursive: true, force: true, maxRetries: 3 });
+}

package/dist/provision/index.d.ts

@@ -0,0 +1,7 @@
+export { platformKey } from './platform.js';
+export { plan, provision, remove, verify } from './provision.js';
+export { ledger, ledgerPath, ownershipPath, targetPath } from './ledger.js';
+export { validateManifest } from './manifest.js';
+export { ProvisionError, isProvisionError, type ProvisionErrorCode } from './errors.js';
+export { stripVerbatimPrefix, toVerbatimPath, externalPath, isInside, safeEntrySegments, safeLinkTarget, redactUrl } from './paths.js';
+export type * from './types.js';

package/dist/provision/index.js

@@ -0,0 +1,6 @@
+export { platformKey } from './platform.js';
+export { plan, provision, remove, verify } from './provision.js';
+export { ledger, ledgerPath, ownershipPath, targetPath } from './ledger.js';
+export { validateManifest } from './manifest.js';
+export { ProvisionError, isProvisionError } from './errors.js';
+export { stripVerbatimPrefix, toVerbatimPath, externalPath, isInside, safeEntrySegments, safeLinkTarget, redactUrl } from './paths.js';

package/dist/provision/ledger.d.ts

@@ -0,0 +1,14 @@
+import type { Ledger, OwnershipManifest } from './types.js';
+export declare const PROVISION_DIR = ".provision";
+export declare function provisionDir(root: string): string;
+export declare function ledgerPath(root: string): string;
+export declare function stagingDir(root: string, item: string, sha256: string): string;
+export declare function trashRoot(root: string): string;
+export declare function pendingDir(root: string): string;
+export declare function targetPath(root: string, installTo: string): string;
+export declare function ownershipPath(target: string): string;
+/** Read `<root>/.provision/ledger.json`; an absent ledger is an empty one. */
+export declare function ledger(root: string): Promise<Ledger>;
+/** Atomic (temp + fsync + rename) ledger write. Single writer by contract. */
+export declare function writeLedger(root: string, data: Ledger): Promise<void>;
+export declare function readOwnership(target: string): Promise<OwnershipManifest | undefined>;

package/dist/provision/ledger.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { ProvisionError } from './errors.js';
+import { readJson, writeFileAtomic } from './fsutil.js';
+import { externalPath } from './paths.js';
+export const PROVISION_DIR = '.provision';
+export function provisionDir(root) {
+    return path.join(externalPath(root), PROVISION_DIR);
+}
+export function ledgerPath(root) {
+    return path.join(provisionDir(root), 'ledger.json');
+}
+export function stagingDir(root, item, sha256) {
+    return path.join(provisionDir(root), 'staging', `${item}-${sha256.slice(0, 12)}`);
+}
+export function trashRoot(root) {
+    return path.join(provisionDir(root), 'trash');
+}
+export function pendingDir(root) {
+    return path.join(provisionDir(root), 'pending');
+}
+export function targetPath(root, installTo) {
+    return path.join(externalPath(root), ...installTo.split('/'));
+}
+export function ownershipPath(target) {
+    return target + '.manifest.json';
+}
+/** Read `<root>/.provision/ledger.json`; an absent ledger is an empty one. */
+export async function ledger(root) {
+    const data = await readJson(ledgerPath(root));
+    if (data === undefined)
+        return { schema: 1, items: {} };
+    if (typeof data !== 'object' || data === null || data.schema !== 1 || typeof data.items !== 'object') {
+        throw new ProvisionError('E_LEDGER', `ledger corrupt: ${ledgerPath(root)}`);
+    }
+    return data;
+}
+/** Atomic (temp + fsync + rename) ledger write. Single writer by contract. */
+export async function writeLedger(root, data) {
+    await writeFileAtomic(ledgerPath(root), JSON.stringify(data, null, 2) + '\n');
+}
+export async function readOwnership(target) {
+    const data = await readJson(ownershipPath(target));
+    if (data === undefined)
+        return undefined;
+    const m = data;
+    if (m.schema !== 1 || typeof m.item !== 'string' || !Array.isArray(m.files)) {
+        throw new ProvisionError('E_LEDGER', `ownership manifest corrupt: ${ownershipPath(target)}`);
+    }
+    return m;
+}

package/dist/provision/manifest.d.ts

@@ -0,0 +1,11 @@
+import type { Manifest, PlatformAsset } from './types.js';
+/** Only `https:` and `file:` are ever accepted, anywhere a URL appears. */
+export declare function assertAllowedUrl(u: string, what: string): URL;
+/** Validate an untrusted manifest object. Throws `ProvisionError('E_MANIFEST')`. */
+export declare function validateManifest(raw: unknown): Manifest;
+/** Candidate download URLs for one asset, in the order they must be tried. */
+export declare function resolveCandidates(manifest: Manifest, asset: PlatformAsset, sourceOrder?: string[]): Array<{
+    source: string;
+    kind: 'https' | 'file';
+    url: URL;
+}>;

package/dist/provision/manifest.js

@@ -0,0 +1,171 @@
+import { ProvisionError } from './errors.js';
+import { redactUrl } from './paths.js';
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function fail(msg, item) {
+    throw new ProvisionError('E_MANIFEST', msg, item === undefined ? undefined : { item });
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Only `https:` and `file:` are ever accepted, anywhere a URL appears. */
+export function assertAllowedUrl(u, what) {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        fail(`${what}: not a valid URL: ${redactUrl(u)}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'file:') {
+        fail(`${what}: only https: and file: are accepted, got ${url.protocol} (${redactUrl(u)})`);
+    }
+    return url;
+}
+function validateSource(raw, index) {
+    if (!isRecord(raw))
+        fail(`sources[${index}] must be an object`);
+    const { id, kind, base } = raw;
+    if (typeof id !== 'string' || !ID_RE.test(id))
+        fail(`sources[${index}].id invalid`);
+    if (kind !== 'https' && kind !== 'file')
+        fail(`sources[${index}].kind must be "https" or "file"`);
+    if (typeof base !== 'string')
+        fail(`sources[${index}].base must be a string`);
+    const url = assertAllowedUrl(base, `sources[${index}].base`);
+    if ((kind === 'https' && url.protocol !== 'https:') || (kind === 'file' && url.protocol !== 'file:')) {
+        fail(`sources[${index}]: kind "${kind}" does not match base protocol ${url.protocol}`);
+    }
+    return { id, kind, base };
+}
+function validatePlatformAsset(raw, itemId, key) {
+    if (!isRecord(raw))
+        fail(`items[${itemId}].platforms[${key}] must be an object`, itemId);
+    const { asset, sha256, size, strip, url } = raw;
+    if (typeof asset !== 'string' || asset.length === 0)
+        fail(`items[${itemId}].platforms[${key}].asset required`, itemId);
+    if (asset.startsWith('/') || asset.includes('..'))
+        fail(`items[${itemId}].platforms[${key}].asset must be a relative name`, itemId);
+    /* MUTATION:manifest-sha256-required */
+    if (typeof sha256 !== 'string' || !SHA256_RE.test(sha256)) {
+        fail(`items[${itemId}].platforms[${key}].sha256 missing or not 64 lower-case hex chars — refusing to guess`, itemId);
+    }
+    const out = { asset, sha256 };
+    if (size !== undefined) {
+        if (typeof size !== 'number' || !Number.isInteger(size) || size < 0)
+            fail(`items[${itemId}].platforms[${key}].size invalid`, itemId);
+        out.size = size;
+    }
+    if (strip !== undefined) {
+        if (typeof strip !== 'number' || !Number.isInteger(strip) || strip < 0)
+            fail(`items[${itemId}].platforms[${key}].strip invalid`, itemId);
+        out.strip = strip;
+    }
+    if (url !== undefined) {
+        if (typeof url !== 'string')
+            fail(`items[${itemId}].platforms[${key}].url must be a string`, itemId);
+        assertAllowedUrl(url, `items[${itemId}].platforms[${key}].url`);
+        out.url = url;
+    }
+    return out;
+}
+function validateItem(raw, index, seen) {
+    if (!isRecord(raw))
+        fail(`items[${index}] must be an object`);
+    const { id, version, kind, installTo, platforms, verify } = raw;
+    if (typeof id !== 'string' || !ID_RE.test(id))
+        fail(`items[${index}].id invalid`);
+    if (seen.has(id))
+        fail(`duplicate item id "${id}"`, id);
+    seen.add(id);
+    if (typeof version !== 'string' || version.length === 0)
+        fail(`items[${id}].version required`, id);
+    if (kind !== 'tar.gz' && kind !== 'zip')
+        fail(`items[${id}].kind must be "tar.gz" or "zip" (.tar.xz is not supported)`, id);
+    if (typeof installTo !== 'string' || installTo.length === 0)
+        fail(`items[${id}].installTo required`, id);
+    const segs = installTo.split('/').filter((s) => s.length > 0);
+    if (segs.length === 0 || installTo.startsWith('/') || /^[A-Za-z]:/.test(installTo) || installTo.includes('\\') || segs.some((s) => s === '..' || s === '.')) {
+        fail(`items[${id}].installTo must be a relative POSIX path inside root`, id);
+    }
+    if (segs[0] === '.provision')
+        fail(`items[${id}].installTo may not live under .provision`, id);
+    if (!isRecord(platforms))
+        fail(`items[${id}].platforms must be an object`, id);
+    const outPlatforms = {};
+    for (const [key, val] of Object.entries(platforms))
+        outPlatforms[key] = validatePlatformAsset(val, id, key);
+    const item = { id, version, kind, installTo: segs.join('/'), platforms: outPlatforms };
+    if (verify !== undefined) {
+        if (!isRecord(verify))
+            fail(`items[${id}].verify must be an object`, id);
+        const { exec, args, expect, timeoutMs } = verify;
+        if (typeof exec !== 'string' || exec.length === 0 || exec.startsWith('/') || exec.includes('..'))
+            fail(`items[${id}].verify.exec must be a relative path inside the tree`, id);
+        const v = { exec };
+        if (args !== undefined) {
+            if (!Array.isArray(args) || !args.every((a) => typeof a === 'string'))
+                fail(`items[${id}].verify.args must be string[]`, id);
+            v.args = args;
+        }
+        if (expect !== undefined) {
+            if (typeof expect !== 'string')
+                fail(`items[${id}].verify.expect must be a string`, id);
+            v.expect = expect;
+        }
+        if (timeoutMs !== undefined) {
+            if (typeof timeoutMs !== 'number' || timeoutMs <= 0)
+                fail(`items[${id}].verify.timeoutMs invalid`, id);
+            v.timeoutMs = timeoutMs;
+        }
+        item.verify = v;
+    }
+    return item;
+}
+/** Validate an untrusted manifest object. Throws `ProvisionError('E_MANIFEST')`. */
+export function validateManifest(raw) {
+    if (!isRecord(raw))
+        fail('manifest must be an object');
+    if (raw['schema'] !== 1)
+        fail('manifest.schema must be 1');
+    if (!Array.isArray(raw['sources']))
+        fail('manifest.sources must be an array');
+    if (!Array.isArray(raw['items']))
+        fail('manifest.items must be an array');
+    const sourceIds = new Set();
+    const sources = raw['sources'].map((s, i) => {
+        const src = validateSource(s, i);
+        if (sourceIds.has(src.id))
+            fail(`duplicate source id "${src.id}"`);
+        sourceIds.add(src.id);
+        return src;
+    });
+    const seen = new Set();
+    const items = raw['items'].map((it, i) => validateItem(it, i, seen));
+    return { schema: 1, sources, items };
+}
+/** Candidate download URLs for one asset, in the order they must be tried. */
+export function resolveCandidates(manifest, asset, sourceOrder) {
+    if (asset.url !== undefined) {
+        const url = assertAllowedUrl(asset.url, 'asset.url');
+        return [{ source: 'url', kind: url.protocol === 'file:' ? 'file' : 'https', url }];
+    }
+    let sources = manifest.sources;
+    if (sourceOrder !== undefined) {
+        const byId = new Map(sources.map((s) => [s.id, s]));
+        sources = sourceOrder.map((id) => {
+            const s = byId.get(id);
+            if (s === undefined)
+                throw new ProvisionError('E_SOURCE', `unknown source id "${id}"`);
+            return s;
+        });
+    }
+    if (sources.length === 0)
+        throw new ProvisionError('E_SOURCE', 'no sources available for asset');
+    return sources.map((s) => {
+        const base = s.base.endsWith('/') ? s.base : s.base + '/';
+        const url = new URL(asset.asset, base);
+        assertAllowedUrl(url.toString(), `source ${s.id}`);
+        return { source: s.id, kind: s.kind, url };
+    });
+}

package/dist/provision/paths.d.ts

@@ -0,0 +1,27 @@
+/** `\\?\C:\x` → `C:\x`; `\\?\UNC\srv\share` → `\\srv\share`. No-op for other paths. */
+export declare function stripVerbatimPrefix(p: string): string;
+/** Inverse of {@link stripVerbatimPrefix} for absolute Windows paths (used only for opening long paths). */
+export declare function toVerbatimPath(p: string): string;
+/**
+ * The form of a path this library exposes to callers: absolute, normalised,
+ * and on Windows never carrying the `\\?\` prefix (which breaks PATH search and
+ * string comparison in every consumer that gets it).
+ */
+export declare function externalPath(p: string, platform?: NodeJS.Platform): string;
+/** True when `child` is `parent` or lies strictly inside it (lexically, after resolution). */
+export declare function isInside(parent: string, child: string): boolean;
+/**
+ * Split an archive entry name into safe path segments, or return null when the
+ * entry must be refused (absolute, drive-qualified, `..`, NUL, empty).
+ * Both `/` and `\` are treated as separators because zip writers disagree.
+ */
+export declare function safeEntrySegments(name: string): string[] | null;
+/**
+ * Resolve a symlink target relative to the entry's directory and check that it
+ * stays inside the tree. Returns the normalised relative POSIX target path of the
+ * link destination, or null when the link would escape.
+ */
+export declare function safeLinkTarget(entrySegments: string[], target: string): string | null;
+/** Redact the query/fragment of a URL for logs (tokens live there). */
+export declare function redactUrl(u: string): string;
+export declare const toPosix: (p: string) => string;

package/dist/provision/paths.js

@@ -0,0 +1,95 @@
+import path from 'node:path';
+/** `\\?\C:\x` → `C:\x`; `\\?\UNC\srv\share` → `\\srv\share`. No-op for other paths. */
+export function stripVerbatimPrefix(p) {
+    if (p.startsWith('\\\\?\\UNC\\'))
+        return '\\\\' + p.slice('\\\\?\\UNC\\'.length);
+    if (p.startsWith('\\\\?\\'))
+        return p.slice('\\\\?\\'.length);
+    return p;
+}
+/** Inverse of {@link stripVerbatimPrefix} for absolute Windows paths (used only for opening long paths). */
+export function toVerbatimPath(p) {
+    if (p.startsWith('\\\\?\\'))
+        return p;
+    if (/^[A-Za-z]:\\/.test(p))
+        return '\\\\?\\' + p;
+    if (p.startsWith('\\\\'))
+        return '\\\\?\\UNC\\' + p.slice(2);
+    return p;
+}
+/**
+ * The form of a path this library exposes to callers: absolute, normalised,
+ * and on Windows never carrying the `\\?\` prefix (which breaks PATH search and
+ * string comparison in every consumer that gets it).
+ */
+export function externalPath(p, platform = process.platform) {
+    const stripped = platform === 'win32' ? stripVerbatimPrefix(p) : p;
+    return path.resolve(stripped);
+}
+/** True when `child` is `parent` or lies strictly inside it (lexically, after resolution). */
+export function isInside(parent, child) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    if (rel === '')
+        return true;
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+const WINDOWS_ABS = /^[A-Za-z]:([\\/]|$)/;
+/**
+ * Split an archive entry name into safe path segments, or return null when the
+ * entry must be refused (absolute, drive-qualified, `..`, NUL, empty).
+ * Both `/` and `\` are treated as separators because zip writers disagree.
+ */
+export function safeEntrySegments(name) {
+    if (name.length === 0 || name.includes('\0'))
+        return null;
+    if (name.startsWith('/') || name.startsWith('\\'))
+        return null;
+    if (WINDOWS_ABS.test(name))
+        return null;
+    const segments = name.split(/[\\/]+/).filter((s) => s.length > 0 && s !== '.');
+    /* MUTATION:path-traversal */
+    if (segments.some((s) => s === '..'))
+        return null;
+    return segments;
+}
+/**
+ * Resolve a symlink target relative to the entry's directory and check that it
+ * stays inside the tree. Returns the normalised relative POSIX target path of the
+ * link destination, or null when the link would escape.
+ */
+export function safeLinkTarget(entrySegments, target) {
+    if (target.length === 0 || target.includes('\0'))
+        return null;
+    if (target.startsWith('/') || target.startsWith('\\') || WINDOWS_ABS.test(target))
+        return null;
+    const dir = entrySegments.slice(0, -1);
+    const parts = target.split(/[\\/]+/).filter((s) => s.length > 0 && s !== '.');
+    const stack = [...dir];
+    for (const part of parts) {
+        if (part === '..') {
+            if (stack.length === 0)
+                return null;
+            stack.pop();
+        }
+        else {
+            stack.push(part);
+        }
+    }
+    return stack.join('/');
+}
+/** Redact the query/fragment of a URL for logs (tokens live there). */
+export function redactUrl(u) {
+    try {
+        const url = new URL(u);
+        url.search = '';
+        url.hash = '';
+        url.username = '';
+        url.password = '';
+        return url.toString();
+    }
+    catch {
+        const q = u.search(/[?#]/);
+        return q === -1 ? u : u.slice(0, q);
+    }
+}
+export const toPosix = (p) => p.split(path.sep).join('/');

package/dist/provision/platform.d.ts

@@ -0,0 +1,6 @@
+import type { PlatformKey } from './types.js';
+/**
+ * Normalised platform key. Only `process.platform` and `process.arch` are consulted;
+ * nothing installed on the host is ever probed.
+ */
+export declare function platformKey(platform?: NodeJS.Platform, arch?: string): PlatformKey;

package/dist/provision/platform.js

@@ -0,0 +1,7 @@
+/**
+ * Normalised platform key. Only `process.platform` and `process.arch` are consulted;
+ * nothing installed on the host is ever probed.
+ */
+export function platformKey(platform = process.platform, arch = process.arch) {
+    return `${platform}-${arch}`;
+}

package/dist/provision/provision.d.ts

@@ -0,0 +1,17 @@
+import type { PlanEntry, PlanOptions, ProvisionOptions, ProvisionResult, RemoveResult, VerifyResult } from './types.js';
+/** Pure planning against the ledger: what would `provision` do for each item. */
+export declare function plan(manifestInput: unknown, options: PlanOptions): Promise<PlanEntry[]>;
+/** Download → sha256 → extract → check → atomic promote → ledger, item by item. */
+export declare function provision(manifestInput: unknown, options: ProvisionOptions): Promise<ProvisionResult[]>;
+/** Delete exactly what the ownership manifest lists; anything else in the target is left alone. */
+export declare function remove(itemId: string, options: {
+    root: string;
+}): Promise<RemoveResult>;
+/**
+ * Recompute every installed item's digests against its ownership manifest and reconcile the
+ * ledger with what is really on disk. Repairs the state left by a kill between
+ * `rename(tree → target)` and the ledger write, and restores an old tree left in trash.
+ */
+export declare function verify(options: {
+    root: string;
+}): Promise<VerifyResult>;