@mpgd/cli 0.31.0 → 0.32.0

package/dist/asset-pack-verify.js

@@ -0,0 +1,920 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, opendir, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { verifyZipV1Archive, ZipDecodeError, } from '@mpgd/phaser-assets/archive-validation';
+import { defaultArchiveWorkerLimits } from '@mpgd/phaser-assets/archives';
+import { validatePhaserPackDeliveryManifest, } from '@mpgd/phaser-assets/pack-format';
+const DEFAULT_MANIFEST_BYTE_CAP = 32 * 1024 * 1024;
+const DEFAULT_VERIFY_TIMEOUT_MS = 120000;
+/** The watchdog arms one millisecond after the deadline. Leave one
+ * millisecond of headroom so the largest accepted timeout plus that offset
+ * still fits the platform timer range instead of clamping to 1 ms. */
+const TIMER_RANGE_MS = 2 ** 31 - 1;
+const MAX_VERIFY_TIMEOUT_MS = TIMER_RANGE_MS - 1;
+const DEFAULT_MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const DEFAULT_MAX_ENTRY_BYTES = 256 * 1024 * 1024;
+const DEFAULT_MAX_EXPANDED_BYTES = 1024 * 1024 * 1024;
+const STREAM_CHUNK_BYTES = 1024 * 1024;
+/** Inventory walking stops beyond this many files so an accidental root
+ * choice cannot turn verification into an unbounded traversal; the report
+ * marks the count truncated instead of failing silently. */
+const INVENTORY_FILE_CAP = 1000000;
+/** Same manifest artifact colliding under case folding means the deployment
+ * is ambiguous on case-insensitive hosts. */
+/** Case-fold the collision key unconditionally: the verifier's host is not
+ * the deployment's consumers, and case-duplicate artifacts are ambiguous
+ * for any case-insensitive host or CDN regardless of where this runs.
+ * The fold mirrors the 1:1 upcase tables of the case-insensitive
+ * filesystems deployments actually target (NTFS, APFS): each code point
+ * maps through its single-code-point uppercase form, so Greek σ and ς
+ * collide (both upcase to Σ) exactly as on those hosts, while mappings
+ * that only exist as multi-character expansions — ß to SS, fi to FI —
+ * stay distinct, matching a 1:1 table and keeping valid NTFS/APFS
+ * deployments from being falsely rejected. Full Unicode case folding
+ * (ext4/F2FS casefold directories) is a different equivalence, recorded
+ * in `notVerified` rather than approximated here. */
+const caseKeyOf = (resolvedPath) => {
+    let key = '';
+    for (const character of resolvedPath) {
+        const upper = character.toUpperCase();
+        // Code points, not UTF-16 units: an astral-plane letter whose
+        // uppercase form is also one code point (a surrogate pair of length
+        // two) folds like any other, while multi-code-point expansions such
+        // as ß to SS keep the original.
+        key += [...upper].length === 1 ? upper : character;
+    }
+    return key;
+};
+const NOT_VERIFIED = [
+    'CDN cache state and origin preservation',
+    'HTTP CORS and Content-Type responses',
+    'Application image display and device compatibility',
+    'Server access control',
+    'Atomic multi-file deployment swaps',
+    'Full Unicode case-fold ambiguity (ext4/F2FS casefold directories): '
+        + 'collision detection folds like NTFS and APFS, under which '
+        + '"Straße.png" and "STRASSE.png" remain distinct files',
+];
+const failWith = (failures, stage, code, message, packId) => {
+    failures.push(packId === undefined ? { stage, code, message } : { stage, code, message, packId });
+};
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+const positiveIntegerOption = (failures, name, value) => {
+    if (value === undefined) {
+        return true;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        failWith(failures, 'args', 'invalid-option', `${name} must be a positive integer`);
+        return false;
+    }
+    return true;
+};
+/** Thrown by I/O helpers when the whole-verification budget expires
+ * mid-read; the failure itself is recorded exactly once by the deadline
+ * control before this sentinel propagates. */
+class VerifyDeadlineError extends Error {
+}
+/** Streaming SHA-256 over an already-opened descriptor: never buffers the
+ * whole file, the hash reads every actual byte rather than trusting stat
+ * or Content-Length alone, and the bytes hashed are the same inode the
+ * path checks validated — a component swapped for a symlink after the
+ * check cannot redirect this read. */
+const streamSha256 = async (path, handle, hasher, deadline) => {
+    let bytes = 0;
+    const stream = handle.createReadStream({
+        highWaterMark: STREAM_CHUNK_BYTES,
+        // closeBounded owns closure under the deadline; an implicit close
+        // after the read would not be raced and could stall the exit path.
+        autoClose: false,
+    });
+    const timer = deadline.armStream(stream);
+    try {
+        for await (const chunk of stream) {
+            const view = chunk;
+            bytes += view.byteLength;
+            hasher.update(view);
+            // Hashing a large chunk is synchronous; sample after it so a final
+            // chunk that crosses the budget cannot be accepted merely because the
+            // stream itself completed and its watchdog was cleared.
+            deadline.sample();
+        }
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            throw error;
+        }
+        // A file changing mid-verification (size or content) surfaces as a
+        // read failure rather than a digest mismatch.
+        throw new Error(`Could not read ${path}: ${errorText(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    deadline.sample();
+    return { bytes, sha256: hasher.digest('hex') };
+};
+const resolveArtifactPath = async (root, realRoot, artifactPath, deadline) => {
+    if (artifactPath.length === 0) {
+        throw new Error('Artifact path is empty');
+    }
+    if (isAbsolute(artifactPath)
+        || /^[a-zA-Z]:[/\\]/u.test(artifactPath)
+        || artifactPath.startsWith('\\\\')) {
+        throw new Error(`Artifact path must be relative: ${artifactPath}`);
+    }
+    let current = root;
+    for (const segment of artifactPath.split(/[\\/]/u)) {
+        if (segment === '' || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            throw new Error(`Artifact path escapes the root: ${artifactPath}`);
+        }
+        current = join(current, segment);
+        let stat;
+        try {
+            // bigint identity stays exact on filesystems whose device or inode
+            // numbers exceed Number.MAX_SAFE_INTEGER.
+            stat = await deadline.race(lstat(current, { bigint: true }));
+        }
+        catch (error) {
+            if (error instanceof VerifyDeadlineError) {
+                throw error;
+            }
+            throw new Error(`Artifact path is missing: ${artifactPath}`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Artifact path must not contain symbolic links: ${artifactPath}`);
+        }
+    }
+    const stat = await deadline.race(lstat(current, { bigint: true }));
+    if (!stat.isFile()) {
+        throw new Error(`Artifact path is not a regular file: ${artifactPath}`);
+    }
+    const rel = relative(realRoot, await deadline.race(realpath(current)));
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`Artifact path escapes the root: ${artifactPath}`);
+    }
+    // The lstat identity travels with the path so the later open() can bind
+    // to this exact inode; a component swapped for a symlink between the
+    // check and the open surfaces as a mismatch instead of a redirect.
+    return { path: current, dev: stat.dev, ino: stat.ino };
+};
+/** Count every regular file under the root for host-limit accounting.
+ * Symlinks are skipped: they are not deployed objects, and manifest
+ * artifacts reject them independently. */
+const inventoryRoot = async (root, deadline) => {
+    let files = 0;
+    let bytes = 0;
+    let largest = 0;
+    let truncated = false;
+    // One shared, bounded pending set instead of recursion: a single
+    // directory handle is open at a time, and directory-heavy deployments
+    // (empty directories never reach the file cap) cannot queue without
+    // limit — the walk reports truncation instead of exhausting memory.
+    const pending = [root];
+    while (!truncated && pending.length > 0) {
+        const directory = pending.pop();
+        if (directory === undefined) {
+            break;
+        }
+        // opendir streams entries in bounded batches, so a single directory
+        // holding more than the cap cannot materialize every dirent first;
+        // each batch read is raced against the deadline like every other
+        // blocking wait.
+        // Retain the directory identity before opening it. A queued directory
+        // can be replaced by a symlink or a different directory while another
+        // entry is being walked; fail closed instead of letting opendir follow a
+        // replacement outside the verified root.
+        const expectedDirectory = await deadline.race(lstat(directory, { bigint: true }));
+        if (expectedDirectory.isSymbolicLink() || !expectedDirectory.isDirectory()) {
+            throw new Error(`Directory changed during inventory: ${directory}`);
+        }
+        const dir = await deadline.race(opendir(directory));
+        let stalled = false;
+        try {
+            const openedDirectory = await deadline.race(lstat(directory, { bigint: true }));
+            if (openedDirectory.isSymbolicLink()
+                || !openedDirectory.isDirectory()
+                || openedDirectory.dev !== expectedDirectory.dev
+                || openedDirectory.ino !== expectedDirectory.ino) {
+                throw new Error(`Directory changed during inventory: ${directory}`);
+            }
+            for (;;) {
+                const entry = await deadline.race(dir.read());
+                if (entry === null) {
+                    break;
+                }
+                deadline.sample();
+                const child = join(directory, entry.name);
+                // Every entry is classified by a fresh lstat, never by the
+                // possibly stale dirent — not even to skip obvious specials — so
+                // an entry whose type changed between the readdir and this call
+                // (symlink swapped in, special replaced by a file) can neither
+                // steer the walk outside the root nor be skipped from the
+                // host-limit counts.
+                const stat = await deadline.race(lstat(child));
+                if (stat.isSymbolicLink()) {
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    pending.push(child);
+                    if (pending.length > INVENTORY_FILE_CAP) {
+                        truncated = true;
+                        break;
+                    }
+                    continue;
+                }
+                if (!stat.isFile()) {
+                    continue;
+                }
+                // Truncation is only marked for an entry that actually counts:
+                // a root of exactly the cap whose next entry is a skipped
+                // symlink or device does not claim to be truncated.
+                if (files >= INVENTORY_FILE_CAP) {
+                    truncated = true;
+                    break;
+                }
+                files++;
+                bytes += stat.size;
+                if (stat.size > largest) {
+                    largest = stat.size;
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof VerifyDeadlineError) {
+                stalled = true;
+            }
+            throw error;
+        }
+        finally {
+            await closeBounded(() => dir.close(), stalled, deadline);
+        }
+    }
+    return { files, bytes, largest, truncated };
+};
+const readManifestCapped = async (manifestPath, cap, deadline) => {
+    // Open through the deadline: a FIFO with no writer blocks inside
+    // open(2) before any stream event exists, and destroying a stream
+    // cannot cancel that pending open.
+    const handle = await deadline.race(open(resolve(manifestPath), 'r'));
+    const chunks = [];
+    let received = 0;
+    let stalled = false;
+    try {
+        const info = await deadline.race(handle.stat());
+        if (info.isFile()) {
+            // Read regular files through the already-opened descriptor so every
+            // individual wait is raced against the same deadline. A stream can
+            // report EOF while buffered data is still being finalized differently
+            // across filesystems; explicit reads make the bytes returned here
+            // exactly the bytes consumed from the descriptor.
+            if (info.size > BigInt(cap)) {
+                throw new Error(`Delivery manifest exceeds ${cap} bytes`);
+            }
+            const expectedBytes = Number(info.size);
+            const buffer = Buffer.allocUnsafe(Math.min(STREAM_CHUNK_BYTES, cap));
+            while (received < expectedBytes) {
+                const readLength = Math.min(buffer.byteLength, expectedBytes - received);
+                const read = handle.read(buffer, 0, readLength, received);
+                const { bytesRead } = await deadline.race(read);
+                if (bytesRead === 0) {
+                    throw new Error(`Delivery manifest changed while reading (expected ${expectedBytes} bytes, received ${received})`);
+                }
+                received += bytesRead;
+                chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+                deadline.sample();
+            }
+            const tail = Buffer.allocUnsafe(1);
+            const { bytesRead: tailBytes } = await deadline.race(handle.read(tail, 0, 1, received));
+            if (tailBytes !== 0) {
+                throw new Error(`Delivery manifest changed while reading (expected ${expectedBytes} bytes, received more)`);
+            }
+        }
+        else {
+            // FIFOs and other non-regular sources retain the stream watchdog: a
+            // pending read must be destroyed after the deadline so a direct
+            // FileHandle.read cannot leave the smoke process alive behind a
+            // rejected race.
+            const stream = handle.createReadStream({
+                highWaterMark: STREAM_CHUNK_BYTES,
+                autoClose: false,
+            });
+            const timer = deadline.armStream(stream);
+            try {
+                for await (const chunk of stream) {
+                    const view = chunk;
+                    received += view.byteLength;
+                    if (received > cap) {
+                        stream.destroy();
+                        throw new Error(`Delivery manifest exceeds ${cap} bytes`);
+                    }
+                    chunks.push(Buffer.from(view));
+                    deadline.sample();
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            stalled = true;
+            throw error;
+        }
+        if (received > cap) {
+            throw error;
+        }
+        throw new Error(`Could not read the delivery manifest: ${errorText(error)}`);
+    }
+    finally {
+        await closeBounded(() => handle.close(), stalled, deadline);
+    }
+    return Buffer.concat(chunks);
+};
+/** Read exactly `bytes` bytes into one pre-allocated buffer from the same
+ * descriptor the identity check validated — a file changing size between
+ * the stat and this read fails instead of verifying different bytes, and
+ * a valid archive near the cap never holds chunk copies beside the
+ * result. */
+const readExact = async (path, handle, bytes, deadline) => {
+    const buffer = Buffer.alloc(bytes);
+    let received = 0;
+    while (received < bytes) {
+        const { bytesRead } = await deadline.race(handle.read(buffer, received, bytes - received, received));
+        if (bytesRead === 0) {
+            throw new Error(`Archive shrank while being read: ${path}`);
+        }
+        received += bytesRead;
+    }
+    // One byte past the declared size must be EOF: an archive appended to
+    // after the descriptor stat cannot verify its prefix and silently
+    // pass while no longer matching its declared size.
+    const tail = Buffer.alloc(1);
+    const { bytesRead: tailBytes } = await deadline.race(handle.read(tail, 0, 1, bytes));
+    if (tailBytes !== 0) {
+        throw new Error(`Archive grew while being read: ${path}`);
+    }
+    return buffer;
+};
+const expectedOf = (pack) => ({
+    formatVersion: 1,
+    archive: {
+        bytes: pack.archive?.bytes ?? 0,
+        sha256: pack.archive?.sha256 ?? '',
+    },
+    entries: pack.assets.flatMap((asset) => asset.files.map((file) => ({
+        path: file.path,
+        method: file.method ?? 'store',
+        bytes: file.bytes,
+        sha256: file.sha256,
+    }))),
+});
+/** The ZIP entry path bound mirrors runtime delivery: the default worker
+ * limit raised to this pack's longest declared entry path, so a manifest
+ * the builder, validator and runtime accept never fails here. */
+const longestDeclaredPathOf = (pack) => {
+    let longest = defaultArchiveWorkerLimits().maxPathLength;
+    for (const asset of pack.assets) {
+        for (const file of asset.files) {
+            if (file.path.length > longest) {
+                longest = file.path.length;
+            }
+        }
+    }
+    return longest;
+};
+/** Core decode limits follow the manifest's own declarations: the archive
+ * byte limit is the declared archive size (already verified by hash), the
+ * expanded limits are the manifest's file byte sums, and the deadline is
+ * the unspent remainder of the whole-verification budget. */
+const coreLimitsOf = (pack, maxEntryBytes, maxExpandedBytes, remainingMs) => {
+    const expanded = pack.assets.reduce((sum, asset) => sum + asset.files.reduce((n, file) => n + file.bytes, 0), 0);
+    return {
+        archiveBytes: pack.archive?.bytes ?? 0,
+        // Declared sizes remain the operative limits — tighter than the caps —
+        // but never exceed the independent bounds, whatever the manifest says.
+        entryBytes: Math.min(maxEntryBytes, Math.max(1, pack.assets.reduce((max, asset) => asset.files.reduce((inner, file) => Math.max(inner, file.bytes), max), 1))),
+        totalExpandedBytes: Math.min(maxExpandedBytes, Math.max(1, expanded)),
+        entryCount: Math.max(1, pack.archive?.entryCount ?? 0),
+        maxPathLength: longestDeclaredPathOf(pack),
+        // The monotonic clock yields fractional milliseconds; the core's
+        // limit checks require integers.
+        decodeDeadlineMs: Math.max(1, Math.floor(remainingMs)),
+    };
+};
+/** Verify a delivery manifest's referenced artifacts against a deployment
+ * root: read-only, deterministic, no network and no extraction. Every
+ * referenced byte is read and hashed; zip archives are additionally decoded
+ * through the shared pure core. Verification continues after the first
+ * failure so one report can carry every distinct problem. */
+export async function verifyAssetPackDelivery(options) {
+    const failures = [];
+    const manifestByteCap = options.manifestByteCap ?? DEFAULT_MANIFEST_BYTE_CAP;
+    const verifyTimeoutMs = options.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS;
+    const maxArchiveBytes = options.maxArchiveBytes ?? DEFAULT_MAX_ARCHIVE_BYTES;
+    const maxEntryBytes = options.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+    const maxExpandedBytes = options.maxExpandedBytes ?? DEFAULT_MAX_EXPANDED_BYTES;
+    const hostLimits = options.hostLimits;
+    const usedLimits = {
+        ...(hostLimits?.maxObjectBytes === undefined ? {} : { maxObjectBytes: hostLimits.maxObjectBytes }),
+        ...(hostLimits?.maxFiles === undefined ? {} : { maxFiles: hostLimits.maxFiles }),
+        ...(hostLimits?.maxTotalBytes === undefined ? {} : { maxTotalBytes: hostLimits.maxTotalBytes }),
+    };
+    if (verifyTimeoutMs > MAX_VERIFY_TIMEOUT_MS) {
+        failWith(failures, 'args', 'invalid-option', `verifyTimeoutMs must be at most ${MAX_VERIFY_TIMEOUT_MS} ms (the platform timer range minus the watchdog headroom)`);
+    }
+    const argsValid = [
+        positiveIntegerOption(failures, 'manifestByteCap', manifestByteCap),
+        positiveIntegerOption(failures, 'verifyTimeoutMs', verifyTimeoutMs),
+        verifyTimeoutMs <= MAX_VERIFY_TIMEOUT_MS,
+        positiveIntegerOption(failures, 'maxArchiveBytes', maxArchiveBytes),
+        positiveIntegerOption(failures, 'maxEntryBytes', maxEntryBytes),
+        positiveIntegerOption(failures, 'maxExpandedBytes', maxExpandedBytes),
+        ...Object.entries(hostLimits ?? {}).map(([name, value]) => positiveIntegerOption(failures, `--${name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}`, value)),
+    ].every((valid) => valid);
+    // Monotonic: a wall-clock correction mid-verification must not extend
+    // or shrink the budget.
+    const startedAt = performance.now();
+    /** The one whole-verification budget; the pure core receives only the
+     * unspent remainder so a late archive cannot restart the clock. */
+    const deadlineBreached = () => {
+        if (performance.now() - startedAt <= verifyTimeoutMs) {
+            return false;
+        }
+        if (!failures.some((entry) => entry.code === 'deadline')) {
+            failWith(failures, 'limits', 'deadline', `Delivery verification exceeded its ${verifyTimeoutMs} ms budget`);
+        }
+        return true;
+    };
+    /** The shared budget control: every blocking filesystem wait below goes
+     * through it, so no single stalled call can outlive the budget. */
+    const deadline = {
+        breach: deadlineBreached,
+        remainingMs: () => verifyTimeoutMs - (performance.now() - startedAt),
+        sample: () => {
+            if (deadlineBreached()) {
+                throw new VerifyDeadlineError();
+            }
+        },
+        // Fires one millisecond past the deadline instant — the breach
+        // predicate treats the deadline itself as still within budget — so a
+        // source that never delivers another chunk (FIFO, stalled mount)
+        // cannot outlive the budget; the recorded failure travels on the
+        // destroy error.
+        armStream: (stream) => setTimeout(() => {
+            if (deadlineBreached()) {
+                stream.destroy(new VerifyDeadlineError());
+            }
+        }, Math.max(1, verifyTimeoutMs - (performance.now() - startedAt) + 1)),
+        race: async (operation) => {
+            let timer;
+            try {
+                return await Promise.race([
+                    operation,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            if (deadlineBreached()) {
+                                reject(new VerifyDeadlineError());
+                            }
+                        }, Math.max(1, verifyTimeoutMs - (performance.now() - startedAt) + 1));
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+    // ---- Stage: manifest -------------------------------------------------
+    // Invalid arguments stop all filesystem work: the deadline itself may
+    // be the invalid value (an oversized timeout clamps the platform timer
+    // to 1 ms, disarming the watchdog), so I/O must not start on it.
+    let manifestBytes;
+    let manifest;
+    if (argsValid) {
+        try {
+            manifestBytes = await readManifestCapped(options.manifestPath, manifestByteCap, deadline);
+        }
+        catch (error) {
+            if (!(error instanceof VerifyDeadlineError)) {
+                failWith(failures, 'manifest', 'manifest-unreadable', errorText(error));
+            }
+        }
+    }
+    if (manifestBytes !== undefined) {
+        try {
+            manifest = validatePhaserPackDeliveryManifest(JSON.parse(manifestBytes.toString('utf8')));
+        }
+        catch (error) {
+            failWith(failures, 'manifest', 'manifest-invalid', errorText(error));
+        }
+    }
+    /** What the chosen manifest requires, independent of verification
+     * outcomes: distinct artifact objects and their declared bytes. */
+    let declaredTotals = { files: 0, bytes: 0 };
+    if (manifest !== undefined) {
+        for (const pack of manifest.packs) {
+            if (pack.delivery === 'zip') {
+                declaredTotals = {
+                    files: declaredTotals.files + 1,
+                    bytes: declaredTotals.bytes + (pack.archive?.bytes ?? 0),
+                };
+                continue;
+            }
+            for (const asset of pack.assets) {
+                declaredTotals = {
+                    files: declaredTotals.files + asset.files.length,
+                    bytes: declaredTotals.bytes
+                        + asset.files.reduce((sum, file) => sum + file.bytes, 0),
+                };
+            }
+        }
+    }
+    // Referenced objects are a subset of the root inventory, so declared
+    // totals are a lower bound: a manifest that already exceeds a host
+    // limit fails before any artifact I/O spends the budget.
+    if (manifest !== undefined && hostLimits?.maxFiles !== undefined
+        && declaredTotals.files > hostLimits.maxFiles) {
+        failWith(failures, 'limits', 'max-files', `Manifest already references ${declaredTotals.files} files, `
+            + `over the limit ${hostLimits.maxFiles}`);
+    }
+    if (manifest !== undefined && hostLimits?.maxTotalBytes !== undefined
+        && declaredTotals.bytes > hostLimits.maxTotalBytes) {
+        failWith(failures, 'limits', 'max-total-bytes', `Manifest already references ${declaredTotals.bytes} bytes, `
+            + `over the limit ${hostLimits.maxTotalBytes}`);
+    }
+    const root = resolve(options.root);
+    let rootIsDirectory = false;
+    let rootMissing = false;
+    if (argsValid) {
+        try {
+            // The deployment root may itself be a symlink (release directories
+            // often are); follow it, unlike the per-component artifact checks.
+            rootIsDirectory = (await deadline.race(stat(root))).isDirectory();
+            // An existing non-directory (a regular file, say) must fail like a
+            // missing root — skipping every stage without a failure would
+            // certify an unchecked deployment.
+            rootMissing = !rootIsDirectory;
+        }
+        catch (error) {
+            // A stalled stat is a deadline problem, not a missing root: the
+            // deadline failure is already recorded, so the report must not add
+            // a false path diagnosis.
+            rootMissing = !(error instanceof VerifyDeadlineError);
+        }
+    }
+    if (rootMissing) {
+        failWith(failures, 'paths', 'root-missing', `Verification root is not a directory: ${options.root}`);
+    }
+    const archives = [];
+    const seenResolved = new Map();
+    let realRoot = root;
+    let rootUsable = rootIsDirectory;
+    if (rootIsDirectory) {
+        try {
+            realRoot = await deadline.race(realpath(root));
+        }
+        catch (error) {
+            // A root that stops resolving mid-verification (a release symlink
+            // swapped between the stat and this call, or the spent budget)
+            // becomes a structured failure — never an escaping rejection that
+            // would cost the caller its report.
+            rootUsable = false;
+            if (!(error instanceof VerifyDeadlineError)) {
+                failWith(failures, 'paths', 'root-unresolvable', `Could not resolve the verification root: ${errorText(error)}`);
+            }
+        }
+    }
+    /** Verified on-disk objects keyed by resolved path. The manifest
+     * validator already rejects duplicate references, so this is
+     * defense in depth for distinct manifest paths that alias the same
+     * file on case-insensitive filesystems: they re-check the new
+     * declaration without re-reading or re-counting the object. */
+    const verifiedArtifacts = new Map();
+    const declaredHostLimitExceeded = failures.some((failure) => failure.stage === 'limits'
+        && (failure.code === 'max-files' || failure.code === 'max-total-bytes'));
+    if (manifest !== undefined && rootUsable && argsValid && !declaredHostLimitExceeded) {
+        try {
+            for (const pack of manifest.packs) {
+                if (deadline.breach()) {
+                    break;
+                }
+                if (pack.delivery === 'files') {
+                    for (const asset of pack.assets) {
+                        for (const file of asset.files) {
+                            if (deadline.breach()) {
+                                break;
+                            }
+                            await verifyReferencedFile(failures, pack, file, root, realRoot, seenResolved, verifiedArtifacts, deadline, hostLimits?.maxObjectBytes);
+                        }
+                    }
+                    continue;
+                }
+                await verifyZipPack(failures, pack, root, realRoot, seenResolved, verifiedArtifacts, archives, deadline, maxArchiveBytes, maxEntryBytes, maxExpandedBytes, hostLimits?.maxObjectBytes);
+            }
+        }
+        catch (error) {
+            // The budget expired mid-I/O; the deadline failure is already
+            // recorded, so stop verifying instead of reporting a read error.
+            if (!(error instanceof VerifyDeadlineError)) {
+                throw error;
+            }
+        }
+    }
+    // ---- Stage: limits ---------------------------------------------------
+    let inventory;
+    const limitsRequested = hostLimits !== undefined
+        && Object.values(hostLimits).some((value) => value !== undefined);
+    if (limitsRequested && rootUsable && argsValid && !deadline.breach()) {
+        try {
+            inventory = await inventoryRoot(realRoot, deadline);
+        }
+        catch (error) {
+            if (!(error instanceof VerifyDeadlineError)) {
+                failWith(failures, 'limits', 'inventory-unreadable', errorText(error));
+            }
+        }
+        if (inventory !== undefined) {
+            // Truncated inventories still run the checks: the counts are lower
+            // bounds, so any breach they show is real even though the exact
+            // totals past the cap stay unknown.
+            const maxFiles = hostLimits?.maxFiles;
+            const maxTotalBytes = hostLimits?.maxTotalBytes;
+            const maxObjectBytes = hostLimits?.maxObjectBytes;
+            if (maxFiles !== undefined && inventory.files > maxFiles) {
+                failWith(failures, 'limits', 'max-files', `Root inventory has ${inventory.files} files, over the limit ${maxFiles}`);
+            }
+            if (maxTotalBytes !== undefined && inventory.bytes > maxTotalBytes) {
+                failWith(failures, 'limits', 'max-total-bytes', `Root inventory holds ${inventory.bytes} bytes, over the limit ${maxTotalBytes}`);
+            }
+            // Object size covers the whole deployment root — unreferenced stale
+            // revisions included — exactly like the count and total limits.
+            if (maxObjectBytes !== undefined && inventory.largest > maxObjectBytes) {
+                failWith(failures, 'limits', 'max-object-bytes', `Root inventory holds an object of ${inventory.largest} bytes, `
+                    + `over the limit ${maxObjectBytes}`);
+            }
+            if (inventory.truncated) {
+                // The walk stopped at the cap, so the limits above were only
+                // checked against a lower bound; refuse to certify the deployment.
+                failWith(failures, 'limits', 'inventory-truncated', `Root inventory exceeded ${INVENTORY_FILE_CAP} files; `
+                    + 'host limits could not be fully verified');
+            }
+        }
+    }
+    return {
+        ok: failures.length === 0,
+        manifest: {
+            sha256: manifestBytes === undefined ? '' : createHash('sha256').update(manifestBytes).digest('hex'),
+            bytes: manifestBytes?.byteLength ?? 0,
+            format: manifest?.format ?? '',
+            version: manifest?.version ?? 0,
+            packs: manifest?.packs.length ?? 0,
+        },
+        referenced: declaredTotals,
+        ...(inventory === undefined ? {} : { inventory }),
+        archives,
+        ...(limitsRequested ? { limits: usedLimits } : {}),
+        failures: [...failures],
+        notVerified: NOT_VERIFIED,
+    };
+}
+/** Resolve one manifest artifact path under the root and register it
+ * against case-folded collisions — the single security-critical
+ * resolve/register path shared by files and zip packs. */
+const resolveAndRegister = async (failures, pack, root, realRoot, artifactPath, seenResolved, deadline) => {
+    let resolved;
+    try {
+        resolved = await resolveArtifactPath(root, realRoot, artifactPath, deadline);
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            // The budget expired mid-resolution; the deadline failure is
+            // already recorded, so propagate the sentinel instead of adding a
+            // misleading path failure.
+            throw error;
+        }
+        failWith(failures, 'paths', 'path-invalid', errorText(error), pack.packId);
+        return undefined;
+    }
+    const caseKey = caseKeyOf(resolved.path);
+    const prior = seenResolved.get(caseKey);
+    if (prior !== undefined) {
+        if (prior !== resolved.path) {
+            failWith(failures, 'paths', 'path-collision', `Manifest paths ${prior} and ${resolved.path} resolve to the same file`, pack.packId);
+            return undefined;
+        }
+        // Duplicate reference to an already-registered object: the caller
+        // re-checks the new declaration but the object counts once.
+        return resolved;
+    }
+    seenResolved.set(caseKey, resolved.path);
+    return resolved;
+};
+/** Close a filesystem handle under the deadline: a close following an
+ * already-timed-out operation queues behind uncancellable work and is
+ * fired and forgotten (the CLI's forced exit releases whatever the queue
+ * still holds), while even a clean-path close is raced, because a stalled
+ * close on a network or FUSE mount would otherwise stop the report from
+ * ever returning. */
+const closeBounded = async (close, stalled, deadline) => {
+    if (stalled) {
+        void close().catch(() => { });
+        return;
+    }
+    await deadline.race(close());
+};
+/** Bind an opened descriptor to the identity the path checks validated:
+ * the same inode, or the component was swapped between check and open. */
+const bindsToValidated = (info, resolved) => info.dev === resolved.dev && info.ino === resolved.ino;
+const verifyReferencedFile = async (failures, pack, file, root, realRoot, seenResolved, verifiedArtifacts, deadline, maxObjectBytes) => {
+    const resolved = await resolveAndRegister(failures, pack, root, realRoot, file.path, seenResolved, deadline);
+    if (resolved === undefined) {
+        return;
+    }
+    const resolvedPath = resolved.path;
+    try {
+        const cached = verifiedArtifacts.get(resolvedPath);
+        if (cached !== undefined) {
+            if (cached.bytes !== file.bytes) {
+                failWith(failures, 'files', 'size-mismatch', `File ${file.path} is ${cached.bytes} bytes, manifest declares ${file.bytes}`, pack.packId);
+            }
+            else if (cached.sha256 !== file.sha256) {
+                failWith(failures, 'files', 'hash-mismatch', `File ${file.path} does not match its manifest digest`, pack.packId);
+            }
+            return;
+        }
+        const handle = await deadline.race(open(resolvedPath, 'r'));
+        let stalled = false;
+        let hashed;
+        try {
+            const info = await deadline.race(handle.stat({ bigint: true }));
+            if (!bindsToValidated(info, resolved)) {
+                failWith(failures, 'paths', 'path-invalid', `Artifact path changed during verification: ${file.path}`, pack.packId);
+                return;
+            }
+            // Size from the bound descriptor fails closed before the hash, so a
+            // huge replacement cannot consume the budget streaming bytes that
+            // were already known not to match.
+            if (info.size !== BigInt(file.bytes)) {
+                failWith(failures, 'files', 'size-mismatch', `File ${file.path} is ${info.size} bytes, manifest declares ${file.bytes}`, pack.packId);
+                return;
+            }
+            // The object cap applies before streaming too: a valid but oversized
+            // artifact must fail as max-object-bytes here rather than consuming
+            // the whole budget and surfacing only a deadline failure.
+            if (maxObjectBytes !== undefined && info.size > BigInt(maxObjectBytes)) {
+                failWith(failures, 'limits', 'max-object-bytes', `File ${file.path} is ${info.size} bytes, over the limit ${maxObjectBytes}`, pack.packId);
+                return;
+            }
+            hashed = await streamSha256(resolvedPath, handle, createHash('sha256'), deadline);
+            // Keep the deadline sentinel distinct from a later size/hash result
+            // even when the final synchronous hash update crossed the boundary.
+            deadline.sample();
+        }
+        catch (error) {
+            if (error instanceof VerifyDeadlineError) {
+                stalled = true;
+            }
+            throw error;
+        }
+        finally {
+            await closeBounded(() => handle.close(), stalled, deadline);
+        }
+        if (hashed.bytes !== file.bytes) {
+            failWith(failures, 'files', 'size-mismatch', `File ${file.path} is ${hashed.bytes} bytes, manifest declares ${file.bytes}`, pack.packId);
+            return;
+        }
+        if (hashed.sha256 !== file.sha256) {
+            failWith(failures, 'files', 'hash-mismatch', `File ${file.path} does not match its manifest digest`, pack.packId);
+            return;
+        }
+        verifiedArtifacts.set(resolvedPath, hashed);
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            throw error;
+        }
+        failWith(failures, 'files', 'unreadable', errorText(error), pack.packId);
+    }
+};
+const verifyZipPack = async (failures, pack, root, realRoot, seenResolved, verifiedArtifacts, archives, deadline, maxArchiveBytes, maxEntryBytes, maxExpandedBytes, maxObjectBytes) => {
+    const archivePath = pack.archive?.path;
+    if (archivePath === undefined) {
+        failWith(failures, 'archive', 'archive-missing', `Zip pack ${pack.packId} lacks an archive path`, pack.packId);
+        return;
+    }
+    const resolved = await resolveAndRegister(failures, pack, root, realRoot, archivePath, seenResolved, deadline);
+    if (resolved === undefined) {
+        return;
+    }
+    const resolvedPath = resolved.path;
+    const declaredBytes = pack.archive?.bytes ?? 0;
+    if (declaredBytes > maxArchiveBytes) {
+        failWith(failures, 'limits', 'max-archive-bytes', `Archive ${archivePath} declares ${declaredBytes} bytes, over the limit ${maxArchiveBytes}`, pack.packId);
+        return;
+    }
+    // Decompression bounds are independent of the manifest's own numbers: a
+    // self-consistent manifest can still declare gigabytes of expansion, and
+    // these caps reject that before any allocation, not after.
+    const declaredEntryBytes = pack.assets.reduce((max, asset) => asset.files.reduce((inner, file) => Math.max(inner, file.bytes), max), 0);
+    const declaredExpandedBytes = pack.assets.reduce((sum, asset) => sum + asset.files.reduce((inner, file) => inner + file.bytes, 0), 0);
+    if (declaredEntryBytes > maxEntryBytes) {
+        failWith(failures, 'limits', 'max-entry-bytes', `Pack ${pack.packId} declares an entry of ${declaredEntryBytes} bytes, `
+            + `over the limit ${maxEntryBytes}`, pack.packId);
+        return;
+    }
+    if (declaredExpandedBytes > maxExpandedBytes) {
+        failWith(failures, 'limits', 'max-expanded-bytes', `Pack ${pack.packId} declares ${declaredExpandedBytes} expanded bytes, `
+            + `over the limit ${maxExpandedBytes}`, pack.packId);
+        return;
+    }
+    let archiveBytes;
+    try {
+        // One descriptor serves the size check, the digest and the decode, so
+        // every check sees the same inode the path checks validated.
+        const handle = await deadline.race(open(resolvedPath, 'r'));
+        let stalled = false;
+        try {
+            const { size, dev, ino } = await deadline.race(handle.stat({ bigint: true }));
+            if (!bindsToValidated({ dev, ino }, resolved)) {
+                failWith(failures, 'paths', 'path-invalid', `Artifact path changed during verification: ${archivePath}`, pack.packId);
+                return;
+            }
+            const cached = verifiedArtifacts.get(resolvedPath);
+            if (cached === undefined) {
+                if (pack.archive !== undefined && size !== BigInt(pack.archive.bytes)) {
+                    failWith(failures, 'archive', 'size-mismatch', `Archive ${archivePath} is ${size} bytes, manifest declares ${pack.archive.bytes}`, pack.packId);
+                    return;
+                }
+                if (size > BigInt(maxArchiveBytes)) {
+                    failWith(failures, 'limits', 'max-archive-bytes', `Archive ${archivePath} is ${size} bytes, over the limit ${maxArchiveBytes}`, pack.packId);
+                    return;
+                }
+                if (maxObjectBytes !== undefined && size > BigInt(maxObjectBytes)) {
+                    failWith(failures, 'limits', 'max-object-bytes', `Archive ${archivePath} is ${size} bytes, over the limit ${maxObjectBytes}`, pack.packId);
+                    return;
+                }
+                archiveBytes = await readExact(resolvedPath, handle, declaredBytes, deadline);
+                const hasher = createHash('sha256');
+                hasher.update(archiveBytes);
+                const actual = { bytes: archiveBytes.byteLength, sha256: hasher.digest('hex') };
+                if (pack.archive !== undefined && actual.sha256 !== pack.archive.sha256) {
+                    failWith(failures, 'archive', 'hash-mismatch', `Archive ${archivePath} does not match its manifest digest`, pack.packId);
+                    return;
+                }
+                verifiedArtifacts.set(resolvedPath, actual);
+            }
+            else {
+                if (pack.archive !== undefined && cached.bytes !== pack.archive.bytes) {
+                    failWith(failures, 'archive', 'size-mismatch', `Archive ${archivePath} is ${cached.bytes} bytes, manifest declares ${pack.archive.bytes}`, pack.packId);
+                    return;
+                }
+                if (pack.archive !== undefined && cached.sha256 !== pack.archive.sha256) {
+                    failWith(failures, 'archive', 'hash-mismatch', `Archive ${archivePath} does not match its manifest digest`, pack.packId);
+                    return;
+                }
+                // The object is already verified and counted; re-read only what the
+                // decode needs.
+                archiveBytes = await readExact(resolvedPath, handle, declaredBytes, deadline);
+            }
+        }
+        catch (error) {
+            if (error instanceof VerifyDeadlineError) {
+                stalled = true;
+            }
+            throw error;
+        }
+        finally {
+            await closeBounded(() => handle.close(), stalled, deadline);
+        }
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            throw error;
+        }
+        failWith(failures, 'archive', 'unreadable', errorText(error), pack.packId);
+        return;
+    }
+    try {
+        // The core only samples its budget around awaited digests, so a
+        // stalled one can outlive it; the shared deadline races the whole
+        // decode, letting the CLI report and take its forced-exit path.
+        const decode = verifyZipV1Archive(archiveBytes, expectedOf(pack), coreLimitsOf(pack, maxEntryBytes, maxExpandedBytes, deadline.remainingMs()));
+        const stats = await deadline.race(decode);
+        archives.push({
+            packId: pack.packId,
+            entries: stats.entries,
+            expandedBytes: stats.expandedBytes,
+        });
+    }
+    catch (error) {
+        if (error instanceof VerifyDeadlineError) {
+            throw error;
+        }
+        const code = error instanceof ZipDecodeError ? error.code : 'decode';
+        failWith(failures, 'archive', `zip-${code}`, `Archive ${archivePath} failed verification: ${errorText(error)}`, pack.packId);
+    }
+};