@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,30 +0,0 @@
-/**
- * Cache validation, invalidation, and download-to-cache logic.
- */
-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, integrity?: ArchiveIntegrityOptions): Promise<void>;
-/**
- * Removes cached tarball, metadata, and partial download files for an archive.
- * @param archive - Resolved archive descriptor
- * @param cacheDir - Cache directory
- */
-export declare function invalidateArchiveCache(archive: ResolvedArchive, cacheDir: string): Promise<void>;

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

@@ -1,248 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Cache validation, invalidation, and download-to-cache logic.
- */
-import { createHash, randomUUID } from 'node:crypto';
-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, 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, fetchWithRetry } from './firefox-download.js';
-/**
- * Computes the SHA-256 hex digest of a file.
- * @param filePath - Path to the file
- */
-async function sha256File(filePath) {
-    const hash = createHash('sha256');
-    const stream = createReadStream(filePath);
-    await pipeline(stream, hash);
-    return hash.digest('hex');
-}
-/**
- * Fetches Mozilla's published SHA256SUMS for the release and extracts the
- * 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>`
- *   `<64-hex-digest> *<release-relative-path>`
- */
-async function fetchPublishedSha256(archive) {
-    try {
-        const response = await fetchWithRetry(archive.checksumsUrl);
-        if (!response.ok) {
-            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 { sha256: match[1] };
-            }
-        }
-        return {
-            sha256: null,
-            reason: `SHA256SUMS does not list ${archive.pathInChecksums} (wrong file, or a non-Mozilla response)`,
-        };
-    }
-    catch (error) {
-        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, integrity = {}) {
-    const lockPath = createSiblingLockPath(join(cacheDir, archive.filename), '.fireforge-cache.lock');
-    await withFileLock(lockPath, async () => {
-        onCacheProgress?.(`Validating source archive cache metadata for ${archive.filename}...`);
-        if (await validateCachedArchive(archive, cacheDir, expectedSha256)) {
-            onCacheProgress?.(`Using validated cached source archive ${archive.filename}`);
-            return;
-        }
-        if (await cacheEntryExists(archive, cacheDir)) {
-            onCacheProgress?.(`Invalid cached source archive metadata; refreshing ${archive.filename}`);
-            await invalidateArchiveCache(archive, cacheDir);
-        }
-        else {
-            await removeArchivePartFiles(archive, cacheDir);
-        }
-        await downloadToCache(archive, cacheDir, onProgress, expectedSha256, onCacheProgress, integrity);
-    });
-}
-async function cacheEntryExists(archive, cacheDir) {
-    return ((await pathExistsStrict(join(cacheDir, archive.filename))) ||
-        (await pathExistsStrict(join(cacheDir, archive.metadataFilename))));
-}
-/**
- * Validates a cached archive using sidecar metadata and SHA-256 checksum.
- * @param archive - Resolved archive descriptor
- * @param cacheDir - Cache directory
- * @returns True if the cache entry is valid
- */
-async function validateCachedArchive(archive, cacheDir, expectedSha256) {
-    const tarballPath = join(cacheDir, archive.filename);
-    const metadataPath = join(cacheDir, archive.metadataFilename);
-    // 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))) {
-        return false;
-    }
-    try {
-        const metadata = validateArchiveMetadata(await readJson(metadataPath));
-        if (metadata.product !== archive.product ||
-            metadata.archiveVersion !== archive.archiveVersion ||
-            metadata.url !== archive.url) {
-            return false;
-        }
-        if (metadata.contentLength !== undefined) {
-            const archiveStats = await stat(tarballPath);
-            if (archiveStats.size !== metadata.contentLength) {
-                return false;
-            }
-        }
-        if (expectedSha256 || metadata.sha256) {
-            const actualHash = await sha256File(tarballPath);
-            if (expectedSha256 && actualHash !== expectedSha256) {
-                return false;
-            }
-            if (metadata.sha256 && actualHash !== metadata.sha256) {
-                return false;
-            }
-        }
-        return true;
-    }
-    catch (error) {
-        verbose(`Cache validation failed for ${tarballPath}; treating cache entry as invalid: ${toError(error).message}`);
-        return false;
-    }
-}
-/**
- * Downloads an archive to cache using an atomic temp file and sidecar metadata.
- * @param archive - Resolved archive descriptor
- * @param cacheDir - Cache directory
- * @param onProgress - Optional progress callback
- */
-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.
-    const partPath = `${tarballPath}.part-${randomUUID()}`;
-    const metadataPath = join(cacheDir, archive.metadataFilename);
-    let promotedTarball = false;
-    try {
-        onCacheProgress?.(`Downloading source archive to cache: ${archive.filename}`);
-        const contentLength = await downloadFile(archive.url, partPath, onProgress);
-        await rename(partPath, tarballPath);
-        promotedTarball = true;
-        onCacheProgress?.(`Calculating source archive SHA-256 for ${archive.filename}...`);
-        const sha256 = await sha256File(tarballPath);
-        if (expectedSha256) {
-            // Operator-pinned digest (firefox.sha256 config): takes precedence
-            // and always fails closed.
-            if (sha256 !== expectedSha256) {
-                throw new ChecksumMismatchError(archive.product, expectedSha256, sha256, archive.url);
-            }
-        }
-        else {
-            // Default integrity check (see verifyAgainstPublishedSha256): any
-            // failure throws, and the catch below deletes the promoted artifact.
-            onCacheProgress?.(`Verifying archive against published SHA256SUMS...`);
-            await verifyAgainstPublishedSha256(archive, sha256, integrity);
-        }
-        onCacheProgress?.(`Writing source archive cache metadata for ${archive.metadataFilename}...`);
-        await writeJson(metadataPath, {
-            requestedVersion: archive.requestedVersion,
-            product: archive.product,
-            archiveVersion: archive.archiveVersion,
-            url: archive.url,
-            ...(contentLength !== undefined ? { contentLength } : {}),
-            sha256,
-            downloadedAt: new Date().toISOString(),
-        });
-        onCacheProgress?.(`Source archive cache metadata written: ${archive.metadataFilename}`);
-    }
-    catch (error) {
-        await removeFile(partPath);
-        if (promotedTarball) {
-            await removeFile(tarballPath);
-            await removeFile(metadataPath);
-        }
-        throw error;
-    }
-}
-/**
- * Removes cached tarball, metadata, and partial download files for an archive.
- * @param archive - Resolved archive descriptor
- * @param cacheDir - Cache directory
- */
-export async function invalidateArchiveCache(archive, cacheDir) {
-    const tarballPath = join(cacheDir, archive.filename);
-    const metadataPath = join(cacheDir, archive.metadataFilename);
-    await removeArchivePartFiles(archive, cacheDir);
-    await removeFile(tarballPath);
-    await removeFile(metadataPath);
-}
-async function removeArchivePartFiles(archive, cacheDir) {
-    const partPrefix = `${archive.filename}.part`;
-    try {
-        const entries = await readdir(cacheDir);
-        await Promise.all(entries
-            .filter((name) => name.startsWith(partPrefix))
-            .map((name) => removeFile(join(cacheDir, name))));
-    }
-    catch {
-        // Cache dir may not exist yet. That's fine.
-    }
-}

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

