import { isUtf8 } from "node:buffer"; import { createHash } from "node:crypto"; import type { Dirent } from "node:fs"; import { lstat, mkdtemp, opendir, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { basename, dirname, isAbsolute, join, resolve } from "node:path"; import type { Readable } from "node:stream"; import { fileURLToPath, pathToFileURL } from "node:url"; import type { ReleaseExposurePort, ReleaseExposureScanVisitor, ReleaseExposureTextVisitor, } from "../application/releaseExposure/ReleaseExposurePort.js"; import type { ExecutionOptions } from "../application/AnalysisProvider.js"; import { ArtifactReaderFailure, type ArtifactEntry, type ArtifactReader, } from "./ArtifactReader.js"; import { ArtifactResourceScope, type ArtifactCleanupAttempt, type ArtifactResourceOwner, } from "./ArtifactResourceScope.js"; import { artifactFileCancellationCause, artifactFilePrimaryFacts, type ArtifactFilePrimaryFacts, } from "./ArtifactFileOperation.js"; import { decodeBinaryPlistText } from "./apple/BinaryPlistMaterializer.js"; import { InternalInvariantError, invariantViolation, } from "../domain/internalInvariant.js"; import { ArtifactEmbeddedFormatProbes } from "./ArtifactEmbeddedFormatProbes.js"; import { asarHeaderAdmissionRecovery, createAsarHeaderSignatureProbe, } from "./AsarHeader.js"; import { DEFAULT_ASAR_HEADER_ADMISSION, type AsarHeaderAdmission, } from "../config/asarHeaderAdmission.js"; import { analysisSettingLimit } from "../domain/analysisSettingDefinitions.js"; import { ArtifactTraversalObservation } from "./ArtifactTraversalObservation.js"; import { classifyEmbeddedExecutablePackage } from "./inventory/classify.js"; import { inventoryArtifactInScope } from "./inventory/ArtifactInventory.js"; import { hashStableRootArtifactHandle, openRootArtifact, releaseRootArtifact, } from "./inventory/hashStableRootArtifact.js"; import { createArtifactReader } from "./createArtifactReader.js"; import { readStableArtifact } from "./readStableArtifact.js"; import { projectArtifactCloseFailure, projectStableArtifactFailure, } from "./StableArtifactFailure.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisResourceConstraintError, cancelledBy, carriedReason, } from "../domain/analysisErrorCore.js"; import type { ArtifactInventoryResult, ArtifactOccurrence, } from "../domain/artifactGraph.js"; import { classifyFatContainerEvidence, readFatContainerHeader, readMachoHeaderPrefixFacts, } from "../domain/apple/machoContainer.js"; import { inspectPeCodeViewFromBuffer } from "../domain/binaryTarget.js"; import { hasBinaryPlistSignature } from "../domain/apple/appleArchiveFormat.js"; import { logicalPathNfc } from "../domain/artifactIdentity.js"; import type { ArtifactAdmissionLimit } from "../domain/artifactOperationError.js"; import { observeMzWindowsHeader } from "../domain/dosMz.js"; import { evidenceSubjectFormatSchema } from "../domain/evidenceSubject.js"; import { byteOrderMarkEncoding } from "../domain/textByteOrderMark.js"; import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { RELEASE_EXPOSURE_PROVIDER } from "../domain/investigationProviders.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { jsonValueSchema } from "../domain/jsonValue.js"; import { err, ok, type Result } from "../domain/result.js"; import { PACKAGED_NATIVE_IMAGES, MAX_RELEASE_EXPOSURE_FILE_BYTES, MAX_RELEASE_EXPOSURE_INVENTORY_BYTES, MAX_RELEASE_EXPOSURE_INVENTORY_ENTRIES, MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES, MAX_RELEASE_EXPOSURE_PACKAGED_PE_BYTES, MAX_RELEASE_EXPOSURE_PACKAGED_PE_READS, MAX_RELEASE_EXPOSURE_SAMPLES, MAX_RELEASE_EXPOSURE_MAP_TARGET_BYTES, MAX_RELEASE_EXPOSURE_SCRIPT_TARGET_BYTES, MAX_RELEASE_EXPOSURE_SOURCE_MAP_BYTES, MAX_RELEASE_EXPOSURE_SOURCE_MAPS, MAX_RELEASE_EXPOSURE_TEXT_BYTES, MAX_RELEASE_EXPOSURE_TEXT_MEMBER_BYTES, type ReleaseExposureScan, } from "../domain/releaseExposure.js"; import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js"; import { appendCallerPath } from "../filesystem/callerPath.js"; import { readFileHandleRange } from "../filesystem/readFileHandleRange.js"; import { isSelectedRegularFileError, RegularFileChangedError, sameRegularFileState, type StableRegularFileDescriptor, } from "../filesystem/RegularFile.js"; import { sourceMapJsonText } from "../domain/sourceMapEnvelope.js"; import { inspectSourceMap, inspectSourceMapSourceContent, } from "../javascript/sourceMaps/SourceMapFormat.js"; import { htmlArtifactReferences } from "../domain/javascript/htmlArtifactReferences.js"; import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js"; import { addSourceMapDirectives } from "../domain/javascript/javascriptStaticAnalysisCalls.js"; import { createJavaScriptAnalysisAccumulator } from "../domain/javascript/javascriptStaticAnalysisState.js"; const OPERATION = "audit_release_exposure"; type PackageFormat = Extract< ArtifactOccurrence["artifact_format"], | "asar" | "bun-standalone" | "deno-standalone" | "dotnet-bundle" | "node-sea" | "pyinstaller" >; const PACKAGE_FORMATS = [ "asar", "bun-standalone", "deno-standalone", "dotnet-bundle", "node-sea", "pyinstaller", ] as const satisfies readonly PackageFormat[]; const EXTRACTABLE = new Set(PACKAGE_FORMATS); const asPackageFormat = (format: string): PackageFormat | null => EXTRACTABLE.has(format) ? (format as PackageFormat) : null; const NATIVE = new Set(["elf", "mach-o", "mach-o-universal", "pe"]); const TEXT_EXTENSION = /\.(?:cjs|css|cts|env|html|htm|ini|js|json|jsx|map|md|mjs|mts|pem|plist|toml|ts|tsx|txt|xml|yaml|yml)$/iu; const SIBLING_LIST_LIMIT = 4096; const CONTAINER_LIST_LIMIT = 4096; const OPEN_CONTAINER_LIMIT = 8; const EMBEDDED_PROBE_LIMIT = 8; const PDB_READ_LIMIT = 4; const LIMITATION_CAP = 8; const SCAN_INTERRUPTED = "The member scan stopped on unfinished cleanup. Members it did not reach are unknown."; const SCAN_CANCELLED = "The member scan was cancelled. Members it did not reach are unknown."; /** Decoded representation bound for one binary plist text member. */ const RELEASE_EXPOSURE_PLIST_DECODE_BYTES = 16 * 1024 * 1024; /** Bytes of a member that decide how its NULs are read. */ const MEMBER_ENCODING_HEADER_BYTES = 512; /** One header byte in this many being NUL is too many for UTF-8 text. */ const WIDE_TEXT_NUL_DIVISOR = 8; const PE_MEMBER_NAME = /\.(?:dll|exe|sys)$/iu; const JAVASCRIPT_MEMBER_NAME = /\.(?:[cm]?[jt]s|[jt]sx)$/iu; /** Markup that `htmlArtifactReferences` reads for scripts. SVG can carry them too. */ const SCRIPT_PAGE_NAME = /\.(?:html?|svg)$/iu; type NativeFormat = "elf" | "mach-o" | "mach-o-universal" | "pe"; type InventoryOccurrence = ArtifactInventoryResult["occurrences"][number]; /** One read attempt. Allowance and read failure are different facts. */ type MemberRead = | { readonly kind: "bytes"; readonly bytes: Buffer } | { readonly kind: "over_allowance"; readonly prefix: Buffer | null } | { readonly kind: "unread" }; type ReadMember = (budget: number) => Promise; /** Interpretation is separate from the member's source path. */ interface SourceMapReference { readonly location: string; readonly kind: "javascript-source-map" | "possible-linker-map"; } const namedMapReference = ( logical: string, location: string, ): SourceMapReference => ({ location, kind: isJavaScriptSourceMapName(logical) ? "javascript-source-map" : "possible-linker-map", }); interface OpenContainer { readonly path: string; readonly reader: ArtifactReader; entries: readonly ArtifactEntry[] | null; /** * Entries by container-relative logical path, in listing order. Inventory * numbers same-path occurrences in that order, so an occurrence's duplicate * ordinal selects its entry no matter which read path reaches it first. */ readonly byPath: Map; } /** Read-only inventory and bounded member scan for one shipped artifact. */ export class ReleaseExposureReader implements ReleaseExposurePort { readonly identity = RELEASE_EXPOSURE_PROVIDER; readonly #resources = new ArtifactResourceScope(); /** * @param asarHeaderAdmission The shared ASAR header/index admission the * composition resolved from REA_ASAR_MAX_HEADER_BYTES and the runtime * asar.max_header_bytes setting; read on each use, so a runtime change * applies to the next audit. */ constructor( private readonly asarHeaderAdmission: AsarHeaderAdmission = DEFAULT_ASAR_HEADER_ADMISSION, ) {} async close(): Promise { try { await this.#resources.close(); } catch (cause: unknown) { throw projectArtifactCloseFailure( cause, RELEASE_EXPOSURE_PROVIDER.id, OPERATION, ); } } async inspect( input: { readonly path: string; readonly max_file_bytes?: number }, options: ExecutionOptions | undefined, visitText: ReleaseExposureTextVisitor, visitInterruptedScan?: ReleaseExposureScanVisitor, ): Promise> { const maxFileBytes = input.max_file_bytes ?? MAX_RELEASE_EXPOSURE_FILE_BYTES; const context: ScanContext = { signal: options?.signal, resources: this.#resources, maxFileBytes, asarHeaderAdmission: this.asarHeaderAdmission, visitText, visitInterruptedScan, siblingCleanup: [], }; try { return await this.#resources.run(async () => { if (options?.signal?.aborted) throw cancelledBy(OPERATION, options.signal); const info = await lstat(input.path); if (info.isSymbolicLink()) throw new AnalysisInputError(OPERATION, undefined, [ { path: ["path"], reason: "invalid_format", message: `Selected artifact is a symlink: ${input.path}.`, }, ]); if (info.isDirectory()) return ok(await scanDirectory(input.path, context)); const snapshot = await readStableArtifact( input.path, maxFileBytes, options?.signal, undefined, this.#resources, ); return ok( await scanFile(input.path, snapshot.bytes, snapshot.sha256, context), ); }); } catch (cause) { return err(releaseExposureFailure(cause, input.path, maxFileBytes)); } } } const scanDirectory = async ( path: string, context: ScanContext, ): Promise => { const inventory = await inventoryArtifactInScope(path, { acquisitionLimits: { maximumEntries: MAX_RELEASE_EXPOSURE_INVENTORY_ENTRIES, maximumBytes: MAX_RELEASE_EXPOSURE_INVENTORY_BYTES, }, // Signing an unpacked native module after packaging is routine. Record the // contradiction instead of refusing the whole audit. integrity: "record-and-continue", resourceScope: context.resources, signal: context.signal, selectedPath: path, asarHeaderAdmission: context.asarHeaderAdmission, }); return consumeInventory({ ...context, path, directory: true, sha256: null, subjectSha256: inventory.manifest.root_sha256, snapshot: null, inventory, }); }; const scanFile = async ( path: string, bytes: Buffer, sha256: string, context: ScanContext, ): Promise => { let inventory: ArtifactInventoryResult | undefined; const limitations: string[] = []; try { inventory = await inventoryArtifactInScope(path, { acquisitionLimits: { maximumEntries: MAX_RELEASE_EXPOSURE_INVENTORY_ENTRIES, maximumBytes: MAX_RELEASE_EXPOSURE_INVENTORY_BYTES, }, integrity: "record-and-continue", resourceScope: context.resources, signal: context.signal, selectedPath: path, expectedRootSha256: sha256, asarHeaderAdmission: context.asarHeaderAdmission, }); } catch (cause) { rethrowReadFailure(cause); // A named admission owns its recovery; keep it typed as the directory scan does. if (cause instanceof ArtifactReaderFailure && cause.admission !== undefined) throw cause; limitations.push( "Artifact inventory did not complete. Member coverage is unknown.", ); } const scanned = await consumeInventory({ ...context, path, directory: false, sha256, subjectSha256: sha256, snapshot: bytes, inventory, }); return { ...scanned, coverage: inventory === undefined ? "unknown" : scanned.coverage, limitations: [...limitations, ...scanned.limitations].slice( 0, LIMITATION_CAP, ), }; }; interface ScanContext { readonly signal: AbortSignal | undefined; readonly resources: ArtifactResourceScope; readonly maxFileBytes: number; readonly asarHeaderAdmission: AsarHeaderAdmission; readonly visitText: ReleaseExposureTextVisitor; readonly visitInterruptedScan: ReleaseExposureScanVisitor | undefined; readonly siblingCleanup: Extract< ArtifactCleanupAttempt, { kind: "failed" } >[]; } interface ConsumeInput extends ScanContext { readonly path: string; readonly directory: boolean; readonly sha256: string | null; readonly subjectSha256: string; readonly snapshot: Buffer | null; readonly inventory: ArtifactInventoryResult | undefined; } const consumeInventory = async ( input: ConsumeInput, ): Promise => { const containers = new Map(); const progress: ScanProgress = {}; let result: ReleaseExposureScan | undefined; let failure: unknown; let failed = false; try { result = await scanOccurrences(input, containers, progress); } catch (cause) { failure = cause; failed = true; } const [firstCleanup, ...remainingCleanup] = [ ...input.siblingCleanup, ...(await releaseContainers(containers, input.resources)), ]; // A cancelled scan keeps what it examined, as one stopped on cleanup does; // the caller still receives the cancellation. const cancelled = failed && wasCancelled(failure); if ( firstCleanup !== undefined || (failed && leftCleanupUnfinished(failure)) || cancelled ) reportInterruptedScan( input, result ?? progress.assemble?.(), cancelled && firstCleanup === undefined && !leftCleanupUnfinished(failure) ? SCAN_CANCELLED : SCAN_INTERRUPTED, ); if (firstCleanup !== undefined) { const primary = failed ? releaseExposureFailure(failure, input.path, input.maxFileBytes) : new ProviderAdapterError(RELEASE_EXPOSURE_PROVIDER.id, OPERATION, { cause: firstCleanup.cause, diagnostics: result === undefined ? undefined : { scan: jsonValueSchema.parse(result) }, }); throw projectStableArtifactFailure( input.resources.cleanupFailure({ kind: "completed" }, [ firstCleanup, ...remainingCleanup, ]), primary, input.path, RELEASE_EXPOSURE_PROVIDER.id, OPERATION, ); } if (failed) throw failure; if (result === undefined) throw invariantViolation("Release exposure scan produced no result."); return result; }; /** What a failed scan can still assemble once it has somewhere to record facts. */ interface ScanProgress { assemble?: () => ReleaseExposureScan; } const leftCleanupUnfinished = (cause: unknown): boolean => { const failure = asReadFailure(cause); if (failure instanceof AnalysisError) return failure.cleanupIncomplete; return ( failure instanceof ArtifactReaderFailure && failure.cleanup !== undefined ); }; const wasCancelled = (cause: unknown): boolean => { const failure = asReadFailure(cause); return ( failure instanceof AnalysisCancelledError || (failure instanceof ArtifactReaderFailure && failure.reason === "cancelled") ); }; /** Completed findings survive the failure; what was not reached stays unknown. */ const reportInterruptedScan = ( input: ConsumeInput, scan: ReleaseExposureScan | undefined, reason: string, ): void => { if (scan === undefined) return; input.visitInterruptedScan?.({ ...scan, coverage: "unknown", limitations: [reason, ...scan.limitations].slice(0, LIMITATION_CAP), }); }; /** Hand each package reader to the resource scope so a failed close keeps its path and can be retried. */ const releaseContainers = async ( containers: Map, resources: ArtifactResourceScope, ): Promise[]> => { const owned = [...containers.values()].reverse(); containers.clear(); const failures: Extract[] = []; for (const container of owned) { const outcome = await resources.release({ kind: "reader", resource: container.path, reader: container.reader, }); if (outcome.kind === "failed") failures.push(outcome); } return failures; }; const scanOccurrences = async ( input: ConsumeInput, containers: Map, progress: ScanProgress, ): Promise => { const occurrences = input.inventory?.occurrences ?? []; const byId = new Map( occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]), ); // Inventory numbers same-path occurrences in listing order; keep that // number as the occurrence's identity within its container. const ordinals = new Map(); const seenPaths = new Map(); for (const occurrence of occurrences) { const ordinal = seenPaths.get(occurrence.logical_path) ?? 0; seenPaths.set(occurrence.logical_path, ordinal + 1); ordinals.set(occurrence.occurrence_id, ordinal); } const nodeFormat = new Map( (input.inventory?.nodes ?? []).map((node) => [ node.artifact_id, node.format, ]), ); const nodeSha = new Map( (input.inventory?.nodes ?? []).map((node) => [ node.artifact_id, node.sha256, ]), ); const parentsWithChildren = new Set( occurrences.flatMap((occurrence) => occurrence.parent_occurrence_id === null ? [] : [occurrence.parent_occurrence_id], ), ); const formatOf = (occurrence: InventoryOccurrence): string => { const fromNode = occurrence.artifact_id === null ? undefined : nodeFormat.get(occurrence.artifact_id); if (fromNode !== undefined && EXTRACTABLE.has(fromNode)) return fromNode; return occurrence.artifact_format; }; const rootFormat = input.inventory?.manifest.root_format ?? (input.snapshot === null ? "directory" : sniffNativeFormat(input.snapshot)) ?? "file"; const state = createState( input.visitText, input.asarHeaderAdmission, input.path, ); progress.assemble = () => assembleScan(input, state, rootFormat); if (EXTRACTABLE.has(rootFormat)) state.formats.add(rootFormat); if (input.snapshot !== null) await examineSelectedFile(state, input, rootFormat, input.snapshot); for (const occurrence of occurrences) { if (input.signal?.aborted) throw cancelledBy(OPERATION, input.signal); if ( !input.directory && occurrence.parent_occurrence_id === null && input.snapshot !== null ) continue; const packaged = packageAncestor(occurrence, byId, formatOf); const format = formatOf(occurrence); const logical = occurrence.logical_path; const location = diskPath(input, occurrence, byId, formatOf) ?? logical; if (hasCompanionName(logical)) state.companionPaths.add(location); noteUnfollowedMapLink(state, occurrence.entry_kind, logical, location); if (occurrence.entry_kind !== "file") continue; const nativeFormat = nativeFormatOf(occurrence, nodeFormat); const onDisk = nativeFormat !== null && !hasExtractableAncestor(occurrence, byId, formatOf) && isAbsolute(location); if (onDisk && nativeFormat !== null) { if (!state.native.has(location)) { state.native.set(location, nativeFormat); const sha256 = shaOf(occurrence, nodeSha); if (sha256 !== undefined) state.nativeDigests.set(location, sha256); if (nativeFormat === "pe") await examinePdb(location, sha256, state, input); await scanEmbeddedPackage( input, occurrence, location, nativeFormat, containers, state, ); } continue; } const packageKind = asPackageFormat(format); if ( packageKind !== null && !hasExtractableAncestor(occurrence, byId, formatOf) ) { state.formats.add(packageKind); if ( !parentsWithChildren.has(occurrence.occurrence_id) && isAbsolute(location) ) await scanUnexpandedContainer( input, occurrence, location, packageKind, containers, state, ); continue; } // A nested package that inventory recognized but did not expand was // never assessed, so its members leave coverage unknown. The nested // package itself is still an unencrypted member of its parent that // inventory already read, so it counts as a readable payload. if ( packageKind !== null && !parentsWithChildren.has(occurrence.occurrence_id) ) { noteNestedPackage(state, packageKind, location); if (!occurrence.encrypted) { state.readable += 1; pushSample(state.memberSamples, location); } continue; } await examineMember(state, input, { logical, format: nativeFormat ?? format, kind: ownerStatedKind(occurrence.format_metadata) ?? occurrence.artifact_kind, kindStated: ownerStatedKind(occurrence.format_metadata) !== null, encrypted: occurrence.encrypted, declaredSize: occurrence.declared_size, location, packageFormat: packaged === undefined ? null : asPackageFormat(formatOf(packaged)), read: (budget) => readOccurrence( input, occurrence, ordinals, containers, byId, formatOf, nodeSha, state, budget, ), }); } if (!input.directory) await scanSiblings(input, state); noteUnreachedTargets(state); return assembleScan(input, state, rootFormat); }; const assembleScan = ( input: ConsumeInput, state: ScanState, rootFormat: string, ): ReleaseExposureScan => { const kind = targetKind(input.path, rootFormat, input.directory); const nativeImages = [...state.native.entries()].map(([path, format]) => { const sha256 = state.nativeDigests.get(path); return { path, format, ...(sha256 === undefined ? {} : { sha256 }) }; }); return { target: { selected_path: input.path, kind, format: rootFormat, sha256: input.sha256, }, subject: { path: input.path, sha256: input.subjectSha256, format: evidenceSubjectFormatSchema.safeParse(rootFormat).success ? rootFormat : "file", }, native_images: nativeImages, fuse_candidates: [ ...(kind === "app" ? [{ path: input.path, role: "app-bundle" as const }] : []), ...nativeImages.map((image) => ({ path: image.path, role: "native-image" as const, })), ], source_maps: { embedded: state.embedded, without_sources: state.withoutSources, unparsed: state.unparsedMaps, skipped: state.skippedMaps, samples: [...state.mapSamples], embedded_paths: [...state.embeddedPaths], plain_paths: [...state.plainPaths], }, extractable: { formats: [...state.formats], readable_members: state.readable, unreadable_members: state.unreadable, samples: [...state.memberSamples], }, debug_companions: { paths: [ ...state.companionPaths, ...[...state.linkerMapGuesses.values()].flatMap((paths) => [...paths]), ], skipped: state.skippedCompanions, }, pdb: { examined: state.pdbExamined, paths: [...state.pdbPaths], image_paths: [...state.pdbImagePaths], failed: state.pdbFailed, }, text_members: { scanned: state.scannedText, skipped: state.skippedText, }, coverage: input.inventory === undefined || state.coverageUnknown ? "unknown" : input.inventory.coverage.status === "complete" ? "complete" : "unknown", omitted: [ ...(state.skippedMaps > 0 ? [ { subject: "source maps", count: state.skippedMaps, reason: "A source map exceeded the map count or byte allowance, could not be read, was a link that is not followed, was past the package entry cap or the HTML inline script limit, was declared but not found, or sat in a script an HTML file loads that was not examined as one; inline CSS source-map directives are not inspected.", }, ] : []), ...(state.skippedText > 0 ? [ { subject: "text members", count: state.skippedText, reason: "A text member exceeded the text byte allowance, could not be read, or was past the package entry cap.", }, ] : []), ...(state.skippedCompanions > 0 ? [ { subject: "debug companions", count: state.skippedCompanions, reason: "A .map file without a JavaScript name could not be classified, or the listing beside the selected file was incomplete.", }, ] : []), ...(state.packagedNative > 0 ? [ { subject: PACKAGED_NATIVE_IMAGES, count: state.packagedNative, reason: "Go, Rust, and Electron fuse readers run on files on disk, not on images stored inside a package.", }, ] : []), ...(state.unprobedImages > 0 ? [ { subject: "embedded package probes", count: state.unprobedImages, reason: `Only ${String(EMBEDDED_PROBE_LIMIT)} native images on disk, and packaged images up to the file byte allowance in total, are probed for an embedded package.`, }, ] : []), ], limitations: [ ...(input.inventory?.limitations ?? []), ...state.limitations, ].slice(0, LIMITATION_CAP), }; }; interface ScanState { embedded: number; withoutSources: number; unparsedMaps: number; skippedMaps: number; mapSamples: string[]; embeddedPaths: string[]; plainPaths: string[]; formats: Set; readable: number; unreadable: number; memberSamples: string[]; /** Companions identified by name. A later declaration does not change them. */ companionPaths: Set; /** * Maps read as non-JSON, by lookup identity, each with its reported spellings, * which symlinks can make differ. A later map or script declaration * retracts the guess. */ linkerMapGuesses: Map>; skippedCompanions: number; pdbExamined: number; pdbPaths: string[]; pdbImagePaths: string[]; pdbFailed: number; coverageUnknown: boolean; pdbAttempts: number; packagedPeReads: number; packagedNative: number; scannedText: number; skippedText: number; textBytes: number; /** Bytes member reads produced, kept even when the read then failed. */ memberBytesRead: number; embeddedProbes: number; /** Member bytes spent probing packaged images for an embedded package. */ packagedProbeBytes: number; unprobedImages: number; native: Map; nativeDigests: Map; limitations: string[]; mapsRead: number; /** * Local targets of source-map declarations, whatever their file name, by * lookup identity, each with the resolved spellings declarations wrote. */ mapTargets: Map>; /** * Map targets a member or sibling reached through a declared spelling. Any * other spelling in the same lookup bucket is a distinct occurrence. */ claimedMapTargets: Set; /** Completion per source occurrence, indexed by exact resolved spelling. */ examinedMembers: Map>>; /** * Local script elements' targets whose names do not say JavaScript, by * lookup identity, each with the resolved spellings pages wrote. */ scriptTargets: Map>; /** Bytes of resolved path offered to `scriptTargets`, kept or refused. */ scriptTargetBytes: number; mapTargetBytes: number; /** * A declared map or script target was refused by its allowance. A later * `.map` may be that target, so it can no longer settle as a linker map. */ mapTargetsDiscarded: boolean; visitText: ReleaseExposureTextVisitor; readonly asarHeaderAdmission: AsarHeaderAdmission; /** * The selected path. An expanded package member reports its location * relative to it, so lookups resolve that location here rather than * against the process working directory. */ readonly anchor: string; } const createState = ( visitText: ReleaseExposureTextVisitor, asarHeaderAdmission: AsarHeaderAdmission, anchor: string, ): ScanState => ({ asarHeaderAdmission, anchor, embedded: 0, withoutSources: 0, unparsedMaps: 0, skippedMaps: 0, mapSamples: [], embeddedPaths: [], plainPaths: [], formats: new Set(), readable: 0, unreadable: 0, memberSamples: [], companionPaths: new Set(), linkerMapGuesses: new Map(), skippedCompanions: 0, pdbExamined: 0, pdbPaths: [], pdbImagePaths: [], pdbFailed: 0, coverageUnknown: false, pdbAttempts: 0, packagedPeReads: 0, packagedNative: 0, scannedText: 0, skippedText: 0, textBytes: 0, memberBytesRead: 0, embeddedProbes: 0, packagedProbeBytes: 0, unprobedImages: 0, native: new Map(), nativeDigests: new Map(), limitations: [], mapsRead: 0, mapTargets: new Map(), claimedMapTargets: new Set(), examinedMembers: new Map(), scriptTargets: new Map(), scriptTargetBytes: 0, mapTargetBytes: 0, mapTargetsDiscarded: false, visitText, }); interface MemberCompletion { map: boolean; script: boolean; } interface MemberView { readonly completion: MemberCompletion; readonly logical: string; readonly format: string; readonly kind: string; /** * The package owner established `kind` from its own records. Inventory's * path roles, such as `resource` for `payload.json`, are only name hints. */ readonly kindStated: boolean; readonly encrypted: boolean; /** Full member size its owner declared, when one did. */ readonly declaredSize: number | null; /** Reported path. A package member names its host file. */ readonly location: string; readonly packageFormat: PackageFormat | null; readonly read: ReadMember; } type MemberRole = Pick; const isJavaScriptMember = (member: MemberRole): boolean => member.kind === "javascript" || JAVASCRIPT_MEMBER_NAME.test(member.logical); const isCssMember = (member: MemberRole): boolean => member.logical.toLowerCase().endsWith(".css"); const isScriptPageMember = (member: MemberRole): boolean => SCRIPT_PAGE_NAME.test(member.logical); /** A member whose scripts can declare a map the directive parser reads. */ const holdsScripts = (member: MemberRole): boolean => isJavaScriptMember(member) || isScriptPageMember(member); /** A member that can declare a map, whether or not the parser reads it. */ const canDeclareMap = (member: MemberRole): boolean => holdsScripts(member) || isCssMember(member); /** Bun loaders whose module contents a compiled executable ships as JavaScript. */ const BUN_SCRIPT_LOADERS = new Set(["js", "jsx", "ts", "tsx"]); const DENO_SCRIPT_MEDIA_TYPES = new Set([ "JavaScript", "Jsx", "Mjs", "Cjs", "TypeScript", "Mts", "Cts", "Tsx", ]); /** * The role a package reader states for its entry, or null when it states none. * A Bun sourcemap region is named `.bunmap`, a Bun module such as * `$bunfs/root/release` need not name a script, and a SEA entry's code path * need not either, so their names alone do not say what they are. */ const ownerStatedKind = ( metadata: ArtifactOccurrence["format_metadata"], ): string | null => { if (metadata?.kind === "bun-standalone-entry") { if (metadata.region === "sourcemap") return "source-map"; if ( metadata.region === "contents" && BUN_SCRIPT_LOADERS.has(metadata.loader_name ?? "") ) return "javascript"; return null; } if (metadata?.kind === "deno-standalone-entry") { if (metadata.role === "remote-module") { if (metadata.media_type_name === "SourceMap") return "source-map"; if (DENO_SCRIPT_MEDIA_TYPES.has(metadata.media_type_name ?? "")) return "javascript"; } if ( metadata.role === "vfs-source-map" || metadata.role === "remote-source-map" ) return "source-map"; if ( metadata.role === "vfs-transpiled" || metadata.role === "remote-transpiled" ) return "javascript"; } if (metadata?.kind === "node-sea-entry" && metadata.role === "main-script") return "javascript"; return null; }; const asNativeFormat = ( format: string | null | undefined, ): NativeFormat | null => format !== undefined && format !== null && NATIVE.has(format) ? (format as NativeFormat) : null; const nativeFormatOf = ( occurrence: InventoryOccurrence, nodeFormat: Map, ): NativeFormat | null => { // An embedded package keeps its container format. The host node may still // be pe or elf, and that native label must not hide the package. if (EXTRACTABLE.has(occurrence.artifact_format)) return null; const fromNode = occurrence.artifact_id === null ? undefined : nodeFormat.get(occurrence.artifact_id); if (fromNode !== undefined && EXTRACTABLE.has(fromNode)) return null; return asNativeFormat(occurrence.artifact_format) ?? asNativeFormat(fromNode); }; const shaOf = ( occurrence: InventoryOccurrence, nodeSha: Map, ): string | undefined => occurrence.artifact_id === null ? undefined : nodeSha.get(occurrence.artifact_id); const overAllowance = (bytes: Buffer): MemberRead => ({ kind: "over_allowance", prefix: bytes.subarray(0, MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES), }); const fitAllowance = (bytes: Buffer, budget: number): MemberRead => bytes.length <= budget ? { kind: "bytes", bytes } : overAllowance(bytes); const examineSelectedFile = async ( state: ScanState, input: ConsumeInput, rootFormat: string, bytes: Buffer, ): Promise => { const nativeFormat = asNativeFormat(rootFormat) ?? sniffNativeFormat(bytes); if (nativeFormat !== null) { state.native.set(input.path, nativeFormat); if (input.sha256 !== null) state.nativeDigests.set(input.path, input.sha256); } if (nativeFormat === "pe") readPdb(state, bytes, input.path); await examineMember(state, input, { logical: basename(input.path), // A selected package executable keeps its native carrier here, so its // name cannot route it as a linker map. format: nativeFormat ?? rootFormat, kind: "file", kindStated: false, encrypted: false, declaredSize: bytes.length, location: input.path, packageFormat: null, read: (budget) => Promise.resolve(fitAllowance(bytes, budget)), }); }; /** * Examine one file member for the checks it can affect. * A listed, unencrypted package member is readable even when a read allowance * skips it, because the allowance belongs to this audit and not to the format. */ const examineMember = async ( state: ScanState, context: ScanContext, listed: Omit, ): Promise => { const completion: MemberCompletion = { map: false, script: false }; const source = { ...listed, completion }; recordMemberCompletion(state, listed.location, completion); const { packageFormat } = listed; if (packageFormat !== null) state.formats.add(packageFormat); let readable = false; const map = isDeclaredMap(state, source); const member = !map && asNativeFormat(listed.format) === null && isScriptTarget(state, listed.location) ? { ...source, kind: "javascript" } : source; completion.map = map; completion.script = !map && isJavaScriptMember(member); // An owner's native format outranks anything the member's name suggests, // for a packaged member and for a selected or listed native image alike. const native = asNativeFormat(member.format) !== null; if (member.encrypted) noteUnreadMember(state, member); else if (native) { if (packageFormat !== null) readable = await examinePackagedBinary(state, member, context); } else if (map) readable = await examineMapMember(state, member, context); else if (isText(member.logical, member.kind)) readable = await examineTextMember(state, member, context); else if (packageFormat !== null) readable = await examinePackagedBinary(state, member, context); else await examineProbedText( state, member, await member.read(MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES), context, ); if (packageFormat === null) return; if (!readable) { state.unreadable += 1; return; } state.readable += 1; pushSample(state.memberSamples, member.location); }; const noteUnreadMember = (state: ScanState, member: MemberView): void => { if (canDeclareMap(member)) state.skippedMaps += 1; if ( member.packageFormat !== null && !member.kindStated && asNativeFormat(member.format) === null ) { if (isDeclaredMap(state, member)) noteUnreadMap( state, namedMapReference(member.logical, member.location), null, ); noteUnreadBinary(state, member); return; } if (asNativeFormat(member.format) !== null) noteUnreadBinary(state, member); else if (isDeclaredMap(state, member)) { noteUnreadMap( state, namedMapReference(member.logical, member.location), null, ); state.skippedText += 1; } else if (isText(member.logical, member.kind)) state.skippedText += 1; else noteUnreadBinary(state, member); }; /** * A member whose bytes were not read. A native one may carry a package that * nothing here can clear, so member coverage stays unknown, as it does for a * packaged image the embedded-package probe could not read. An unclassified * one whose header was never read may be such an image too, so it leaves * coverage unknown as well. A caller that counts the failed read itself passes * `countUnreadable: false`, so the member is counted once. */ const noteUnreadBinary = ( state: ScanState, member: MemberView, countUnreadable = true, ): void => { const native = asNativeFormat(member.format); if (native !== null) { state.packagedNative += 1; if (countUnreadable) noteUnexaminedPackage(state); else state.coverageUnknown = true; pushLimitation( state, `Did not probe ${member.location} for an embedded package.`, ); } else { state.skippedText += 1; state.coverageUnknown = true; pushLimitation( state, `Could not read ${member.location} to rule out a native image or package.`, ); } if (native === "pe" || PE_MEMBER_NAME.test(member.logical)) notePeNotExamined(state, member.location); }; const notePeNotExamined = (state: ScanState, location: string): void => { state.pdbFailed += 1; pushLimitation(state, `Did not examine PE debug records in ${location}.`); }; const examineMapMember = async ( state: ScanState, member: MemberView, context: ScanContext, ): Promise => { // A member a script names or an owner marks as a map is a JavaScript map // whatever it is called. Only an undeclared `.map` may be a linker map. // Another spelling of a declared target is undeclared until the scan ends. const undeclared = member.logical.toLowerCase().endsWith(".map") && !claimMapTarget(state, member.location); const declared: SourceMapReference & Pick = { ...(undeclared ? namedMapReference(member.logical, member.location) : { location: member.location, kind: "javascript-source-map" as const }), read: member.read, }; const bytesReadBefore = state.memberBytesRead; const read = await readMap(state, declared); const header = read === null ? null : headerOfRead(read.loaded); if (undeclared && read !== null && header !== null && hasNodeShebang(header)) return examineShebangMap(state, member, read.loaded, bytesReadBefore); // A shebang whose program an unresolved variable names may run Node, so the // member may be a script and is no linker-map evidence, as for a sibling. if ( undeclared && read !== null && header !== null && nodeShebang(header) === undefined ) { state.skippedMaps += 1; state.skippedCompanions += 1; if (read.loaded.kind === "bytes") scanText( state, member, read.loaded.bytes.length, decodeMemberText(read.loaded.bytes), ); // A read the allowance stopped leaves the text unchecked. else state.skippedText += 1; return true; } const packaged = read === null ? null : packagedFormatOfRead(state, member, read.loaded); if (packaged === "asar") { noteNestedPackage(state, "asar", member.location); return true; } if (packaged !== null) return examinePackagedBinary( state, { ...member, format: packaged }, context, ); // A package member whose PE header is undecided may be native, so its `MZ` // prefix is no evidence of a linker map. if ( header !== null && member.packageFormat !== null && !member.kindStated && noteUndecidedPe(state, member, header) ) { // Bytes read in full are still text, so their credential markers count. if (read?.loaded.kind === "bytes") scanText( state, member, read.loaded.bytes.length, decodeMemberText(read.loaded.bytes), ); else state.skippedText += 1; return true; } if (read !== null) settleMapRead(state, declared, read); const loaded = read?.loaded ?? null; if (loaded?.kind === "bytes") scanText( state, member, loaded.bytes.length, decodeMemberText(loaded.bytes), ); // A package member's name is not its format, so one whose header was never // read may be a native image or package, as on the text route. else if ( header === null && member.packageFormat !== null && !member.kindStated ) noteUnreadBinary(state, member); else state.skippedText += 1; return loaded?.kind !== "unread"; }; /** * An undeclared `.map` that starts with a Node shebang is a script, such as * `runner.map`, so it is not a linker map. Its completed map read keeps its * slot and its bytes are reused for the text and inline-map checks. */ const examineShebangMap = ( state: ScanState, member: MemberView, loaded: MemberRead, bytesReadBefore: number, ): boolean => { member.completion.map = false; member.completion.script = true; const remaining = MAX_RELEASE_EXPOSURE_TEXT_BYTES - state.textBytes; if ( loaded.kind === "bytes" && loaded.bytes.length <= Math.min(MAX_RELEASE_EXPOSURE_TEXT_MEMBER_BYTES, remaining) ) return examineLoadedText( state, { ...member, kind: "javascript" }, loaded, bytesReadBefore, ); state.textBytes += Math.min( Math.max(remaining, 0), state.memberBytesRead - bytesReadBefore, ); state.skippedText += 1; state.skippedMaps += 1; return loaded.kind !== "unread"; }; /** The first bytes a read returned, or null when it returned none. */ const headerOfRead = (loaded: MemberRead): Buffer | null => loaded.kind === "bytes" ? loaded.bytes : loaded.kind === "over_allowance" ? loaded.prefix : null; /** * Take a slot from the map count and return the bytes this read may use. The * read is what the count bounds, so it is charged before the file is opened: * an oversized or unreadable map spends its slot like a parsed one. With no * slot left, only the probe is read, which can still settle a linker map. */ const chargeMapRead = ( state: ScanState, ): { hasSlot: boolean; bytes: number } => { if (state.mapsRead >= MAX_RELEASE_EXPOSURE_SOURCE_MAPS) return { hasSlot: false, bytes: MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES }; state.mapsRead += 1; return { hasSlot: true, bytes: MAX_RELEASE_EXPOSURE_SOURCE_MAP_BYTES }; }; interface MapRead { readonly hasSlot: boolean; readonly loaded: MemberRead; } /** The bytes a map read may use, or null when no read is allowed. */ const readMap = async ( state: ScanState, map: SourceMapReference & Pick, ): Promise => { const { hasSlot, bytes } = chargeMapRead(state); if (!hasSlot && map.kind === "javascript-source-map") { state.skippedMaps += 1; return null; } return { hasSlot, loaded: await map.read(bytes) }; }; const settleMapRead = ( state: ScanState, map: SourceMapReference, { hasSlot, loaded }: MapRead, ): void => { if (loaded.kind === "unread") noteUnreadMap(state, map, null); else if (loaded.kind === "over_allowance") noteUnreadMap(state, map, loaded.prefix); else if (hasSlot) readSourceMap(state, map, loaded.bytes); else noteUnreadMap(state, map, loaded.bytes); }; /** * Settle a .map whose body was not parsed. A JavaScript name, JSON prefix, * or whitespace-only prefix keeps it a possible source map. Other prefixes * cannot parse as one, which is the same evidence that classifies a small * linker map. */ const noteUnreadMap = ( state: ScanState, map: SourceMapReference, prefix: Buffer | null, ): void => { if (map.kind === "javascript-source-map") { state.skippedMaps += 1; return; } if (prefix !== null && !mayHaveSourceMapPrefix(prefix)) { noteLinkerMapGuess(state, map.location); return; } state.skippedMaps += 1; state.skippedCompanions += 1; }; /** * A map's text in the encoding its byte order mark names, or null for one this * reader does not decode, which leaves the map unresolved. Unmarked bytes are * read as UTF-8, as a source map is. */ const mapText = (bytes: Buffer): string | null => { const encoding = byteOrderMarkEncoding(bytes); if (encoding === null) return bytes.toString("utf8"); if (encoding === "utf-32") return null; return new TextDecoder(encoding).decode(bytes); }; const mayHaveSourceMapPrefix = (prefix: Buffer): boolean => { const text = mapText(prefix); return text === null || mayHaveSourceMapText(text); }; const mayHaveSourceMapText = (decoded: string): boolean => { const text = sourceMapJsonText(decoded).trimStart(); return text.length === 0 || text.startsWith("{"); }; const readSourceMap = ( state: ScanState, map: SourceMapReference, bytes: Buffer, ): void => { const text = mapText(bytes); if (text !== null) { readSourceMapText(state, map, text); return; } pushSample(state.mapSamples, map.location); state.unparsedMaps += 1; }; /** Read map text already decoded by the member's owner, such as a UTF-16 script. */ const readSourceMapText = ( state: ScanState, map: SourceMapReference, text: string, ): void => { const inspected = inspectSourceMapSourceContent(text); if (inspected.embedded) { state.embedded += 1; pushSample(state.embeddedPaths, map.location); } if (inspected.complete) { pushSample(state.mapSamples, map.location); if (!inspected.embedded) { state.withoutSources += 1; pushSample(state.plainPaths, map.location); } return; } // Linker maps share the suffix but are not JavaScript source maps. // JSON-looking maps remain unresolved when decoding fails or hits a limit. if (map.kind === "possible-linker-map" && !mayHaveSourceMapText(text)) { noteLinkerMapGuess(state, map.location); return; } pushSample(state.mapSamples, map.location); state.unparsedMaps += 1; }; /** * A script role says how a member is loaded, not what its bytes are. A `.map` * or script target whose text parses as a source map is read as one, so a * page that loads `main.map` as a script cannot hide the sources it ships. */ const scriptHoldsMap = ( state: ScanState, member: MemberView, text: string, ): boolean => { if (!isJavaScriptMember(member)) return false; if ( !member.logical.toLowerCase().endsWith(".map") && !isScriptTarget(state, member.location) ) return false; let parsed: unknown; try { parsed = JSON.parse(sourceMapJsonText(text)); } catch { return false; } if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false; return ( "version" in parsed && ("mappings" in parsed || "sources" in parsed || "sections" in parsed) ); }; /** * Read a script member as the source map it holds, from the text that * recognized it, so a byte order mark decides the encoding for both reads. */ const readScriptAsMap = ( state: ScanState, member: MemberView, bytes: Buffer, text: string, ): void => { const { hasSlot } = chargeMapRead(state); if (hasSlot && bytes.length <= MAX_RELEASE_EXPOSURE_SOURCE_MAP_BYTES) readSourceMapText( state, { location: member.location, kind: "javascript-source-map" }, text, ); else state.skippedMaps += 1; }; const examineTextMember = async ( state: ScanState, member: MemberView, context: ScanContext, ): Promise => { // CSS can declare inline maps, but the directive parser only handles JavaScript. if (isCssMember(member)) state.skippedMaps += 1; const remaining = MAX_RELEASE_EXPOSURE_TEXT_BYTES - state.textBytes; if (remaining <= 0) { // A packaged member's name is not its format, so one whose header was // never read may be a native image or package, as an unread `.bin` may. if (member.packageFormat !== null && !member.kindStated) { state.coverageUnknown = true; pushLimitation( state, `Did not read ${member.location} past the text allowance to rule out a native image or package.`, ); } state.skippedText += 1; // A name is not a script's role: `runner.txt` may start with a Node // shebang, and the header that would say so is past the allowance too, so // any unread member that could hold a script leaves its maps unassessed. if (!isCssMember(member)) state.skippedMaps += 1; return true; } const bytesReadBefore = state.memberBytesRead; const loaded = await member.read( Math.min(MAX_RELEASE_EXPOSURE_TEXT_MEMBER_BYTES, remaining), ); const packaged = packagedFormatOfRead(state, member, loaded); if (packaged !== null) { state.textBytes += state.memberBytesRead - bytesReadBefore; if (packaged !== "asar") return examinePackagedBinary( state, { ...member, format: packaged }, context, ); noteNestedPackage(state, "asar", member.location); return true; } // A package member's name is not its format. One kept only as a prefix may // have its PE signature past that prefix, so it stays undecided, as on the // map route; text read in full has no later bytes to decide it. if ( loaded.kind === "over_allowance" && loaded.prefix !== null && member.packageFormat !== null && !member.kindStated ) noteUndecidedPe(state, member, loaded.prefix); return examineLoadedText( state, scriptRoleOfRead(member, loaded), loaded, bytesReadBefore, ); }; /** * A text member's name may not say it is a script: `runner.txt` can start * with a Node shebang. The bytes this read returned decide, so every route * into the text reader gives such a file its JavaScript role. */ const scriptRoleOfRead = ( member: MemberView, loaded: MemberRead, ): MemberView => { if (holdsScripts(member)) return member; const header = headerOfRead(loaded); if (header === null || !hasNodeShebang(header)) return member; member.completion.script = true; return { ...member, kind: "javascript" }; }; const examineLoadedText = ( state: ScanState, member: MemberView, loaded: MemberRead, bytesReadBefore: number, ): boolean => { if (loaded.kind === "bytes") { const text = decodeMemberText(loaded.bytes); scanText(state, member, loaded.bytes.length, text); if (holdsScripts(member)) { if (text === null) state.skippedMaps += 1; else if (scriptHoldsMap(state, member, text.text)) readScriptAsMap(state, member, loaded.bytes, text.text); else { if (isJavaScriptMember(member)) examineInlineMaps(state, member, text.text, member.logical); // A page another page loads as a script still ships as a page. if (isScriptPageMember(member)) examineHtmlScripts(state, member, text.text); } } else if (!isCssMember(member) && nodeShebang(loaded.bytes) === undefined) // A program named by an unresolved variable may be Node, so the // member's maps stay unassessed rather than absent. state.skippedMaps += 1; } else { // The allowance bounds the read, so a read that yielded no text still spends it. state.textBytes += state.memberBytesRead - bytesReadBefore; // A packaged member's name is not its format, so one whose header was // never read may be a native image or package, as an unread `.bin` may. if ( loaded.kind === "unread" && member.packageFormat !== null && !member.kindStated ) noteUnreadBinary(state, member); else state.skippedText += 1; // A header cut short of its first line, or never read, cannot rule out a // Node shebang, so a text-named member's maps stay unassessed as well. if ( holdsScripts(member) || (!isCssMember(member) && shebangUndecided(headerOfRead(loaded))) ) state.skippedMaps += 1; } return loaded.kind !== "unread"; }; /** * Whether a header leaves a Node shebang undecided: none was read, it could * start one and ends before the shebang line does, or its program is named by * an environment variable. */ const shebangUndecided = (header: Buffer | null): boolean => header === null || ("#!".startsWith(header.toString("latin1", 0, 2)) && !header.includes(0x0a)) || nodeShebang(header) === undefined; /** * A shebang that runs Node makes a file a script whatever it is called. The * path classifier cannot see this, so the first bytes read establish it. */ const hasNodeShebang = (prefix: Buffer): boolean => nodeShebang(prefix) === true; /** * Whether a shebang runs Node. An `env -S` program whose name comes from a * `${NAME}` the scan cannot resolve, such as `${NODE_BIN}`, may be Node, so * it is undefined rather than false. */ const nodeShebang = (prefix: Buffer): boolean | undefined => { if (prefix.toString("latin1", 0, 2) !== "#!") return false; const [line = ""] = prefix.toString("latin1", 2).split("\n", 1); const [, interpreter = "", operands = ""] = /^(\S*)[ \t]*(.*)$/su.exec(line.trim()) ?? []; const program = basename(interpreter) === "env" ? envProgram(operands) : { text: interpreter, expands: false }; if (program === undefined) return false; const name = basename(program.text); if (/^node(?:js)?$/u.test(name)) return true; return program.expands && name.includes("${") ? undefined : false; }; /** One `env` field, and whether `env -S` expands a `${NAME}` inside it. */ interface EnvField { readonly text: string; readonly expands: boolean; } /** `env` options whose argument is the next field, as in `-u NODE_OPTIONS`. */ const ENV_OPTION_WITH_ARGUMENT = new Set([ "-u", "--unset", "-C", "--chdir", "-P", ]); /** * The program an `env` shebang runs: the first field that is neither an * option, an option's argument, nor a `NAME=value` setting. `-S` takes the * rest of the line as one string and splits it as `env` does, so quoted * spaces stay inside their field. */ const envProgram = (operands: string): EnvField | undefined => { const fields: EnvField[] = []; let rest = operands; const next = (): EnvField | undefined => { if (fields.length > 0) return fields.shift(); const [, field, after = ""] = /^[ \t]*([^ \t]+)(.*)$/su.exec(rest) ?? []; rest = after; return field === undefined ? undefined : { text: field, expands: false }; }; for (let entry = next(); entry !== undefined; entry = next()) { const field = entry.text; // Past `--` nothing is an option, but settings still come first. if (field === "--") { for (let word = next(); word !== undefined; word = next()) if (!word.text.includes("=")) return word; return undefined; } if (ENV_OPTION_WITH_ARGUMENT.has(field)) { next(); continue; } const attached = /^-[0iv]*S(.*)$/su.exec(field)?.[1] ?? (field.startsWith("--split-string=") ? field.slice("--split-string=".length) : undefined); if (attached !== undefined) { // The kernel passes the whole line as one operand, so an `-S` read from // the line itself owns everything after it, separators included. const fromLine = fields.length === 0; const words = splitEnvString(fromLine ? attached + rest : attached); if (words === undefined) return undefined; if (fromLine) rest = ""; fields.unshift(...words); continue; } if (field.startsWith("-") || field.includes("=")) continue; return entry; } return undefined; }; /** Escapes `env -S` accepts outside single quotes, as GNU coreutils reads them. */ const ENV_SPLIT_ESCAPES: Readonly> = { "\\": "\\", "'": "'", '"': '"', "#": "#", $: "$", f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", }; /** * Split an `env -S` string on its unquoted spaces and tabs. Single quotes keep * text literally but for `\\` and `\'`; double quotes and bare text take the * escapes above, `\_` separates fields outside quotes and is a space inside * them, `\c` ends the string, and a `#` that starts a field begins a comment. * `${NAME}` stays as written: it can only change a value, never which field is * the program, so its field is marked as expanding. A string `env` itself * rejects, such as an unterminated quote or an unknown escape, runs nothing. */ const splitEnvString = (text: string): EnvField[] | undefined => { const fields: EnvField[] = []; let field: string | null = null; let expands = false; let quote: "'" | '"' | null = null; const end = (): void => { if (field !== null) fields.push({ text: field, expands }); field = null; expands = false; }; for (let index = 0; index < text.length; index += 1) { const character = text[index] ?? ""; if (quote === "'") { const escaped = text[index + 1]; if (character === "'") quote = null; else if (character === "\\" && (escaped === "\\" || escaped === "'")) { field += escaped; index += 1; } else field += character; continue; } if (character === "\\") { const escaped = text[index + 1]; index += 1; if (escaped === "c") { if (quote !== null) return undefined; break; } if (escaped === "_") { if (quote === null) end(); else field += " "; continue; } const value = escaped === undefined ? undefined : ENV_SPLIT_ESCAPES[escaped]; if (value === undefined) return undefined; field = (field ?? "") + value; continue; } if (character === "$" && text[index + 1] === "{") expands = true; if (quote === '"') { if (character === '"') quote = null; else field += character; continue; } if (character === " " || character === "\t") end(); else if (character === "#" && field === null) break; else if (character === "'" || character === '"') { quote = character; field ??= ""; } else field = (field ?? "") + character; } if (quote !== null) return undefined; end(); return fields; }; /** * A name is not a format: a package member called `payload.json` or * `payload.js.map` can be a PE or an ASAR, and a script or map declaration * names whatever is at its target, and inventory's role for a member is a * guess from that name. The route's own read decides, so real text and maps * cost no further read. Only a kind the package owner stated is kept. */ const packagedFormatOfRead = ( state: ScanState, member: MemberView, loaded: MemberRead, ): NativeFormat | "asar" | null => { if (member.packageFormat === null || member.kindStated) return null; if (loaded.kind === "unread") return null; const header = loaded.kind === "bytes" ? loaded.bytes : loaded.prefix; if (header === null) return null; const native = sniffNativeFormat( header, loaded.kind === "bytes" ? header.length : member.declaredSize, ); if (native !== null) return native; return probeNestedAsar( state, member.location, header, loaded.kind === "bytes", ) ? "asar" : null; }; /** * Recognize text from bounded content. A name such as `.env.production`, * `server.key`, or `credentials` is not a complete statement of what a file is. * Content that could not be probed leaves text coverage undecided. */ const examineProbedText = async ( state: ScanState, member: MemberView, probe: MemberRead, context: ScanContext, ): Promise => { const prefix = probe.kind === "bytes" ? probe.bytes : probe.kind === "over_allowance" ? probe.prefix : null; if (prefix === null) { state.skippedText += 1; // The header that would give a Node shebang its script role was never // read, so the file's maps stay unassessed, as an unread `runner.js`'s do. state.skippedMaps += 1; } else if (hasNodeShebang(prefix)) { // The probe already read the header, so the role holds even when the // text allowance is spent before the text reader reads it again. member.completion.script = true; await examineTextMember(state, { ...member, kind: "javascript" }, context); } else if ( prefix.length > 0 && (!prefix.includes(0) || declaresTextEncoding(prefix)) ) await examineTextMember(state, member, context); }; /** * A script element's body declares maps as a script file does. Bodies past the * HTML owner's retained limit were not read, so each counts as a skipped map. */ const examineHtmlScripts = ( state: ScanState, member: MemberView, source: string, ): void => { const { baseHref, scripts, inlineScripts, inlineScriptCount } = htmlArtifactReferences(source); for (const { scriptPath, scriptType } of scripts) if (scriptType !== null) noteScriptReference(state, member, scriptPath, baseHref); for (const script of inlineScripts) examineInlineMaps( state, member, script.text, script.scriptType === "module" ? "inline.mjs" : "inline.js", ); state.skippedMaps += inlineScriptCount - inlineScripts.length; }; /** * A script element loads its target whatever the file is called, and a remote * script is not shipped. Every local target is recorded so it is examined as a * script when it is reached, and one that is never reached, such as a sibling * of a selected file, stays unassessed rather than absent. A target that cannot * be placed on disk stays unassessed. */ const noteScriptReference = ( state: ScanState, member: MemberView, scriptPath: string, baseHref: string | null, ): void => { try { const page = pathToFileURL(anchoredLocation(state, member.location)); const url = new URL( scriptPath, baseHref === null ? page : new URL(baseHref, page), ); if (url.protocol === "http:" || url.protocol === "https:") return; noteScriptTarget(state, fileURLToPath(url)); } catch { state.skippedMaps += 1; } }; /** * A base href is copied into every target it resolves, so a page's paths can * outgrow its text many times over. A target past the allowance stays unassessed. * A target already read is not a linker map, whatever its first read guessed, * and its script was not examined, so its source-map coverage stays unknown. */ const noteScriptTarget = (state: ScanState, location: string): void => { const target = memberLocationKey(state, location); const spellings = state.scriptTargets.get(target); const spelling = anchoredLocation(state, location); if (spellings?.has(spelling)) return; retractLinkerMapGuesses(state, location); state.scriptTargetBytes += Buffer.byteLength(spelling); if (state.scriptTargetBytes > MAX_RELEASE_EXPOSURE_SCRIPT_TARGET_BYTES) { state.skippedMaps += 1; state.mapTargetsDiscarded = true; } else if (spellings === undefined) state.scriptTargets.set(target, new Set([spelling])); else spellings.add(spelling); }; /** * Whether a page loaded this exact location as a script. Another spelling in * the same lookup bucket is a distinct file that keeps its own role. */ const isScriptTarget = (state: ScanState, location: string): boolean => state.scriptTargets .get(memberLocationKey(state, location)) ?.has(anchoredLocation(state, location)) === true; const examineInlineMaps = ( state: ScanState, member: MemberView, source: string, sourcePath: string, ): void => { const parsed = parseJavaScriptSource(source, sourcePath); if (parsed === null) { state.skippedMaps += 1; return; } const directives = createJavaScriptAnalysisAccumulator(source.length); addSourceMapDirectives(source, parsed.comments ?? [], directives); for (const { declared_url: url } of directives.sourceMaps) { // URL schemes are case-insensitive (RFC 3986 section 3.1). if (!/^data:/iu.test(url)) { noteLocalMapReference(state, member, url); continue; } const comma = url.indexOf(","); if (state.mapsRead >= MAX_RELEASE_EXPOSURE_SOURCE_MAPS || comma < 0) { state.skippedMaps += 1; continue; } try { const metadata = url.slice(0, comma); const payload = url.slice(comma + 1); const decoded = /;base64$/iu.test(metadata) ? Buffer.from(decodeURIComponent(payload), "base64") : Buffer.from(decodeURIComponent(payload), "utf8"); if (decoded.length > MAX_RELEASE_EXPOSURE_SOURCE_MAP_BYTES) { state.skippedMaps += 1; continue; } state.mapsRead += 1; // An inline declaration is a JavaScript map even if its JSON is invalid. readSourceMap( state, { kind: "javascript-source-map", location: member.location }, decoded, ); } catch { state.unparsedMaps += 1; } } }; /** * A declaration names its map by location, not by file name. Every local * target is recorded so it is examined as a map when it is reached, and one * that is never reached, such as a sibling of a selected file, stays * unassessed rather than absent. A target already * examined as ordinary text was not assessed as a map, so coverage is unknown. * A `file:` URL names one absolute location rather than a path beside the * script, so even a `.map` target stays unassessed until that location is * reached. Any other scheme is remote. */ const noteLocalMapReference = ( state: ScanState, member: MemberView, url: string, ): void => { if (/^file:/iu.test(url)) { try { noteMapTarget(state, fileURLToPath(url)); } catch { state.skippedMaps += 1; } return; } if (/^[a-z][a-z0-9+.-]+:/iu.test(url)) return; const path = url.replace(/[?#].*$/su, ""); if (path.length === 0) return; let decoded: string; try { decoded = decodeURIComponent(path); } catch { state.skippedMaps += 1; return; } noteMapTarget( state, resolve(dirname(anchoredLocation(state, member.location)), decoded), ); }; /** * A short URL is expanded by the declaring member's directory, so declared * paths can outgrow their text many times over. A target past the allowance * stays unassessed. */ const noteMapTarget = (state: ScanState, location: string): void => { const target = memberLocationKey(state, location); const spellings = state.mapTargets.get(target); const spelling = anchoredLocation(state, location); if (spellings?.has(spelling)) return; // A late declaration can identify an exact occurrence already examined as // a linker-map candidate. Claim that identity before final target coverage // considers other spellings in the normalized bucket. if (state.examinedMembers.get(target)?.has(spelling) === true) state.claimedMapTargets.add(target); // Retract once per exact declaration; repeating it must not consume peers // that only share its normalized lookup key. state.skippedMaps += retractLinkerMapGuesses(state, location); state.mapTargetBytes += Buffer.byteLength(spelling); if (state.mapTargetBytes > MAX_RELEASE_EXPOSURE_MAP_TARGET_BYTES) { state.skippedMaps += 1; state.mapTargetsDiscarded = true; } else if (spellings === undefined) state.mapTargets.set(target, new Set([spelling])); else spellings.add(spelling); }; /** * Whether a declaration wrote this exact location. A lookup bucket alone * does not prove which of its occurrences a declaration means. */ const claimMapTarget = (state: ScanState, location: string): boolean => { const key = memberLocationKey(state, location); if ( state.mapTargets.get(key)?.has(anchoredLocation(state, location)) !== true ) return false; state.claimedMapTargets.add(key); return true; }; /** * Lookup identity for a member location. Inventory reports logical paths in * NFC, so a declared target spelled in another normalization form still * names the same member. The declared URL itself is left as written. */ const memberLocationKey = (state: ScanState, location: string): string => logicalPathNfc(anchoredLocation(state, location)); /** * Where a member location lives. A disk location is already absolute; an * expanded package member's location is relative to the selected path. */ const anchoredLocation = (state: ScanState, location: string): string => resolve(state.anchor, location); /** Retract one source occurrence; a normalized lookup bucket is not identity. */ const retractLinkerMapGuesses = ( state: ScanState, location: string, ): number => { const key = memberLocationKey(state, location); const paths = state.linkerMapGuesses.get(key); if (paths === undefined) return 0; const spelling = anchoredLocation(state, location); const guess = [...paths].find( (path) => anchoredLocation(state, path) === spelling, ); if (guess !== undefined) { paths.delete(guess); if (paths.size === 0) state.linkerMapGuesses.delete(key); return 1; } // Without an exact source spelling, normalization cannot prove which // occurrence the declaration means. Keep companion coverage unresolved. state.skippedCompanions += paths.size; state.linkerMapGuesses.delete(key); return paths.size; }; const noteLinkerMapGuess = (state: ScanState, location: string): void => { // Once a map or script declaration was discarded, this map may be its target. if (state.mapTargetsDiscarded) { state.skippedMaps += 1; state.skippedCompanions += 1; return; } const key = memberLocationKey(state, location); const paths = state.linkerMapGuesses.get(key) ?? new Set(); state.linkerMapGuesses.set(key, paths.add(location)); }; /** * An owner's stated role or a declaration outranks the member's name, and an * inventory path role is only that name: a `.map` that an owner marks as * JavaScript or a page loads as a script is not a map. */ const isDeclaredMap = (state: ScanState, member: MemberView): boolean => { if (member.kindStated && member.kind === "source-map") return true; const key = memberLocationKey(state, member.location); if (state.mapTargets.has(key)) return true; if (member.kind === "javascript" || isScriptTarget(state, member.location)) return false; return isSourceMap(member.logical, member.kind); }; /** Keep normalized lookup separate from exact spelling and source occurrence. */ const recordMemberCompletion = ( state: ScanState, location: string, completion: MemberCompletion, ): void => { const key = memberLocationKey(state, location); const bucket = state.examinedMembers.get(key) ?? new Map>(); const spelling = anchoredLocation(state, location); const members = bucket.get(spelling) ?? new Set(); members.add(completion); bucket.set(spelling, members); state.examinedMembers.set(key, bucket); }; /** A path reference is complete only when every exact matching source occurrence was examined in that role. */ const completedTarget = ( state: ScanState, location: string, role: keyof MemberCompletion, ): boolean => { const bucket = state.examinedMembers.get(memberLocationKey(state, location)); const exact = bucket?.get(anchoredLocation(state, location)); // Inventory normalizes some package paths. Without an exact spelling, // completion holds only if every candidate in that lookup bucket has it. const candidates = exact === undefined ? [...(bucket?.values() ?? [])].flatMap((members) => [...members]) : [...exact]; return candidates.length > 0 && candidates.every((member) => member[role]); }; /** * A declared map or script target that was never reached was not assessed. * When no declared spelling was reached, another spelling of the target may * be the declared map, so its linker-map guess is no companion evidence. */ const noteUnreachedTargets = (state: ScanState): void => { for (const [target, spellings] of state.mapTargets) { const examined = [...spellings].every((spelling) => completedTarget(state, spelling, "map"), ); if (!examined) state.skippedMaps += 1; if (state.claimedMapTargets.has(target)) continue; const guesses = state.linkerMapGuesses.get(target); if (guesses === undefined) continue; state.linkerMapGuesses.delete(target); state.skippedCompanions += guesses.size; if (examined) state.skippedMaps += guesses.size; } for (const spellings of state.scriptTargets.values()) if ( ![...spellings].every((spelling) => completedTarget(state, spelling, "script"), ) ) state.skippedMaps += 1; }; /** Text decoded from a member; `complete` is false when part of it went unread. */ interface MemberText { readonly text: string; readonly complete: boolean; } /** * A binary plist that cannot be fully decoded keeps its raw bytes in the scan, * for the ASCII strings they show, beside whatever text it did decode, but its * other strings were not examined. */ const decodeBinaryPlistMember = (bytes: Buffer): MemberText => { try { const decoded = decodeBinaryPlistText( bytes, RELEASE_EXPOSURE_PLIST_DECODE_BYTES, ); return decoded.complete ? decoded : { text: `${decoded.text}\n${bytes.toString("utf8")}`, complete: false }; } catch (cause: unknown) { // A broken internal assumption is a REA defect, not an undecodable plist. if (cause instanceof InternalInvariantError) throw cause; return { text: bytes.toString("utf8"), complete: false }; } }; /** * Bytes that name their own text encoding, whose NULs are that encoding's * structure rather than a sign of binary data. `decodeMemberText` reads each of * these; a probe that admits on NULs alone would drop them unexamined. */ const declaresTextEncoding = (bytes: Buffer): boolean => byteOrderMarkEncoding(bytes) !== null || hasBinaryPlistSignature(bytes); /** * The text a member's bytes encode, or null when they cannot be read as text. * A member's kind says nothing about its encoding: wide text has no byte order * mark to explain its NULs, and a scan of it would match nothing and still count * as complete. A NUL inside UTF-8 text does not change how the rest of it reads. * A binary plist has its own object encoding, so its owner decodes it. */ const decodeMemberText = (bytes: Buffer): MemberText | null => { const encoding = byteOrderMarkEncoding(bytes); if (encoding === "utf-32") return null; if (encoding !== null) return { text: new TextDecoder(encoding).decode(bytes), complete: true }; if (hasBinaryPlistSignature(bytes)) return decodeBinaryPlistMember(bytes); if (hasNonUtf8Nul(bytes)) return null; return { text: bytes.toString("utf8"), complete: true }; }; const scanText = ( state: ScanState, member: MemberView, byteLength: number, text: MemberText | null, ): void => { if ( byteLength > MAX_RELEASE_EXPOSURE_TEXT_MEMBER_BYTES || state.textBytes + byteLength > MAX_RELEASE_EXPOSURE_TEXT_BYTES ) { state.skippedText += 1; return; } state.textBytes += byteLength; if (text === null) { state.skippedText += 1; return; } if (text.complete) state.scannedText += 1; else state.skippedText += 1; state.visitText(text.text, member.location); }; /** * Probe a package member that is neither text nor a map. Only its header is * read unless the bytes declare a PE, so large binary members cost no budget * that a later source map or text member needs. */ const examinePackagedBinary = async ( state: ScanState, member: MemberView, context: ScanContext, ): Promise => { const probe = await member.read(MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES); if (probe.kind === "unread") { // `examineMember` counts this failed read. noteUnreadBinary(state, member, false); return false; } const header = probe.kind === "bytes" ? probe.bytes : probe.prefix; const native = asNativeFormat(member.format) ?? (header === null ? null : sniffNativeFormat( header, probe.kind === "bytes" ? header.length : member.declaredSize, )); if (native === null && header !== null) noteUndecidedPe(state, member, header); if ( native === null && header !== null && probeNestedAsar(state, member.location, header, probe.kind === "bytes") ) { noteNestedPackage(state, "asar", member.location); return true; } if (native !== null) { state.packagedNative += 1; await probePackagedImage(state, member, native, context); } else await examineProbedText(state, member, probe, context); if (native !== "pe") return true; if (state.packagedPeReads >= MAX_RELEASE_EXPOSURE_PACKAGED_PE_READS) { notePeNotExamined(state, member.location); return true; } state.packagedPeReads += 1; const image = probe.kind === "bytes" ? probe : await member.read(MAX_RELEASE_EXPOSURE_PACKAGED_PE_BYTES); if (image.kind === "bytes") readPdb(state, image.bytes, member.location); else notePeNotExamined(state, member.location); return image.kind !== "unread"; }; /** * An `MZ` header whose PE signature lies past the bytes read may be native, so * the image stays unexamined by the on-disk readers, and it may carry a * package that nothing here can clear. Returns whether the header was undecided. */ /** An `MZ` header whose PE signature lies past the bytes read, so it may be native. */ const isUndecidedPeHeader = (header: Buffer): boolean => { if (header.toString("latin1", 0, 2) !== "MZ") return false; const windows = observeMzWindowsHeader(header); return ( windows.state === "signature-needed" || (windows.state === "candidate" && windows.signature === "unobserved") ); }; const noteUndecidedPe = ( state: ScanState, member: Pick, header: Buffer, ): boolean => { if (!isUndecidedPeHeader(header)) return false; state.packagedNative += 1; notePeNotExamined(state, member.location); noteUnexaminedPackage(state); return true; }; const readPdb = (state: ScanState, bytes: Buffer, imagePath: string): void => { const header = observeMzWindowsHeader(bytes); if (header.state !== "declared" || header.signature !== "PE") { state.pdbFailed += 1; return; } state.pdbExamined += 1; try { const parsed = inspectPeCodeViewFromBuffer(bytes, header.offset); if (!parsed.ok) { state.pdbFailed += 1; pushLimitation(state, `${imagePath}: ${parsed.error.message}`); } else if (parsed.value !== undefined && parsed.value.pdbPath.length > 0) { const record = parsed.value; pushSample(state.pdbPaths, record.pdbPath); pushSample(state.pdbImagePaths, imagePath); } } catch { state.pdbFailed += 1; } }; const examinePdb = async ( filePath: string, expectedSha256: string | undefined, state: ScanState, { signal, resources, maxFileBytes }: ScanContext, ): Promise => { if (state.pdbAttempts >= PDB_READ_LIMIT) { state.pdbFailed += 1; return; } state.pdbAttempts += 1; try { const snapshot = await readStableArtifact( filePath, maxFileBytes, signal, undefined, resources, ); if (expectedSha256 !== undefined && snapshot.sha256 !== expectedSha256) throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, ); readPdb(state, snapshot.bytes, filePath); } catch (cause) { rethrowReadFailure(cause); state.pdbFailed += 1; pushLimitation(state, `Could not read PE debug records from ${filePath}.`); } }; const readOccurrence = async ( input: ConsumeInput, occurrence: InventoryOccurrence, ordinals: ReadonlyMap, containers: Map, byId: Map, formatOf: (occurrence: InventoryOccurrence) => string, nodeSha: Map, state: ScanState, budget: number, ): Promise => { const parent = occurrence.parent_occurrence_id === null ? undefined : byId.get(occurrence.parent_occurrence_id); const packaged = packageAncestor(occurrence, byId, formatOf); const container = packaged ?? parent; const containerFormat = container === undefined ? null : formatOf(container); const extractable = containerFormat !== null && EXTRACTABLE.has(containerFormat); const compressed = occurrence.compressed_size !== null && occurrence.compressed_size > 0; const located = occurrence.source_location; if ( extractable && container !== undefined && containerFormat !== null && (compressed || located === null) ) { const containerPath = diskPath(input, container, byId, formatOf); if (containerPath === null) return { kind: "unread" }; return readContainerMember( input, container, containerPath, containerFormat, shaOf(container, nodeSha), shaOf(occurrence, nodeSha), occurrence, ordinals, containers, budget, state, ); } if (located !== null && !compressed && parent !== undefined) { if ( input.snapshot !== null && parent.parent_occurrence_id === null && located.offset >= 0 && located.offset + located.length <= input.snapshot.length ) return fitAllowance( input.snapshot.subarray( located.offset, located.offset + located.length, ), budget, ); const parentPath = diskPath(input, parent, byId, formatOf); if (parentPath !== null) { const bytes = await readSpan( parentPath, located.offset, Math.min(located.length, budget), state, input, ); if (bytes === null) return { kind: "unread" }; return located.length > budget ? overAllowance(bytes) : { kind: "bytes", bytes }; } } const filePath = diskPath(input, occurrence, byId, formatOf); if (filePath === null) return { kind: "unread" }; if (input.snapshot !== null && filePath === input.path) return fitAllowance(input.snapshot, budget); return readDiskMember( filePath, budget, shaOf(occurrence, nodeSha), state, input, ); }; type EmbeddedPackageProbe = | { readonly kind: "package"; readonly format: PackageFormat } | { readonly kind: "absent" } | { readonly kind: "unreadable" }; /** * Own one member descriptor. A failed close stays retained by the resource * scope, and the primary failure survives it. */ const withMemberDescriptor = async ( filePath: string, { resources, signal }: ScanContext, use: (source: StableRegularFileDescriptor) => Promise, ): Promise => { const source = await openRootArtifact(filePath, resources, signal); let settled: Result; try { settled = ok(await use(source)); } catch (cause) { settled = err(asReadFailure(cause)); } await releaseRootArtifact( filePath, source.owner, resources, settled.ok ? { kind: "completed", digest: null } : { kind: "failed", cause: settled.error }, signal, ); if (!settled.ok) throw settled.error; return settled.value; }; const embeddedPackageFormat = async ( filePath: string, nativeFormat: NativeFormat, state: ScanState, context: ScanContext, location: string, expectedSha256?: string, ): Promise => { try { return await withMemberDescriptor(filePath, context, async (source) => { if (source.initial.size > context.maxFileBytes) { pushLimitation( state, `Did not probe ${location} for an embedded package because it exceeds ${String(context.maxFileBytes)} bytes.`, ); return { kind: "unreadable" }; } const probes = new ArtifactEmbeddedFormatProbes( filePath, source, context.signal, ); const classified = await classifyEmbeddedExecutablePackage( probes, nativeFormat, context.signal, ); if (classified !== undefined) return { kind: "package", format: classified.format }; // A negative probe clears member coverage, so it only stands for the // image inventory hashed: a replacement is a changed member, not an // image without a package. if (expectedSha256 !== undefined) { const digest = await hashStableRootArtifactHandle( filePath, source.handle, source.initial, context.signal, ); if (digest.sha256 !== expectedSha256) throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, ); } return { kind: "absent" }; }); } catch (cause) { rethrowReadFailure(cause); pushLimitation( state, `Could not probe ${location} for an embedded package.`, ); return { kind: "unreadable" }; } }; /** * The embedded-package probes read carrier offsets from a file, and a package * member has no file of its own, so its bytes stay on disk for the probe alone. */ const embeddedPackageFormatOfBytes = async ( bytes: Buffer, member: MemberView, nativeFormat: NativeFormat, state: ScanState, context: ScanContext, ): Promise => { try { const root = await mkdtemp(join(tmpdir(), "rea-release-member-")); const owner: ArtifactResourceOwner = { kind: "lease", resource: root, lease: { release: () => rm(root, { force: true, recursive: true }) }, }; let settled: Result; try { const filePath = join(root, "member"); await writeFile(filePath, bytes, { flag: "wx", mode: 0o600 }); settled = ok( await embeddedPackageFormat( filePath, nativeFormat, state, context, member.location, ), ); } catch (cause) { settled = err(cause); } // The directory holds the member's bytes, so a failed removal stays owned. const removal = await context.resources.release(owner); if (removal.kind === "failed") throw context.resources.cleanupFailure( settled.ok ? { kind: "completed" } : { kind: "failed", cause: settled.error }, [removal], ); if (!settled.ok) throw settled.error; return settled.value; } catch (cause) { rethrowReadFailure(cause); pushLimitation( state, `Could not probe ${member.location} for an embedded package.`, ); return { kind: "unreadable" }; } }; /** * A packaged executable can carry its own package, whose members this scan does * not expand. Only an image the embedded-package owner cleared leaves member * coverage intact. All members share one file's byte allowance. */ const probePackagedImage = async ( state: ScanState, member: MemberView, nativeFormat: NativeFormat, context: ScanContext, ): Promise => { const bytesReadBefore = state.memberBytesRead; const allowance = context.maxFileBytes - state.packagedProbeBytes; const image = allowance > 0 ? await member.read(allowance) : null; if (image?.kind !== "bytes") { state.packagedProbeBytes += Math.min( Math.max(allowance, 0), state.memberBytesRead - bytesReadBefore, ); state.unprobedImages += 1; noteUnexaminedPackage(state); pushLimitation( state, `Did not probe ${member.location} for an embedded package.`, ); return; } state.packagedProbeBytes += image.bytes.length; const probe = await embeddedPackageFormatOfBytes( image.bytes, member, nativeFormat, state, context, ); if (probe.kind === "unreadable") noteUnexaminedPackage(state); else if (probe.kind === "package") noteNestedPackage(state, probe.format, member.location); }; const scanEmbeddedPackage = async ( input: ConsumeInput, occurrence: InventoryOccurrence, filePath: string, nativeFormat: NativeFormat, containers: Map, state: ScanState, ): Promise => { if (state.embeddedProbes >= EMBEDDED_PROBE_LIMIT) { noteUnexaminedPackage(state); state.unprobedImages += 1; pushLimitation( state, `Stopped probing native images for embedded packages after ${String(EMBEDDED_PROBE_LIMIT)} files.`, ); return; } state.embeddedProbes += 1; const probe = await embeddedPackageFormat( filePath, nativeFormat, state, input, filePath, state.nativeDigests.get(filePath), ); if (probe.kind === "unreadable") { noteUnexaminedPackage(state); return; } if (probe.kind === "absent") return; state.formats.add(probe.format); await scanUnexpandedContainer( input, occurrence, filePath, probe.format, containers, state, ); }; const scanUnexpandedContainer = async ( input: ConsumeInput, occurrence: InventoryOccurrence, filePath: string, format: PackageFormat, containers: Map, state: ScanState, ): Promise => { let entries: readonly ArtifactEntry[]; try { const container = await openContainer( containers, occurrence.occurrence_id, filePath, format, input.inventory?.nodes.find( (node) => node.artifact_id === occurrence.artifact_id, )?.sha256, state, input.signal, ); if (container === null) { noteUnexaminedPackage(state); return; } entries = await containerEntries( container, state, input.signal, (entry) => { noteUnlistedEntry(state, entry); }, ); } catch (cause) { rethrowReadFailure(cause); noteUnexaminedPackage(state); pushLimitation(state, `Could not list ${filePath}.`); return; } for (const entry of entries) { if (input.signal?.aborted) throw cancelledBy(OPERATION, input.signal); const location = `${filePath}/${entry.path}`; if (hasCompanionName(entry.path)) state.companionPaths.add(location); noteUnfollowedMapLink(state, entry.kind, entry.path, location); if (entry.kind !== "file") continue; const stated = ownerStatedKind(entry.formatMetadata); await examineMember(state, input, { logical: entry.path, format: stated === "javascript" ? "javascript-bundle" : "file", kind: stated ?? "file", kindStated: stated !== null, encrypted: entry.encrypted, declaredSize: entry.declaredSize, location, packageFormat: format, read: (budget) => readListedEntry( containers.get(occurrence.occurrence_id), entry, filePath, budget, state, input.signal, ), }); } }; /** An unlisted package leaves every member-based check undecided. */ const noteUnexaminedPackage = (state: ScanState): void => { state.unreadable += 1; state.coverageUnknown = true; }; const noteNestedPackage = ( state: ScanState, format: PackageFormat, location: string, ): void => { state.formats.add(format); noteUnexaminedPackage(state); pushLimitation(state, `Nested package ${location} was not expanded.`); }; /** * The ASAR owner's signature test. A match does not establish a valid archive. * A probe that stops at the header admission, or runs out of a prefix read * before it decides, leaves the member undecided rather than not an ASAR: the * member may still carry a package nothing here reads, so coverage becomes * unknown while the member is examined as whatever else it may be. */ const probeNestedAsar = ( state: ScanState, location: string, bytes: Buffer, complete: boolean, ): boolean => { const observed = createAsarHeaderSignatureProbe( state.asarHeaderAdmission, ).write(bytes); if (observed.state === "matched") return true; if ( observed.state === "limit" || (observed.state === "pending" && !complete && observed.extents !== undefined) ) { noteUnexaminedPackage(state); pushLimitation( state, `Could not decide whether ${location} holds an ASAR within the header admission.`, ); } return false; }; const readListedEntry = async ( container: OpenContainer | undefined, entry: ArtifactEntry, filePath: string, budget: number, state: ScanState, signal: AbortSignal | undefined, ): Promise => { if (container === undefined) return { kind: "unread" }; try { return await readEntryBytes(container.reader, entry, budget, state, signal); } catch (cause) { rethrowReadFailure(cause); pushLimitation(state, `Could not read ${entry.path} from ${filePath}.`); return { kind: "unread" }; } }; const readContainerMember = async ( input: ConsumeInput, parent: InventoryOccurrence, parentPath: string, parentFormat: string, expectedSha256: string | undefined, memberSha256: string | undefined, occurrence: InventoryOccurrence, ordinals: ReadonlyMap, containers: Map, budget: number, state: ScanState, ): Promise => { const format = asPackageFormat(parentFormat); if (format === null) return { kind: "unread" }; try { const container = await openContainer( containers, parent.occurrence_id, parentPath, format, expectedSha256, state, input.signal, ); if (container === null) return { kind: "unread" }; await containerEntries(container, state, input.signal); const entry = container.byPath.get(entryPath(occurrence, parent))?.[ ordinals.get(occurrence.occurrence_id) ?? 0 ]; if (entry === undefined || entry.kind !== "file") return { kind: "unread" }; // The container digest binds packed members to the captured snapshot. An // unpacked member is read from its companion on disk, so it is bound to // the digest inventory recorded for that member instead. return await readEntryBytes( container.reader, entry, budget, state, input.signal, entry.unpacked === true && memberSha256 !== undefined ? { sha256: memberSha256, changed: `ASAR member changed before interpretation: ${occurrence.logical_path}`, } : undefined, ); } catch (cause) { rethrowReadFailure(cause); pushLimitation(state, `Could not read ${occurrence.logical_path}.`); return { kind: "unread" }; } }; const openContainer = async ( containers: Map, id: string, filePath: string, format: PackageFormat, expectedSha256: string | undefined, state: ScanState, signal: AbortSignal | undefined, ): Promise => { const cached = containers.get(id); if (cached !== undefined) return cached; if (containers.size >= OPEN_CONTAINER_LIMIT) { pushLimitation( state, `Stopped opening package readers after ${String(OPEN_CONTAINER_LIMIT)} containers.`, ); return null; } if (signal?.aborted) throw cancelledBy(OPERATION, signal); const reader = createArtifactReader(filePath, format, { environment: process.env, unreadableDirectories: "omit", asarHeaderAdmission: state.asarHeaderAdmission, }); if (reader === undefined) return null; const container: OpenContainer = { path: filePath, reader, entries: null, byPath: new Map(), }; containers.set(id, container); if (expectedSha256 !== undefined) await reader.prepareContainer?.(expectedSha256, signal); return container; }; const containerEntries = async ( container: OpenContainer, state: ScanState, signal: AbortSignal | undefined, onPastCap?: (entry: ArtifactEntry) => void, ): Promise => { if (container.entries !== null) return container.entries; const listed: ArtifactEntry[] = []; const traversal = new ArtifactTraversalObservation(); let count = 0; let truncated = false; for await (const entry of traversal.entries(container.reader, signal)) { count += 1; if (count > CONTAINER_LIST_LIMIT) { if (!truncated) { truncated = true; state.coverageUnknown = true; pushLimitation( state, `Stopped listing a package after ${String(CONTAINER_LIST_LIMIT)} entries.`, ); } onPastCap?.(entry); continue; } listed.push(entry); const key = logicalPathNfc(entry.path).replace(/\/+$/u, ""); const sameName = container.byPath.get(key); if (sameName === undefined) container.byPath.set(key, [entry]); else sameName.push(entry); } const coverage = traversal.snapshot(); if (coverage.status === "unknown") state.coverageUnknown = true; for (const limitation of coverage.limitations) pushLimitation(state, limitation); container.entries = listed; return listed; }; const readEntryBytes = async ( reader: ArtifactReader, entry: ArtifactEntry, budget: number, state: ScanState, signal: AbortSignal | undefined, expected?: ExpectedMemberDigest, ): Promise => { const stream = await reader.open(entry, signal); return readStreamBounded(stream, budget, state, signal, expected); }; /** An inventoried digest the member's complete bytes must still match. */ interface ExpectedMemberDigest { readonly sha256: string; readonly changed: string; } const readStreamBounded = async ( stream: Readable, budget: number, state: ScanState, signal: AbortSignal | undefined, expected?: ExpectedMemberDigest, ): Promise => { const chunks: Buffer[] = []; const hash = expected === undefined ? undefined : createHash("sha256"); let total = 0; let overBudget = false; let failure: unknown; try { for await (const chunk of stream) { if (signal?.aborted) throw cancelledBy(OPERATION, signal); const piece = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); chunks.push(piece); total += piece.length; state.memberBytesRead += piece.length; if (total > budget) { overBudget = true; break; } hash?.update(piece); } // The digest covers the whole member, so it is only checked when the // member ended within the allowance. A member past the allowance is never // read further to finish the hash: it stays over_allowance, unverified. if ( !overBudget && expected !== undefined && hash !== undefined && hash.digest("hex") !== expected.sha256 ) throw new ArtifactReaderFailure("integrity", expected.changed); } catch (cause) { failure = cause; } let closeFailure: unknown; try { stream.destroy(); } catch (cause) { closeFailure = cause; } if (failure !== undefined && closeFailure !== undefined) throw new AggregateError( [failure, closeFailure], "Member read and stream close both failed.", ); if (closeFailure !== undefined) throw closeFailure; if (failure !== undefined) throw failure; const bytes = Buffer.concat(chunks); return overBudget ? overAllowance(bytes) : { kind: "bytes", bytes }; }; const readSpan = async ( filePath: string, offset: number, length: number, state: ScanState, context: ScanContext, ): Promise => { const { signal } = context; if ( !Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0 || !Number.isSafeInteger(offset + length) ) return null; try { return await withMemberDescriptor( filePath, context, async ({ handle, initial }) => { const observed = await handle.stat(); if (!sameRegularFileState(initial, observed)) throw new ArtifactReaderFailure( "integrity", `Artifact changed before read: ${filePath}`, ); if (offset + length > observed.size) return null; // Charge bytes as they arrive, so a read that fails after partial // progress still counts what it consumed against the allowance. let charged = 0; const bytes = await readFileHandleRange( handle, offset, length, (bytesRead) => { state.memberBytesRead += bytesRead - charged; charged = bytesRead; if (signal?.aborted) throw cancelledBy(OPERATION, signal); }, ); const after = await handle.stat(); if (!sameRegularFileState(initial, after)) throw new ArtifactReaderFailure( "integrity", `Artifact changed during read: ${filePath}`, ); state.memberBytesRead += bytes.length - charged; return Buffer.from(bytes); }, ); } catch (cause) { rethrowReadFailure(cause); pushLimitation(state, `Could not read ${filePath}.`); return null; } }; const readDiskMember = async ( filePath: string, maxBytes: number, expectedSha256: string | undefined, state: ScanState, context: ScanContext, ): Promise => { try { const snapshot = await readStableArtifact( filePath, maxBytes, context.signal, undefined, context.resources, ); if (expectedSha256 !== undefined && snapshot.sha256 !== expectedSha256) throw new ArtifactReaderFailure( "integrity", `Member changed during acquisition: ${filePath}`, ); return { kind: "bytes", bytes: snapshot.bytes }; } catch (cause) { rethrowReadFailure(cause); if (cause instanceof ArtifactReaderFailure && cause.reason === "limit") return { kind: "over_allowance", prefix: await readSpan( filePath, 0, Math.min(maxBytes, MAX_RELEASE_EXPOSURE_MEMBER_PROBE_BYTES), state, context, ), }; pushLimitation(state, `Could not read ${filePath}.`); return { kind: "unread" }; } }; const asReadFailure = (cause: unknown): unknown => cause instanceof RegularFileChangedError ? new ArtifactReaderFailure("integrity", cause.message, { cause }) : cause; /** * A read that left cleanup unfinished is never a skipped member, whatever its * reason: only the error tells the caller a descriptor is still retained. */ const rethrowReadFailure = (cause: unknown): void => { const failure = asReadFailure(cause); if (failure instanceof AnalysisError) throw failure; if ( failure instanceof ArtifactReaderFailure && (failure.reason === "cancelled" || failure.reason === "integrity" || failure.cleanup !== undefined) ) throw failure; }; /** * List the parent directory up to the sibling allowance. The stream stops at * the allowance, so a very large directory costs no more than the limit. */ const listSiblings = async ( directory: string, state: ScanState, { signal, resources, siblingCleanup }: ScanContext, ): Promise => { let owner: OwnedDirectoryHandle; try { owner = new OwnedDirectoryHandle(await opendir(directory)); } catch { noteIncompleteSiblings(state); return []; } const entries: Dirent[] = []; let listed: Result; try { let truncated = false; for (;;) { if (signal?.aborted) throw cancelledBy(OPERATION, signal); const entry = await owner.handle.read(); if (entry === null) break; if (entries.length >= SIBLING_LIST_LIMIT) { truncated = true; break; } entries.push(entry); } listed = ok(truncated); } catch (cause) { listed = err(cause); } const attempt = await resources.release({ kind: "directory-handle", resource: `directory beside the selected file: ${directory}`, handle: owner, }); if (!listed.ok && listed.error instanceof AnalysisError) { if (attempt.kind === "failed") throw resources.cleanupFailure({ kind: "failed", cause: listed.error }, [ attempt, ]); throw listed.error; } if (attempt.kind === "failed") siblingCleanup.push(attempt); if (!listed.ok || listed.value) noteIncompleteSiblings(state); return entries; }; const noteIncompleteSiblings = (state: ScanState): void => { state.skippedCompanions += 1; pushLimitation( state, "The directory beside the selected file could not be listed completely.", ); }; const scanSiblings = async ( input: ConsumeInput, state: ScanState, ): Promise => { const directory = dirname(input.path); const own = basename(input.path); for (const entry of await listSiblings(directory, state, input)) { if (input.signal?.aborted) throw cancelledBy(OPERATION, input.signal); if (entry.name === own) continue; const sibling = appendCallerPath(directory, entry.name); if (hasCompanionName(entry.name)) { state.companionPaths.add(sibling); continue; } if (!entry.name.toLowerCase().endsWith(".map")) continue; if (isJavaScriptSourceMapName(entry.name)) continue; // A declared map stays a source map and a loaded script stays a script, // and `noteUnreachedTargets` counts either one. if (claimMapTarget(state, sibling) || isScriptTarget(state, sibling)) continue; // A link is not followed, so a linker map it names stays unread, not absent. if (entry.isSymbolicLink()) { state.skippedCompanions += 1; continue; } if (!entry.isFile()) continue; await classifySiblingMap(sibling, state, input); } }; /** * Siblings are in scope only for debug-companion discovery, so a sibling map * never reaches the selected artifact's source-map counts. Its read still * spends the same map count, or a directory of .map files would multiply the * byte allowance by the listing allowance. */ const classifySiblingMap = async ( sibling: string, state: ScanState, input: ConsumeInput, ): Promise => { const { hasSlot, bytes } = chargeMapRead(state); const loaded = await readDiskMember(sibling, bytes, undefined, state, input); if (loaded.kind === "unread") { state.skippedCompanions += 1; return; } const prefix = loaded.kind === "bytes" ? loaded.bytes : loaded.prefix; if (loaded.kind === "bytes" && hasSlot && parsesAsSourceMap(loaded.bytes)) return; // A native header outranks the name, as it does for a member. if ( prefix !== null && sniffNativeFormat( prefix, loaded.kind === "bytes" ? prefix.length : null, ) !== null ) return; // A Node shebang names a script, as it does for a member's `.map`. if (prefix !== null && hasNodeShebang(prefix)) return; // An undecided PE header may be native, so it is no linker-map evidence, // nor is a shebang whose program an unresolved variable names. if ( prefix === null || isUndecidedPeHeader(prefix) || mayHaveSourceMapPrefix(prefix) || nodeShebang(prefix) === undefined ) state.skippedCompanions += 1; else noteLinkerMapGuess(state, sibling); }; const parsesAsSourceMap = (bytes: Buffer): boolean => { const text = mapText(bytes); if (text === null) return false; try { inspectSourceMap(text); return true; } catch { return false; } }; const diskPath = ( input: ConsumeInput, occurrence: InventoryOccurrence, byId: Map, formatOf: (occurrence: InventoryOccurrence) => string, ): string | null => { if (hasExtractableAncestor(occurrence, byId, formatOf)) return null; if ( occurrence.source_path !== undefined && occurrence.source_path.length > 0 && isAbsolute(occurrence.source_path) ) return occurrence.source_path; if (!input.directory) { if (occurrence.parent_occurrence_id === null) return input.path; return null; } if (occurrence.logical_path.split("/").includes("..")) return null; if (occurrence.logical_path.length === 0 || occurrence.logical_path === ".") return input.path; const source = occurrence.source_path; return appendCallerPath( input.path, source !== undefined && logicalPathNfc(source) === occurrence.logical_path ? source : occurrence.logical_path, ); }; const packageAncestor = ( occurrence: InventoryOccurrence, byId: Map, formatOf: (occurrence: InventoryOccurrence) => string, ): InventoryOccurrence | undefined => { const seen = new Set(); let parentId = occurrence.parent_occurrence_id; while (parentId !== null) { if (seen.has(parentId)) return undefined; seen.add(parentId); const parent = byId.get(parentId); if (parent === undefined) return undefined; if (EXTRACTABLE.has(formatOf(parent))) return parent; parentId = parent.parent_occurrence_id; } return undefined; }; const hasExtractableAncestor = ( occurrence: InventoryOccurrence, byId: Map, formatOf: (occurrence: InventoryOccurrence) => string, ): boolean => packageAncestor(occurrence, byId, formatOf) !== undefined; const entryPath = ( occurrence: InventoryOccurrence, parent: InventoryOccurrence, ): string => { const logical = occurrence.logical_path; const parentLogical = parent.logical_path; if (parentLogical.length === 0 || parentLogical === ".") return logical; const prefix = `${parentLogical}/`; return logical.startsWith(prefix) ? logical.slice(prefix.length) : logical; }; /** * Readers do not follow links, so a map one names, or a map a script or page * it names could hold, stays unread, not absent. The link is one omission * however many declarations reach it. */ const noteUnfollowedMapLink = ( state: ScanState, kind: string, logical: string, location: string, ): void => { if (kind !== "symlink") return; if ( !isSourceMap(logical, "file") && !canDeclareMap({ kind: "file", logical }) ) return; recordMemberCompletion(state, location, { map: true, script: true }); state.skippedMaps += 1; // A generic `.map` link may name a linker map, as an unread map may. if (isSourceMap(logical, "file") && !isJavaScriptSourceMapName(logical)) state.skippedCompanions += 1; }; const noteUnlistedEntry = (state: ScanState, entry: ArtifactEntry): void => { noteUnfollowedMapLink(state, entry.kind, entry.path, entry.path); if (entry.kind !== "file") return; if (entry.encrypted) state.unreadable += 1; if (isSourceMap(entry.path, "file")) { noteUnreadMap(state, namedMapReference(entry.path, entry.path), null); state.skippedText += 1; } else if (isText(entry.path, "file")) state.skippedText += 1; }; const JAVASCRIPT_SOURCE_MAP = /\.(?:cjs|css|cts|js|jsx|mjs|mts|ts|tsx)\.map$/iu; const isJavaScriptSourceMapName = (logical: string): boolean => JAVASCRIPT_SOURCE_MAP.test(logical); const isSourceMap = (logical: string, kind: string): boolean => kind === "source-map" || logical.toLowerCase().endsWith(".map"); const isDeclaredText = (kind: string): boolean => kind === "javascript" || kind === "source-map" || kind === "plist" || kind === "entitlements"; const isText = (logical: string, kind: string): boolean => isDeclaredText(kind) || TEXT_EXTENSION.test(logical); const hasCompanionName = (logical: string): boolean => { const lower = logical.toLowerCase(); return ( lower.endsWith(".pdb") || lower.endsWith(".debug") || lower.endsWith(".dsym") ); }; /** * FAT identity from the container owner. A prefix can only rule a universal * image out against the member's real size: without one, or with slices past * the prefix, the image may be native and stays counted as one. */ const sniffFatFormat = ( bytes: Buffer, size: number | null, ): "mach-o-universal" | null => { const known = size !== null && size >= bytes.length; const header = readFatContainerHeader(bytes, known ? size : bytes.length); if (header.state !== "parsed") return null; return known && classifyFatContainerEvidence(header, bytes).state === "not-mach-o" ? null : "mach-o-universal"; }; /** Header facts from the executable owners. A JVM class is not a FAT Mach-O. */ const sniffNativeFormat = ( bytes: Buffer, size: number | null = bytes.length, ): NativeFormat | null => { if ( bytes.length >= 4 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46 ) return "elf"; if (readMachoHeaderPrefixFacts(bytes).format !== null) return "mach-o"; const universal = sniffFatFormat(bytes, size); if (universal !== null) return universal; const windows = observeMzWindowsHeader(bytes); if (windows.state === "declared" && windows.signature === "PE") return "pe"; return null; }; const targetKind = ( path: string, format: string, directory: boolean, ): ReleaseExposureScan["target"]["kind"] => { if (directory && basename(path).toLowerCase().endsWith(".app")) return "app"; if (directory || format === "directory") return "directory"; if (format === "asar") return "asar"; if (NATIVE.has(format) || EXTRACTABLE.has(format)) return "executable"; return "file"; }; /** * Wide text is valid UTF-8 when its characters are ASCII, so validity alone * cannot separate it from UTF-8 holding a NUL. Density can: UTF-16 puts a NUL in * every other byte of each ASCII character, and a stray NUL is one byte of many. */ const hasNonUtf8Nul = (bytes: Buffer): boolean => { const header = bytes.subarray(0, MEMBER_ENCODING_HEADER_BYTES); const nuls = header.reduce((count, byte) => count + (byte === 0 ? 1 : 0), 0); return ( nuls > 0 && (nuls * WIDE_TEXT_NUL_DIVISOR >= header.length || !isUtf8(bytes)) ); }; const pushSample = (samples: string[], value: string): void => { if ( value.length === 0 || samples.includes(value) || samples.length >= MAX_RELEASE_EXPOSURE_SAMPLES ) return; samples.push(value); }; const pushLimitation = (state: ScanState, message: string): void => { if ( state.limitations.length >= LIMITATION_CAP || state.limitations.includes(message) ) return; state.limitations.push(message); }; const fileSizeRecovery = (maxFileBytes: number) => maxFileBytes >= MAX_RELEASE_EXPOSURE_FILE_BYTES ? fixedAllowanceOptions( `The release exposure input allowance of ${String(MAX_RELEASE_EXPOSURE_FILE_BYTES)} bytes (this release has no runtime override)`, "input", ) : { retryable: false as const, remediationAction: `Raise max_file_bytes above ${String(maxFileBytes)} bytes or select a smaller artifact. The ceiling is ${String(MAX_RELEASE_EXPOSURE_FILE_BYTES)} bytes.`, }; /** * The header admission is its own bound, not the selected-file ceiling, so * max_file_bytes cannot repair it. The recovery names the shared setting the * composition threaded into this reader. */ const asarHeaderAdmissionFailure = ( cause: ArtifactReaderFailure, admission: ArtifactAdmissionLimit, ): AnalysisResourceConstraintError => new AnalysisResourceConstraintError( OPERATION, "capacity", admission.requiredBytes === undefined ? `An ASAR header/index exceeds ${String(admission.maximumBytes)} bytes.` : `An ASAR header/index of ${String(admission.requiredBytes)} bytes exceeds ${String(admission.maximumBytes)} bytes.`, { asar_max_header_bytes: admission.maximumBytes, ...(admission.requiredBytes === undefined ? {} : { required_header_bytes: admission.requiredBytes }), }, { cause, retryable: false, remediationAction: asarHeaderAdmissionRecovery(admission), limit: { ...analysisSettingLimit( "asar.max_header_bytes", admission.maximumBytes, admission.source, ), ...(admission.requiredBytes === undefined ? {} : { required_value: admission.requiredBytes }), }, }, ); const releaseExposureLimitFailure = ( cause: ArtifactReaderFailure, maxFileBytes: number, ): AnalysisResourceConstraintError => cause.admission === undefined ? new AnalysisResourceConstraintError( OPERATION, "file-size", cause.message, { max_file_bytes: maxFileBytes }, { cause, ...fileSizeRecovery(maxFileBytes) }, ) : asarHeaderAdmissionFailure(cause, cause.admission); const releaseExposureFailurePrimary = ( facts: ArtifactFilePrimaryFacts, path: string, maxFileBytes: number, ): AnalysisError => { const { cause, origin } = facts; if (origin === "owned-or-classified" && cause instanceof AnalysisError) return cause; if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure && cause.reason === "integrity" ) return new AnalysisArtifactChangedError(OPERATION, path, cause.message, { cause, }); if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure && cause.reason === "cancelled" ) return cancelledBy( OPERATION, carriedReason(artifactFileCancellationCause(cause)), ); if ( origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure ) { if (cause.reason === "limit") return releaseExposureLimitFailure(cause, maxFileBytes); if (cause.reason === "path" || cause.reason === "format") return new AnalysisInputError(OPERATION, { cause }, [ { path: ["path"], reason: "invalid_format", message: cause.message }, ]); } if (cause instanceof Error && "code" in cause) { if (cause.code === "EACCES" || cause.code === "EPERM") return new AnalysisAccessDeniedError(OPERATION, path, cause.code, { cause, }); if (isSelectedRegularFileError(cause)) return new AnalysisInputError(OPERATION, { cause }, [ { path: ["path"], reason: "invalid_value", message: `Selected artifact could not be read (${String(cause.code)}): ${path}.`, }, ]); } return new ProviderAdapterError(RELEASE_EXPOSURE_PROVIDER.id, OPERATION, { cause, diagnostics: { path, reason: cause instanceof Error ? cause.message : String(cause), }, }); }; const releaseExposureFailure = ( cause: unknown, path: string, maxFileBytes: number, ): AnalysisError => projectStableArtifactFailure( cause, releaseExposureFailurePrimary( artifactFilePrimaryFacts(cause), path, maxFileBytes, ), path, RELEASE_EXPOSURE_PROVIDER.id, OPERATION, );