@intincrab/updiff 0.0.0-stage → 0.1.1

package/dist/diff.js

@@ -0,0 +1,525 @@
+import { registrableDomain } from "./hosts.js";
+import { formatBytes, stableJson } from "./util.js";
+/** Entitlements that change what the app can reach or how safely it runs. */
+const SENSITIVE_ENTITLEMENTS = {
+    'com.apple.security.device.camera': 'use the camera',
+    'com.apple.security.device.audio-input': 'record from the microphone',
+    'com.apple.security.device.microphone': 'record from the microphone',
+    'com.apple.security.device.usb': 'talk to USB devices',
+    'com.apple.security.device.bluetooth': 'use Bluetooth',
+    'com.apple.security.personal-information.location': 'read your location',
+    'com.apple.security.personal-information.addressbook': 'read your contacts',
+    'com.apple.security.personal-information.calendars': 'read your calendars',
+    'com.apple.security.personal-information.photos-library': 'read your photo library',
+    'com.apple.security.automation.apple-events': 'control other apps through Apple Events',
+    'com.apple.security.cs.disable-library-validation': 'load code signed by other developers',
+    'com.apple.security.cs.allow-dyld-environment-variables': 'be injected with libraries through environment variables',
+    'com.apple.security.cs.allow-unsigned-executable-memory': 'run unsigned executable memory',
+    'com.apple.security.cs.disable-executable-page-protection': 'turn off executable page protection',
+    'com.apple.security.cs.debugger': 'debug other processes',
+    'com.apple.security.get-task-allow': 'be debugged and inspected by other processes',
+    'com.apple.developer.endpoint-security.client': 'watch system-wide process and file activity (Endpoint Security)',
+    'com.apple.developer.system-extension.install': 'install system extensions',
+    'com.apple.developer.networking.networkextension': 'filter, proxy or route network traffic (Network Extension)',
+    'com.apple.developer.networking.vpn.api': 'configure VPNs',
+    'com.apple.security.cs.allow-jit': 'generate code at runtime (JIT)',
+};
+/** Entitlements that are common and low-risk enough to stay "notable" when added. */
+const MILD_ENTITLEMENTS = new Set(['com.apple.security.cs.allow-jit']);
+const PRIVACY_NAMES = {
+    NSCameraUsageDescription: 'Camera',
+    NSMicrophoneUsageDescription: 'Microphone',
+    NSAudioCaptureUsageDescription: 'System audio recording',
+    NSContactsUsageDescription: 'Contacts',
+    NSCalendarsUsageDescription: 'Calendars',
+    NSCalendarsFullAccessUsageDescription: 'Calendars (full access)',
+    NSCalendarsWriteOnlyAccessUsageDescription: 'Calendars (add events)',
+    NSRemindersUsageDescription: 'Reminders',
+    NSRemindersFullAccessUsageDescription: 'Reminders (full access)',
+    NSPhotoLibraryUsageDescription: 'Photos',
+    NSPhotoLibraryAddUsageDescription: 'Photos (add only)',
+    NSLocationUsageDescription: 'Location',
+    NSLocationWhenInUseUsageDescription: 'Location',
+    NSLocationAlwaysUsageDescription: 'Location (always)',
+    NSLocationAlwaysAndWhenInUseUsageDescription: 'Location (always)',
+    NSAppleEventsUsageDescription: 'Control other apps (Apple Events)',
+    NSBluetoothAlwaysUsageDescription: 'Bluetooth',
+    NSBluetoothPeripheralUsageDescription: 'Bluetooth',
+    NSLocalNetworkUsageDescription: 'Devices on your local network',
+    NSSpeechRecognitionUsageDescription: 'Speech recognition',
+    NSDesktopFolderUsageDescription: 'Desktop folder',
+    NSDocumentsFolderUsageDescription: 'Documents folder',
+    NSDownloadsFolderUsageDescription: 'Downloads folder',
+    NSRemovableVolumesUsageDescription: 'Removable drives',
+    NSNetworkVolumesUsageDescription: 'Network drives',
+    NSFileProviderDomainUsageDescription: 'Cloud file providers',
+    NSSystemAdministrationUsageDescription: 'Administrator actions',
+    NSMotionUsageDescription: 'Motion data',
+    NSHomeKitUsageDescription: 'HomeKit',
+    NSFocusStatusUsageDescription: 'Focus status',
+    NSFaceIDUsageDescription: 'Face ID',
+    NSIdentityUsageDescription: 'Identity documents',
+};
+const KIND_LABEL = {
+    main: 'main executable',
+    helperApp: 'helper app',
+    xpcService: 'XPC service',
+    appExtension: 'app extension',
+    loginItem: 'login item',
+    privilegedHelper: 'privileged helper (runs as root)',
+    systemExtension: 'system extension',
+    framework: 'framework',
+    plugin: 'plug-in bundle',
+    executable: 'executable',
+    nativeModule: 'native Node module',
+};
+const HIGH_RISK_KINDS = new Set(['loginItem', 'privilegedHelper', 'systemExtension']);
+function privacyName(key) {
+    return PRIVACY_NAMES[key] ?? key.replace(/^NS/, '').replace(/UsageDescription$/, '');
+}
+/** "Helper app Foo Helper.app", for the start of a finding title. */
+function subjectOf(item) {
+    const label = KIND_LABEL[item.kind];
+    return `${label[0].toUpperCase()}${label.slice(1)} ${shortName(item.path)}`;
+}
+function show(v) {
+    if (v === undefined)
+        return '(none)';
+    if (typeof v === 'string')
+        return v;
+    return stableJson(v);
+}
+function entitlementSeverity(key) {
+    if (key.startsWith('com.apple.security.temporary-exception.'))
+        return 'high';
+    if (MILD_ENTITLEMENTS.has(key))
+        return 'notable';
+    return key in SENSITIVE_ENTITLEMENTS ? 'high' : 'notable';
+}
+function entitlementTitle(key, item) {
+    const what = SENSITIVE_ENTITLEMENTS[key];
+    const subject = item.kind === 'main' ? 'App' : subjectOf(item);
+    return what ? `${subject} can now ${what}` : `${subject} gained entitlement ${key}`;
+}
+function shortName(path) {
+    return path.slice(path.lastIndexOf('/') + 1);
+}
+function isEnabled(v) {
+    return v !== undefined && v !== false && v !== 0 && !(Array.isArray(v) && v.length === 0);
+}
+function diffEntitlements(a, b, item, out) {
+    const where = [item.path];
+    for (const key of Object.keys(b)) {
+        const before = a[key];
+        const after = b[key];
+        if (stableJson(before) === stableJson(after))
+            continue;
+        if (!isEnabled(before) && isEnabled(after)) {
+            out.push({
+                severity: entitlementSeverity(key),
+                category: 'entitlement',
+                change: 'added',
+                title: entitlementTitle(key, item),
+                detail: `${key} = ${show(after)}`,
+                where,
+            });
+        }
+        else if (Array.isArray(before) && Array.isArray(after)) {
+            const beforeSet = new Set(before.map(stableJson));
+            const afterSet = new Set(after.map(stableJson));
+            const added = after.filter((x) => !beforeSet.has(stableJson(x)));
+            const removed = before.filter((x) => !afterSet.has(stableJson(x)));
+            if (added.length) {
+                out.push({
+                    severity: key.startsWith('com.apple.security.temporary-exception.') ? 'high' : 'notable',
+                    category: 'entitlement',
+                    change: 'changed',
+                    title: `${key} gained ${added.length} value${added.length === 1 ? '' : 's'}`,
+                    detail: added.map(show).join(', '),
+                    where,
+                });
+            }
+            if (removed.length) {
+                out.push({
+                    severity: 'info',
+                    category: 'entitlement',
+                    change: 'changed',
+                    title: `${key} lost ${removed.length} value${removed.length === 1 ? '' : 's'}`,
+                    detail: removed.map(show).join(', '),
+                    where,
+                });
+            }
+        }
+        else if (isEnabled(before) && !isEnabled(after)) {
+            if (key === 'com.apple.security.app-sandbox')
+                out.push(sandboxRemoved(item, 'changed'));
+            else
+                out.push({ severity: 'info', category: 'entitlement', change: 'removed', title: `Entitlement ${key} turned off`, where });
+        }
+        else {
+            out.push({
+                severity: 'notable',
+                category: 'entitlement',
+                change: 'changed',
+                title: `Entitlement ${key} changed`,
+                detail: `${show(before)} → ${show(after)}`,
+                where,
+            });
+        }
+    }
+    for (const key of Object.keys(a)) {
+        if (key in b)
+            continue;
+        if (key === 'com.apple.security.app-sandbox' && isEnabled(a[key]))
+            out.push(sandboxRemoved(item, 'removed'));
+        else
+            out.push({ severity: 'info', category: 'entitlement', change: 'removed', title: `Entitlement ${key} removed`, where });
+    }
+}
+function sandboxRemoved(item, change) {
+    return {
+        severity: 'high',
+        category: 'entitlement',
+        change,
+        title: item.kind === 'main' ? 'App is no longer sandboxed' : `${subjectOf(item)} is no longer sandboxed`,
+        where: [item.path],
+    };
+}
+function diffSigning(a, b, out) {
+    const sa = a.signing;
+    const sb = b.signing;
+    if (!sa || !sb)
+        return;
+    const subject = b.kind === 'main' ? 'App' : subjectOf(b);
+    const where = [b.path];
+    const trusted = (s) => s.status === 'signed';
+    if (trusted(sa) && !trusted(sb)) {
+        out.push({ severity: 'high', category: 'signing', change: 'changed', title: `${subject} is no longer signed by a developer`, detail: `signature: ${sa.status} → ${sb.status}`, where });
+    }
+    else if (sa.status !== sb.status) {
+        out.push({ severity: 'info', category: 'signing', change: 'changed', title: `${subject} signature changed`, detail: `${sa.status} → ${sb.status}`, where });
+    }
+    if (sa.teamId && sb.teamId && sa.teamId !== sb.teamId) {
+        out.push({
+            severity: 'high',
+            category: 'signing',
+            change: 'changed',
+            title: `${subject} is signed by a different developer team`,
+            detail: `${sa.teamId} → ${sb.teamId}${sb.authorities[0] ? ` (${sb.authorities[0]})` : ''}`,
+            where,
+        });
+    }
+    else if ((sa.authorities[0] ?? '') !== (sb.authorities[0] ?? '') && sa.authorities[0] && sb.authorities[0]) {
+        out.push({ severity: 'notable', category: 'signing', change: 'changed', title: `${subject} signing certificate changed`, detail: `${sa.authorities[0]} → ${sb.authorities[0]}`, where });
+    }
+    if (sa.hardenedRuntime && !sb.hardenedRuntime) {
+        out.push({ severity: 'high', category: 'signing', change: 'removed', title: `${subject} dropped the hardened runtime`, where });
+    }
+    else if (!sa.hardenedRuntime && sb.hardenedRuntime) {
+        out.push({ severity: 'info', category: 'signing', change: 'added', title: `${subject} enabled the hardened runtime`, where });
+    }
+}
+function matchCode(a, b) {
+    const byKeyA = new Map(a.map((c) => [`${c.kind}|${c.key}`, c]));
+    const pairs = [];
+    const unmatchedB = [];
+    const usedA = new Set();
+    for (const c of b) {
+        const m = byKeyA.get(`${c.kind}|${c.key}`) ?? (c.kind === 'main' ? a.find((x) => x.kind === 'main') : undefined);
+        if (m && !usedA.has(m)) {
+            pairs.push([m, c]);
+            usedA.add(m);
+        }
+        else
+            unmatchedB.push(c);
+    }
+    // A renamed bundle keeps its bundle identifier.
+    const added = [];
+    for (const c of unmatchedB) {
+        const m = c.bundleId ? a.find((x) => !usedA.has(x) && x.kind === c.kind && x.bundleId === c.bundleId) : undefined;
+        if (m) {
+            pairs.push([m, c]);
+            usedA.add(m);
+        }
+        else
+            added.push(c);
+    }
+    return { pairs, added, removed: a.filter((x) => !usedA.has(x)) };
+}
+function describeCode(c) {
+    const parts = [];
+    if (c.bundleId)
+        parts.push(c.bundleId);
+    if (c.version)
+        parts.push(`v${c.version}`);
+    if (c.signing?.teamId)
+        parts.push(`team ${c.signing.teamId}`);
+    const ents = Object.keys(c.entitlements ?? {});
+    if (ents.length)
+        parts.push(`entitlements: ${ents.join(', ')}`);
+    return parts.join(' · ');
+}
+function diffCode(a, b, out) {
+    const { pairs, added, removed } = matchCode(a.code, b.code);
+    const mainTeam = b.signing.teamId;
+    for (const [ca, cb] of pairs) {
+        diffSigning(ca, cb, out);
+        if (ca.entitlements || cb.entitlements)
+            diffEntitlements(ca.entitlements ?? {}, cb.entitlements ?? {}, cb, out);
+        if (cb.kind === 'framework' && ca.version !== cb.version && cb.version) {
+            const isElectron = cb.path.endsWith('/Electron Framework.framework');
+            out.push({
+                severity: isElectron ? 'notable' : 'info',
+                category: isElectron ? 'electron' : 'code',
+                change: 'changed',
+                title: isElectron ? `Electron ${ca.version ?? '?'} → ${cb.version}` : `${shortName(cb.path)} ${ca.version ?? '?'} → ${cb.version}`,
+                where: [cb.path],
+            });
+        }
+    }
+    for (const c of added) {
+        out.push({
+            severity: HIGH_RISK_KINDS.has(c.kind) ? 'high' : 'notable',
+            category: 'code',
+            change: 'added',
+            title: `New ${KIND_LABEL[c.kind]}: ${shortName(c.path)}`,
+            detail: describeCode(c) || undefined,
+            where: [c.path],
+        });
+        if (c.signing?.teamId && mainTeam && c.signing.teamId !== mainTeam) {
+            out.push({
+                severity: 'high',
+                category: 'signing',
+                change: 'added',
+                title: `New ${KIND_LABEL[c.kind]} ${shortName(c.path)} is signed by another developer team`,
+                detail: `${c.signing.teamId}${c.signing.authorities[0] ? ` (${c.signing.authorities[0]})` : ''}; the app is ${mainTeam}`,
+                where: [c.path],
+            });
+        }
+        for (const [key, value] of Object.entries(c.entitlements ?? {})) {
+            if (entitlementSeverity(key) !== 'high' || !isEnabled(value))
+                continue;
+            out.push({ severity: 'high', category: 'entitlement', change: 'added', title: entitlementTitle(key, c), detail: `${key} = ${show(value)}`, where: [c.path] });
+        }
+    }
+    for (const c of removed) {
+        out.push({ severity: 'info', category: 'code', change: 'removed', title: `Removed ${KIND_LABEL[c.kind]}: ${shortName(c.path)}`, where: [c.path] });
+    }
+}
+function describeBackground(i) {
+    const parts = [i.label ? `label ${i.label}` : undefined, i.program ? `runs ${i.program}` : undefined];
+    if (i.runAtLoad)
+        parts.push('starts at login');
+    if (i.keepAlive)
+        parts.push('kept alive');
+    return parts.filter(Boolean).join(' · ');
+}
+function diffBackground(a, b, out) {
+    const byFile = new Map(a.map((i) => [i.file, i]));
+    for (const i of b) {
+        const prev = byFile.get(i.file);
+        const kind = i.kind === 'launchAgent' ? 'background agent' : 'background daemon (runs as root)';
+        if (!prev) {
+            out.push({ severity: 'high', category: 'background', change: 'added', title: `New ${kind}: ${shortName(i.file)}`, detail: describeBackground(i), where: [i.file] });
+            continue;
+        }
+        byFile.delete(i.file);
+        if (stableJson(prev) !== stableJson(i)) {
+            out.push({
+                severity: 'notable',
+                category: 'background',
+                change: 'changed',
+                title: `${shortName(i.file)} changed`,
+                detail: `${describeBackground(prev)} → ${describeBackground(i)}`,
+                where: [i.file],
+            });
+        }
+    }
+    for (const i of byFile.values()) {
+        out.push({ severity: 'info', category: 'background', change: 'removed', title: `Removed background item ${shortName(i.file)}`, where: [i.file] });
+    }
+}
+function diffInfo(a, b, out) {
+    const ia = a.info;
+    const ib = b.info;
+    for (const [key, text] of Object.entries(ib.privacyUsage)) {
+        if (!(key in ia.privacyUsage)) {
+            out.push({ severity: 'high', category: 'privacy', change: 'added', title: `Can now ask for access to ${privacyName(key)}`, detail: `${key}: “${text}”`, where: ['Contents/Info.plist'] });
+        }
+        else if (ia.privacyUsage[key] !== text) {
+            out.push({ severity: 'info', category: 'privacy', change: 'changed', title: `Explanation for ${privacyName(key)} access changed`, detail: `“${ia.privacyUsage[key]}” → “${text}”`, where: ['Contents/Info.plist'] });
+        }
+    }
+    for (const key of Object.keys(ia.privacyUsage)) {
+        if (!(key in ib.privacyUsage))
+            out.push({ severity: 'info', category: 'privacy', change: 'removed', title: `No longer asks for ${privacyName(key)}`, where: ['Contents/Info.plist'] });
+    }
+    const addedSchemes = ib.urlSchemes.filter((s) => !ia.urlSchemes.includes(s));
+    const removedSchemes = ia.urlSchemes.filter((s) => !ib.urlSchemes.includes(s));
+    for (const s of addedSchemes)
+        out.push({ severity: 'notable', category: 'urlScheme', change: 'added', title: `Opens ${s}:// links`, detail: 'Web pages and other apps can launch it with this URL scheme.', where: ['Contents/Info.plist'] });
+    if (removedSchemes.length)
+        out.push({ severity: 'info', category: 'urlScheme', change: 'removed', title: `Stopped handling ${removedSchemes.map((s) => `${s}://`).join(', ')}`, where: ['Contents/Info.plist'] });
+    if (!ia.atsArbitraryLoads && ib.atsArbitraryLoads) {
+        out.push({ severity: 'high', category: 'network', change: 'added', title: 'Allows unencrypted HTTP connections (App Transport Security relaxed)', where: ['Contents/Info.plist'] });
+    }
+    else if (ia.atsArbitraryLoads && !ib.atsArbitraryLoads) {
+        out.push({ severity: 'info', category: 'network', change: 'removed', title: 'No longer allows arbitrary HTTP connections', where: ['Contents/Info.plist'] });
+    }
+    const newExceptions = ib.atsExceptionDomains.filter((d) => !ia.atsExceptionDomains.includes(d));
+    if (newExceptions.length)
+        out.push({ severity: 'notable', category: 'network', change: 'added', title: `New App Transport Security exceptions`, detail: newExceptions.join(', '), where: ['Contents/Info.plist'] });
+    if (ia.backgroundOnly !== ib.backgroundOnly) {
+        out.push({ severity: 'notable', category: 'identity', change: 'changed', title: ib.backgroundOnly ? 'Now runs without a Dock icon (agent app)' : 'Now shows a Dock icon', where: ['Contents/Info.plist'] });
+    }
+    if (ia.sparkleFeedUrl && ib.sparkleFeedUrl && ia.sparkleFeedUrl !== ib.sparkleFeedUrl) {
+        out.push({ severity: 'high', category: 'updater', change: 'changed', title: 'Update feed moved', detail: `${ia.sparkleFeedUrl} → ${ib.sparkleFeedUrl}`, where: ['Contents/Info.plist'] });
+    }
+    else if (!ia.sparkleFeedUrl && ib.sparkleFeedUrl) {
+        out.push({ severity: 'notable', category: 'updater', change: 'added', title: 'Added a Sparkle update feed', detail: ib.sparkleFeedUrl, where: ['Contents/Info.plist'] });
+    }
+    else if (ia.sparkleFeedUrl && !ib.sparkleFeedUrl) {
+        out.push({ severity: 'notable', category: 'updater', change: 'removed', title: 'Removed its Sparkle update feed', detail: ia.sparkleFeedUrl, where: ['Contents/Info.plist'] });
+    }
+    if (ia.sparklePublicKey && ia.sparklePublicKey !== ib.sparklePublicKey) {
+        out.push({
+            severity: 'high',
+            category: 'updater',
+            change: ib.sparklePublicKey ? 'changed' : 'removed',
+            title: ib.sparklePublicKey ? 'Update signing key changed' : 'Update signing key removed',
+            detail: 'Future updates are verified against a different key. Confirm this with the developer.',
+            where: ['Contents/Info.plist'],
+        });
+    }
+    for (const p of ib.privilegedExecutables.filter((x) => !ia.privilegedExecutables.includes(x))) {
+        out.push({ severity: 'high', category: 'background', change: 'added', title: `Declares a new privileged helper: ${p}`, detail: 'Helpers installed this way run as root.', where: ['Contents/Info.plist'] });
+    }
+    if (ia.minimumSystemVersion !== ib.minimumSystemVersion && ib.minimumSystemVersion) {
+        out.push({ severity: 'info', category: 'identity', change: 'changed', title: `Minimum macOS ${ia.minimumSystemVersion ?? '?'} → ${ib.minimumSystemVersion}`, where: ['Contents/Info.plist'] });
+    }
+}
+function diffElectron(a, b, out) {
+    const pa = a.electron?.packages ?? {};
+    const pb = b.electron?.packages ?? {};
+    const added = Object.keys(pb).filter((n) => !(n in pa)).sort();
+    const removed = Object.keys(pa).filter((n) => !(n in pb)).sort();
+    const bumped = Object.keys(pb).filter((n) => n in pa && stableJson(pa[n]) !== stableJson(pb[n])).sort();
+    const fmt = (n, p) => `${n}@${(p[n] ?? []).join('|')}`;
+    if (added.length) {
+        out.push({
+            severity: 'notable',
+            category: 'package',
+            change: 'added',
+            title: `${added.length} new bundled npm package${added.length === 1 ? '' : 's'}`,
+            detail: added.map((n) => fmt(n, pb)).join(', '),
+            where: b.electron?.appSource ? [b.electron.appSource] : undefined,
+        });
+    }
+    if (removed.length) {
+        out.push({ severity: 'info', category: 'package', change: 'removed', title: `${removed.length} bundled npm package${removed.length === 1 ? '' : 's'} removed`, detail: removed.join(', ') });
+    }
+    if (bumped.length) {
+        out.push({
+            severity: 'info',
+            category: 'package',
+            change: 'changed',
+            title: `${bumped.length} bundled npm package${bumped.length === 1 ? '' : 's'} changed version`,
+            detail: bumped.map((n) => `${n} ${(pa[n] ?? []).join('|')} → ${(pb[n] ?? []).join('|')}`).join(', '),
+        });
+    }
+    if (!a.electron && b.electron) {
+        out.push({ severity: 'notable', category: 'electron', change: 'added', title: 'Now built with Electron', detail: b.electron.electronVersion ? `Electron ${b.electron.electronVersion}` : undefined });
+    }
+}
+function groupByDomain(hosts) {
+    const out = new Map();
+    for (const h of Object.keys(hosts)) {
+        const d = registrableDomain(h);
+        const list = out.get(d);
+        if (list)
+            list.push(h);
+        else
+            out.set(d, [h]);
+    }
+    return out;
+}
+function diffHosts(a, b, out) {
+    const domainsA = groupByDomain(a.hosts);
+    const domainsB = groupByDomain(b.hosts);
+    for (const [domain, hosts] of [...domainsB].sort(([x], [y]) => x.localeCompare(y))) {
+        const before = domainsA.get(domain);
+        if (!before) {
+            const viaUrl = hosts.some((h) => b.hosts[h].viaUrl);
+            const where = [...new Set(hosts.flatMap((h) => b.hosts[h].where))].slice(0, 3);
+            out.push({
+                severity: 'notable',
+                category: 'host',
+                change: 'added',
+                title: `New domain ${domain}`,
+                detail: `${hosts.sort().join(', ')}${viaUrl ? '' : ' (seen only as a bare string, not in a URL)'}`,
+                where,
+            });
+            continue;
+        }
+        const newHosts = hosts.filter((h) => !before.includes(h)).sort();
+        if (newHosts.length) {
+            out.push({
+                severity: 'info',
+                category: 'host',
+                change: 'added',
+                title: `New host${newHosts.length === 1 ? '' : 's'} under ${domain}`,
+                detail: newHosts.join(', '),
+                where: [...new Set(newHosts.flatMap((h) => b.hosts[h].where))].slice(0, 3),
+            });
+        }
+    }
+    const gone = [...domainsA.keys()].filter((d) => !domainsB.has(d)).sort();
+    if (gone.length) {
+        out.push({ severity: 'info', category: 'host', change: 'removed', title: `${gone.length} domain${gone.length === 1 ? '' : 's'} no longer mentioned`, detail: gone.join(', ') });
+    }
+}
+const SEVERITY_ORDER = { high: 0, notable: 1, info: 2 };
+const CATEGORY_ORDER = [
+    'signing', 'privacy', 'entitlement', 'background', 'updater', 'network', 'code', 'urlScheme', 'electron', 'package', 'host', 'identity',
+];
+export function diffSnapshots(a, b) {
+    const findings = [];
+    if (a.app.bundleId !== b.app.bundleId) {
+        findings.push({ severity: 'high', category: 'identity', change: 'changed', title: 'These are different apps', detail: `${a.app.bundleId} → ${b.app.bundleId}` });
+    }
+    diffInfo(a, b, findings);
+    diffCode(a, b, findings);
+    diffBackground(a.backgroundItems, b.backgroundItems, findings);
+    diffElectron(a, b, findings);
+    diffHosts(a, b, findings);
+    const substantive = findings.length;
+    if (a.app.version !== b.app.version || a.app.build !== b.app.build) {
+        findings.push({ severity: 'info', category: 'identity', change: 'changed', title: `Version ${a.app.version} (${a.app.build}) → ${b.app.version} (${b.app.build})` });
+    }
+    if (a.app.sizeBytes !== b.app.sizeBytes) {
+        const delta = b.app.sizeBytes - a.app.sizeBytes;
+        const pct = a.app.sizeBytes ? ((delta / a.app.sizeBytes) * 100).toFixed(1) : '∞';
+        findings.push({ severity: 'info', category: 'identity', change: 'changed', title: `Size ${delta >= 0 ? '+' : ''}${formatBytes(delta)} (${delta >= 0 ? '+' : ''}${pct}%), files ${a.app.fileCount} → ${b.app.fileCount}` });
+    }
+    findings.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 f of findings)
+        counts[f.severity]++;
+    return {
+        app: { name: b.app.name, bundleId: b.app.bundleId },
+        from: { version: a.app.version, build: a.app.build, takenAt: a.takenAt, path: a.app.path },
+        to: { version: b.app.version, build: b.app.build, takenAt: b.takenAt, path: b.app.path },
+        findings,
+        counts,
+        identical: substantive === 0 && a.fingerprint === b.fingerprint,
+    };
+}
+export function filterBySeverity(report, min) {
+    const findings = report.findings.filter((f) => SEVERITY_ORDER[f.severity] <= SEVERITY_ORDER[min]);
+    const counts = { high: 0, notable: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return { ...report, findings, counts };
+}

package/dist/exec.js

@@ -0,0 +1,19 @@
+import { execFile } from 'node:child_process';
+/**
+ * Runs a command without a shell. Never throws on a non-zero exit.
+ * `input` is written to the command's stdin (for prompts such as a disk image licence).
+ */
+export function run(file, args, timeoutMs = 60_000, input) {
+    return new Promise((resolve) => {
+        const child = execFile(file, args, { maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs, encoding: 'utf8' }, (error, stdout, stderr) => {
+            let code = 0;
+            if (error) {
+                const raw = error.code;
+                code = typeof raw === 'number' ? raw : 1;
+            }
+            resolve({ code, stdout: stdout ?? '', stderr: stderr ?? '' });
+        });
+        if (input !== undefined)
+            child.stdin?.end(input);
+    });
+}

package/dist/hosts.js

@@ -0,0 +1,120 @@
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const HOSTNAME = `(?:${LABEL}\\.)+[a-z][a-z0-9-]{0,22}[a-z0-9]`;
+/** A host after a URL scheme, optionally with user info. */
+const URL_RE = new RegExp(`\\b(?:https?|wss?|ftp)://(?:[^\\s"'<>/@\\\\]{1,64}@)?(${HOSTNAME})(?![a-z0-9-])`, 'gi');
+/** A hostname alone inside a string literal: "events.vendor.io". */
+const LITERAL_RE = new RegExp(`["'\`](${HOSTNAME})["'\`]`, 'gi');
+/**
+ * Top-level domains accepted for bare string literals. Kept short on purpose: bare
+ * strings like "Foo.app", "README.md" and "build.sh" would otherwise read as hosts.
+ * Hosts that follow a URL scheme accept any alphabetic top-level domain.
+ */
+const LITERAL_TLDS = new Set(('com net org io ai dev co me us uk de fr nl se no fi dk es it pt pl ch at be ie jp cn kr tw hk sg in au nz ca br mx ' +
+    'ru ua cz hu ro gr tr il za eu info biz tv cloud xyz gg ly so to fm gl im ac cc edu gov mil int').split(' '));
+/** Exact hosts and suffixes that are namespaces, documentation placeholders or reserved names. */
+const IGNORED_HOSTS = new Set([
+    'www.w3.org',
+    'w3.org',
+    'schemas.xmlsoap.org',
+    'schemas.microsoft.com',
+    'schemas.openxmlformats.org',
+    'ns.adobe.com',
+    'purl.org',
+    'xmlns.com',
+    'json-schema.org',
+    'example.com',
+    'example.net',
+    'example.org',
+    'www.example.com',
+    'www.example.net',
+    'www.example.org',
+]);
+const IGNORED_SUFFIXES = ['.localhost', '.local', '.test', '.invalid', '.example', '.internal', '.lan', '.home.arpa'];
+export function isIgnoredHost(host) {
+    if (host === 'localhost' || IGNORED_HOSTS.has(host))
+        return true;
+    return IGNORED_SUFFIXES.some((s) => host.endsWith(s));
+}
+function tldOf(host) {
+    return host.slice(host.lastIndexOf('.') + 1);
+}
+/**
+ * Suffixes under which each subdomain belongs to a different owner. A short,
+ * hand-picked part of the Public Suffix List that covers the common cases.
+ */
+const MULTI_PART_SUFFIXES = new Set([
+    'co.uk', 'org.uk', 'ac.uk', 'gov.uk', 'me.uk', 'ltd.uk', 'plc.uk',
+    'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au',
+    'co.jp', 'ne.jp', 'or.jp', 'ac.jp', 'go.jp',
+    'com.br', 'net.br', 'org.br', 'gov.br',
+    'com.cn', 'net.cn', 'org.cn', 'gov.cn', 'edu.cn',
+    'co.in', 'net.in', 'org.in', 'gov.in', 'ac.in',
+    'co.kr', 'or.kr', 'go.kr',
+    'co.nz', 'org.nz', 'govt.nz',
+    'com.mx', 'com.tr', 'com.tw', 'com.hk', 'com.sg', 'com.my', 'com.ar', 'com.co', 'com.vn', 'com.ph', 'com.pk',
+    'co.za', 'co.il', 'co.id', 'co.th',
+    'github.io', 'gitlab.io', 'pages.dev', 'workers.dev', 'vercel.app', 'netlify.app', 'herokuapp.com',
+    'appspot.com', 'web.app', 'firebaseapp.com', 'azurewebsites.net', 'cloudfront.net', 'blob.core.windows.net',
+    's3.amazonaws.com', 'fly.dev', 'onrender.com', 'ngrok.io', 'ngrok-free.app', 'r2.dev', 'supabase.co',
+]);
+/** The domain a host belongs to: `api.eu.vendor.co.uk` → `vendor.co.uk`. */
+export function registrableDomain(host) {
+    const labels = host.split('.');
+    for (let take = Math.min(4, labels.length - 1); take >= 2; take--) {
+        const suffix = labels.slice(-take).join('.');
+        if (MULTI_PART_SUFFIXES.has(suffix))
+            return labels.slice(-(take + 1)).join('.');
+    }
+    return labels.slice(-2).join('.');
+}
+function add(map, host, where, viaUrl) {
+    const rec = map.get(host);
+    if (rec) {
+        rec.count++;
+        rec.viaUrl ||= viaUrl;
+        if (rec.where.length < 3 && !rec.where.includes(where))
+            rec.where.push(where);
+    }
+    else {
+        map.set(host, { count: 1, viaUrl, where: [where] });
+    }
+}
+function cleanHost(raw) {
+    return raw.toLowerCase().replace(/\.$/, '');
+}
+/** Finds hostnames in text (source code, JSON, HTML, or a binary read as latin1). */
+export function extractHosts(text, where, into = new Map(), literals = true) {
+    for (const m of text.matchAll(URL_RE)) {
+        const host = cleanHost(m[1]);
+        if (!/[a-z]/.test(tldOf(host)) || isIgnoredHost(host))
+            continue;
+        add(into, host, where, true);
+    }
+    if (literals) {
+        for (const m of text.matchAll(LITERAL_RE)) {
+            const host = cleanHost(m[1]);
+            if (!LITERAL_TLDS.has(tldOf(host)) || isIgnoredHost(host))
+                continue;
+            // "this.is" / "e.g" style tokens: a one-letter first label is rarely a real host.
+            if (/^[a-z]\./.test(host) && host.split('.').length === 2)
+                continue;
+            add(into, host, where, false);
+        }
+    }
+    return into;
+}
+export function mergeHosts(into, from) {
+    for (const [host, rec] of from) {
+        const cur = into.get(host);
+        if (!cur)
+            into.set(host, { count: rec.count, viaUrl: rec.viaUrl, where: [...rec.where] });
+        else {
+            cur.count += rec.count;
+            cur.viaUrl ||= rec.viaUrl;
+            for (const w of rec.where)
+                if (cur.where.length < 3 && !cur.where.includes(w))
+                    cur.where.push(w);
+        }
+    }
+    return into;
+}