@@ -1,30 +0,0 @@
-/**
- * Download with retry, stall detection, and progress tracking.
- */
-/**
- * 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
- * @param destPath - Destination file path
- * @param onProgress - Optional progress callback
- * @returns The content-length if available, otherwise undefined
- */
-export declare function downloadFile(url: string, destPath: string, onProgress?: ProgressCallback): Promise<number | undefined>;

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

@@ -1,152 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Download with retry, stall detection, and progress tracking.
- */
-import { createWriteStream } from 'node:fs';
-import { basename } from 'node:path';
-import { Readable, Transform } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { DownloadError, VersionNotFoundError } from '../errors/download.js';
-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;
-/** HTTP status codes that are retryable. */
-const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
-/** Base delay between retries in milliseconds. */
-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
- * (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 async function fetchWithRetry(url) {
-    let lastError;
-    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => {
-            controller.abort();
-        }, REQUEST_TIMEOUT_MS);
-        try {
-            const response = await fetch(url, { signal: controller.signal });
-            if (!RETRYABLE_STATUS_CODES.has(response.status)) {
-                return response;
-            }
-            lastError = new DownloadError(`HTTP ${response.status}: ${response.statusText}`, url);
-        }
-        catch (error) {
-            // Network / timeout errors are retryable
-            lastError = error;
-        }
-        finally {
-            clearTimeout(timer);
-        }
-        if (attempt < MAX_ATTEMPTS - 1) {
-            await sleep(RETRY_BASE_DELAY_MS * (attempt + 1) ** 2);
-        }
-    }
-    if (lastError instanceof DownloadError) {
-        throw lastError;
-    }
-    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.
- * @param url - URL being downloaded (for error messages)
- * @param timeoutMs - Stall timeout in milliseconds
- */
-function createStallDetector(url, timeoutMs = DOWNLOAD_STALL_TIMEOUT_MS) {
-    let timer;
-    const clearTimer = () => {
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            timer = undefined;
-        }
-    };
-    const detector = new Transform({
-        transform(chunk, _encoding, callback) {
-            clearTimer();
-            timer = setTimeout(() => {
-                detector.destroy(new DownloadError(`Download stalled: no data received for ${Math.round(timeoutMs / 1000)} seconds`, url));
-            }, timeoutMs);
-            callback(null, chunk);
-        },
-        flush(callback) {
-            clearTimer();
-            callback();
-        },
-        destroy(error, callback) {
-            clearTimer();
-            callback(error);
-        },
-    });
-    // Start the initial timer (covers the case where the first chunk never arrives).
-    timer = setTimeout(() => {
-        detector.destroy(new DownloadError(`Download stalled: no data received for ${Math.round(timeoutMs / 1000)} seconds`, url));
-    }, timeoutMs);
-    return detector;
-}
-/**
- * Downloads a file from a URL with progress tracking, timeout, and retry.
- * @param url - URL to download
- * @param destPath - Destination file path
- * @param onProgress - Optional progress callback
- * @returns The content-length if available, otherwise undefined
- */
-export async function downloadFile(url, destPath, onProgress) {
-    const response = await fetchArchive(url);
-    if (!response.body) {
-        throw new DownloadError('No response body received', url);
-    }
-    const totalSize = parseInt(response.headers.get('content-length') ?? '0', 10);
-    let downloadedSize = 0;
-    const fileStream = createWriteStream(destPath);
-    const nodeStream = Readable.fromWeb(response.body);
-    const stallDetector = createStallDetector(url);
-    if (onProgress && totalSize > 0) {
-        const progress = new Transform({
-            transform(chunk, _encoding, callback) {
-                downloadedSize += chunk.length;
-                onProgress(downloadedSize, totalSize);
-                callback(null, chunk);
-            },
-        });
-        await pipeline(nodeStream, stallDetector, progress, fileStream);
-    }
-    else {
-        await pipeline(nodeStream, stallDetector, fileStream);
-    }
-    return totalSize > 0 ? totalSize : undefined;
-}

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

@@ -1,42 +0,0 @@
-/**
- * Firefox source extraction and installed version detection.
- */
-/**
- * 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 undefined when all are safe
- */
-export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | undefined;
-/**
- * Validates symlink and hardlink targets from a `tar -tvf` listing.
- *
- * A relative link target without `..` segments can only resolve inside the
- * extraction root, so only absolute or `..`-containing targets are rejected.
- * Symlinks are `l`-typed lines with a ` -> target` suffix (the last arrow is
- * taken, so a link whose own name contains ` -> ` still parses to its real
- * 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 undefined
- */
-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.
- * @param archivePath - Path to the archive
- * @param destDir - Destination directory
- */
-export declare function extractTarXz(archivePath: string, destDir: string, onProgress?: (message: string) => void): Promise<void>;
-/**
- * Gets the Firefox version from an existing source directory.
- * @param engineDir - Path to the engine directory
- * @returns Firefox version string
- */
-export declare function getFirefoxVersion(engineDir: string): Promise<string | undefined>;
-/**
- * Formats bytes into a human-readable string.
- * @param bytes - Number of bytes
- * @returns Formatted string (e.g., "1.5 GB")
- */
-export declare function formatBytes(bytes: number): string;