import { isAbsolute } from "node:path"; import { ArtifactPathRegistry, normalizeArtifactPath, } from "../ArtifactPaths.js"; import { ArtifactReaderFailure, type ArtifactEntry, type ArtifactReader, } from "../ArtifactReader.js"; import { AsarArtifactReader } from "../AsarArtifactReader.js"; import { CpioArtifactReader } from "../CpioArtifactReader.js"; import type { ArtifactNode } from "../../domain/artifactGraph.js"; import { classifyArtifactContent, createArtifactNode, createOccurrence, nearestParent, type MutableOccurrence, } from "./ArtifactGraphConstruction.js"; import { STRICT_INTEGRITY_POLICY, type ArtifactIntegrityPolicy, } from "./types.js"; import { hashReadable } from "../ArtifactHash.js"; export interface PendingIntegrityContradiction { readonly logicalPath: string; readonly declaredSha256: string; readonly observedSha256: string; readonly entryKind: "file" | "slice"; readonly unpacked: boolean; } const UNAVAILABLE_UNPACKED_LIMITATION = "ASAR unpacked companion bytes were unavailable; no content hash or child artifact was produced."; const emptyScan = (): { readonly nodes: Map; readonly occurrences: MutableOccurrence[]; readonly pendingContradictions: PendingIntegrityContradiction[]; } => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] }); interface ScanContext { readonly reader: ArtifactReader; readonly signal: AbortSignal | undefined; readonly integrity: ArtifactIntegrityPolicy; readonly nodes: Map; readonly occurrences: MutableOccurrence[]; readonly pendingContradictions: PendingIntegrityContradiction[]; readonly occurrenceByPath: Map; readonly registry: ArtifactPathRegistry; readonly expandedContainerIds: Set; } export const scanReader = async ( reader: ArtifactReader | undefined, signal?: AbortSignal, integrity: ArtifactIntegrityPolicy = STRICT_INTEGRITY_POLICY, ): Promise<{ readonly nodes: Map; readonly occurrences: MutableOccurrence[]; readonly pendingContradictions: PendingIntegrityContradiction[]; }> => { const { nodes, occurrences, pendingContradictions } = emptyScan(); if (reader === undefined) return { nodes, occurrences, pendingContradictions }; const context: ScanContext = { reader, signal, integrity, nodes, occurrences, pendingContradictions, occurrenceByPath: new Map(), registry: new ArtifactPathRegistry(), expandedContainerIds: new Set(), }; await visitArtifactEntries(context, reader, ""); // Archive directories may appear after their children. Resolve containment // against the complete index before directory identities are materialized. for (const occurrence of occurrences) occurrence.parent_occurrence_id = nearestParent( occurrence.logical_path, context.occurrenceByPath, context.expandedContainerIds, )?.occurrence_id ?? null; return { nodes, occurrences, pendingContradictions }; }; const visitArtifactEntries = async ( context: ScanContext, currentReader: ArtifactReader, prefix: string, ): Promise => { const stack: Array<{ readonly reader: ArtifactReader; readonly prefix: string; readonly iterator: AsyncIterator; readonly owned: boolean; }> = [ { reader: currentReader, prefix, iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](), owned: false, }, ]; try { while (stack.length > 0) { const frame = stack.at(-1); if (frame === undefined) break; const next = await frame.iterator.next(); if (next.done) { stack.pop(); if (frame.owned) await frame.reader.close(); continue; } const entry = next.value; const logicalPath = normalizeArtifactPath( frame.prefix.length === 0 ? entry.path : `${frame.prefix}/${entry.path}`, ); const expandable = isExpandableAsar(entry, logicalPath) || entry.nestedArchive === "gzip-cpio"; context.registry.add(logicalPath, expandable ? "directory" : entry.kind); const occurrence = createOccurrence(entry, logicalPath, null); let digested: DigestedEntry | undefined; try { digested = await digestArtifactEntry( context, frame.reader, entry, logicalPath, ); } catch (cause: unknown) { if (!isUnavailableUnpackedEntry(cause, entry)) { // A streamed CRC, size-bound, or format failure is per-member // evidence loss under record-and-continue: keep the occurrence // unavailable with its diagnostic, without inventing a node. if ( context.integrity.mode !== "record-and-continue" || !(cause instanceof ArtifactReaderFailure) || (cause.reason !== "integrity" && cause.reason !== "limit" && cause.reason !== "format") ) throw cause; occurrence.hash_status = "unavailable"; occurrence.limitations.push( `Member content could not be verified: ${cause.message}`, ); context.occurrences.push(occurrence); context.occurrenceByPath.set(logicalPath, occurrence); continue; } occurrence.hash_status = "unavailable"; occurrence.limitations.push(UNAVAILABLE_UNPACKED_LIMITATION); } if (digested !== undefined) { context.nodes.set(digested.node.artifact_id, digested.node); occurrence.artifact_id = digested.node.artifact_id; occurrence.hash_status = digested.mismatched ? "mismatched" : "verified"; if (digested.mismatched) occurrence.limitations.push( "Declared integrity metadata contradicts observed bytes.", ...digested.mismatchDetails, ); } context.occurrences.push(occurrence); context.occurrenceByPath.set(logicalPath, occurrence); if (expandable && digested?.mismatched !== true) { const parent = frame.reader; const nested: ArtifactReader = entry.nestedArchive === "gzip-cpio" ? new CpioArtifactReader( (signal) => parent.open(entry, signal), context.integrity.mode, ) : new AsarArtifactReader(entry.adapterKey); // Only traversed containers can own members, not opaque archive-named files. context.expandedContainerIds.add(occurrence.occurrence_id); stack.push({ reader: nested, prefix: logicalPath, iterator: nested.entries(context.signal)[Symbol.asyncIterator](), owned: true, }); } } } finally { await Promise.allSettled( stack .filter(({ owned }) => owned) .map(async ({ reader, iterator }) => { await iterator.return?.(); await reader.close(); }), ); } }; interface DigestedEntry { readonly node: ArtifactNode; readonly mismatched: boolean; /** Declared and observed values of a non-SHA-256 checksum that disagreed. */ readonly mismatchDetails: readonly string[]; } const digestArtifactEntry = async ( context: ScanContext, currentReader: ArtifactReader, entry: ArtifactEntry, logicalPath: string, ): Promise => { if ( (entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted || entry.contentUnavailable === true ) return undefined; const checksum = entry.declaredChecksum; const digest = await hashReadable( await currentReader.open(entry, context.signal), context.signal, checksum?.algorithm, ); const sha256Mismatch = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256; const checksumMismatch = checksum !== undefined && checksum.value !== digest.also; const mismatched = sha256Mismatch || checksumMismatch; if (mismatched && context.integrity.mode === "fail") throw new ArtifactReaderFailure( "integrity", sha256Mismatch || checksum === undefined ? `Artifact integrity metadata disagrees with content: ${logicalPath}` : `Declared ${checksum.algorithm} checksum disagrees with content: ${logicalPath}`, undefined, { logicalPath, declaredSha256: entry.declaredSha256, calculatedSha256: digest.sha256, unpacked: entry.unpacked, }, ); if (sha256Mismatch && entry.declaredSha256 !== null) context.pendingContradictions.push({ logicalPath, declaredSha256: entry.declaredSha256, observedSha256: digest.sha256, entryKind: entry.kind, unpacked: entry.unpacked, }); const classified = entry.kind === "slice" ? ({ kind: "universal-slice", format: "mach-o" } as const) : classifyArtifactContent(logicalPath, digest.prefix, digest.bytes); return { node: createArtifactNode({ sha256: digest.sha256, size: digest.bytes, kind: classified.kind, format: classified.format, executable: entry.executable, contentState: "embedded", limitations: mismatched ? [ "Observed content contradicts declared integrity metadata and is untrusted.", ] : [], }), mismatched, mismatchDetails: checksumMismatch ? [ `Declared ${checksum.algorithm} ${checksum.value} disagrees with observed ${digest.also ?? "unavailable"}.`, ] : [], }; }; const isExpandableAsar = (entry: ArtifactEntry, logicalPath: string): boolean => entry.kind === "file" && logicalPath.toLowerCase().endsWith(".asar") && isAbsolute(entry.adapterKey); const isUnavailableUnpackedEntry = ( cause: unknown, entry: ArtifactEntry, ): boolean => entry.unpacked && cause instanceof ArtifactReaderFailure && cause.reason === "unavailable";