@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/file-lock.js

@@ -1,18 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { LockContentionError } from '../errors/base.js';
 import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
+import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
+export { LOCK_PID_FILE };
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
 /**
  * Minimum interval between stale-lock probes while a waiter polls. Probing
- * exactly once per waiter means a holder that dies *after* that probe leaves
- * the waiter polling a permanently dead lock until `timeoutMs` — up to 24
+ * exactly once per waiter means a holder that dies after that probe leaves
+ * the waiter polling a permanently dead lock until `timeoutMs`, up to 24
  * hours for the build lock (see `withBuildLock` in mach.ts). Re-probing on a
  * small interval bounds that to seconds while keeping the per-poll cost
  * negligible: one stat plus one small read every ~5 s.
@@ -23,52 +26,10 @@ const STALE_REPROBE_INTERVAL_MS = 5_000;
  * deadline extension but no progress line of its own.
  */
 const WAIT_PROBE_INTERVAL_MS = 5_000;
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
-/**
- * Filename of a lock directory's owner record, relative to the lock dir.
- *
- * Exported so external readers (`tree-store.ts`) share the constant instead of
- * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
- */
-export const LOCK_PID_FILE = 'pid';
-/**
- * Reads the owner PID (line 1), acquisition token (line 2), and diagnostic
- * metadata (lines 3+, see {@link FileLockOptions.ownerMetadata}) from a lock
- * directory's PID file. Returns `{ present: false }` when the PID file is
- * missing or the PID does not parse as a finite integer (caller falls back
- * to the age-only staleness heuristic).
- *
- * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file — so the token line
- * stays compatible.
- */
-async function readLockOwner(lockPath) {
-    try {
-        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const [pidLine, tokenLine, ...metadataLines] = pidContent.split('\n');
-        const pid = parseInt((pidLine ?? '').trim(), 10);
-        if (Number.isFinite(pid)) {
-            const metadata = metadataLines.map((line) => line.trim()).filter((line) => line.length > 0);
-            const token = tokenLine?.trim();
-            if (token !== undefined && token.length > 0) {
-                return { present: true, pid, token, metadata };
-            }
-            return { present: true, pid, metadata };
-        }
-    }
-    catch {
-        // PID file missing or unreadable — treat as absent.
-    }
-    return { present: false };
-}
 /** Sibling directory in which waiters advertise themselves. */
 function lockWaitersDir(lockPath) {
     return `${lockPath}.waiters`;
@@ -127,7 +88,7 @@ export async function readLockStatus(lockPath) {
     }
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
-        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
     return { held: true, holder, heldForMs, queueDepth: queue.depth };
 }
