@intincrab/updiff 0.1.1 → 0.2.0

package/dist/installer.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, open, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { run } from "./exec.js";
+import { TOOL_VERSION } from "./version.js";
+export const USER_AGENT = `updiff/${TOOL_VERSION} (+https://github.com/intincrab/updiff)`;
+/**
+ * Some vendors serve their Homebrew download URL only to Homebrew clients (Warp
+ * answers 404 otherwise). The ledger fetches exactly what a cask points to, so it
+ * retries those with a User-Agent that says it is Homebrew-compatible and still names itself.
+ */
+export const HOMEBREW_COMPAT_USER_AGENT = `Homebrew/4.6 (compatible; updiff/${TOOL_VERSION}; +https://github.com/intincrab/updiff)`;
+/**
+ * Downloads `url` to `dest`, hashing as it goes. Fails above `maxBytes` and, when
+ * `expectedSha256` is given, on a checksum mismatch.
+ */
+export async function download(url, dest, options) {
+    const get = (userAgent) => fetch(url, { redirect: 'follow', headers: { 'user-agent': userAgent }, signal: AbortSignal.timeout(30 * 60_000) });
+    let res = await get(USER_AGENT);
+    if (res.status === 403 || res.status === 404) {
+        await res.body?.cancel();
+        res = await get(HOMEBREW_COMPAT_USER_AGENT);
+    }
+    if (!res.ok || !res.body)
+        throw new Error(`Download failed: HTTP ${res.status} for ${url}`);
+    const declared = Number(res.headers.get('content-length') ?? 0);
+    if (declared > options.maxBytes)
+        throw new Error(`Download is ${declared} bytes, over the ${options.maxBytes}-byte limit`);
+    const hash = createHash('sha256');
+    let bytes = 0;
+    const meter = new Transform({
+        transform(chunk, _enc, cb) {
+            bytes += chunk.length;
+            if (bytes > options.maxBytes) {
+                cb(new Error(`Download exceeded the ${options.maxBytes}-byte limit`));
+                return;
+            }
+            hash.update(chunk);
+            cb(null, chunk);
+        },
+    });
+    await pipeline(Readable.fromWeb(res.body), meter, createWriteStream(dest));
+    const sha256 = hash.digest('hex');
+    if (options.expectedSha256 && options.expectedSha256 !== sha256) {
+        throw new Error(`Checksum mismatch: expected ${options.expectedSha256}, got ${sha256}`);
+    }
+    return { file: dest, bytes, sha256 };
+}
+/**
+ * Identifies a downloaded installer. A disk image (UDIF) is recognised by the `koly`
+ * block in its last 512 bytes; its first bytes are compressed data and can look like
+ * bzip2 ("BZh", UDBZ images such as Slack's and Chrome's) or anything else.
+ */
+export function detectContainer(head, tail) {
+    if (tail && tail.length >= 512 && tail.toString('latin1', tail.length - 512, tail.length - 508) === 'koly')
+        return 'dmg';
+    if (head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b && head[2] === 0x03 && head[3] === 0x04)
+        return 'zip';
+    if (head.length >= 4 && head.toString('latin1', 0, 4) === 'xar!')
+        return 'pkg';
+    if (head.length >= 2 && head[0] === 0x1f && head[1] === 0x8b)
+        return 'tar';
+    if (head.length >= 3 && head.toString('latin1', 0, 3) === 'BZh')
+        return 'tar';
+    if (head.length >= 6 && head[0] === 0xfd && head.toString('latin1', 1, 5) === '7zXZ')
+        return 'tar';
+    if (head.length >= 262 && head.toString('latin1', 257, 262) === 'ustar')
+        return 'tar';
+    return 'dmg';
+}
+async function readEnds(file) {
+    const fh = await open(file, 'r');
+    try {
+        const size = (await fh.stat()).size;
+        const head = Buffer.alloc(512);
+        const { bytesRead } = await fh.read(head, 0, 512, 0);
+        const tail = Buffer.alloc(Math.min(512, size));
+        await fh.read(tail, 0, tail.length, size - tail.length);
+        return { head: head.subarray(0, bytesRead), tail };
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Finds app bundles under `root` without descending into them. */
+export async function findApps(root, maxDepth = 8) {
+    const found = [];
+    const walk = async (dir, depth) => {
+        let dirents;
+        try {
+            dirents = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const d of dirents) {
+            if (!d.isDirectory() || d.isSymbolicLink())
+                continue;
+            const p = join(dir, d.name);
+            if (d.name.endsWith('.app'))
+                found.push(p);
+            else if (depth < maxDepth)
+                await walk(p, depth + 1);
+        }
+    };
+    await walk(root, 0);
+    return found.sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b));
+}
+/**
+ * Unpacks an installer into `workDir` and returns the app bundle it holds. Nothing in
+ * the installer is run: disk images are mounted read-only, packages are expanded with
+ * `pkgutil --expand-full` (scripts are written out, not executed).
+ */
+export async function extractApp(file, workDir, appNames) {
+    const { head, tail } = await readEnds(file);
+    let kind = detectContainer(head, tail);
+    const out = join(workDir, 'contents');
+    await mkdir(workDir, { recursive: true });
+    let mountPoint;
+    const cleanup = async () => {
+        if (mountPoint) {
+            const res = await run('/usr/bin/hdiutil', ['detach', mountPoint, '-quiet']);
+            if (res.code !== 0)
+                await run('/usr/bin/hdiutil', ['detach', mountPoint, '-force', '-quiet']);
+        }
+        await rm(workDir, { recursive: true, force: true });
+    };
+    try {
+        const mount = async () => {
+            const point = join(workDir, 'mnt');
+            await mkdir(point, { recursive: true });
+            // "Y" accepts a licence agreement if the image shows one.
+            const r = await run('/usr/bin/hdiutil', ['attach', file, '-readonly', '-nobrowse', '-noautoopen', '-noverify', '-mountpoint', point], 10 * 60_000, 'Y\n');
+            if (r.code === 0)
+                mountPoint = point;
+            return r;
+        };
+        let res;
+        if (kind === 'zip') {
+            await mkdir(out);
+            res = await run('/usr/bin/ditto', ['-x', '-k', file, out], 15 * 60_000);
+        }
+        else if (kind === 'pkg') {
+            res = await run('/usr/sbin/pkgutil', ['--expand-full', file, out], 15 * 60_000);
+        }
+        else if (kind === 'tar') {
+            await mkdir(out);
+            res = await run('/usr/bin/tar', ['-xf', file, '-C', out], 15 * 60_000);
+        }
+        else {
+            res = await mount();
+        }
+        if (res.code !== 0 && (kind === 'zip' || kind === 'tar')) {
+            // A guess from the first bytes can be wrong; a disk image is the usual other answer.
+            const second = await mount();
+            if (second.code === 0) {
+                kind = 'dmg';
+                res = second;
+            }
+        }
+        if (res.code !== 0)
+            throw new Error(`Could not unpack the ${kind}: ${(res.stderr || res.stdout).trim().split('\n').pop()}`);
+        const apps = await findApps(mountPoint ?? out);
+        const wanted = appNames.map((n) => n.toLowerCase());
+        const appPath = apps.find((p) => wanted.includes(p.slice(p.lastIndexOf('/') + 1).toLowerCase())) ?? apps[0];
+        if (!appPath)
+            throw new Error(`No .app bundle found in the ${kind}`);
+        return { appPath, kind, cleanup };
+    }
+    catch (err) {
+        await cleanup();
+        throw err;
+    }
+}

