waybetter 0.1.0 → 0.6.0

package/cli/privacy.mjs

@@ -0,0 +1,768 @@
+// `waybetter privacy-scan`: the release gate that keeps personal names and account names out of
+// everything an app publishes. It reads a list of forbidden terms (one per line, kept OUTSIDE every
+// repository), always adds this machine's account name and home folder name, and searches files,
+// folders, archives, git-tracked files and (with --history) a whole repository for them.
+//
+//   - Text and binary alike: every file is searched as bytes, in UTF-8, UTF-16LE and UTF-16BE.
+//   - Containers are opened: zip (and .nupkg/.jar), tar, gzip, zstd, ar/.deb, and with an external
+//     tool xz/bzip2 (xz, bzip2 or 7-Zip), NSIS installers, AppImage/squashfs (7-Zip or unsquashfs)
+//     and DMG (zlib images natively, others with 7-Zip). A container that could not be opened is an
+//     error, not a pass.
+//   - A term is never printed. A hit shows the file, line:column or byte offset, and the term as its
+//     first letter plus `***`; the context shown has every term masked the same way.
+//
+// Matching: a term is a hit as a whole word, case-insensitively (letters with diacritics count as
+// their base letter). A term of three characters or fewer is usually also an ordinary word fragment
+// (`max(`, `max-width`), so it is a hit only in a path (`Users\<it>`, `/home/<it>`, `\<it>\`,
+// `/<it>/`, `Users-<it>-`) or as the capitalized standalone word.
+//
+// Reviewed false positives go in an allowlist file inside the repository: lines of
+// `<file glob>: <regular expression>`, where the expression is tested against the hit's context with
+// the term replaced by `<term>` (another hit nearby reads `<other>`). The file never contains a term (the scan refuses one that does).
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, lstatSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import * as zlib from 'node:zlib';
+
+export const TERMS_ENV = 'WAYBETTER_FORBIDDEN_TERMS';
+export const SEVEN_ZIP_ENV = 'WAYBETTER_7Z';
+const CONFIG_FILE = 'waybetter.release.json';
+
+export const PRIVACY_USAGE = `Usage:
+  waybetter privacy-scan <paths...> [--terms <file>] [--allow <file>] [--tracked] [--untracked]
+                         [--history] [--all] [--json] [--if-terms] [--no-auto]
+      Searches files, folders and archives for forbidden terms (personal names, account names) and
+      exits 1 on a hit, 2 when something could not be opened. Terms: --terms, else the file named by
+      ${TERMS_ENV}, else "forbiddenTerms" in ${CONFIG_FILE}; this machine's account name and
+      home folder name are always added (--no-auto: not). A term is never printed.
+      --tracked    each path is inside a git work tree: only the files git tracks (and their names)
+      --untracked  with --tracked: also files git neither tracks nor ignores
+      --history    each path is a repository: every blob, path, commit message, tag and identity
+      --allow      reviewed false positives: lines of "<file glob>: <regex over the context, the
+                   term written <term>>" (default: "privacyAllowlist" in ${CONFIG_FILE})
+      --all        list every hit (default: the first 5 of each file)
+      --if-terms   do nothing, quietly, when no terms file exists (for a contributor's test run)`;
+
+class PrivacyError extends Error {}
+const fail = message => { throw new PrivacyError(message); };
+
+// ---------------------------------------------------------------------------------------------
+// Terms
+
+/** Account names that say nothing about a person: never added automatically. */
+const GENERIC_ACCOUNTS = new Set(['root', 'user', 'users', 'admin', 'administrator', 'runner', 'runneradmin', 'ubuntu', 'build',
+  'builder', 'ci', 'docker', 'node', 'vagrant', 'default', 'nobody', 'home', 'dev', 'developer', 'owner', 'guest', 'test',
+  'app', 'work', 'vscode', 'codespace', 'gitpod', 'circleci', 'jenkins', 'buildkite', 'ec2-user', 'azureuser', 'pi', 'public']);
+
+/** The lines of a terms file: one term each, `#` comments and blank lines skipped. */
+export function parseTerms(text) {
+  return text.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+}
+
+const expandHome = value => value.replace(/^~(?=$|[\\/])/, homedir());
+
+/** The nearest waybetter.release.json's privacy settings (paths made absolute), or {}. */
+export function privacyConfig(cwd) {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    const file = join(dir, CONFIG_FILE);
+    if (existsSync(file)) {
+      let raw;
+      try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch { return {}; }
+      const at = value => (typeof value === 'string' && value.trim() ? resolve(dir, expandHome(value.trim())) : undefined);
+      return { root: dir, forbiddenTerms: at(raw.forbiddenTerms), privacyAllowlist: at(raw.privacyAllowlist) };
+    }
+    if (dirname(dir) === dir) return {};
+  }
+}
+
+/**
+ * The terms to search for: the file's lines plus (unless `auto` is false) this machine's account
+ * name and home folder name. `file` may be missing (then only the automatic ones).
+ * Returns `{ terms: [{ text, rule }], fromFile }`; rule is "word" or "account" (see the header).
+ */
+export function collectTerms({ file, auto = true, extra = [] } = {}) {
+  const seen = new Map();
+  const add = (text, automatic) => {
+    const value = text.trim();
+    const key = value.toLowerCase();
+    if (value.length < 2 || seen.has(key)) return;
+    if (automatic && GENERIC_ACCOUNTS.has(key)) return;
+    seen.set(key, { text: value, rule: [...value].length <= 3 ? 'account' : 'word' });
+  };
+  let fromFile = 0;
+  if (file) {
+    for (const term of parseTerms(readFileSync(file, 'utf8'))) add(term, false);
+    fromFile = seen.size;
+  }
+  for (const term of extra) add(term, false);
+  if (auto) {
+    let user = '';
+    try { user = userInfo().username; } catch { /* no passwd entry */ }
+    add(user, true);
+    add(basename(homedir()), true);
+  }
+  return { terms: [...seen.values()], fromFile };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Matching (on bytes, read as a latin1 string so one regular expression sees every encoding)
+
+const ENCODINGS = ['utf8', 'utf16le', 'utf16be'];
+const FOLDS = { a: 'àáâãäåā', c: 'çćč', e: 'èéêëēęě', g: 'ğ', i: 'ìíîïıī', l: 'ł', n: 'ñńň', o: 'òóôõöøō', r: 'ř', s: 'şšśș', t: 'țť', u: 'ùúûüūů', y: 'ýÿ', z: 'žźż' };
+
+function bytesOf(text, encoding) {
+  if (encoding === 'utf8') return Buffer.from(text, 'utf8');
+  const bytes = Buffer.from(text, 'utf16le');
+  return encoding === 'utf16be' ? bytes.swap16() : bytes;
+}
+const hex = bytes => [...bytes].map(byte => `\\x${byte.toString(16).padStart(2, '0')}`).join('');
+
+/** One character in one encoding; `fold`: either case, and the letter's diacritic forms. */
+function unit(char, encoding, fold) {
+  const forms = new Set([char]);
+  if (fold) {
+    const lower = char.toLowerCase();
+    for (const form of [lower, char.toUpperCase(), ...(FOLDS[lower] ?? '')]) {
+      forms.add(form);
+      forms.add(form.toUpperCase());
+    }
+    if (lower === 'i') forms.add('İ');
+  }
+  const encoded = [...new Set([...forms].filter(form => [...form].length === 1).map(form => hex(bytesOf(form, encoding))))];
+  return encoded.length === 1 ? encoded[0] : `(?:${encoded.join('|')})`;
+}
+const literal = (text, encoding, fold) => [...text].map(char => unit(char, encoding, fold)).join('');
+const oneOf = (texts, encoding, fold) => `(?:${texts.map(text => literal(text, encoding, fold)).join('|')})`;
+
+const ALNUM = 'A-Za-z0-9';
+const BEFORE = { utf8: `(?<![${ALNUM}])`, utf16le: `(?<![${ALNUM}]\\x00)`, utf16be: `(?<!\\x00[${ALNUM}])` };
+const AFTER = { utf8: `(?![${ALNUM}])`, utf16le: `(?![${ALNUM}]\\x00)`, utf16be: `(?!\\x00[${ALNUM}])` };
+const SEPARATORS = ['\\', '/', '%5C', '%2F'];
+
+/**
+ * The alternatives (regular expression sources) that make `term` a hit. `firm` leaves out the one
+ * that three random bytes satisfy (the capitalized word in UTF-8), see `stringLike`.
+ */
+function alternatives(term, firm = false) {
+  const out = [];
+  for (const encoding of ENCODINGS) {
+    const word = literal(term.text, encoding, true);
+    if (term.rule === 'word') {
+      out.push(`${BEFORE[encoding]}${word}${AFTER[encoding]}`);
+      continue;
+    }
+    const sep = oneOf(SEPARATORS, encoding, true);
+    // In a path: between separators, right after a Users/home folder, or in a dash-flattened path.
+    out.push(`(?<=${sep})${word}(?=${sep})`);
+    out.push(`(?<=${oneOf(['Users', 'home'], encoding, true)}${sep}+)${word}${AFTER[encoding]}`);
+    out.push(`(?<=${literal('Users-', encoding, true)})${word}(?=${literal('-', encoding, false)})`);
+    // The capitalized standalone word.
+    const [first, ...rest] = [...term.text];
+    const capitalized = literal(first.toUpperCase(), encoding, false) + literal(rest.join('').toLowerCase(), encoding, false);
+    if (!firm || encoding !== 'utf8') out.push(`${BEFORE[encoding]}${capitalized}${AFTER[encoding]}`);
+  }
+  return out;
+}
+
+/**
+ * Whether the bytes at [start, end) sit in text rather than in compressed or random data: part of a
+ * run of 12 or more printable characters, or a field between two NUL bytes. Megabytes of media hold
+ * every three-letter sequence by chance; they do not hold it inside a sentence.
+ */
+function stringLike(text, start, end) {
+  const printable = code => (code >= 0x20 && code <= 0x7e) || code === 9 || code === 10 || code === 13;
+  let run = end - start;
+  for (let at = start - 1; at >= 0 && run < 12 && printable(text.charCodeAt(at)); at -= 1) run += 1;
+  for (let at = end; at < text.length && run < 12 && printable(text.charCodeAt(at)); at += 1) run += 1;
+  if (run >= 12) return true;
+  return (start === 0 || text.charCodeAt(start - 1) === 0) && (end === text.length || text.charCodeAt(end) === 0);
+}
+
+/** First letter + `***`: the only form of a term that is ever printed. */
+export const maskTerm = text => `${[...text][0]}***`;
+
+/** A matcher over bytes for a term list. */
+export function createMatcher(terms) {
+  const each = terms.map(term => ({ term, mask: maskTerm(term.text), source: alternatives(term).join('|') }));
+  const all = each.length ? new RegExp(each.map(entry => `(?:${entry.source})`).join('|'), 'g') : undefined;
+  const single = each.map(entry => new RegExp(entry.source, 'g'));
+  const firm = each.map(entry => (entry.term.rule === 'account' ? new RegExp(alternatives(entry.term, true).join('|'), 'g') : undefined));
+  const startsAt = (expression, window, at) => {
+    expression.lastIndex = at;
+    return expression.exec(window)?.index === at;
+  };
+
+  /** Every hit in `buffer`: `{ offset, length, mask, encoding }`, in order. `binary`: not a text file. */
+  function find(buffer, binary = false) {
+    if (!all || !buffer.length) return [];
+    const text = buffer.latin1Slice(0, buffer.length);
+    const hits = [];
+    all.lastIndex = 0;
+    let end = -1;
+    for (let match = all.exec(text); match; match = all.exec(text)) {
+      if (match.index >= end) {
+        end = match.index + match[0].length;
+        // Which term: the one whose own expression matches at this offset (seen with its context).
+        const from = Math.max(0, match.index - 64);
+        const window = text.slice(from, end + 8);
+        const which = single.findIndex(expression => startsAt(expression, window, match.index - from));
+        const mask = each[which]?.mask ?? '?***';
+        if (binary && firm[which] && !startsAt(firm[which], window, match.index - from) && !stringLike(text, match.index, end)) continue;
+        // (UTF-16 text matches in one byte order or, a byte earlier, in the other: the label names neither.)
+        hits.push({ offset: match.index, length: match[0].length, mask, encoding: match[0].includes('\x00') ? 'utf16' : 'utf8' });
+      }
+      if (match[0].length === 0) all.lastIndex += 1;
+    }
+    return hits;
+  }
+
+  /** `text` (a latin1 view of bytes) with every hit replaced by `mark` (default: the term's mask). */
+  function redact(text, mark) {
+    let out = text;
+    for (let i = 0; i < single.length; i += 1) {
+      single[i].lastIndex = 0;
+      out = out.replace(single[i], mark ?? each[i].mask);
+    }
+    return out;
+  }
+
+  return { find, redact, size: each.length };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Allowlist
+
+const globToRegExp = glob => new RegExp(`^${glob.split('**').map(part => part.split('*').map(piece =>
+  piece.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('?', '[^/]')).join('[^/]*')).join('.*')}$`);
+
+/** Reads an allowlist file: `<file glob>: <regex>` lines. It must not contain a term itself. */
+export function loadAllowlist(file, matcher) {
+  if (!file || !existsSync(file)) return [];
+  const raw = readFileSync(file);
+  if (matcher.find(raw).length) fail(`${file}: the allowlist must not contain a term (write <term> in its place)`);
+  const rules = [];
+  raw.toString('utf8').split(/\r?\n/).forEach((line, index) => {
+    const text = line.trim();
+    if (!text || text.startsWith('#')) return;
+    const cut = text.indexOf(': ');
+    if (cut <= 0) fail(`${file}:${index + 1}: expected "<file glob>: <regex>"`);
+    let pattern;
+    try { pattern = new RegExp(text.slice(cut + 2).trim()); } catch (error) { fail(`${file}:${index + 1}: ${error.message}`); }
+    rules.push({ glob: globToRegExp(text.slice(0, cut).trim()), pattern, line: index + 1, used: 0 });
+  });
+  return rules;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Containers
+
+const startsWith = (buffer, bytes, at = 0) => buffer.length >= at + bytes.length && bytes.every((byte, i) => buffer[at + i] === byte);
+const ascii = (buffer, from, length) => buffer.latin1Slice(Math.min(from, buffer.length), Math.min(from + length, buffer.length)).replace(/\0.*$/s, '');
+
+function* tarEntries(buffer) {
+  let at = 0;
+  let longName;
+  while (at + 512 <= buffer.length) {
+    const header = buffer.subarray(at, at + 512);
+    if (header.every(byte => byte === 0)) break;
+    const sizeField = header.subarray(124, 136);
+    const size = sizeField[0] & 0x80
+      ? Number(sizeField.subarray(4).readBigUInt64BE(0))
+      : parseInt(ascii(header, 124, 12).trim() || '0', 8) || 0;
+    const type = String.fromCharCode(header[156] || 48);
+    const data = buffer.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'L') { longName = data.toString('utf8').replace(/\0+$/, ''); continue; }
+    if (type === 'x' || type === 'g') {
+      const path = /\d+ path=([^\n]*)\n/.exec(data.toString('utf8'));
+      if (type === 'x' && path) longName = path[1];
+      yield { name: `${longName ?? 'pax'} (pax header)`, data };
+      continue;
+    }
+    const prefix = ascii(header, 345, 155);
+    const name = longName ?? (prefix ? `${prefix}/${ascii(header, 0, 100)}` : ascii(header, 0, 100));
+    longName = undefined;
+    // The header also carries a link target and the owner's user and group names.
+    yield { name, data: type === '0' || type === '7' ? data : undefined, meta: [ascii(header, 157, 100), ascii(header, 265, 32), ascii(header, 297, 32)] };
+  }
+}
+
+function* zipEntries(buffer, note) {
+  const end = buffer.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+  if (end < 0) { note('zip: no central directory'); return; }
+  let count = buffer.readUInt16LE(end + 10);
+  let at = buffer.readUInt32LE(end + 16);
+  if (at === 0xffffffff || count === 0xffff) {
+    const locator = end - 20;
+    if (locator < 0 || !startsWith(buffer, [0x50, 0x4b, 0x06, 0x07], locator)) { note('zip64: no locator'); return; }
+    const record = Number(buffer.readBigUInt64LE(locator + 8));
+    count = Number(buffer.readBigUInt64LE(record + 32));
+    at = Number(buffer.readBigUInt64LE(record + 48));
+  }
+  yield { name: '(zip directory)', data: buffer.subarray(at, end + 22 + buffer.readUInt16LE(end + 20)), leaf: true };
+  for (let i = 0; i < count; i += 1) {
+    if (!startsWith(buffer, [0x50, 0x4b, 0x01, 0x02], at)) { note('zip: broken central directory'); return; }
+    const method = buffer.readUInt16LE(at + 10);
+    let size = buffer.readUInt32LE(at + 20);
+    let full = buffer.readUInt32LE(at + 24);
+    const nameLength = buffer.readUInt16LE(at + 28);
+    const extraLength = buffer.readUInt16LE(at + 30);
+    const commentLength = buffer.readUInt16LE(at + 32);
+    let local = buffer.readUInt32LE(at + 42);
+    const name = buffer.toString('utf8', at + 46, at + 46 + nameLength);
+    for (let extra = at + 46 + nameLength; extra + 4 <= at + 46 + nameLength + extraLength;) {
+      const id = buffer.readUInt16LE(extra);
+      const length = buffer.readUInt16LE(extra + 2);
+      if (id === 1) {
+        let field = extra + 4;
+        if (full === 0xffffffff) { full = Number(buffer.readBigUInt64LE(field)); field += 8; }
+        if (size === 0xffffffff) { size = Number(buffer.readBigUInt64LE(field)); field += 8; }
+        if (local === 0xffffffff) local = Number(buffer.readBigUInt64LE(field));
+      }
+      extra += 4 + length;
+    }
+    at += 46 + nameLength + extraLength + commentLength;
+    if (name.endsWith('/')) continue;
+    const start = local + 30 + buffer.readUInt16LE(local + 26) + buffer.readUInt16LE(local + 28);
+    const packed = buffer.subarray(start, start + size);
+    if (method === 0) yield { name, data: packed };
+    else if (method === 8) {
+      try { yield { name, data: zlib.inflateRawSync(packed) }; } catch (error) { note(`zip: ${name}: ${error.message}`); }
+    } else note(`zip: ${name}: compression method ${method}`);
+  }
+}
+
+function* arEntries(buffer) {
+  let at = 8;
+  while (at + 60 <= buffer.length) {
+    const name = ascii(buffer, at, 16).trim().replace(/\/$/, '');
+    const size = parseInt(ascii(buffer, at + 48, 10).trim(), 10) || 0;
+    yield { name: `${name} (ar header)`, data: buffer.subarray(at, at + 60), leaf: true };
+    yield { name, data: buffer.subarray(at + 60, at + 60 + size) };
+    at += 60 + size + (size % 2);
+  }
+}
+
+/** The decompressed partitions of a DMG whose chunks are raw or zlib; undefined when it has others. */
+function dmgPartitions(buffer) {
+  const trailer = buffer.subarray(buffer.length - 512);
+  const dataFork = Number(trailer.readBigUInt64BE(24));
+  const xmlAt = Number(trailer.readBigUInt64BE(216));
+  const xml = buffer.toString('latin1', xmlAt, xmlAt + Number(trailer.readBigUInt64BE(224)));
+  const blocks = /<key>blkx<\/key>([\s\S]*?)<\/array>/.exec(xml)?.[1] ?? '';
+  const partitions = [];
+  for (const [, encoded] of blocks.matchAll(/<data>([\s\S]*?)<\/data>/g)) {
+    const table = Buffer.from(encoded.replace(/\s+/g, ''), 'base64');
+    if (ascii(table, 0, 4) !== 'mish') continue;
+    const parts = [];
+    for (let i = 0; i < table.readUInt32BE(200); i += 1) {
+      const entry = 204 + i * 40;
+      const type = table.readUInt32BE(entry);
+      const from = dataFork + Number(table.readBigUInt64BE(entry + 24));
+      const packed = buffer.subarray(from, from + Number(table.readBigUInt64BE(entry + 32)));
+      if (type === 1) parts.push(packed);
+      else if (type === 0x80000005) parts.push(zlib.inflateSync(packed));
+      else if (type === 0x80000006 || type === 0x80000007 || type === 0x80000008) return undefined;
+    }
+    partitions.push(Buffer.concat(parts));
+  }
+  return partitions;
+}
+
+/** The offset where an ELF file ends (an AppImage's squashfs payload starts there). */
+function elfEnd(buffer) {
+  if (buffer[4] !== 2 || buffer[5] !== 1) return undefined;
+  return Number(buffer.readBigUInt64LE(0x28)) + buffer.readUInt16LE(0x3a) * buffer.readUInt16LE(0x3c);
+}
+
+/** Whether bytes start like a container this scan would open. */
+const isContainer = head => startsWith(head, [0x1f, 0x8b]) || startsWith(head, [0x50, 0x4b, 0x03, 0x04]) || ascii(head, 257, 5) === 'ustar'
+  || ascii(head, 0, 8) === '!<arch>\n' || startsWith(head, [0x28, 0xb5, 0x2f, 0xfd]) || startsWith(head, [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00])
+  || ascii(head, 0, 4) === 'hsqs' || startsWith(head, [0x4d, 0x5a]) || startsWith(head, [0x7f, 0x45, 0x4c, 0x46]);
+
+let sevenZipPath;
+function sevenZip(env) {
+  if (sevenZipPath !== undefined) return sevenZipPath;
+  const candidates = [env[SEVEN_ZIP_ENV], '7z', '7zz', '7za'];
+  if (process.platform === 'win32') {
+    for (const base of [env.ProgramFiles, env['ProgramFiles(x86)'], env.ProgramW6432]) if (base) candidates.push(join(base, '7-Zip', '7z.exe'));
+  }
+  sevenZipPath = candidates.filter(Boolean).find(file => spawnSync(file, ['i'], { stdio: 'ignore', windowsHide: true }).status === 0) ?? '';
+  return sevenZipPath;
+}
+
+/** Runs a filter (`xz -dc`, `bzip2 -dc`) over bytes; undefined when the tool is missing or fails. */
+function pipe(tool, args, input) {
+  const result = spawnSync(tool, args, { input, maxBuffer: 2 ** 31 - 1, windowsHide: true });
+  return result.status === 0 ? result.stdout : undefined;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The scan
+
+const CHUNK = 64 * 1024 * 1024;
+const OVERLAP = 4096;
+const utf8 = latin1 => Buffer.from(latin1, 'latin1').toString('utf8');
+const printable = text => text.replace(/\0/g, '').replace(/[\x01-\x1f\x7f-\x9f]+/g, ' ').trim();
+
+/**
+ * A scan over any number of inputs. `report()` gives
+ * `{ hits, files: [{ file, count, masks, hits: [{ where, mask, encoding, context }] }], unopened, scanned, bytes }`.
+ */
+export function createScan({ terms, allow = [], env = process.env } = {}) {
+  const matcher = createMatcher(terms);
+  const files = new Map();
+  const unopened = [];
+  let scanned = 0;
+  let bytes = 0;
+
+  function record(name, hit, where, context, allowContext) {
+    const file = safeName(name);
+    for (const rule of allow) {
+      if (rule.glob.test(file) && rule.pattern.test(allowContext)) { rule.used += 1; return; }
+    }
+    let entry = files.get(file);
+    if (!entry) files.set(file, entry = { file, count: 0, masks: {}, hits: [] });
+    entry.count += 1;
+    entry.masks[hit.mask] = (entry.masks[hit.mask] ?? 0) + 1;
+    entry.hits.push({ where, mask: hit.mask, encoding: hit.encoding, context });
+  }
+
+  const safeName = name => printable(utf8(matcher.redact(Buffer.from(name, 'utf8').latin1Slice())));
+
+  /** The allowlist's view of a hit: its surroundings with this hit written <term>, any other <other>. */
+  const marked = (buffer, from, to, hit) => printable(`${matcher.redact(buffer.latin1Slice(from, hit.offset), '<other>')}<term>${matcher.redact(buffer.latin1Slice(hit.offset + hit.length, to), '<other>')}`);
+
+  /** Searches bytes; `base`: their offset inside the file, `skip`: hits below this offset were seen. */
+  function bytesOfFile(file, buffer, { base = 0, skip = 0, textual } = {}) {
+    const isText = textual ?? !buffer.subarray(0, 8000).includes(0);
+    const hits = matcher.find(buffer, !isText);
+    if (!hits.length) return;
+    let line = 1;
+    let lineStart = 0;
+    let cursor = 0;
+    for (const hit of hits) {
+      if (hit.offset < skip) continue;
+      let where;
+      let from;
+      let to;
+      if (isText && hit.encoding === 'utf8') {
+        for (let next = buffer.indexOf(10, cursor); next >= 0 && next < hit.offset; next = buffer.indexOf(10, cursor)) {
+          line += 1;
+          lineStart = next + 1;
+          cursor = next + 1;
+        }
+        where = `${line}:${hit.offset - lineStart + 1}`;
+        const lineEnd = buffer.indexOf(10, hit.offset);
+        from = Math.max(lineStart, hit.offset - 100);
+        to = Math.min(lineEnd < 0 ? buffer.length : lineEnd, hit.offset + hit.length + 100);
+      } else {
+        where = `@0x${(base + hit.offset).toString(16)}`;
+        from = Math.max(0, hit.offset - 160);
+        to = Math.min(buffer.length, hit.offset + hit.length + 160);
+      }
+      const near = buffer.latin1Slice(Math.max(from, hit.offset - 60), Math.min(to, hit.offset + hit.length + 60));
+      record(file, hit, where, printable(matcher.redact(near)), marked(buffer, from, to, hit));
+    }
+  }
+
+  /** A name (a path inside an archive, a git path, an identity) searched as text. */
+  function text(file, value, label = 'name') {
+    const buffer = Buffer.from(value, 'utf8');
+    for (const hit of matcher.find(buffer)) {
+      const shown = printable(utf8(matcher.redact(buffer.latin1Slice(0, buffer.length))));
+      record(file, hit, label, shown.slice(0, 200), marked(buffer, 0, buffer.length, hit));
+    }
+  }
+
+  /** Extracts with 7-Zip (or unsquashfs) into a temporary folder, scans it, removes it. */
+  function extracted(file, buffer, depth, { type, tool = 'container' } = {}) {
+    const dir = mkdtempSync(join(tmpdir(), 'wb-privacy-'));
+    try {
+      const source = join(dir, 'in');
+      const out = join(dir, 'out');
+      writeFileSync(source, buffer);
+      const seven = sevenZip(env);
+      let done = false;
+      if (seven) {
+        done = spawnSync(seven, ['x', '-y', '-bd', `-o${out}`, ...(type ? [`-t${type}`] : []), source], { stdio: 'ignore', windowsHide: true }).status === 0;
+      }
+      if (!done && type === 'SquashFS') {
+        done = spawnSync('unsquashfs', ['-no-progress', '-d', out, source], { stdio: 'ignore' }).status === 0;
+      }
+      if (!done || !existsSync(out)) {
+        unopened.push(`${file}: ${tool} not opened (install 7-Zip, or set ${SEVEN_ZIP_ENV})`);
+        return;
+      }
+      folder(out, `${file}!`, depth + 1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
+  /** One file's bytes: searched, and opened when they are a container. */
+  function content(file, buffer, depth = 0) {
+    const note = message => unopened.push(`${file}: ${message}`);
+    const inner = (entries) => {
+      for (const entry of entries) {
+        const name = `${file}!/${safeName(entry.name)}`;
+        text(name, entry.name);
+        for (const value of entry.meta ?? []) text(`${name} (tar header)`, value, 'owner');
+        if (entry.leaf) bytesOfFile(name, entry.data, { textual: false });
+        else if (entry.data) content(name, entry.data, depth + 1);
+      }
+    };
+    const filtered = (data, what) => {
+      if (data) content(file, data, depth + 1);
+      else note(`${what} not opened`);
+    };
+    if (depth === 0) { scanned += 1; bytes += buffer.length; }
+    if (depth > 8) { bytesOfFile(file, buffer); return; }
+    try {
+      if (startsWith(buffer, [0x1f, 0x8b])) {
+        bytesOfFile(`${file} (gzip header)`, buffer.subarray(0, 512), { textual: false });
+        let data;
+        try { data = zlib.gunzipSync(buffer); } catch (error) { note(`gzip: ${error.message}`); }
+        if (data) content(file, data, depth + 1);
+      } else if (startsWith(buffer, [0x50, 0x4b, 0x03, 0x04])) {
+        inner(zipEntries(buffer, note));
+      } else if (buffer.length > 512 && ascii(buffer, 257, 5) === 'ustar') {
+        inner(tarEntries(buffer));
+      } else if (ascii(buffer, 0, 8) === '!<arch>\n') {
+        inner(arEntries(buffer));
+      } else if (startsWith(buffer, [0x28, 0xb5, 0x2f, 0xfd])) {
+        let data;
+        try { data = zlib.zstdDecompressSync?.(buffer); } catch { /* reported below */ }
+        filtered(data ?? pipe('zstd', ['-dc'], buffer), 'zstd');
+      } else if (startsWith(buffer, [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00])) {
+        filtered(pipe('xz', ['-dc'], buffer), 'xz (install xz)');
+      } else if (startsWith(buffer, [0x42, 0x5a, 0x68]) && buffer[3] >= 0x31 && buffer[3] <= 0x39 && startsWith(buffer, [0x31, 0x41, 0x59, 0x26, 0x53, 0x59], 4)) {
+        filtered(pipe('bzip2', ['-dc'], buffer), 'bzip2 (install bzip2)');
+      } else if (ascii(buffer, 0, 4) === 'hsqs') {
+        extracted(file, buffer, depth, { type: 'SquashFS', tool: 'squashfs' });
+      } else if (buffer.length > 512 && ascii(buffer, buffer.length - 512, 4) === 'koly') {
+        const partitions = dmgPartitions(buffer);
+        if (partitions) partitions.forEach((data, i) => bytesOfFile(`${file}!/partition ${i}`, data, { textual: false }));
+        else extracted(file, buffer, depth, { tool: 'dmg' });
+      } else if (startsWith(buffer, [0x7f, 0x45, 0x4c, 0x46]) && ascii(buffer, 8, 2) === 'AI' && buffer[10] === 2) {
+        bytesOfFile(file, buffer);
+        const end = elfEnd(buffer);
+        if (end && ascii(buffer, end, 4) === 'hsqs') extracted(file, buffer.subarray(end), depth, { type: 'SquashFS', tool: 'AppImage' });
+        else note('AppImage: payload not found');
+      } else if (startsWith(buffer, [0x4d, 0x5a]) && buffer.includes('NullsoftInst')) {
+        bytesOfFile(file, buffer);
+        extracted(file, buffer, depth, { type: 'Nsis', tool: 'NSIS installer' });
+      } else {
+        bytesOfFile(file, buffer);
+      }
+    } catch (error) {
+      if (error instanceof PrivacyError) throw error;
+      note(`not opened (${error.message})`);
+      bytesOfFile(file, buffer);
+    }
+  }
+
+  /** A file on disk under the name `file`. Large plain files are read in overlapping chunks. */
+  function diskFile(path, file, depth = 0) {
+    const size = lstatSync(path).size;
+    if (size <= CHUNK * 4) { content(file, readFileSync(path), depth); return; }
+    scanned += 1;
+    bytes += size;
+    const handle = openSync(path, 'r');
+    const buffer = Buffer.alloc(CHUNK + OVERLAP);
+    let container = false;
+    try {
+      container = isContainer(buffer.subarray(0, readSync(handle, buffer, 0, 512, 0)));
+      for (let at = 0; at < size; at += CHUNK) {
+        const from = Math.max(0, at - OVERLAP);
+        const read = readSync(handle, buffer, 0, Math.min(CHUNK + (at - from), size - from), from);
+        bytesOfFile(file, buffer.subarray(0, read), { base: from, skip: at - from, textual: false });
+      }
+    } finally {
+      closeSync(handle);
+    }
+    if (container) unopened.push(`${file}: a container larger than ${(CHUNK * 4) / 2 ** 20} MB, searched as plain bytes only`);
+  }
+
+  function folder(path, prefix, depth = 0) {
+    for (const entry of readdirSync(path, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      const full = join(path, entry.name);
+      const file = `${prefix}/${safeName(entry.name)}`;
+      text(file, entry.name);
+      if (entry.isDirectory()) { if (entry.name !== '.git') folder(full, file, depth); }
+      else if (entry.isFile()) diskFile(full, file, depth);
+    }
+  }
+
+  /** A file, folder or archive, shown relative to `cwd`. */
+  function path(target, cwd = process.cwd()) {
+    const full = resolve(cwd, target);
+    if (!existsSync(full)) fail(`not found: ${safeName(target)}`);
+    // Outside the working directory only the name is shown (the folders above it are not published).
+    const inside = relative(cwd, full);
+    const outside = inside.startsWith('..') || resolve(cwd, inside) !== full;
+    const shown = safeName(outside ? basename(full) : inside.replaceAll('\\', '/') || '.');
+    text(shown, outside ? basename(full) : inside);
+    if (lstatSync(full).isDirectory()) folder(full, shown === '.' ? '' : shown);
+    else diskFile(full, shown);
+  }
+
+  const git = (repo, args, options = {}) => {
+    const result = spawnSync('git', ['-C', repo, ...args], { maxBuffer: 2 ** 31 - 1, windowsHide: true, ...options });
+    if (result.status !== 0) fail(`git ${args[0]} failed in ${safeName(repo)}: ${String(result.stderr ?? '').trim().split('\n')[0]}`);
+    return result.stdout;
+  };
+
+  /** The files git tracks under `target` (and, with `untracked`, the ones it neither tracks nor ignores). */
+  function tracked(target, { cwd = process.cwd(), untracked = false } = {}) {
+    const dir = resolve(cwd, target);
+    const list = git(dir, ['ls-files', '-z', ...(untracked ? ['--cached', '--others', '--exclude-standard'] : [])]).toString('utf8').split('\0').filter(Boolean);
+    for (const name of [...new Set(list)]) {
+      const full = join(dir, name);
+      const shown = safeName(relative(cwd, full).replaceAll('\\', '/'));
+      text(shown, name);
+      let stat;
+      try { stat = lstatSync(full); } catch { continue; } // deleted in the work tree
+      if (stat.isFile()) diskFile(full, shown);
+    }
+  }
+
+  /** Everything a repository would publish: blobs, paths, commit and tag messages, identities, ref names. */
+  function history(target, { cwd = process.cwd() } = {}) {
+    const dir = resolve(cwd, target);
+    const label = safeName(relative(cwd, dir).replaceAll('\\', '/') || '.');
+    const names = new Map();
+    for (const line of git(dir, ['rev-list', '--all', '--objects']).toString('utf8').split('\n')) {
+      const space = line.indexOf(' ');
+      if (space > 0 && line.length > space + 1 && !names.has(line.slice(0, space))) names.set(line.slice(0, space), line.slice(space + 1));
+    }
+    for (const [, name] of names) text(`${label} history: ${safeName(name)}`, name, 'path');
+    const ids = [...names.keys()];
+    const kinds = git(dir, ['cat-file', '--batch-check=%(objectname) %(objecttype) %(objectsize)'], { input: `${ids.join('\n')}\n` }).toString('utf8').split('\n');
+    const blobs = kinds.map(line => line.split(' ')).filter(parts => parts[1] === 'blob');
+    // In batches, so a repository with large media never sits in memory whole.
+    for (let i = 0; i < blobs.length;) {
+      const batch = [];
+      for (let size = 0; i < blobs.length && (size < CHUNK * 4 || !batch.length); i += 1) {
+        batch.push(blobs[i]);
+        size += Number(blobs[i][2]);
+      }
+      const out = git(dir, ['cat-file', '--batch'], { input: `${batch.map(parts => parts[0]).join('\n')}\n` });
+      let at = 0;
+      for (const [id, , size] of batch) {
+        at = out.indexOf(10, at) + 1;
+        content(`${label} history: ${safeName(names.get(id))} (blob ${id.slice(0, 10)})`, out.subarray(at, at + Number(size)));
+        at += Number(size) + 1;
+      }
+    }
+    const log = git(dir, ['log', '--all', '--format=%H%x00%an%x00%ae%x00%cn%x00%ce%x00%B%x01']).toString('utf8');
+    for (const entry of log.split('\x01')) {
+      const [id, author, authorMail, committer, committerMail, message] = entry.replace(/^\n/, '').split('\0');
+      if (!id) continue;
+      const commit = `${label} history: commit ${id.slice(0, 10)}`;
+      text(commit, `${author} <${authorMail}>`, 'author');
+      text(commit, `${committer} <${committerMail}>`, 'committer');
+      text(commit, message ?? '', 'message');
+    }
+    const refs = git(dir, ['for-each-ref', '--format=%(refname)%00%(taggername) %(taggeremail)%00%(contents)%01']).toString('utf8');
+    for (const entry of refs.split('\x01')) {
+      const [ref, tagger, message] = entry.replace(/^\n/, '').split('\0');
+      if (!ref) continue;
+      text(`${label} history: ${safeName(ref)}`, ref, 'ref');
+      if (tagger?.trim()) text(`${label} history: ${safeName(ref)}`, tagger, 'tagger');
+      if (ref.startsWith('refs/tags/') && message) text(`${label} history: ${safeName(ref)}`, message, 'tag message');
+    }
+  }
+
+  function report() {
+    const list = [...files.values()];
+    return { hits: list.reduce((sum, entry) => sum + entry.count, 0), files: list, unopened: [...unopened], scanned, bytes, terms: matcher.size };
+  }
+
+  return { path, tracked, history, content, text, report };
+}
+
+/** The report as lines (hits masked). `all`: every hit instead of the first five of each file. */
+export function formatReport(report, { all = false, label = 'privacy-scan' } = {}) {
+  const lines = [];
+  for (const entry of report.files) {
+    const masks = Object.entries(entry.masks).map(([mask, count]) => `${mask} x${count}`).join(', ');
+    lines.push(`${entry.file}: ${entry.count} ${entry.count === 1 ? 'hit' : 'hits'} (${masks})`);
+    for (const hit of all ? entry.hits : entry.hits.slice(0, 5)) {
+      lines.push(`    ${hit.where}  ${hit.mask}${hit.encoding === 'utf8' ? '' : ` [${hit.encoding}]`}  ${hit.context.slice(0, 160)}`);
+    }
+    if (!all && entry.hits.length > 5) lines.push(`    ... ${entry.hits.length - 5} more (--all)`);
+  }
+  for (const item of report.unopened) lines.push(`not opened: ${item}`);
+  const size = report.bytes >= 2 ** 20 ? `${(report.bytes / 2 ** 20).toFixed(1)} MB` : `${report.bytes} bytes`;
+  lines.push(`${label}: ${report.hits} ${report.hits === 1 ? 'hit' : 'hits'} in ${report.files.length} ${report.files.length === 1 ? 'file' : 'files'}`
+    + `${report.unopened.length ? `, ${report.unopened.length} not opened` : ''} (${report.scanned} files, ${size}, ${report.terms} terms)`);
+  return lines;
+}
+
+/**
+ * Scans artifacts and throws when one holds a term or could not be opened (the release gate).
+ * `paths`: files or folders; `terms`/`allowlist`: files (both optional).
+ */
+export function assertClean(paths, { terms, allowlist, cwd = process.cwd(), env = process.env, log = console.log, label = 'privacy-scan' } = {}) {
+  const file = env[TERMS_ENV] || terms;
+  if (file && !existsSync(file)) fail(`terms file not found (${TERMS_ENV} or "forbiddenTerms"): fix the path, it is the release gate`);
+  const collected = collectTerms({ file });
+  const matcher = createMatcher(collected.terms);
+  const scan = createScan({ terms: collected.terms, allow: loadAllowlist(allowlist, matcher), env });
+  for (const target of paths) scan.path(target, cwd);
+  const report = scan.report();
+  for (const line of formatReport(report, { label })) log(line);
+  if (report.hits) fail(`${report.hits} forbidden ${report.hits === 1 ? 'term' : 'terms'} in the artifacts: nothing was released`);
+  if (report.unopened.length) fail(`${report.unopened.length} ${report.unopened.length === 1 ? 'container' : 'containers'} could not be opened, so the artifacts are not proven clean`);
+  return report;
+}
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  if (i < 0) return undefined;
+  const [, value] = args.splice(i, 2);
+  if (value === undefined) fail(`${name} needs a value`);
+  return value;
+}
+function toggle(args, name) {
+  const i = args.indexOf(name);
+  if (i >= 0) args.splice(i, 1);
+  return i >= 0;
+}
+
+/** `waybetter privacy-scan ...`; returns the exit code (0 clean, 1 hits, 2 something not opened). */
+export function privacyCommand(argv, { cwd = process.cwd(), env = process.env, log = console.log } = {}) {
+  const args = [...argv];
+  if (toggle(args, '--help') || toggle(args, '-h')) { log(PRIVACY_USAGE); return 0; }
+  const config = privacyConfig(cwd);
+  const explicit = flag(args, '--terms');
+  const allowFile = flag(args, '--allow');
+  const options = Object.fromEntries(['--tracked', '--untracked', '--history', '--all', '--json', '--if-terms', '--no-auto'].map(name => [name, toggle(args, name)]));
+  const unknown = args.find(arg => arg.startsWith('--'));
+  if (unknown) fail(`unknown option ${unknown}`);
+
+  const candidate = explicit ? resolve(cwd, expandHome(explicit)) : env[TERMS_ENV] ? resolve(cwd, expandHome(env[TERMS_ENV])) : config.forbiddenTerms;
+  const file = candidate && existsSync(candidate) ? candidate : undefined;
+  if (!file && options['--if-terms']) return 0;
+  if (explicit && !file) fail('--terms: file not found');
+  const collected = collectTerms({ file, auto: !options['--no-auto'] });
+  if (!collected.terms.length) fail('no terms: pass --terms <file> or set ' + TERMS_ENV);
+  const matcher = createMatcher(collected.terms);
+  const allow = loadAllowlist(allowFile ? resolve(cwd, allowFile) : config.privacyAllowlist, matcher);
+  const scan = createScan({ terms: collected.terms, allow, env });
+  const targets = args.length ? args : ['.'];
+  for (const target of targets) {
+    if (options['--history']) scan.history(target, { cwd });
+    if (options['--tracked']) scan.tracked(target, { cwd, untracked: options['--untracked'] });
+    if (!options['--history'] && !options['--tracked']) scan.path(target, cwd);
+  }
+  const report = scan.report();
+  if (options['--json']) log(JSON.stringify(report, null, 2));
+  else {
+    for (const line of formatReport(report, { all: options['--all'] })) log(line);
+    if (!file) log(`privacy-scan: no terms file, only this machine's account name was searched (--terms, ${TERMS_ENV})`);
+  }
+  return report.hits ? 1 : report.unopened.length ? 2 : 0;
+}