@@ -138,13 +99,13 @@ export async function readLockStatus(lockPath) {
  */
 async function registerWaiter(lockPath, startedAt) {
     const dir = lockWaitersDir(lockPath);
-    const file = join(dir, `${String(startedAt)}-${String(process.pid)}-${randomUUID()}`);
+    const file = join(dir, `${startedAt}-${process.pid}-${randomUUID()}`);
     try {
         await ensureDir(dir);
-        await writeFile(file, `${String(process.pid)}\n`, 'utf-8');
+        await writeFile(file, `${process.pid}\n`, 'utf-8');
     }
     catch (error) {
-        // Advisory only — never fail a lock acquisition over the queue display.
+        // Advisory only. Never fail a lock acquisition over the queue display.
         verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
         return async () => {
             /* nothing to remove */
@@ -158,13 +119,13 @@ async function registerWaiter(lockPath, startedAt) {
  * Reads the contended lock's owner and queue in one go. One probe per cycle
  * serves both the progress line and the deadline extension, so the two can
  * never disagree about the position they saw. Failure to read the owner
- * degrades to `holder: undefined` — a diagnostic must never break the wait
- * loop.
+ * degrades to `holder: undefined`, since a diagnostic must never break the
+ * wait loop.
  */
 async function probeWaitState(lockPath, startedAt) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
-        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
     return { holder, queue: await readLockQueue(lockPath, startedAt) };
 }
@@ -174,13 +135,13 @@ async function probeWaitState(lockPath, startedAt) {
  *
  * A naive stat → read-PID → `rm` sequence has a TOCTOU hole: two waiters
  * both observe the dead owner, one removes the stale dir and `mkdir`s its
- * own lock, and the other's already-decided `rm` then deletes the *fresh*
- * lock — two processes inside the critical section at once.
+ * own lock, and the other's already-decided `rm` then deletes the fresh
+ * lock, putting two processes inside the critical section at once.
  *
  * Rename-aside closes it: `rename()` is atomic, so exactly one reaper wins
  * ownership of the directory (the loser gets ENOENT and re-polls), and
  * nothing ever deletes the live path directly. After winning the rename the
- * owner is re-read from the renamed dir — if it is now a *live* process (the
+ * owner is re-read from the renamed dir. If it is now a live process (the
  * lock was released and re-acquired between the staleness read and the
  * rename), it is renamed back instead of reaped.
  *
@@ -189,13 +150,13 @@ async function probeWaitState(lockPath, startedAt) {
  *   legitimately held and the caller should keep waiting.
  */
 async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
-    const reapPath = `${lockPath}.reaping-${String(process.pid)}-${randomUUID()}`;
+    const reapPath = `${lockPath}.reaping-${process.pid}-${randomUUID()}`;
     try {
         await rename(lockPath, reapPath);
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT') {
-            // Another reaper won, or the owner released — either way, retry mkdir.
+            // Another reaper won, or the owner released. Either way, retry mkdir.
             verbose(`Stale lock disappeared before reaping completed: ${lockPath}`);
             return true;
         }
@@ -205,16 +166,16 @@ async function reapStaleLock(lockPath, ageMs, onStaleLockMessage) {
     // We exclusively own reapPath now. Re-verify: the owner may have changed
     // between the staleness probe and the rename (release + fresh acquire).
     const owner = await readLockOwner(reapPath);
-    if (owner.present && isProcessAlive(owner.pid)) {
+    if (owner.present && isLockOwnerAlive(owner)) {
         try {
             await rename(reapPath, lockPath);
-            verbose(`Aborted stale-lock reap of ${lockPath}: owner PID ${String(owner.pid)} is alive (lock was re-acquired mid-probe)`);
+            verbose(`Aborted stale-lock reap of ${lockPath}: owner PID ${owner.pid} is alive (lock was re-acquired mid-probe)`);
         }
         catch (restoreError) {
             // Rename-back can only fail if a third process mkdir'd the lock path
             // in this instant. The displaced live owner keeps running without its
-            // lock — surface it loudly instead of hiding the lost exclusion.
-            warn(`Could not restore live lock for PID ${String(owner.pid)} at ${lockPath} ` +
+            // lock, so surface it loudly instead of hiding the lost exclusion.
+            warn(`Could not restore live lock for PID ${owner.pid} at ${lockPath} ` +
                 `(${toError(restoreError).message}). Displaced lock kept at ${reapPath} for inspection.`);
         }
         return false;
@@ -238,21 +199,22 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
         const ageMs = Date.now() - lockStat.mtimeMs;
-        // Check PID FIRST, independent of age. Age-gating everything means a
+        // Check the PID first, independent of age. Age-gating everything means a
         // lock younger than `staleMs` (default 5 minutes) is never removed even
-        // when its PID file points at a process that has already exited — the
-        // situation after SIGINT'ing `furnace preview`, where the signal handler
+        // when its PID file points at a process that has already exited. That is
+        // the situation after SIGINT'ing `furnace preview`, where the signal handler
         // calls `process.exit` and `withFileLock`'s release never runs. With the
         // PID-first check an explicitly-dead owner unblocks immediately.
         const owner = await readLockOwner(lockPath);
         if (owner.present) {
-            if (!isProcessAlive(owner.pid)) {
+            if (!isLockOwnerAlive(owner)) {
                 return await reapStaleLock(lockPath, ageMs, onStaleLockMessage);
             }
-            // PID is alive — respect it regardless of age. A slow `mach build`
-            // legitimately holds the lock past the stale threshold and we don't
-            // want to race-remove it.
-            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${String(owner.pid)} is still running — not removing`);
+            // The owner is alive (PID exists and, where `/proc` can tell, it is
+            // the process that acquired the lock, not a recycled PID), so respect
+            // it regardless of age. A slow `mach build` legitimately holds the
+            // lock past the stale threshold and we don't want to race-remove it.
+            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${owner.pid} is still running — not removing`);
             return false;
         }
         // No readable PID file. Fall back to the age-only heuristic so locks
@@ -275,25 +237,22 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
 }
 /**
  * Releases a lock previously acquired by this process, verifying ownership
- * first. An unconditional `finally { rm }` would remove *whichever* lock
- * directory is present — if a stale-lock reaper had (in a pathological race)
+ * first. An unconditional `finally { rm }` would remove whichever lock
+ * directory is present. If a stale-lock reaper had (in a pathological race)
  * replaced our lock, that deletes the new owner's lock and compounds the
  * double-acquisition. When the PID file no longer names us, warn and leave
  * the directory alone.
  *
- * `ownerFileWritten` is false when our own owner-file write failed at
- * acquisition (non-fatal there); ownership then cannot be verified and the
- * removal is unconditional, which is strictly better than leaking the lock.
+ * The owner record is always present here: `writeLockOwner` is fatal, so an
+ * acquisition whose record failed to write never reached the operation.
  */
-async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
-    if (ownerFileWritten) {
-        const owner = await readLockOwner(lockPath);
-        if (owner.present &&
-            (owner.pid !== process.pid || (owner.token !== undefined && owner.token !== ownerToken))) {
-            warn(`Not removing lock ${lockPath}: it is now owned by PID ${String(owner.pid)} — ` +
-                'this process no longer holds it.');
-            return;
-        }
+async function releaseLock(lockPath, ownerToken) {
+    const owner = await readLockOwner(lockPath);
+    if (owner.present &&
+        (owner.pid !== process.pid || (owner.token !== undefined && owner.token !== ownerToken))) {
+        warn(`Not removing lock ${lockPath}: it is now owned by PID ${owner.pid} — ` +
+            'this process no longer holds it.');
+        return;
     }
     await rm(lockPath, { recursive: true, force: true });
 }
@@ -301,11 +260,11 @@ async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
  * Removes a lock directory only if this process still owns it, for callers
  * that hold no acquisition token.
  *
- * The ownership half of {@link releaseLock}, minus the token check — a
+ * The ownership half of {@link releaseLock}, minus the token check: a
  * signal-time sweeper knows which lock paths its own operations opened, but
  * not the per-acquisition UUID those acquisitions minted. The PID check is
  * still the one that matters: it stops the sweeper deleting a lock a
- * DIFFERENT process acquired in the window between our operation dying and
+ * different process acquired in the window between our operation dying and
  * the sweep running.
  *
  * Never throws: callers are shutdown paths where a slow or failing I/O must
@@ -334,44 +293,52 @@ export async function releaseLockIfOwned(lockPath) {
  * Typed as {@link LockContentionError} (a `FireForgeError`) so the CLI
  * boundary prints the refusal as one clean line instead of an "Unexpected
  * error" stack. Callers supplying `onTimeoutMessage` still get the holder
- * identification appended — the reason-first copy stays theirs, the "who
+ * identification appended: the reason-first copy stays theirs, the "who
  * holds it" is ours.
+ *
+ * `queue` is read at expiry by the caller, not carried over from the last
+ * progress probe: see {@link formatQueuePositionReached}.
  */
 async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
     const owner = await readLockOwner(lockPath);
-    const liveHolder = owner.present && isProcessAlive(owner.pid) ? owner : undefined;
+    const liveHolder = owner.present && isLockOwnerAlive(owner) ? owner : undefined;
     const details = liveHolder !== undefined && liveHolder.metadata.length > 0
         ? ` (${liveHolder.metadata.join(', ')})`
         : '';
     const position = formatQueuePositionReached(queue);
     if (onTimeoutMessage !== undefined) {
-        const identifiedHolder = liveHolder !== undefined
-            ? ` The lock is held by PID ${String(liveHolder.pid)}${details}.`
-            : '';
+        const identifiedHolder = liveHolder !== undefined ? ` The lock is held by PID ${liveHolder.pid}${details}.` : '';
         return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}${position}`, cause);
     }
     const holderHint = liveHolder !== undefined
-        ? ` It is held by running process ${String(liveHolder.pid)}${details} — wait for it to finish, or stop it and retry.`
+        ? ` It is held by running process ${liveHolder.pid}${details} — wait for it to finish, or stop it and retry.`
         : ' If no other FireForge process is running, remove the lock directory and retry.';
     return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}${position}`, cause);
 }
 /**
  * States the queue position the expired wait actually reached.
  *
- * Silence here is what made the worst outcome invisible: a wait that expires
+ * Silence here made the worst outcome invisible: a wait that expires
  * one position from the head has paid the whole budget for nothing, and the
  * operator cannot tell that from a queue that never moved. Naming the
  * position turns "raise the budget" into an informed decision instead of a
- * guess. Omitted when no queue was observed — an empty registry is not
+ * guess. Omitted when no queue was observed, since an empty registry is not
  * evidence of an empty queue.
+ *
+ * The queue is read at the moment the budget expires rather than taken from
+ * the last progress probe. A probe snapshot is up to one `waitProgressMs`
+ * stale, and, the reason this changed, it may not exist at all: a short
+ * budget can expire before the first probe lands (a slow runner's
+ * `registerWaiter` alone can outlast it), and a caller that configured no
+ * probe at all never had one. Both used to lose the position silently.
  */
 function formatQueuePositionReached(queue) {
-    if (queue === undefined || queue.depth === 0)
+    if (queue.depth === 0)
         return '';
     if (queue.ahead === 0) {
-        return ` You were next in a queue of ${String(queue.depth)} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
+        return ` You were next in a queue of ${queue.depth} when the wait expired — a larger --wait-lock would very likely have got a turn.`;
     }
-    return ` You were still ${String(queue.ahead)} from the head of a queue of ${String(queue.depth)} when the wait expired; re-run with a larger --wait-lock.`;
+    return ` You were still ${queue.ahead} from the head of a queue of ${queue.depth} when the wait expired; re-run with a larger --wait-lock.`;
 }
 /**
  * Runs one wait probe: reads holder and queue, and reports progress when the
@@ -395,13 +362,13 @@ async function runWaitProbe(lockPath, startedAt, timeoutMs, options) {
  * SIGTERM'd command leaves its lock on disk. The next contender reclaims it
  * immediately (the PID-first staleness check sees a dead owner), but in the
  * window between, `fireforge status --lock` reports the lock held by a
- * process that is not running — which is exactly the question an operator
- * asks after a kill. The signal sweep closes that window.
+ * process that is not running, which is the question an operator asks after
+ * a kill. The signal sweep closes that window.
  *
  * Paths only: the per-acquisition token lives in `withFileLock`'s frame and
  * a sweeper cannot see it. {@link releaseLockIfOwned} checks the PID, which
- * is the check that matters — it stops the sweep deleting a lock a
- * DIFFERENT process acquired in the meantime.
+ * is the check that matters: it stops the sweep deleting a lock a
+ * different process acquired in the meantime.
  */
 const heldLocks = new Set();
 /**
@@ -435,14 +402,12 @@ export async function withFileLock(lockPath, operation, options = {}) {
     let lastStaleProbeAt;
     let currentPollMs = pollMs;
     let lastProbeAt = startedAt;
-    /** Best (lowest) queue position seen so far; used to detect an advance. */
+    /** Best (lowest) queue position seen so far. Used to detect an advance. */
     let bestAhead;
-    /** Last observed queue state, so the timeout refusal can name the position reached. */
-    let lastQueue;
     /** Set on first contention so an uncontended acquire costs nothing. */
     let deregisterWaiter;
     // One cadence drives both the progress line and the deadline extension.
-    // Either feature alone is enough to want the probe; neither is worth a
+    // Either feature alone is enough to want the probe. Neither is worth a
     // second timer.
     const probeIntervalMs = options.waitProgressMs ?? WAIT_PROBE_INTERVAL_MS;
     const probeWanted = (options.onWaitProgress !== undefined && options.waitProgressMs !== undefined) ||
@@ -469,26 +434,31 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     }
                 }
                 if (Date.now() >= deadline) {
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, lastQueue);
+                    // The queue is read here, not carried over from the last progress
+                    // probe: the position the wait reached is the one number that says
+                    // whether a larger budget would have helped, and it must not depend
+                    // on a probe having happened to land inside the budget. We are still
+                    // registered at this point. `deregisterWaiter` runs in the `finally`
+                    // below, which is only entered once this refusal has been built.
+                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
                 }
                 if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
                     lastProbeAt = Date.now();
-                    // Report the budget that is CURRENTLY in force, not the one
+                    // Report the budget that is currently in force, not the one
                     // originally requested: once an extension has been granted, the
                     // requested figure is stale, and a progress line that keeps
                     // quoting it reads as a timeout that does not fire.
                     const probe = await runWaitProbe(lockPath, startedAt, deadline - startedAt, options);
-                    lastQueue = probe.queue;
-                    // An advance — someone ahead of us took their turn and finished —
+                    // An advance (someone ahead of us took their turn and finished)
                     // buys a fresh budget, because the wait is working. Only a queue
                     // that stops moving starves, which is the case the timeout is for.
                     //
-                    // The FIRST observation is a seed, never an advance. `bestAhead`
+                    // The first observation is a seed, never an advance. `bestAhead`
                     // used to start `undefined`, so the opening probe always satisfied
                     // this test and handed out a free full budget: a `--wait-lock 300`
                     // run outlived its 300 s even against a queue that never moved
-                    // once, which is exactly the "it does not reliably give up after N
-                    // seconds" a downstream fork reported.
+                    // once, which is the "it does not reliably give up after N
+                    // seconds" behaviour a downstream fork reported.
                     if (hardDeadline !== undefined) {
                         if (bestAhead === undefined) {
                             bestAhead = probe.queue.ahead;
@@ -511,32 +481,24 @@ export async function withFileLock(lockPath, operation, options = {}) {
         }
     }
     finally {
-        // Leaving the queue happens the moment we stop waiting — whether we
+        // Leaving the queue happens the moment we stop waiting, whether we
         // acquired the lock or timed out.
         await deregisterWaiter?.();
     }
-    // Stamp ownership (PID + per-acquisition token) into the lock directory so
-    // stale-lock recovery can check liveness and release can verify the lock
-    // is still ours before removing it.
+    // Stamp ownership (PID + per-acquisition token + acquisition time) into
+    // the lock directory so stale-lock recovery can check liveness and release
+    // can verify the lock is still ours before removing it. Fatal on failure:
+    // an owner-less lock is reaped by the age heuristic after five minutes,
+    // which for a multi-hour build meant a second holder mid-critical-section.
+    // `writeLockOwner` removes the just-created directory before throwing.
     const ownerToken = randomUUID();
-    let ownerFileWritten = false;
-    try {
-        const metadata = options.ownerMetadata
-            ?.map((line) => line.replace(/\r?\n/g, ' ').trim())
-            .filter((line) => line.length > 0) ?? [];
-        await writeFile(join(lockPath, LOCK_PID_FILE), `${String(process.pid)}\n${ownerToken}\n${metadata.length > 0 ? `${metadata.join('\n')}\n` : ''}`, 'utf-8');
-        ownerFileWritten = true;
-    }
-    catch {
-        // Non-fatal: stale recovery falls back to age-only heuristic and release
-        // falls back to unconditional removal.
-    }
+    await writeLockOwner(lockPath, ownerToken, options.ownerMetadata);
     heldLocks.add(lockPath);
     try {
         return await operation();
     }
     finally {
         heldLocks.delete(lockPath);
-        await releaseLock(lockPath, ownerToken, ownerFileWritten);
+        await releaseLock(lockPath, ownerToken);
     }
 }

package/dist/src/core/firefox-cache.d.ts

@@ -3,13 +3,25 @@
  */
 import type { ResolvedArchive } from './firefox-archive.js';
 import type { ProgressCallback } from './firefox-download.js';
+/** Options governing the default (unpinned) integrity check. */
+export interface ArchiveIntegrityOptions {
+    /**
+     * Accept the download with a warning when the published SHA256SUMS cannot
+     * be obtained (`firefox.allowUnverifiedDownload`). Default: fail closed.
+     */
+    allowUnverifiedDownload?: boolean;
+}
 /**
  * Ensures a valid cached archive exists, downloading it if needed.
  * @param archive - Resolved archive descriptor
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
+ * @param expectedSha256 - Operator-pinned digest. When set it replaces the
+ *   published-SHA256SUMS check
+ * @param onCacheProgress - Phase progress messages
+ * @param integrity - Default integrity-check options (unpinned downloads)
  */
-export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback, expectedSha256?: string, onCacheProgress?: (message: string) => void): Promise<void>;
+export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback, expectedSha256?: string, onCacheProgress?: (message: string) => void, integrity?: ArchiveIntegrityOptions): Promise<void>;
 /**
  * Removes cached tarball, metadata, and partial download files for an archive.
  * @param archive - Resolved archive descriptor

package/dist/src/core/firefox-cache.js

@@ -7,13 +7,13 @@ import { createReadStream } from 'node:fs';
 import { readdir, rename, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
-import { ChecksumMismatchError } from '../errors/download.js';
+import { ChecksumMismatchError, ChecksumUnavailableError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { validateArchiveMetadata } from './firefox-archive.js';
-import { downloadFile } from './firefox-download.js';
+import { downloadFile, fetchWithRetry } from './firefox-download.js';
 /**
  * Computes the SHA-256 hex digest of a file.
  * @param filePath - Path to the file
@@ -26,10 +26,15 @@ async function sha256File(filePath) {
 }
 /**
  * Fetches Mozilla's published SHA256SUMS for the release and extracts the
- * digest for this archive. Returns null when the checksum file cannot be
- * fetched or does not list the archive — the caller warns loudly and
- * continues (offline mirrors and staging hosts legitimately lack it), while
- * a FETCHED-but-mismatching digest always fails closed.
+ * digest for this archive. Yields a reason instead of a digest when the
+ * checksum file cannot be fetched (non-2xx, network error, timeout) or does
+ * not list the archive (a captive portal's HTML page lands here too). The
+ * caller decides whether that fails closed. The request goes through the
+ * same `fetchWithRetry` as the archive download (same 60 s abort ceiling
+ * per attempt, same three-attempt back-off on 429/5xx and network errors),
+ * so an unresponsive checksum host cannot hang the command after the
+ * tarball has landed, and one transient blip on the small checksum request
+ * does not fail the verification closed and discard the archive.
  *
  * Line format (both variants appear in the wild):
  *   `<64-hex-digest>  <release-relative-path>`
@@ -37,33 +42,67 @@ async function sha256File(filePath) {
  */
 async function fetchPublishedSha256(archive) {
     try {
-        const response = await fetch(archive.checksumsUrl);
+        const response = await fetchWithRetry(archive.checksumsUrl);
         if (!response.ok) {
-            verbose(`SHA256SUMS fetch returned HTTP ${String(response.status)} for ${archive.checksumsUrl}`);
-            return null;
+            return { sha256: null, reason: `HTTP ${response.status} fetching SHA256SUMS` };
         }
         const body = await response.text();
         for (const line of body.split('\n')) {
             const match = /^([0-9a-f]{64})\s+\*?(.+)$/.exec(line.trim());
             if (match?.[1] && match[2] === archive.pathInChecksums) {
-                return match[1];
+                return { sha256: match[1] };
             }
         }
-        verbose(`SHA256SUMS at ${archive.checksumsUrl} does not list ${archive.pathInChecksums}`);
-        return null;
+        return {
+            sha256: null,
+            reason: `SHA256SUMS does not list ${archive.pathInChecksums} (wrong file, or a non-Mozilla response)`,
+        };
     }
     catch (error) {
-        verbose(`SHA256SUMS fetch failed for ${archive.checksumsUrl}: ${toError(error).message}`);
-        return null;
+        return { sha256: null, reason: `SHA256SUMS fetch failed: ${toError(error).message}` };
     }
 }
+/**
+ * Default integrity check for a download with no operator pin: the archive
+ * digest must equal the one Mozilla publishes. TLS alone is thin trust for
+ * the artifact that becomes the git baseline every patch is built on: a
+ * compromised CDN response would otherwise be trusted with no signal.
+ *
+ * Fails closed both on a mismatch and when the published digest cannot be
+ * obtained: a 404, a captive-portal HTML page, or a dropped connection
+ * would otherwise quietly downgrade the check to "TLS looked fine", which
+ * is the condition an attacker positioned on the network can
+ * arrange. `allowUnverifiedDownload` (an explicit config opt-in for offline
+ * mirrors) degrades the unavailable case to a loud warning. A fetched but
+ * mismatching digest is never accepted.
+ */
+async function verifyAgainstPublishedSha256(archive, actualSha256, options) {
+    const published = await fetchPublishedSha256(archive);
+    if (published.sha256 !== null) {
+        if (actualSha256 !== published.sha256) {
+            throw new ChecksumMismatchError(archive.product, published.sha256, actualSha256, archive.url);
+        }
+        return;
+    }
+    verbose(`${published.reason} (${archive.checksumsUrl})`);
+    if (options.allowUnverifiedDownload !== true) {
+        throw new ChecksumUnavailableError(archive.product, archive.checksumsUrl, published.reason, archive.url);
+    }
+    warn(`Could not verify ${archive.filename} against Mozilla's published SHA256SUMS ` +
+        `(${published.reason}). firefox.allowUnverifiedDownload is set, so the download is ` +
+        'trusted on TLS alone — pin firefox.sha256 in fireforge.json to verify it.');
+}
 /**
  * Ensures a valid cached archive exists, downloading it if needed.
  * @param archive - Resolved archive descriptor
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
+ * @param expectedSha256 - Operator-pinned digest. When set it replaces the
+ *   published-SHA256SUMS check
+ * @param onCacheProgress - Phase progress messages
+ * @param integrity - Default integrity-check options (unpinned downloads)
  */
-export async function ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onCacheProgress) {
+export async function ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onCacheProgress, integrity = {}) {
     const lockPath = createSiblingLockPath(join(cacheDir, archive.filename), '.fireforge-cache.lock');
     await withFileLock(lockPath, async () => {
         onCacheProgress?.(`Validating source archive cache metadata for ${archive.filename}...`);
@@ -78,7 +117,7 @@ export async function ensureCachedArchive(archive, cacheDir, onProgress, expecte
         else {
             await removeArchivePartFiles(archive, cacheDir);
         }
-        await downloadToCache(archive, cacheDir, onProgress, expectedSha256, onCacheProgress);
+        await downloadToCache(archive, cacheDir, onProgress, expectedSha256, onCacheProgress, integrity);
     });
 }
 async function cacheEntryExists(archive, cacheDir) {
@@ -94,7 +133,7 @@ async function cacheEntryExists(archive, cacheDir) {
 async function validateCachedArchive(archive, cacheDir, expectedSha256) {
     const tarballPath = join(cacheDir, archive.filename);
     const metadataPath = join(cacheDir, archive.metadataFilename);
-    // Deliberately outside the try/catch below: a permission error probing the
+    // Outside the try/catch below on purpose: a permission error probing the
     // cache must propagate instead of reading as "invalid cache" and triggering
     // a re-download into a directory we cannot write anyway.
     if (!(await pathExistsStrict(tarballPath)) || !(await pathExistsStrict(metadataPath))) {
@@ -135,7 +174,7 @@ async function validateCachedArchive(archive, cacheDir, expectedSha256) {
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
  */
-async function downloadToCache(archive, cacheDir, onProgress, expectedSha256, onCacheProgress) {
+async function downloadToCache(archive, cacheDir, onProgress, expectedSha256, onCacheProgress, integrity = {}) {
     const tarballPath = join(cacheDir, archive.filename);
     // Use a unique .part path so concurrent downloads for the same archive
     // do not clobber each other's partial files.
@@ -157,24 +196,10 @@ async function downloadToCache(archive, cacheDir, onProgress, expectedSha256, on
             }
         }
         else {
-            // Default integrity check: verify against Mozilla's published
-            // SHA256SUMS. TLS alone is thin trust for the artifact that becomes
-            // the git baseline every patch is built on — a compromised CDN
-            // response would otherwise be trusted with no signal. Mismatch fails
-            // closed (the catch below deletes the artifact); an unfetchable
-            // SHA256SUMS degrades to a loud warning so offline/mirror workflows
-            // keep working (pin firefox.sha256 in fireforge.json to fail closed
-            // even then).
+            // Default integrity check (see verifyAgainstPublishedSha256): any
+            // failure throws, and the catch below deletes the promoted artifact.
             onCacheProgress?.(`Verifying archive against published SHA256SUMS...`);
-            const publishedSha256 = await fetchPublishedSha256(archive);
-            if (publishedSha256 === null) {
-                warn(`Could not verify ${archive.filename} against Mozilla's published SHA256SUMS ` +
-                    `(${archive.checksumsUrl} unavailable). The download is trusted on TLS alone — ` +
-                    'set firefox.sha256 in fireforge.json to require checksum verification.');
-            }
-            else if (sha256 !== publishedSha256) {
-                throw new ChecksumMismatchError(archive.product, publishedSha256, sha256, archive.url);
-            }
+            await verifyAgainstPublishedSha256(archive, sha256, integrity);
         }
         onCacheProgress?.(`Writing source archive cache metadata for ${archive.metadataFilename}...`);
         await writeJson(metadataPath, {
@@ -219,6 +244,6 @@ async function removeArchivePartFiles(archive, cacheDir) {
     }
     catch (error) {
         void error;
-        // Cache dir may not exist yet — that's fine.
+        // Cache dir may not exist yet. That's fine.
     }
 }