@hominis/fireforge 0.45.0 → 0.46.0

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 precisely 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) {
@@ -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, {

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

@@ -5,6 +5,21 @@
  * Progress callback for download operations.
  */
 export type ProgressCallback = (downloaded: number, total: number) => void;
+/**
+ * Fetches a URL with timeout and bounded retry for transient failures
+ * (429/5xx, network errors, the per-request timeout).
+ *
+ * Any other response — 2xx or a non-retryable failure such as 404 — is
+ * returned as-is on the first attempt; the caller decides what a given
+ * status means for ITS request. Shared by the tarball download and the
+ * SHA256SUMS lookup so both requests the download makes survive the same
+ * transient blips: with checksum verification failing closed, an
+ * un-retried checksum fetch would throw away a just-landed 600 MB archive
+ * over one dropped connection.
+ *
+ * @throws DownloadError once every attempt has failed with a retryable error
+ */
+export declare function fetchWithRetry(url: string): Promise<Response>;
 /**
  * Downloads a file from a URL with progress tracking, timeout, and retry.
  * @param url - URL to download

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

@@ -7,7 +7,13 @@ import { basename } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { DownloadError, VersionNotFoundError } from '../errors/download.js';
-/** Default request timeout in milliseconds (60 seconds). */
+import { sleep } from '../utils/sleep.js';
+/**
+ * Per-attempt request timeout in milliseconds (60 seconds). Every request
+ * the download makes — the tarball and the SHA256SUMS lookup in
+ * `firefox-cache.ts` — goes through {@link fetchWithRetry} and so shares
+ * this abort ceiling.
+ */
 const REQUEST_TIMEOUT_MS = 60_000;
 /** Maximum number of download attempts. */
 const MAX_ATTEMPTS = 3;
@@ -18,11 +24,20 @@ const RETRY_BASE_DELAY_MS = 1_000;
 /** Stall detection timeout — abort if no data received for this duration (30 seconds). */
 const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
 /**
- * Fetches a URL with timeout and bounded retry for transient failures.
+ * Fetches a URL with timeout and bounded retry for transient failures
+ * (429/5xx, network errors, the per-request timeout).
  *
- * Non-retryable errors (e.g. 404) are thrown immediately.
+ * Any other response — 2xx or a non-retryable failure such as 404 — is
+ * returned as-is on the first attempt; the caller decides what a given
+ * status means for ITS request. Shared by the tarball download and the
+ * SHA256SUMS lookup so both requests the download makes survive the same
+ * transient blips: with checksum verification failing closed, an
+ * un-retried checksum fetch would throw away a just-landed 600 MB archive
+ * over one dropped connection.
+ *
+ * @throws DownloadError once every attempt has failed with a retryable error
  */
-async function fetchWithRetry(url) {
+export async function fetchWithRetry(url) {
     let lastError;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
         const controller = new AbortController();
@@ -31,23 +46,12 @@ async function fetchWithRetry(url) {
         }, REQUEST_TIMEOUT_MS);
         try {
             const response = await fetch(url, { signal: controller.signal });
-            if (response.status === 404) {
-                throw new VersionNotFoundError(basename(url).replace('.source.tar.xz', ''));
-            }
-            if (RETRYABLE_STATUS_CODES.has(response.status)) {
-                lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
-            }
-            else if (!response.ok) {
-                throw new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
-            }
-            else {
+            if (!RETRYABLE_STATUS_CODES.has(response.status)) {
                 return response;
             }
+            lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
         }
         catch (error) {
-            if (error instanceof VersionNotFoundError || error instanceof DownloadError) {
-                throw error;
-            }
             // Network / timeout errors are retryable
             lastError = error;
         }
@@ -55,9 +59,7 @@ async function fetchWithRetry(url) {
             clearTimeout(timer);
         }
         if (attempt < MAX_ATTEMPTS - 1) {
-            await new Promise((resolve) => {
-                setTimeout(resolve, RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
-            });
+            await sleep(RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
         }
     }
     if (lastError instanceof DownloadError) {
@@ -65,6 +67,20 @@ async function fetchWithRetry(url) {
     }
     throw new DownloadError(lastError instanceof Error ? lastError.message : 'Download failed after retries', url, lastError instanceof Error ? lastError : undefined);
 }
+/**
+ * Fetches the archive itself: a 404 is the release not existing
+ * (`VersionNotFoundError`), any other non-2xx is a `DownloadError`.
+ */
+async function fetchArchive(url) {
+    const response = await fetchWithRetry(url);
+    if (response.status === 404) {
+        throw new VersionNotFoundError(basename(url).replace('.source.tar.xz', ''));
+    }
+    if (!response.ok) {
+        throw new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
+    }
+    return response;
+}
 /**
  * Creates a Transform stream that aborts if no data is received within the stall timeout.
  * The timer resets on each chunk. If it fires, the stream is destroyed with a DownloadError.
@@ -110,7 +126,7 @@ function createStallDetector(url, timeoutMs = DOWNLOAD_STALL_TIMEOUT_MS) {
  * @returns The content-length if available, otherwise undefined
  */
 export async function downloadFile(url, destPath, onProgress) {
-    const response = await fetchWithRetry(url);
+    const response = await fetchArchive(url);
     if (!response.body) {
         throw new DownloadError('No response body received', url);
     }

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

@@ -2,11 +2,12 @@
  * Firefox source extraction and installed version detection.
  */
 /**
- * Validates entry names from a `tar -tf` listing.
+ * Validates entry names from a `tar -tf` listing: escaping paths and
+ * `.git` members are both rejected.
  * @param names - Listing lines (one member name per line)
- * @returns The first unsafe member name, or null when all are safe
+ * @returns The first unsafe member name, or undefined when all are safe
  */
-export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | null;
+export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | undefined;
 /**
  * Validates symlink and hardlink targets from a `tar -tvf` listing.
  *
@@ -17,9 +18,9 @@ export declare function findUnsafeArchiveEntryName(names: readonly string[]): st
  * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
  *
  * @param verboseLines - `tar -tvf` listing lines
- * @returns A description of the first unsafe link found, or null
+ * @returns A description of the first unsafe link found, or undefined
  */
-export declare function findUnsafeArchiveLink(verboseLines: readonly string[]): string | null;
+export declare function findUnsafeArchiveLink(verboseLines: readonly string[]): string | undefined;
 /**
  * Extracts a tar.xz archive after a listing preflight that rejects
  * path-traversal member names and escaping link targets.

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

@@ -20,19 +20,42 @@ function isUnsafeArchivePath(path) {
     return path.split(/[\\/]/).includes('..');
 }
 /**
- * Validates entry names from a `tar -tf` listing.
+ * Returns true when an archive member path has a `.git` segment at any
+ * depth (`.git`, `.git/config`, `foo/.git/hooks/pre-commit`). Such a member
+ * lands INSIDE the extraction root, so the traversal check passes it — but
+ * the extracted tree is immediately turned into a git repository and
+ * committed, and git honours a pre-seeded `.git/config` (`core.fsmonitor`,
+ * `core.hooksPath`) or `.git/hooks/*` on that first commit. Only the `.git`
+ * directory/file is rejected; `.gitmodules`, `.gitignore` and the like are
+ * legitimate upstream files.
+ */
+function hasGitSegment(path) {
+    return path.split(/[\\/]/).some((segment) => segment.toLowerCase() === '.git');
+}
+/**
+ * Returns true when an archive member NAME must be rejected: an escaping
+ * path, or a `.git` segment (see {@link hasGitSegment}). Link targets use
+ * the narrower {@link isUnsafeArchivePath} — a target can only be reached
+ * through a member name that was checked here.
+ */
+function isUnsafeArchiveMemberName(name) {
+    return isUnsafeArchivePath(name) || hasGitSegment(name);
+}
+/**
+ * Validates entry names from a `tar -tf` listing: escaping paths and
+ * `.git` members are both rejected.
  * @param names - Listing lines (one member name per line)
- * @returns The first unsafe member name, or null when all are safe
+ * @returns The first unsafe member name, or undefined when all are safe
  */
 export function findUnsafeArchiveEntryName(names) {
     for (const raw of names) {
         const name = raw.trim();
         if (name.length === 0)
             continue;
-        if (isUnsafeArchivePath(name))
+        if (isUnsafeArchiveMemberName(name))
             return name;
     }
-    return null;
+    return undefined;
 }
 /**
  * Validates symlink and hardlink targets from a `tar -tvf` listing.
@@ -44,7 +67,7 @@ export function findUnsafeArchiveEntryName(names) {
  * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
  *
  * @param verboseLines - `tar -tvf` listing lines
- * @returns A description of the first unsafe link found, or null
+ * @returns A description of the first unsafe link found, or undefined
  */
 export function findUnsafeArchiveLink(verboseLines) {
     for (const line of verboseLines) {
@@ -64,7 +87,7 @@ export function findUnsafeArchiveLink(verboseLines) {
                 return `hardlink target: ${target}`;
         }
     }
-    return null;
+    return undefined;
 }
 /**
  * Lists the archive and rejects members that could escape the extraction
@@ -111,7 +134,7 @@ function createLineScanner(onLine) {
 }
 /**
  * Runs one tar listing pass, streaming lines through `checkLine` and
- * returning the first unsafe finding (or null) plus the exit code.
+ * returning the first unsafe finding (or undefined) plus the exit code.
  *
  * Streaming matters for safety, not just memory: a buffered `exec` collector
  * silently truncates at 50 MB, and a full Firefox `-tvf` listing already
@@ -124,10 +147,10 @@ function createLineScanner(onLine) {
 async function runListingScan(archivePath, tarFlag, checkLine) {
     // LC_ALL=C keeps the -tvf column format stable for the link parse.
     const listEnv = { LC_ALL: 'C', LANG: 'C' };
-    let unsafe = null;
+    let unsafe;
     let stderrTail = '';
     const scanner = createLineScanner((line) => {
-        if (unsafe === null) {
+        if (unsafe === undefined) {
             unsafe = checkLine(line);
         }
     });
@@ -146,24 +169,19 @@ async function runListingScan(archivePath, tarFlag, checkLine) {
 }
 async function preflightArchiveEntries(archivePath) {
     const [nameScan, linkScan] = await Promise.all([
-        runListingScan(archivePath, '-tf', (line) => {
-            const name = line.trim();
-            if (name.length === 0)
-                return null;
-            return isUnsafeArchivePath(name) ? name : null;
-        }),
+        runListingScan(archivePath, '-tf', (line) => findUnsafeArchiveEntryName([line])),
         runListingScan(archivePath, '-tvf', (line) => findUnsafeArchiveLink([line])),
     ]);
     if (nameScan.exitCode !== 0) {
         throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameScan.exitCode}:\n${nameScan.stderrTail}`));
     }
-    if (nameScan.unsafe !== null) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root: ${nameScan.unsafe}`));
+    if (nameScan.unsafe !== undefined) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root or seed .git: ${nameScan.unsafe}`));
     }
     if (linkScan.exitCode !== 0) {
         throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${linkScan.exitCode}:\n${linkScan.stderrTail}`));
     }
-    if (linkScan.unsafe !== null) {
+    if (linkScan.unsafe !== undefined) {
         throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${linkScan.unsafe})`));
     }
 }

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

@@ -5,26 +5,9 @@
  * {@link downloadFirefoxSource} orchestrator.
  */
 import type { FirefoxProduct } from '../types/config.js';
+import type { ArchiveIntegrityOptions } from './firefox-cache.js';
 import type { ProgressCallback } from './firefox-download.js';
-export { resolveArchive } from './firefox-archive.js';
-export type { ProgressCallback } from './firefox-download.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.9.0esr")
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Full URL to the source tarball
- */
-export declare function getDownloadUrl(version: string, product?: FirefoxProduct, candidate?: string): string;
-/**
- * Gets the filename for a Firefox source tarball.
- * @param version - Firefox version
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Tarball filename
- */
-export declare function getTarballFilename(version: string, product?: FirefoxProduct, candidate?: string): string;
 /**
  * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
  * CLI command uses this to swap spinners between the bytes-on-the-wire phase
@@ -49,20 +32,35 @@ export type FirefoxSourceProgressCallback = (message: string) => void;
  * @returns names of the directories that were removed
  */
 export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<string[]>;
+/** Inputs for {@link downloadFirefoxSource}. */
+export interface DownloadFirefoxSourceOptions {
+    /** Firefox version to fetch, e.g. `140.9.0esr`. */
+    version: string;
+    /** Product channel the version belongs to. */
+    product: FirefoxProduct;
+    /** Directory the extracted source tree is moved into. */
+    destDir: string;
+    /** Directory holding downloaded tarballs between runs. */
+    cacheDir: string;
+    /** Called with byte progress for the whole transfer. */
+    onProgress?: ProgressCallback | undefined;
+    /** Called when the run moves from downloading to extracting. */
+    onPhase?: FirefoxSourcePhaseCallback | undefined;
+    /** Expected archive checksum; verified after download when supplied. */
+    expectedSha256?: string | undefined;
+    /** Called with byte progress within the current phase. */
+    onPhaseProgress?: FirefoxSourceProgressCallback | undefined;
+    /**
+     * Release-candidate build directory (e.g. `build2`), resolving the archive
+     * under `candidates/` instead of `releases/`.
+     */
+    candidate?: string | undefined;
+    /** Integrity-check defaults for unpinned downloads. */
+    integrity?: ArchiveIntegrityOptions | undefined;
+}
 /**
  * Downloads and extracts Firefox source.
- * @param version - Firefox version to download
- * @param product - Firefox product type
- * @param destDir - Destination directory for extracted source
- * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback for the download byte stream
- * @param onPhase - Optional callback fired when the function transitions
- *   between phases (`'download'` → `'extract'`). Fires exactly once per
- *   phase even if the cached archive path skips the wire entirely.
- * @param expectedSha256 - Expected archive checksum; verified after download when supplied
- * @param onPhaseProgress - Called with byte progress within the current phase
- * @param candidate - Optional release-candidate build directory (e.g.
- *   "build2") resolving the archive under `candidates/` instead of
- *   `releases/`.
+ *
+ * @param options - See {@link DownloadFirefoxSourceOptions}.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback, candidate?: string): Promise<void>;
+export declare function downloadFirefoxSource(options: DownloadFirefoxSourceOptions): Promise<void>;

package/dist/src/core/firefox.js

@@ -14,28 +14,7 @@ import { resolveArchive } from './firefox-archive.js';
 import { ensureCachedArchive, invalidateArchiveCache } from './firefox-cache.js';
 import { extractTarXz } from './firefox-extract.js';
 // ── Re-exports (preserve public API) ──
-export { resolveArchive } from './firefox-archive.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
-/**
- * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.9.0esr")
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Full URL to the source tarball
- */
-export function getDownloadUrl(version, product = 'firefox', candidate) {
-    return resolveArchive(version, product, candidate).url;
-}
-/**
- * Gets the filename for a Firefox source tarball.
- * @param version - Firefox version
- * @param product - Firefox product type
- * @param candidate - Optional release-candidate build directory (e.g. "build2")
- * @returns Tarball filename
- */
-export function getTarballFilename(version, product = 'firefox', candidate) {
-    return resolveArchive(version, product, candidate).filename;
-}
 /**
  * Classifies an extraction failure as archive corruption (invalidate the
  * cache and re-download) versus an environmental problem (keep the cached
@@ -95,27 +74,17 @@ export async function sweepOrphanedEngineWorkDirs(destDir) {
 }
 /**
  * Downloads and extracts Firefox source.
- * @param version - Firefox version to download
- * @param product - Firefox product type
- * @param destDir - Destination directory for extracted source
- * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback for the download byte stream
- * @param onPhase - Optional callback fired when the function transitions
- *   between phases (`'download'` → `'extract'`). Fires exactly once per
- *   phase even if the cached archive path skips the wire entirely.
- * @param expectedSha256 - Expected archive checksum; verified after download when supplied
- * @param onPhaseProgress - Called with byte progress within the current phase
- * @param candidate - Optional release-candidate build directory (e.g.
- *   "build2") resolving the archive under `candidates/` instead of
- *   `releases/`.
+ *
+ * @param options - See {@link DownloadFirefoxSourceOptions}.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate) {
+export async function downloadFirefoxSource(options) {
+    const { version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate, integrity, } = options;
     const archive = resolveArchive(version, product, candidate);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);
     onPhase?.('download');
-    await ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onPhaseProgress);
+    await ensureCachedArchive(archive, cacheDir, onProgress, expectedSha256, onPhaseProgress, integrity);
     // Extract to a unique temporary directory so concurrent downloads for
     // the same destination do not clobber each other.
     onPhase?.('extract');

package/dist/src/core/furnace-apply-dry-run.d.ts

@@ -4,14 +4,9 @@
  * stay within the per-file line budget. Consumed only by that module.
  */
 import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
-interface DirectoryEntry {
-    isFile(): boolean;
-    isSymbolicLink?(): boolean;
-    name: string;
-}
+import { type DirectoryEntry } from './furnace-dir-entry.js';
 /** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
 export declare function buildCustomDryRunActions(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig, targetDir: string, entries: DirectoryEntry[]): Promise<{
     actions: DryRunAction[];
     stepErrors: StepError[];
 }>;
-export {};

package/dist/src/core/furnace-apply-dry-run.js

@@ -9,14 +9,8 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { describeLocaleFtlJarMnRegistration, describeSharedFtlPrune } from './furnace-apply-ftl.js';
 import { describeFragmentExpansion } from './furnace-css-fragments.js';
+import { isRegularFile } from './furnace-dir-entry.js';
 import { validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
-function isRegularFile(entry) {
-    if (!entry.isFile())
-        return false;
-    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
-        return false;
-    return true;
-}
 /** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
 export async function buildCustomDryRunActions(ctx, config, targetDir, entries) {
     const { engineDir, name, componentDir, ftlDir } = ctx;

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -1,16 +1,5 @@
 import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
-interface DirectoryEntry {
-    isFile(): boolean;
-    isSymbolicLink?(): boolean;
-    name: string;
-}
-/**
- * True for a plain-file directory entry — symlinks and directories are
- * never copy candidates. Exported for the patch-owned overwrite probe,
- * which walks the same override copy-candidate set as apply.
- */
-export declare function isRegularFile(entry: DirectoryEntry): boolean;
 /**
  * Filter deciding which files in an override workspace directory are candidates
  * for copying into the engine. Exported so `furnace remove` can invert apply