reaproof 0.3.0 → 0.4.0

package/src/cli.mjs

@@ -5,13 +5,26 @@ import { applyFix, planFix, undoLastFix } from './fix.mjs';
 import { MeasureError, measureWithRea, REA_PACKAGE } from './measure.mjs';
 import { isWebAddress, scanDeployedSite } from './remote.mjs';
 import { createReporter, pickLanguage } from './report.mjs';
+import { hasLeakAtOrAbove, LEAK_SEVERITIES } from './rules.mjs';
 import { resolveTargets, scan, ScanError, withoutFiles } from './scan.mjs';
 import { toPrintable, toVisibleJson } from './text.mjs';
 
 const COMMANDS = { scan: runScan, fix: runFix, undo: runUndo, measure: runMeasure };
+const OPTIONS = {
+  json: { type: 'boolean' },
+  yes: { type: 'boolean', short: 'y' },
+  // The mildest leak that still stops a release.
+  'fail-on': { type: 'string' },
+  lang: { type: 'string' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' },
+};
 const EXIT_OK = 0;
 const EXIT_FINDINGS = 1;
 const EXIT_USAGE = 2;
+// Nothing could be read: an address that did not answer, or a target with nothing in it
+// that this scanner opens. A check that read nothing must not pass for a clean one.
+const EXIT_UNREAD = 3;
 
 /**
  * Everything the command needs from the outside world, so the flow can be driven by a
@@ -38,24 +51,24 @@ export async function main(argv, outside) {
   };
   let parsed;
   try {
-    parsed = parseArgs({
-      args: argv,
-      options: {
-        json: { type: 'boolean' },
-        yes: { type: 'boolean', short: 'y' },
-        lang: { type: 'string' },
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean', short: 'v' },
-      },
-      allowPositionals: true,
-    });
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
   } catch (error) {
-    terminal.printError(createReporter(pickLanguage()).usageError(error));
-    return EXIT_USAGE;
+    // What can still be read of the command says how to answer it: in which language, and as JSON or not.
+    const { values } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: false });
+    const report = createReporter(pickLanguage(typeof values.lang === 'string' ? values.lang : undefined));
+    const wantsJson = values.json === true;
+    const reason = report.usageError(error);
+    // A person is shown how the command is used. An agent gets the reason alone.
+    const message = wantsJson ? reason : `${reason}\n\n${report.help}`;
+    return fail(terminal, report, wantsJson, EXIT_USAGE, { code: 'usage', message });
   }
 
-  const { values: options, positionals } = parsed;
+  const { values, positionals } = parsed;
+  const options = { ...values, failOn: values['fail-on'] ?? 'high' };
   const report = createReporter(pickLanguage(options.lang));
+  if (!LEAK_SEVERITIES.includes(options.failOn)) {
+    return fail(terminal, report, options.json, EXIT_USAGE, { code: 'usage', message: report.failOnError(options.failOn) });
+  }
   if (options.help) {
     terminal.print(report.help);
     return EXIT_OK;
@@ -72,17 +85,31 @@ export async function main(argv, outside) {
     return await COMMANDS[command](target, options, report, terminal);
   } catch (error) {
     if (error instanceof ScanError) {
-      terminal.printError(report.scanError(error));
-      return EXIT_USAGE;
+      const { code, path, details } = error;
+      const exitCode = code === 'page-unreachable' ? EXIT_UNREAD : EXIT_USAGE;
+      return fail(terminal, report, options.json, exitCode, { code, message: report.scanError(error), path, ...details });
     }
     if (error instanceof MeasureError) {
-      terminal.printError(report.measureFailed(error));
-      return EXIT_USAGE;
+      const failure = { code: 'measure-failed', message: report.measureFailed(error) };
+      return fail(terminal, report, options.json, EXIT_USAGE, failure);
     }
     throw error;
   }
 }
 
+/**
+ * Says why the command stopped, and hands back the code it ends with. When JSON was asked
+ * for it is JSON on standard output like any other answer, so that whoever parses the
+ * output is never handed nothing.
+ *
+ * @param {{ code: string, message: string }} failure and whatever else is known about it
+ */
+function fail(terminal, report, wantsJson, exitCode, failure) {
+  if (wantsJson) terminal.print(toJson({ exitCode, error: failure }, report));
+  else terminal.printError(failure.message);
+  return exitCode;
+}
+
 /**
  * The one command most people need. For a person at a terminal it carries on from the
  * report: it offers to build when nothing is built yet, and to take out what can be taken
@@ -93,13 +120,14 @@ async function runScan(target, options, report, terminal) {
   const result = isWebAddress(target)
     ? await scanDeployedSite(target)
     : await scanOrOfferBuild(resolve(target), ask, report, terminal);
-  terminal.print(options.json ? toJson(withExplanation(result, report), report) : report.scan(result));
+  const ending = endingOf(result, options);
+  terminal.print(options.json ? toJson(withExplanation(result, report, ending), report) : report.scan(result));
 
   // A deployed result plans nothing: none of its findings is a file on disk.
   const mapPaths = planFix(result);
-  if (!ask || mapPaths.length === 0) return exitCodeFor(result);
+  if (!ask || mapPaths.length === 0) return closeWith(ending, options, report, terminal);
   terminal.print(`\n${report.fixPlan(result.root, mapPaths)}`);
-  if (!(await ask(report.confirmQuestion))) return exitCodeFor(result);
+  if (!(await ask(report.confirmQuestion))) return closeWith(ending, options, report, terminal);
   return takeOutMaps(result, mapPaths, options, report, terminal);
 }
 
@@ -108,7 +136,7 @@ async function scanOrOfferBuild(root, ask, report, terminal) {
     return scan(root);
   } catch (error) {
     // Only a missing build output carries the command that would produce it.
-    const buildCommand = error instanceof ScanError ? error.buildCommand : null;
+    const buildCommand = error instanceof ScanError ? error.details.buildCommand : null;
     if (!ask || !buildCommand || !(await ask(report.buildQuestion(buildCommand.join(' '))))) throw error;
     if (!terminal.runBuild(buildCommand, root)) throw new ScanError('build-failed', root);
     return scan(root);
@@ -125,9 +153,10 @@ async function runFix(target, options, report, terminal) {
   const root = toLocalRoot(target);
   const before = scan(root);
   const mapPaths = planFix(before);
+  const ending = endingOf(before, options);
   if (mapPaths.length === 0) {
-    terminal.print(options.json ? toJson({ movedCount: 0, before }, report) : report.nothingToFix);
-    return exitCodeFor(before);
+    terminal.print(options.json ? toJson({ ...ending, movedCount: 0, before }, report) : report.nothingToFix);
+    return closeWith(ending, options, report, terminal);
   }
 
   if (!options.yes) {
@@ -142,7 +171,7 @@ async function runFix(target, options, report, terminal) {
     }
     if (!(await terminal.ask(report.confirmQuestion))) {
       terminal.print(report.cancelled);
-      return exitCodeFor(before);
+      return closeWith(ending, options, report, terminal);
     }
   }
   return takeOutMaps(before, mapPaths, options, report, terminal);
@@ -152,8 +181,13 @@ function takeOutMaps(before, mapPaths, options, report, terminal) {
   const applied = applyFix(before.root, mapPaths);
   // The moved files are the only change, so the rest of the output is not read again.
   const after = withoutFiles(before, mapPaths);
-  terminal.print(options.json ? toJson({ ...applied, before, after }, report) : report.fixDone(before, after, applied));
-  return exitCodeFor(after);
+  // The check has been made already, so an output with nothing left in it is not a failure.
+  const exitCode = hasLeakAtOrAbove(after.leaks, options.failOn) ? EXIT_FINDINGS : EXIT_OK;
+  const ending = { failOn: options.failOn, exitCode };
+  terminal.print(
+    options.json ? toJson({ ...ending, ...applied, before, after }, report) : report.fixDone(before, after, applied),
+  );
+  return closeWith(ending, options, report, terminal);
 }
 
 function runUndo(target, options, report, terminal) {
@@ -168,7 +202,7 @@ function runUndo(target, options, report, terminal) {
 
 async function runMeasure(target, options, report, terminal) {
   const root = toLocalRoot(target);
-  const targets = resolveTargets(root);
+  const { targets } = resolveTargets(root);
   // rea is someone else's program: it is downloaded and run only after a yes.
   if (!options.yes) {
     if (options.json) {
@@ -196,14 +230,35 @@ async function runMeasure(target, options, report, terminal) {
   return EXIT_OK;
 }
 
-/** The JSON a scan prints: the result, plus what it means and what to do, in words. */
-function withExplanation(result, report) {
-  return { ...result, explain: report.explain(result) };
+/**
+ * The JSON a scan prints: the result, plus what it means and what to do, in words. The
+ * verdict comes first and the list of findings last, so an answer that a reader cuts short
+ * still says the most important thing.
+ *
+ * @param {{ failOn: string, exitCode: number }} ending
+ */
+function withExplanation(result, report, ending) {
+  const { risk, leaks, findings, ...facts } = result;
+  return { risk, leaks, ...ending, explain: report.explain(result), ...facts, findings };
+}
+
+/**
+ * How a command ends when that follows from a result. A leak is worth failing a release
+ * check over when it is critical or high, unless `--fail-on` says otherwise: medium ones
+ * too, or critical ones alone. The answer says how it ends as well, for whoever reads a
+ * log later and for an agent that is not shown the exit code: `failOn` and `exitCode` in
+ * the JSON, and a closing line in the text (`closeWith`).
+ */
+function endingOf(result, options) {
+  const stops = hasLeakAtOrAbove(result.leaks, options.failOn);
+  const exitCode = stops ? EXIT_FINDINGS : result.risk === 'unrated' ? EXIT_UNREAD : EXIT_OK;
+  return { failOn: options.failOn, exitCode };
 }
 
-/** Critical and high leaks are the ones worth failing a release check over. */
-function exitCodeFor({ leaks }) {
-  return leaks.critical + leaks.high > 0 ? EXIT_FINDINGS : EXIT_OK;
+function closeWith({ failOn, exitCode }, options, report, terminal) {
+  const closing = options.json ? null : report.closing(exitCode, failOn);
+  if (closing) terminal.print(`\n${closing}`);
+  return exitCode;
 }
 
 function readPackageVersion() {

package/src/electron.mjs

@@ -1,14 +1,9 @@
-import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
-import { join } from 'node:path';
-import { readAt } from './bytes.mjs';
-
 // Layout from @electron/fuses: the sentinel, one version byte, one length byte, then one
 // byte per fuse in FuseV1Options order.
 const SENTINEL = Buffer.from('dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX');
 const WIRE_VERSION = 1;
 const FUSE_ENABLED = 0x31;
 const WIRE_HEADER_BYTES = 2;
-const SCAN_CHUNK_BYTES = 4 * 1024 * 1024;
 // Fuses that let someone run or debug the shipped app as a development tool. All three are
 // on in a stock Electron build.
 const DEVELOPMENT_FUSES = [
@@ -16,53 +11,33 @@ const DEVELOPMENT_FUSES = [
   [2, 'nodeOptions'],
   [3, 'nodeCliInspect'],
 ];
-const MACOS_FRAMEWORK_NAME = 'Electron Framework.framework';
-
-/** Where the fuses of a macOS Electron app live, given a directory the scanner came across. */
-export function electronBinaryIn(directory, name) {
-  return name === MACOS_FRAMEWORK_NAME ? join(directory, 'Electron Framework') : null;
-}
 
 /**
- * Reports development fuses left on in a packaged Electron binary.
+ * Reports development fuses left on, when a stretch of a file holds Electron's fuse list.
+ * The list sits in Electron's own binary, whatever the system and whatever the file is
+ * called, so it is looked for in the bytes and not by name.
  *
- * @param {string} path how the binary is shown to the user
- * @param {string} binaryPath absolute path
+ * @param {string} path how the file is shown to the user
+ * @param {import('./bytes.mjs').ByteSource} source the whole file
+ * @param {{ position: number, bytes: Buffer }} chunk the stretch of it being searched
  */
-export function checkElectronFuses(path, binaryPath) {
-  const enabled = readEnabledDevelopmentFuses(binaryPath);
+export function checkElectronFuses(path, source, { position, bytes }) {
+  const index = bytes.indexOf(SENTINEL);
+  if (index === -1) return [];
+  const enabled = readEnabledDevelopmentFuses(source, position + index + SENTINEL.length);
   if (!enabled || enabled.length === 0) return [];
   return [{ rule: 'electron-fuse', severity: 'medium', path, detail: { enabled } }];
 }
 
-/** @returns {string[] | null} null when the file is not an Electron binary this can read */
-function readEnabledDevelopmentFuses(binaryPath) {
-  let fd;
+/** @returns {string[] | null} null when what follows the sentinel is not a fuse list this can read */
+function readEnabledDevelopmentFuses(source, wirePosition) {
   try {
-    fd = openSync(binaryPath, 'r');
-    const sentinelPosition = findSentinel(fd, fstatSync(fd).size);
-    if (sentinelPosition === -1) return null;
-
-    const wirePosition = sentinelPosition + SENTINEL.length;
-    const [version, length] = readAt(fd, wirePosition, WIRE_HEADER_BYTES);
+    const [version, length] = source.read(wirePosition, WIRE_HEADER_BYTES);
     if (version !== WIRE_VERSION) return null;
-    const wire = readAt(fd, wirePosition + WIRE_HEADER_BYTES, length);
-    return DEVELOPMENT_FUSES.filter(([index]) => wire[index] === FUSE_ENABLED).map(([, name]) => name);
+    const wire = source.read(wirePosition + WIRE_HEADER_BYTES, length);
+    return DEVELOPMENT_FUSES.filter(([fuse]) => wire[fuse] === FUSE_ENABLED).map(([, name]) => name);
   } catch {
-    // Missing, unreadable or cut short: nothing can be said about it.
+    // Cut short: nothing can be said about it.
     return null;
-  } finally {
-    if (fd !== undefined) closeSync(fd);
-  }
-}
-
-/** Reads the file in overlapping chunks, so a sentinel across a chunk boundary is still found. */
-function findSentinel(fd, fileBytes) {
-  const buffer = Buffer.alloc(SCAN_CHUNK_BYTES + SENTINEL.length - 1);
-  for (let position = 0; position < fileBytes; position += SCAN_CHUNK_BYTES) {
-    const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
-    const index = buffer.subarray(0, bytesRead).indexOf(SENTINEL);
-    if (index !== -1) return position + index;
   }
-  return -1;
 }

package/src/macho.mjs

@@ -0,0 +1,256 @@
+// Layouts are those of Apple's <mach-o/fat.h>, <mach-o/loader.h> and <mach-o/nlist.h>, and
+// of xnu's cs_blobs.h for the signature. A Mach-O is little-endian on every Mac built since
+// 2006; the universal wrapper and the signature are big-endian.
+const UNIVERSAL_MAGIC = 0xcafebabe;
+const UNIVERSAL_MAGIC_64 = 0xcafebabf;
+const MAGIC_32 = 0xfeedface;
+const MAGIC_64 = 0xfeedfacf;
+// A Java class file opens with the same four bytes as a universal binary and then states
+// its version, 45 or more, where a universal binary counts its slices.
+const MAX_SLICES = 16;
+const HEADER_BYTES = { [MAGIC_32]: 28, [MAGIC_64]: 32 };
+const SYMBOL_BYTES = { [MAGIC_32]: 12, [MAGIC_64]: 16 };
+const MAX_COMMAND_BYTES = 16 * 1024 * 1024;
+
+const FILE_KINDS = { 2: 'executable', 6: 'library', 8: 'library' };
+const ARM64 = 0x0100000c;
+const ARCHITECTURES = { [ARM64]: 'arm64', 0x01000007: 'x86_64', 0x0200000c: 'arm64_32', 7: 'i386', 12: 'arm' };
+const ARM64E_SUBTYPE = 2;
+const SUBTYPE_MASK = 0x00ffffff;
+
+const LC_SYMTAB = 0x2;
+const LC_CODE_SIGNATURE = 0x1d;
+const LC_BUILD_VERSION = 0x32;
+// Builds from before LC_BUILD_VERSION say what they are for by which "minimum version"
+// command they carry: macOS, iOS, tvOS or watchOS.
+const PLATFORM_BY_VERSION_COMMAND = { 0x24: 1, 0x25: 2, 0x2f: 3, 0x30: 4 };
+// PLATFORM_* of <mach-o/loader.h>. Mac Catalyst apps run on the Mac under its rules; the
+// phone, TV, watch and headset systems and their simulators share theirs.
+const SYSTEM_BY_PLATFORM = { 1: 'macos', 6: 'macos', 2: 'ios', 3: 'ios', 4: 'ios', 7: 'ios', 8: 'ios', 9: 'ios', 11: 'ios', 12: 'ios' };
+const MACOS_PLATFORM = 1;
+
+// In a symbol's type byte: any of the top three bits marks an entry written for a debugger,
+// the lowest bit a name that other files may link against, and the three between them say
+// where the name is defined, or with none of them set, that it is defined somewhere else.
+const DEBUG_ENTRY_BITS = 0xe0;
+const EXTERNAL_BIT = 0x01;
+const DEFINED_BITS = 0x0e;
+const SOURCE_NAME_ENTRY = 0x64;
+const SYMBOLS_PER_READ = 65536;
+const MAX_NAME_BYTES = 1024;
+// Real programs name a few thousand original files in a few hundred kilobytes. The limit
+// keeps a file that claims far more from filling memory.
+const MAX_SOURCE_NAME_BYTES = 4 * 1024 * 1024;
+
+const EMBEDDED_SIGNATURE_MAGIC = 0xfade0cc0;
+const CODE_DIRECTORY_MAGIC = 0xfade0c02;
+const ENTITLEMENTS_MAGIC = 0xfade7171;
+const CODE_DIRECTORY_SLOT = 0;
+const ENTITLEMENTS_SLOT = 5;
+const MAX_SIGNATURE_BLOBS = 64;
+const MAX_ENTITLEMENTS_BYTES = 1024 * 1024;
+
+/**
+ * One architecture's build inside a Mach-O file.
+ *
+ * @typedef {object} MachOImage
+ * @property {string} architecture for example 'arm64'
+ * @property {'executable' | 'library' | 'other'} kind
+ * @property {'macos' | 'ios' | 'other'} system which family of Apple systems it is built for;
+ *   'ios' takes in tvOS, watchOS and visionOS, whose rules are the same
+ * @property {number} debugEntries symbol table entries written for a debugger
+ * @property {number} localNames names of functions and variables that nothing outside the file needs
+ * @property {number} exportedNames names defined here that other files may link against
+ * @property {string[]} sourcePaths the original files, as the linker recorded where they were
+ * @property {{ flags: number, entitlements: string } | null} signature null when the build is not signed
+ */
+
+/**
+ * Reads what a Mach-O file says about itself, without running it or any other program.
+ *
+ * @param {import('./bytes.mjs').ByteSource} source
+ * @returns {MachOImage[] | null} one image per architecture; null when the bytes are not a
+ *   Mach-O, or are cut short or malformed, which the system would not load either
+ */
+export function readMachO(source) {
+  try {
+    const images = listSlices(source).map(({ start, bytes }) => readImage(readerWithin(source.read, start, bytes)));
+    return images.length > 0 && !images.includes(null) ? images : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A reader that stays inside one stretch of the bytes, whatever offsets the file claims. */
+function readerWithin(read, start, bytes) {
+  return Object.assign(
+    (offset, length) => {
+      if (offset + length > bytes) throw new Error('a read reaches past the end');
+      return read(start + offset, length);
+    },
+    { bytes },
+  );
+}
+
+/** @returns {{ start: number, bytes: number }[]} where each architecture's build sits; none for another kind of file */
+function listSlices(source) {
+  if (source.byteLength < 8) return [];
+  const opening = source.read(0, 8);
+  const magic = opening.readUInt32BE(0);
+  if (magic !== UNIVERSAL_MAGIC && magic !== UNIVERSAL_MAGIC_64) return [{ start: 0, bytes: source.byteLength }];
+
+  const sliceCount = opening.readUInt32BE(4);
+  if (sliceCount > MAX_SLICES) return [];
+  const isWide = magic === UNIVERSAL_MAGIC_64;
+  const entryBytes = isWide ? 32 : 20;
+  const table = source.read(8, sliceCount * entryBytes);
+  return Array.from({ length: sliceCount }, (_, index) => {
+    const entry = table.subarray(index * entryBytes);
+    const start = isWide ? Number(entry.readBigUInt64BE(8)) : entry.readUInt32BE(8);
+    const bytes = isWide ? Number(entry.readBigUInt64BE(16)) : entry.readUInt32BE(12);
+    if (start + bytes > source.byteLength) throw new Error('a slice reaches past the end of the file');
+    return { start, bytes };
+  }).sort((one, other) => one.start - other.start).map((slice, index, slices) => {
+    // Each build has its own stretch of the file. Builds that share bytes are not what a
+    // linker writes, and would have the same bytes read once for every one of them.
+    if (index > 0 && slice.start < slices[index - 1].start + slices[index - 1].bytes) throw new Error('slices overlap');
+    return slice;
+  });
+}
+
+/**
+ * @param {((offset: number, length: number) => Buffer) & { bytes: number }} read stays inside the slice
+ * @returns {MachOImage | null} null when the slice is not a Mach-O image
+ */
+function readImage(read) {
+  const magic = read.bytes >= 4 ? read(0, 4).readUInt32LE(0) : 0;
+  if (!(magic in HEADER_BYTES)) return null;
+  const header = read(0, HEADER_BYTES[magic]);
+  const commandBytes = header.readUInt32LE(20);
+  if (commandBytes > MAX_COMMAND_BYTES) throw new Error('the load commands are implausibly large');
+  const commands = read(HEADER_BYTES[magic], commandBytes);
+  const commandCount = header.readUInt32LE(16);
+
+  let symbolTable = null;
+  let signature = null;
+  // A build that does not say what it is for is taken as one for the Mac.
+  let platform = MACOS_PLATFORM;
+  // A read past the end of the commands throws, which also ends a count that is not true.
+  for (let index = 0, offset = 0; index < commandCount; index += 1) {
+    const command = commands.readUInt32LE(offset);
+    const size = commands.readUInt32LE(offset + 4);
+    if (size < 8) throw new Error('a load command has no size');
+    if (command === LC_SYMTAB) {
+      symbolTable = {
+        offset: commands.readUInt32LE(offset + 8),
+        count: commands.readUInt32LE(offset + 12),
+        namesOffset: commands.readUInt32LE(offset + 16),
+        namesBytes: commands.readUInt32LE(offset + 20),
+      };
+    } else if (command === LC_CODE_SIGNATURE) {
+      signature = { offset: commands.readUInt32LE(offset + 8), bytes: commands.readUInt32LE(offset + 12) };
+    } else if (command === LC_BUILD_VERSION) {
+      platform = commands.readUInt32LE(offset + 8);
+    } else if (command in PLATFORM_BY_VERSION_COMMAND) {
+      platform = PLATFORM_BY_VERSION_COMMAND[command];
+    }
+    offset += size;
+  }
+
+  return {
+    architecture: nameArchitecture(header.readUInt32LE(4), header.readUInt32LE(8)),
+    kind: FILE_KINDS[header.readUInt32LE(12)] ?? 'other',
+    system: SYSTEM_BY_PLATFORM[platform] ?? 'other',
+    ...(symbolTable ? readSymbols(read, symbolTable, SYMBOL_BYTES[magic]) : NO_SYMBOLS),
+    signature: signature && readSignature(readerWithin(read, signature.offset, signature.bytes)),
+  };
+}
+
+const NO_SYMBOLS = { debugEntries: 0, localNames: 0, exportedNames: 0, sourcePaths: [] };
+
+function nameArchitecture(cpuType, cpuSubtype) {
+  if (cpuType === ARM64 && (cpuSubtype & SUBTYPE_MASK) === ARM64E_SUBTYPE) return 'arm64e';
+  return ARCHITECTURES[cpuType] ?? `cpu ${cpuType}`;
+}
+
+function readSymbols(read, { offset, count, namesOffset, namesBytes }, symbolBytes) {
+  let debugEntries = 0;
+  let localNames = 0;
+  let exportedNames = 0;
+  let sourceNameBytes = 0;
+  const sourceNames = [];
+  const readName = (nameOffset) => {
+    if (nameOffset >= namesBytes) return '';
+    const name = read(namesOffset + nameOffset, Math.min(MAX_NAME_BYTES, namesBytes - nameOffset));
+    const end = name.indexOf(0);
+    return name.toString('utf8', 0, end === -1 ? name.length : end);
+  };
+
+  for (let first = 0; first < count; first += SYMBOLS_PER_READ) {
+    const symbolsRead = Math.min(SYMBOLS_PER_READ, count - first);
+    const symbols = read(offset + first * symbolBytes, symbolsRead * symbolBytes);
+    for (let at = 0; at < symbols.length; at += symbolBytes) {
+      const type = symbols[at + 4];
+      if (type & DEBUG_ENTRY_BITS) {
+        debugEntries += 1;
+        if (type === SOURCE_NAME_ENTRY && sourceNameBytes < MAX_SOURCE_NAME_BYTES) {
+          const name = readName(symbols.readUInt32LE(at));
+          sourceNames.push(name);
+          // An empty name still costs a read, so it counts for something.
+          sourceNameBytes += name.length + 1;
+        }
+      } else if (!(type & EXTERNAL_BIT)) {
+        localNames += 1;
+      } else if (type & DEFINED_BITS) {
+        exportedNames += 1;
+      }
+    }
+  }
+  return { debugEntries, localNames, exportedNames, sourcePaths: joinSourcePaths(sourceNames) };
+}
+
+/**
+ * The linker records each original file as two names in a row, its folder (ending in a
+ * slash) and then the file, and closes the file's entries with an empty name.
+ */
+function joinSourcePaths(names) {
+  const paths = new Set();
+  let folder = '';
+  for (const name of names) {
+    if (name.endsWith('/')) {
+      folder = name;
+    } else {
+      if (name) paths.add(name.startsWith('/') ? name : folder + name);
+      folder = '';
+    }
+  }
+  return [...paths];
+}
+
+/** @param {(offset: number, length: number) => Buffer} read stays inside the signature */
+function readSignature(read) {
+  const opening = read(0, 12);
+  if (opening.readUInt32BE(0) !== EMBEDDED_SIGNATURE_MAGIC) throw new Error('not an embedded signature');
+  const blobCount = opening.readUInt32BE(8);
+  if (blobCount > MAX_SIGNATURE_BLOBS) throw new Error('the signature lists implausibly many parts');
+  const index = read(12, blobCount * 8);
+
+  let flags = null;
+  let entitlements = '';
+  for (let at = 0; at < index.length; at += 8) {
+    const slot = index.readUInt32BE(at);
+    const blobOffset = index.readUInt32BE(at + 4);
+    if (slot === CODE_DIRECTORY_SLOT) {
+      const codeDirectory = read(blobOffset, 16);
+      if (codeDirectory.readUInt32BE(0) !== CODE_DIRECTORY_MAGIC) throw new Error('not a code directory');
+      flags = codeDirectory.readUInt32BE(12);
+    } else if (slot === ENTITLEMENTS_SLOT) {
+      const blob = read(blobOffset, 8);
+      if (blob.readUInt32BE(0) !== ENTITLEMENTS_MAGIC) throw new Error('not an entitlements list');
+      const textBytes = Math.min(blob.readUInt32BE(4) - 8, MAX_ENTITLEMENTS_BYTES);
+      entitlements = read(blobOffset + 8, textBytes).toString('utf8');
+    }
+  }
+  if (flags === null) throw new Error('the signature has no code directory');
+  return { flags, entitlements };
+}