package/dist/macho.js

@@ -0,0 +1,35 @@
+const MH_MAGIC = 0xfeedface;
+const MH_MAGIC_64 = 0xfeedfacf;
+const LC_ENCRYPTION_INFO = 0x21;
+const LC_ENCRYPTION_INFO_64 = 0x2c;
+/**
+ * Whether a thin Mach-O image is FairPlay-encrypted, from its load commands
+ * (LC_ENCRYPTION_INFO / _64 with a non-zero cryptid). `head` must hold the header
+ * and the load commands; 64 KB covers real binaries. Returns undefined when `head`
+ * isn't a little-endian Mach-O.
+ *
+ * Mac App Store apps for macOS are not encrypted; iPhone and iPad apps that run on
+ * Apple silicon Macs are, and their strings can't be read.
+ */
+export function isEncryptedMachO(head) {
+    if (head.length < 28)
+        return undefined;
+    const magic = head.readUInt32LE(0);
+    if (magic !== MH_MAGIC && magic !== MH_MAGIC_64)
+        return undefined;
+    const ncmds = head.readUInt32LE(16);
+    let offset = magic === MH_MAGIC_64 ? 32 : 28;
+    for (let i = 0; i < ncmds && offset + 8 <= head.length; i++) {
+        const cmd = head.readUInt32LE(offset);
+        const size = head.readUInt32LE(offset + 4);
+        if ((cmd === LC_ENCRYPTION_INFO || cmd === LC_ENCRYPTION_INFO_64) && offset + 20 <= head.length) {
+            // struct encryption_info_command { cmd, cmdsize, cryptoff, cryptsize, cryptid }
+            if (head.readUInt32LE(offset + 16) !== 0)
+                return true;
+        }
+        if (size < 8)
+            break;
+        offset += size;
+    }
+    return false;
+}

package/dist/pkg-report.js

@@ -0,0 +1,211 @@
+import { basename } from 'node:path';
+import { CATEGORY_ORDER, SEVERITY_ORDER } from "./diff.js";
+import { formatBytes, lineDiff } from "./util.js";
+const plain = { bold: (s) => s, dim: (s) => s, warn: (s) => s };
+const ansi = {
+    bold: (s) => `\x1b[1m${s}\x1b[22m`,
+    dim: (s) => `\x1b[2m${s}\x1b[22m`,
+    warn: (s) => `\x1b[33m${s}\x1b[39m`,
+};
+function describeLaunch(i) {
+    const bits = [i.label ? `label ${i.label}` : undefined, i.program ? `runs ${i.program}` : undefined, i.runAtLoad ? (i.kind === 'daemon' ? 'starts at boot' : 'starts at login') : undefined, i.keepAlive ? 'kept alive' : undefined];
+    return bits.filter(Boolean).join(' · ');
+}
+function scriptHeader(s) {
+    const what = s.binary ? 'binary' : `${s.interpreter ?? 'no interpreter line'}, ${s.lines} line${s.lines === 1 ? '' : 's'}`;
+    return `${s.name} (${what}, ${formatBytes(s.bytes)})`;
+}
+/** What an installer package would do, for reading before running it. */
+export function renderPkg(r, options = {}) {
+    const st = options.color ? ansi : plain;
+    const maxLines = options.full ? Infinity : (options.maxScriptLines ?? 40);
+    const lines = [];
+    const title = r.distribution?.title ?? r.components[0]?.id ?? basename(r.file);
+    lines.push(st.bold(`${title}  ${basename(r.file)}`), st.dim(`sha256 ${r.sha256} · ${formatBytes(r.bytes)}`), '');
+    const sig = r.signature;
+    lines.push(`Signature      ${sig.signer ?? sig.status}${sig.notarized ? ' · notarized' : ''}`);
+    lines.push(`Gatekeeper     ${r.gatekeeper.assessment}${r.gatekeeper.source ? ` (${r.gatekeeper.source})` : ''}`);
+    const root = r.components.some((c) => c.auth === 'root');
+    lines.push(`Runs as        ${root ? st.warn('root: the installer asks for an administrator password') : 'the current user'}`);
+    if (r.distribution) {
+        const js = r.distribution.scripts.length + r.distribution.checks.length;
+        lines.push(`Installer UI   ${js ? st.warn(`${js} JavaScript check${js === 1 ? '' : 's'} run when the installer opens`) : 'no JavaScript'}`);
+    }
+    for (const c of r.components) {
+        lines.push('', st.bold(`Component ${c.id ?? '(unnamed)'}${c.version ? ` ${c.version}` : ''}`) + st.dim(`  → ${c.installLocation} · ${c.files} file${c.files === 1 ? '' : 's'}, ${formatBytes(c.bytes)}`));
+        for (const a of c.apps)
+            lines.push(`  App          ${a.path}${a.bundleId ? ` (${a.bundleId}${a.version ? ` ${a.version}` : ''}${a.teamId ? `, team ${a.teamId}` : ''})` : ''}`);
+        for (const l of c.launchItems)
+            lines.push(st.warn(`  Launch ${l.kind.padEnd(6)} ${l.path}`) + (describeLaunch(l) ? st.dim(`  ${describeLaunch(l)}`) : ''));
+        for (const p of c.systemLevel)
+            lines.push(st.warn(`  System level ${p}`));
+        if (c.outsideApplications.length) {
+            lines.push(`  Outside /Applications: ${c.outsideApplications.slice(0, 12).join(', ')}${c.outsideApplications.length > 12 ? ` and ${c.outsideApplications.length - 12} more` : ''}`);
+        }
+        if (!c.scripts.length)
+            lines.push(st.dim('  No install scripts.'));
+        for (const s of c.scripts) {
+            lines.push('', `  ${s.hook ? st.warn(`Runs ${s.name === 'preinstall' ? 'before' : 'after'} installing${c.auth === 'root' ? ' as root' : ''}:`) : 'Helper file:'} ${scriptHeader(s)}`);
+            if (s.content === undefined) {
+                lines.push(st.dim(s.binary ? '    (binary: not shown)' : '    (too large to show)'));
+                continue;
+            }
+            const body = s.content.replace(/\n$/, '').split('\n');
+            for (const l of body.slice(0, maxLines))
+                lines.push(st.dim('    │ ') + l);
+            if (body.length > maxLines)
+                lines.push(st.dim(`    │ … ${body.length - maxLines} more lines (use --full)`));
+        }
+    }
+    if (r.distribution && (r.distribution.scripts.length || r.distribution.checks.length)) {
+        lines.push('', st.bold('Installer JavaScript'));
+        for (const check of r.distribution.checks)
+            lines.push(`  ${check}`);
+        for (const js of r.distribution.scripts) {
+            const body = js.split('\n');
+            for (const l of body.slice(0, maxLines))
+                lines.push(st.dim('    │ ') + l);
+            if (body.length > maxLines)
+                lines.push(st.dim(`    │ … ${body.length - maxLines} more lines (use --full)`));
+        }
+    }
+    lines.push('', st.dim('Nothing was installed or run: the package was only unpacked.'));
+    return lines.join('\n') + '\n';
+}
+export function renderPkgMarkdown(r) {
+    const out = [`# ${r.distribution?.title ?? r.components[0]?.id ?? basename(r.file)}`, '', `\`${basename(r.file)}\` · sha256 \`${r.sha256}\` · ${formatBytes(r.bytes)}`, ''];
+    out.push(`- Signature: ${r.signature.signer ?? r.signature.status}${r.signature.notarized ? ' (notarized)' : ''}`);
+    out.push(`- Gatekeeper: ${r.gatekeeper.assessment}${r.gatekeeper.source ? ` (${r.gatekeeper.source})` : ''}`);
+    out.push(`- Runs as: ${r.components.some((c) => c.auth === 'root') ? 'root' : 'the current user'}`, '');
+    for (const c of r.components) {
+        out.push(`## ${c.id ?? 'Component'} ${c.version ?? ''}`, '', `Installs to \`${c.installLocation}\` (${c.files} files, ${formatBytes(c.bytes)}).`, '');
+        for (const a of c.apps)
+            out.push(`- App \`${a.path}\` ${a.bundleId ?? ''} ${a.version ?? ''}`);
+        for (const l of c.launchItems)
+            out.push(`- Launch ${l.kind} \`${l.path}\`: ${describeLaunch(l)}`);
+        for (const p of c.systemLevel)
+            out.push(`- System level \`${p}\``);
+        if (c.outsideApplications.length)
+            out.push(`- Outside /Applications: ${c.outsideApplications.map((p) => `\`${p}\``).join(', ')}`);
+        for (const s of c.scripts) {
+            out.push('', `### ${s.hook ? 'Script' : 'Helper'}: ${scriptHeader(s)}`, '');
+            if (s.content !== undefined)
+                out.push('```sh', s.content.replace(/\n$/, ''), '```');
+        }
+        out.push('');
+    }
+    return out.join('\n') + '\n';
+}
+function teamOf(signer) {
+    return /\(([A-Z0-9]{10})\)\s*$/.exec(signer ?? '')?.[1];
+}
+/** What changed between two versions of an installer package. */
+export function diffPkgs(a, b) {
+    const f = [];
+    const at = (where) => [where];
+    if (a.signature.notarized && !b.signature.notarized)
+        f.push({ severity: 'high', category: 'signing', change: 'removed', title: 'Package is no longer notarized' });
+    if (teamOf(a.signature.signer) && teamOf(b.signature.signer) && teamOf(a.signature.signer) !== teamOf(b.signature.signer)) {
+        f.push({ severity: 'high', category: 'signing', change: 'changed', title: 'Package is signed by a different developer', detail: `${a.signature.signer} → ${b.signature.signer}` });
+    }
+    else if (a.signature.signer && !b.signature.signer) {
+        f.push({ severity: 'high', category: 'signing', change: 'removed', title: 'Package is no longer signed', detail: b.signature.status });
+    }
+    if (a.gatekeeper.assessment === 'accepted' && b.gatekeeper.assessment === 'rejected') {
+        f.push({ severity: 'high', category: 'signing', change: 'changed', title: 'Gatekeeper now rejects the package', detail: b.gatekeeper.source });
+    }
+    const rootA = a.components.some((c) => c.auth === 'root');
+    const rootB = b.components.some((c) => c.auth === 'root');
+    if (!rootA && rootB)
+        f.push({ severity: 'high', category: 'install', change: 'added', title: 'Now installs as root (asks for an administrator password)' });
+    const byId = new Map(a.components.map((c) => [c.id ?? c.installLocation, c]));
+    for (const cb of b.components) {
+        const key = cb.id ?? cb.installLocation;
+        const ca = byId.get(key);
+        byId.delete(key);
+        const label = cb.id ?? 'component';
+        if (!ca) {
+            f.push({ severity: 'notable', category: 'install', change: 'added', title: `New component ${label}`, detail: `installs to ${cb.installLocation}` });
+        }
+        const scriptsA = new Map((ca?.scripts ?? []).map((s) => [s.name, s]));
+        for (const s of cb.scripts) {
+            const old = scriptsA.get(s.name);
+            scriptsA.delete(s.name);
+            if (!old) {
+                f.push({
+                    severity: s.hook ? 'high' : 'notable',
+                    category: 'script',
+                    change: 'added',
+                    title: s.hook ? `New ${s.name} script${cb.auth === 'root' ? ' (runs as root)' : ''}` : `New helper file ${s.name}`,
+                    detail: s.content?.replace(/\n$/, '').split('\n').slice(0, 30).map((l) => `+ ${l}`).join('\n'),
+                    where: at(label),
+                });
+            }
+            else if (old.content !== s.content || old.bytes !== s.bytes) {
+                const changes = old.content !== undefined && s.content !== undefined ? lineDiff(old.content, s.content) : ['(binary or too large to compare)'];
+                const added = changes.filter((l) => l.startsWith('+ ')).length;
+                const removed = changes.filter((l) => l.startsWith('- ')).length;
+                f.push({
+                    severity: 'notable',
+                    category: 'script',
+                    change: 'changed',
+                    title: `${s.hook ? 'Script' : 'Helper file'} ${s.name} changed (+${added} −${removed} lines)`,
+                    detail: changes.slice(0, 40).join('\n') + (changes.length > 40 ? `\n… ${changes.length - 40} more changed lines` : ''),
+                    where: at(label),
+                });
+            }
+        }
+        for (const s of scriptsA.values())
+            f.push({ severity: 'info', category: 'script', change: 'removed', title: `Removed ${s.name}`, where: at(label) });
+        const launchA = new Map((ca?.launchItems ?? []).map((l) => [l.path, l]));
+        for (const l of cb.launchItems) {
+            const old = launchA.get(l.path);
+            if (!old) {
+                f.push({ severity: 'high', category: 'background', change: 'added', title: `Installs a new launch ${l.kind}: ${l.path}`, detail: describeLaunch(l), where: at(label) });
+            }
+            else if (old.program !== l.program || old.runAtLoad !== l.runAtLoad || old.keepAlive !== l.keepAlive) {
+                f.push({ severity: 'notable', category: 'background', change: 'changed', title: `Launch ${l.kind} ${l.path} changed`, detail: `${describeLaunch(old)} → ${describeLaunch(l)}`, where: at(label) });
+            }
+        }
+        const sysA = new Set(ca?.systemLevel ?? []);
+        for (const p of cb.systemLevel)
+            if (!sysA.has(p))
+                f.push({ severity: 'high', category: 'install', change: 'added', title: `Installs a new system-level item: ${p}`, where: at(label) });
+        const outA = new Set(ca?.outsideApplications ?? []);
+        const newOut = cb.outsideApplications.filter((p) => !outA.has(p));
+        if (newOut.length)
+            f.push({ severity: 'notable', category: 'install', change: 'added', title: 'Installs files in new places outside /Applications', detail: newOut.join(', '), where: at(label) });
+        const appsA = new Map((ca?.apps ?? []).map((x) => [x.path, x]));
+        for (const app of cb.apps) {
+            const old = appsA.get(app.path);
+            if (!old)
+                f.push({ severity: 'notable', category: 'install', change: 'added', title: `Installs a new app: ${app.path}`, detail: app.bundleId, where: at(label) });
+            else if (old.teamId && app.teamId && old.teamId !== app.teamId) {
+                f.push({ severity: 'high', category: 'signing', change: 'changed', title: `${app.path} is signed by a different developer team`, detail: `${old.teamId} → ${app.teamId}`, where: at(label) });
+            }
+        }
+    }
+    for (const gone of byId.values())
+        f.push({ severity: 'info', category: 'install', change: 'removed', title: `Removed component ${gone.id ?? gone.installLocation}` });
+    const jsA = (a.distribution?.scripts ?? []).join('\n');
+    const jsB = (b.distribution?.scripts ?? []).join('\n');
+    if (jsA !== jsB) {
+        const changes = lineDiff(jsA, jsB);
+        f.push({ severity: 'notable', category: 'script', change: 'changed', title: 'Installer JavaScript changed', detail: changes.slice(0, 40).join('\n') });
+    }
+    if (a.sha256 === b.sha256)
+        f.length = 0;
+    f.sort((x, y) => SEVERITY_ORDER[x.severity] - SEVERITY_ORDER[y.severity] || CATEGORY_ORDER.indexOf(x.category) - CATEGORY_ORDER.indexOf(y.category) || x.title.localeCompare(y.title));
+    const counts = { high: 0, notable: 0, info: 0 };
+    for (const x of f)
+        counts[x.severity]++;
+    const side = (r) => ({ version: r.components[0]?.version ?? '?', build: r.sha256.slice(0, 12), takenAt: '', path: r.file });
+    return {
+        app: { name: b.distribution?.title ?? basename(b.file), bundleId: b.components[0]?.id ?? '' },
+        from: side(a),
+        to: side(b),
+        findings: f,
+        counts,
+        identical: a.sha256 === b.sha256,
+    };
+}

package/dist/pkg.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, posix } from 'node:path';
+import { readIdentity } from "./bundle.js";
+import { parseSpctl, readSigning } from "./codesign.js";
+import { decodeEntities, readPlistFile, str } from "./plist.js";
+import { run } from "./exec.js";
+/** Attribute map of one XML start tag. */
+function attrs(tag) {
+    const out = {};
+    for (const m of tag.matchAll(/([\w:-]+)\s*=\s*"([^"]*)"/g))
+        out[m[1]] = decodeEntities(m[2]);
+    return out;
+}
+/** Parses `pkgutil --check-signature`. */
+export function parseCheckSignature(text) {
+    const status = /Status:\s*(.+)/.exec(text)?.[1]?.trim() ?? 'unknown';
+    const signer = /^\s*1\.\s*(.+)$/m.exec(text)?.[1]?.trim();
+    return { status, ...(signer ? { signer } : {}), notarized: /Notarization:\s*trusted by the Apple notary service/i.test(text) };
+}
+/** JavaScript and checks a Distribution file runs when Installer opens it. */
+export function parseDistribution(xml) {
+    const title = /<title>([\s\S]*?)<\/title>/.exec(xml)?.[1]?.trim();
+    const scripts = [...xml.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)]
+        .map((m) => decodeEntities(m[1].replace(/^\s*<!\[CDATA\[|\]\]>\s*$/g, '')).trim())
+        .filter(Boolean);
+    const checks = [];
+    for (const m of xml.matchAll(/<(installation-check|volume-check)\b([^>]*)>/g)) {
+        const a = attrs(m[2]);
+        if (a.script)
+            checks.push(`${m[1]}: ${a.script}`);
+    }
+    return { ...(title ? { title: decodeEntities(title) } : {}), scripts, checks };
+}
+function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        let bytes = 0;
+        createReadStream(file)
+            .on('data', (c) => {
+            hash.update(c);
+            bytes += c.length;
+        })
+            .on('end', () => resolve({ sha256: hash.digest('hex'), bytes }))
+            .on('error', reject);
+    });
+}
+async function walk(root) {
+    const out = [];
+    const queue = [''];
+    while (queue.length) {
+        const rel = queue.pop();
+        let dirents;
+        try {
+            dirents = await readdir(join(root, rel), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const d of dirents) {
+            const r = rel ? `${rel}/${d.name}` : d.name;
+            if (d.isDirectory()) {
+                out.push({ rel: r, isDir: true, size: 0 });
+                queue.push(r);
+            }
+            else if (d.isFile() || d.isSymbolicLink()) {
+                let size = 0;
+                try {
+                    size = (await lstat(join(root, r))).size;
+                }
+                catch {
+                    // Unreadable: count it with size 0.
+                }
+                out.push({ rel: r, isDir: false, size });
+            }
+        }
+    }
+    return out;
+}
+async function readScripts(dir, maxBytes) {
+    const entries = (await walk(dir)).filter((e) => !e.isDir).sort((a, b) => a.rel.localeCompare(b.rel));
+    const scripts = [];
+    for (const e of entries) {
+        const buf = await readFile(join(dir, e.rel));
+        const binary = buf.subarray(0, 4096).includes(0);
+        const text = binary ? undefined : buf.toString('utf8');
+        const shebang = text?.startsWith('#!') ? text.slice(2, text.indexOf('\n') >>> 0).trim() : undefined;
+        scripts.push({
+            name: e.rel,
+            hook: e.rel === 'preinstall' || e.rel === 'postinstall',
+            ...(shebang ? { interpreter: basename(shebang.split(/\s+/)[0] === '/usr/bin/env' ? (shebang.split(/\s+/)[1] ?? shebang) : shebang.split(/\s+/)[0]) } : {}),
+            binary,
+            bytes: buf.length,
+            lines: text ? text.split('\n').length : 0,
+            ...(text !== undefined && buf.length <= maxBytes ? { content: text } : {}),
+        });
+    }
+    // Hooks first, in the order they run; then helper files.
+    const rank = (x) => (x.name === 'preinstall' ? 0 : x.name === 'postinstall' ? 1 : 2);
+    return scripts.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name));
+}
+async function readComponent(dir, scriptMaxBytes) {
+    let info = {};
+    try {
+        const xml = await readFile(join(dir, 'PackageInfo'), 'utf8');
+        info = attrs(/<pkg-info\b([^>]*)>/.exec(xml)?.[1] ?? '');
+    }
+    catch {
+        // A component without PackageInfo still has a payload to show.
+    }
+    const installLocation = info['install-location'] || '/';
+    const payloadDir = join(dir, 'Payload');
+    const entries = await walk(payloadDir);
+    const dest = (rel) => posix.join(installLocation, rel);
+    const apps = [];
+    const launchItems = [];
+    const outside = new Set();
+    const systemLevel = [];
+    let files = 0;
+    let bytes = 0;
+    for (const e of entries) {
+        const path = dest(e.rel);
+        if (!e.isDir) {
+            files++;
+            bytes += e.size;
+        }
+        if (e.isDir && e.rel.endsWith('.app') && !/\.app\//.test(e.rel)) {
+            const id = await readIdentity(join(payloadDir, e.rel));
+            const signing = await readSigning(join(payloadDir, e.rel));
+            apps.push({ path, bundleId: id?.bundleId, version: id?.version, teamId: signing.teamId });
+        }
+        // System-wide launchd jobs, or ones an app registers from inside its bundle (SMAppService).
+        const launchd = /^\/Library\/(LaunchDaemons|LaunchAgents)\/[^/]+\.plist$/.exec(path) ?? /\.app\/Contents\/Library\/(LaunchDaemons|LaunchAgents)\/[^/]+\.plist$/.exec(path);
+        if (launchd && !e.isDir) {
+            const plist = await readPlistFile(join(payloadDir, e.rel));
+            const args = plist?.ProgramArguments;
+            launchItems.push({
+                path,
+                kind: launchd[1] === 'LaunchDaemons' ? 'daemon' : 'agent',
+                label: str(plist?.Label),
+                program: str(plist?.Program) ?? str(plist?.BundleProgram) ?? (Array.isArray(args) && typeof args[0] === 'string' ? args[0] : undefined),
+                runAtLoad: plist?.RunAtLoad === true,
+                keepAlive: plist?.KeepAlive === true || (typeof plist?.KeepAlive === 'object' && plist.KeepAlive !== null),
+            });
+        }
+        if ((e.isDir && /\.(kext|systemextension|dext)$/.test(path)) || /^\/Library\/PrivilegedHelperTools\/[^/]+$/.test(path))
+            systemLevel.push(path);
+        if (!path.startsWith('/Applications/') && path !== '/Applications' && !e.isDir) {
+            // Collapse to the first three levels so a framework doesn't list every file.
+            outside.add(path.split('/').slice(0, 4).join('/'));
+        }
+    }
+    return {
+        ...(info.identifier ? { id: info.identifier } : {}),
+        ...(info.version ? { version: info.version } : {}),
+        installLocation,
+        ...(info.auth ? { auth: info.auth } : {}),
+        scripts: await readScripts(join(dir, 'Scripts'), scriptMaxBytes),
+        files,
+        bytes,
+        apps: apps.sort((a, b) => a.path.localeCompare(b.path)),
+        launchItems: launchItems.sort((a, b) => a.path.localeCompare(b.path)),
+        outsideApplications: [...outside].sort(),
+        systemLevel: [...new Set(systemLevel)].sort(),
+    };
+}
+/**
+ * Expands an installer package and reports what it would do: scripts that run
+ * during installation, what it installs and where, launch daemons and agents,
+ * system-level items, its signature and Gatekeeper's verdict. Nothing is installed
+ * and no script is run: `pkgutil --expand-full` only unpacks.
+ */
+export async function inspectPkg(file, options = {}) {
+    const work = await mkdtemp(join(tmpdir(), 'updiff-pkg-'));
+    try {
+        const out = join(work, 'x');
+        const res = await run('/usr/sbin/pkgutil', ['--expand-full', file, out], 15 * 60_000);
+        if (res.code !== 0)
+            throw new Error(`pkgutil could not expand ${file}: ${(res.stderr || res.stdout).trim().split('\n').pop()}`);
+        const { sha256, bytes } = await sha256File(file);
+        const sig = await run('/usr/sbin/pkgutil', ['--check-signature', file]);
+        const spctl = await run('/usr/sbin/spctl', ['-a', '-vv', '-t', 'install', file], 120_000);
+        const scriptMaxBytes = options.scriptMaxBytes ?? 256 * 1024;
+        let distribution;
+        const components = [];
+        const top = await readdir(out, { withFileTypes: true });
+        if (top.some((d) => d.name === 'Distribution')) {
+            distribution = parseDistribution(await readFile(join(out, 'Distribution'), 'utf8'));
+            for (const d of top)
+                if (d.isDirectory() && d.name.endsWith('.pkg'))
+                    components.push(await readComponent(join(out, d.name), scriptMaxBytes));
+        }
+        else {
+            components.push(await readComponent(out, scriptMaxBytes));
+        }
+        return {
+            file,
+            sha256,
+            bytes,
+            signature: parseCheckSignature(sig.stdout + sig.stderr),
+            gatekeeper: parseSpctl(spctl.stdout + spctl.stderr),
+            ...(distribution ? { distribution } : {}),
+            components,
+        };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}