@intincrab/updiff 0.0.0-stage → 0.2.0

package/dist/extensions.js

@@ -0,0 +1,453 @@
+import { existsSync } from 'node:fs';
+import { lstat, open, readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isScannableText } from "./bundle.js";
+import { CATEGORY_ORDER, SEVERITY_ORDER } from "./diff.js";
+import { extractHosts, mergeHosts, registrableDomain } from "./hosts.js";
+import { sortedUnique } from "./util.js";
+const CHROMIUM = [
+    { host: 'chrome', name: 'Chrome', dir: 'Google/Chrome' },
+    { host: 'brave', name: 'Brave', dir: 'BraveSoftware/Brave-Browser' },
+    { host: 'edge', name: 'Edge', dir: 'Microsoft Edge' },
+    { host: 'arc', name: 'Arc', dir: 'Arc/User Data' },
+    { host: 'vivaldi', name: 'Vivaldi', dir: 'Vivaldi' },
+    { host: 'chromium', name: 'Chromium', dir: 'Chromium' },
+];
+const EDITORS = [
+    { host: 'vscode', name: 'VS Code', dir: '.vscode' },
+    { host: 'cursor', name: 'Cursor', dir: '.cursor' },
+    { host: 'windsurf', name: 'Windsurf', dir: '.windsurf' },
+    { host: 'vscodium', name: 'VSCodium', dir: '.vscode-oss' },
+];
+/** Where to look: the user's home, or `$UPDIFF_EXTENSIONS_ROOT` (for tests). */
+export function extensionsRoot() {
+    return process.env.UPDIFF_EXTENSIONS_ROOT || homedir();
+}
+/** Compares dotted versions numerically: "1.10.0" > "1.9.2". */
+export function compareVersions(a, b) {
+    const pa = a.split(/[._-]/).map((x) => Number.parseInt(x, 10));
+    const pb = b.split(/[._-]/).map((x) => Number.parseInt(x, 10));
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = Number.isNaN(pa[i] ?? 0) ? 0 : (pa[i] ?? 0);
+        const y = Number.isNaN(pb[i] ?? 0) ? 0 : (pb[i] ?? 0);
+        if (x !== y)
+            return x - y;
+    }
+    return a.localeCompare(b);
+}
+async function readJson(path) {
+    try {
+        return JSON.parse((await readFile(path, 'utf8')).replace(/^/, ''));
+    }
+    catch {
+        return undefined;
+    }
+}
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+const asObj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+/** Resolves "__MSG_extName__" from the extension's default locale. */
+async function localized(dir, value, defaultLocale) {
+    if (typeof value !== 'string')
+        return undefined;
+    const m = /^__MSG_(.+)__$/.exec(value);
+    if (!m)
+        return value;
+    for (const locale of [defaultLocale, 'en', 'en_US'].filter((x) => typeof x === 'string')) {
+        const messages = asObj(await readJson(join(dir, '_locales', locale, 'messages.json')));
+        const key = Object.keys(messages).find((k) => k.toLowerCase() === m[1].toLowerCase());
+        const msg = key ? asObj(messages[key]).message : undefined;
+        if (typeof msg === 'string')
+            return msg;
+    }
+    return value;
+}
+async function chromiumExtensions(base, host, hostName) {
+    const out = [];
+    let profiles;
+    try {
+        profiles = (await readdir(base, { withFileTypes: true }))
+            .filter((d) => d.isDirectory() && (d.name === 'Default' || /^Profile \d+$/.test(d.name)))
+            .map((d) => d.name);
+    }
+    catch {
+        return out;
+    }
+    for (const profile of profiles) {
+        const extDir = join(base, profile, 'Extensions');
+        let ids;
+        try {
+            ids = (await readdir(extDir)).filter((n) => /^[a-p]{32}$/.test(n));
+        }
+        catch {
+            continue;
+        }
+        for (const id of ids) {
+            // Chrome keeps the previous version until restart; the highest one is current.
+            const versions = (await readdir(join(extDir, id))).filter((v) => existsSync(join(extDir, id, v, 'manifest.json'))).sort(compareVersions);
+            const v = versions.at(-1);
+            if (!v)
+                continue;
+            const dir = join(extDir, id, v);
+            const m = asObj(await readJson(join(dir, 'manifest.json')));
+            const mv = typeof m.manifest_version === 'number' ? m.manifest_version : undefined;
+            // MV2 mixes host patterns into "permissions"; split them out.
+            const perms = strings(m.permissions);
+            const isPattern = (p) => p === '<all_urls>' || p.includes('://');
+            const contentScripts = Array.isArray(m.content_scripts) ? m.content_scripts.flatMap((c) => strings(asObj(c).matches)) : [];
+            out.push({
+                host,
+                hostName,
+                kind: 'browser',
+                profile,
+                id,
+                name: (await localized(dir, m.name, m.default_locale)) ?? id,
+                version: typeof m.version === 'string' ? m.version : v,
+                path: dir,
+                permissions: sortedUnique(perms.filter((p) => !isPattern(p))),
+                hostPermissions: sortedUnique([...strings(m.host_permissions), ...perms.filter(isPattern)]),
+                optionalPermissions: sortedUnique([...strings(m.optional_permissions), ...strings(m.optional_host_permissions)]),
+                contentScriptMatches: sortedUnique(contentScripts),
+                ...(typeof m.update_url === 'string' ? { updateUrl: m.update_url } : {}),
+                ...(mv !== undefined ? { manifestVersion: mv } : {}),
+            });
+        }
+    }
+    return out;
+}
+async function firefoxExtensions(base) {
+    const out = [];
+    let profiles;
+    try {
+        profiles = (await readdir(base, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+    }
+    catch {
+        return out;
+    }
+    for (const profile of profiles) {
+        const db = asObj(await readJson(join(base, profile, 'extensions.json')));
+        for (const a of Array.isArray(db.addons) ? db.addons.map(asObj) : []) {
+            // Only add-ons the user installed: not system add-ons or built-in themes.
+            if (a.type !== 'extension' || a.location !== 'app-profile' || typeof a.id !== 'string')
+                continue;
+            // signedState 3 is "privileged": Mozilla's own add-ons (New Tab and the like), shipped by Firefox itself.
+            if (a.signedState === 3)
+                continue;
+            const user = asObj(a.userPermissions);
+            const optional = asObj(a.optionalPermissions);
+            out.push({
+                host: 'firefox',
+                hostName: 'Firefox',
+                kind: 'browser',
+                // "wm2l86yg.default-release" → "default-release"
+                profile: profile.replace(/^[a-z0-9]{8}\./, ''),
+                id: a.id,
+                name: typeof asObj(a.defaultLocale).name === 'string' ? asObj(a.defaultLocale).name : a.id,
+                version: typeof a.version === 'string' ? a.version : '?',
+                path: typeof a.path === 'string' ? a.path : join(base, profile),
+                permissions: sortedUnique(strings(user.permissions)),
+                hostPermissions: sortedUnique(strings(user.origins)),
+                optionalPermissions: sortedUnique([...strings(optional.permissions), ...strings(optional.origins)]),
+                contentScriptMatches: [],
+                ...(typeof a.updateURL === 'string' ? { updateUrl: a.updateURL } : {}),
+                active: a.active === true,
+            });
+        }
+    }
+    return out;
+}
+const MACHO = new Set([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe, 0xbebafeca]);
+/** Domains in an editor extension's code and the native binaries it ships. */
+async function scanEditorExtension(dir, budgetBytes) {
+    const hosts = new Map();
+    const native = [];
+    let used = 0;
+    const queue = [''];
+    while (queue.length) {
+        const rel = queue.pop();
+        let dirents;
+        try {
+            dirents = await readdir(join(dir, rel), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const d of dirents) {
+            const r = rel ? `${rel}/${d.name}` : d.name;
+            if (d.isDirectory()) {
+                queue.push(r);
+                continue;
+            }
+            if (!d.isFile())
+                continue;
+            const abs = join(dir, r);
+            if (d.name.endsWith('.node') || /\.(dylib|so)$/.test(d.name) || ((await lstat(abs)).mode & 0o111) !== 0) {
+                const fh = await open(abs, 'r');
+                const head = Buffer.alloc(4);
+                await fh.read(head, 0, 4, 0);
+                await fh.close();
+                if (MACHO.has(head.readUInt32BE(0)))
+                    native.push(r);
+                continue;
+            }
+            if (!isScannableText(r) || used >= budgetBytes)
+                continue;
+            const text = await readFile(abs, 'utf8');
+            used += text.length;
+            const found = extractHosts(text, r, new Map(), true);
+            // A file with over a thousand bare hostnames is a bundled list, not code.
+            const bare = [...found.values()].filter((h) => !h.viaUrl).length;
+            if (bare > 1000)
+                for (const [h, rec] of found)
+                    if (!rec.viaUrl)
+                        found.delete(h);
+            mergeHosts(hosts, found);
+        }
+    }
+    return { domains: sortedUnique([...hosts.keys()].map(registrableDomain)), nativeBinaries: native.sort() };
+}
+async function editorExtensions(base, host, hostName, scanCode) {
+    const extDir = join(base, 'extensions');
+    let dirs;
+    try {
+        dirs = (await readdir(extDir, { withFileTypes: true })).filter((d) => d.isDirectory() && !d.name.startsWith('.')).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    // Several versions can sit side by side until the editor restarts; keep the highest per id.
+    const best = new Map();
+    for (const name of dirs) {
+        const pkg = asObj(await readJson(join(extDir, name, 'package.json')));
+        if (typeof pkg.name !== 'string' || typeof pkg.version !== 'string')
+            continue;
+        const id = `${typeof pkg.publisher === 'string' ? pkg.publisher : 'unknown'}.${pkg.name}`.toLowerCase();
+        const cur = best.get(id);
+        if (!cur || compareVersions(pkg.version, cur.pkg.version) > 0)
+            best.set(id, { dir: join(extDir, name), pkg });
+    }
+    const out = [];
+    for (const [id, { dir, pkg }] of best) {
+        let display = typeof pkg.displayName === 'string' ? pkg.displayName : pkg.name;
+        const nls = /^%(.+)%$/.exec(display);
+        if (nls) {
+            const strs = asObj(await readJson(join(dir, 'package.nls.json')));
+            const v = strs[nls[1]];
+            if (typeof v === 'string')
+                display = v;
+        }
+        const code = scanCode ? await scanEditorExtension(dir, 64 * 1024 * 1024) : { domains: [], nativeBinaries: [] };
+        out.push({
+            host,
+            hostName,
+            kind: 'editor',
+            id,
+            name: display,
+            version: pkg.version,
+            path: dir,
+            permissions: [],
+            hostPermissions: [],
+            optionalPermissions: [],
+            contentScriptMatches: [],
+            ...(typeof pkg.publisher === 'string' ? { publisher: pkg.publisher } : {}),
+            activationEvents: sortedUnique(strings(pkg.activationEvents)),
+            extensionDependencies: sortedUnique(strings(pkg.extensionDependencies).map((x) => x.toLowerCase())),
+            extensionPack: sortedUnique(strings(pkg.extensionPack).map((x) => x.toLowerCase())),
+            npmDependencies: sortedUnique(Object.keys(asObj(pkg.dependencies))),
+            nativeBinaries: code.nativeBinaries,
+            domains: code.domains,
+        });
+    }
+    return out;
+}
+/** Finds installed browser and editor extensions. */
+export async function discoverExtensions(options = {}) {
+    const root = options.root ?? extensionsRoot();
+    const support = join(root, 'Library', 'Application Support');
+    const found = [];
+    for (const b of CHROMIUM)
+        found.push(...(await chromiumExtensions(join(support, b.dir), b.host, b.name)));
+    found.push(...(await firefoxExtensions(join(support, 'Firefox', 'Profiles'))));
+    for (const e of EDITORS)
+        found.push(...(await editorExtensions(join(root, e.dir), e.host, e.name, options.scanCode !== false)));
+    return found.sort((a, b) => a.hostName.localeCompare(b.hostName) || (a.profile ?? '').localeCompare(b.profile ?? '') || a.name.localeCompare(b.name));
+}
+export function extensionKey(e) {
+    return `${e.host}|${e.profile ?? ''}|${e.id}`;
+}
+// ── Risk rules ────────────────────────────────────────────────────────────────
+/** Permissions that reach browsing data, the network or other software. */
+const SENSITIVE_PERMISSIONS = new Set([
+    'cookies', 'history', 'webRequest', 'webRequestBlocking', 'debugger', 'nativeMessaging', 'management', 'proxy', 'privacy',
+    'clipboardRead', 'desktopCapture', 'tabCapture', 'browsingData', 'contentSettings', 'declarativeNetRequestWithHostAccess',
+    'webNavigation', 'downloads', 'pageCapture', 'scripting', 'userScripts', 'vpnProvider', 'certificateProvider',
+]);
+/** Permissions with little reach on their own. */
+const LOW_PERMISSIONS = new Set([
+    'storage', 'unlimitedStorage', 'alarms', 'contextMenus', 'notifications', 'offscreen', 'idle', 'sidePanel', 'i18n',
+    'fontSettings', 'power', 'tts', 'theme', 'menus', 'activeTab', 'action', 'commands',
+]);
+/** A host pattern that matches every website. */
+export function isBroadPattern(p) {
+    return p === '<all_urls>' || /^(\*|https?|wss?|file):\/\/\*?\/\*?$/.test(p) || /^(\*|https?):\/\/\*\/.*$/.test(p);
+}
+function permissionSeverity(p) {
+    if (SENSITIVE_PERMISSIONS.has(p))
+        return 'high';
+    return LOW_PERMISSIONS.has(p) ? 'info' : 'notable';
+}
+const ALWAYS_ON = new Set(['*', 'onStartupFinished']);
+function label(e) {
+    return `${e.name} (${e.hostName}${e.profile && e.profile !== 'Default' ? `, ${e.profile}` : ''})`;
+}
+function describeNew(e) {
+    if (e.kind === 'editor') {
+        const parts = [`v${e.version}`];
+        if (e.activationEvents?.some((x) => ALWAYS_ON.has(x)))
+            parts.push('starts with every window');
+        if (e.extensionPack?.length || e.extensionDependencies?.length)
+            parts.push(`pulls in ${[...(e.extensionPack ?? []), ...(e.extensionDependencies ?? [])].join(', ')}`);
+        if (e.nativeBinaries?.length)
+            parts.push(`${e.nativeBinaries.length} native binar${e.nativeBinaries.length === 1 ? 'y' : 'ies'}`);
+        return parts.join(' · ');
+    }
+    const sites = [...e.hostPermissions, ...e.contentScriptMatches];
+    return [`v${e.version}`, e.permissions.length ? `permissions: ${e.permissions.join(', ')}` : undefined, sites.length ? `sites: ${sites.some(isBroadPattern) ? 'all websites' : sites.slice(0, 5).join(', ') + (sites.length > 5 ? '…' : '')}` : undefined]
+        .filter(Boolean)
+        .join(' · ');
+}
+function added(a, b) {
+    const before = new Set(a ?? []);
+    return (b ?? []).filter((x) => !before.has(x));
+}
+function diffOne(a, b, out) {
+    const who = label(b);
+    const where = [`${b.hostName} ${b.id}`];
+    const versionNote = a.version !== b.version ? ` in ${b.version}` : '';
+    if (b.kind === 'browser') {
+        for (const p of added(a.permissions, b.permissions)) {
+            out.push({ severity: permissionSeverity(p), category: 'permission', change: 'added', title: `${who} gained the "${p}" permission${versionNote}`, where });
+        }
+        const sitesA = [...a.hostPermissions, ...a.contentScriptMatches];
+        const newSites = added(sitesA, [...b.hostPermissions, ...b.contentScriptMatches]);
+        if (newSites.some(isBroadPattern) && !sitesA.some(isBroadPattern)) {
+            out.push({ severity: 'high', category: 'permission', change: 'added', title: `${who} can now read and change all websites${versionNote}`, detail: newSites.filter(isBroadPattern).join(', '), where });
+        }
+        const specific = newSites.filter((s) => !isBroadPattern(s));
+        if (specific.length) {
+            out.push({ severity: 'notable', category: 'permission', change: 'added', title: `${who} gained access to ${specific.length} more site${specific.length === 1 ? '' : 's'}${versionNote}`, detail: specific.join(', '), where });
+        }
+        const optional = added(a.optionalPermissions, b.optionalPermissions);
+        if (optional.length)
+            out.push({ severity: 'info', category: 'permission', change: 'added', title: `${who} can now ask for more permissions later`, detail: optional.join(', '), where });
+        const lost = [...added(b.permissions, a.permissions), ...added([...b.hostPermissions, ...b.contentScriptMatches], sitesA)];
+        if (lost.length)
+            out.push({ severity: 'info', category: 'permission', change: 'removed', title: `${who} dropped permissions`, detail: lost.join(', '), where });
+        if (a.updateUrl && b.updateUrl && a.updateUrl !== b.updateUrl) {
+            out.push({ severity: 'high', category: 'updater', change: 'changed', title: `${who} now updates from a different server`, detail: `${a.updateUrl} → ${b.updateUrl}`, where });
+        }
+        if (a.manifestVersion && b.manifestVersion && a.manifestVersion !== b.manifestVersion) {
+            out.push({ severity: 'info', category: 'code', change: 'changed', title: `${who} moved to Manifest V${b.manifestVersion}`, where });
+        }
+    }
+    else {
+        const pulled = added([...(a.extensionPack ?? []), ...(a.extensionDependencies ?? [])], [...(b.extensionPack ?? []), ...(b.extensionDependencies ?? [])]);
+        if (pulled.length) {
+            out.push({ severity: 'high', category: 'install', change: 'added', title: `${who} now installs other extensions${versionNote}`, detail: pulled.join(', '), where });
+        }
+        if (!a.activationEvents?.some((x) => ALWAYS_ON.has(x)) && b.activationEvents?.some((x) => ALWAYS_ON.has(x))) {
+            out.push({ severity: 'notable', category: 'background', change: 'changed', title: `${who} now starts with every editor window${versionNote}`, detail: b.activationEvents.filter((x) => ALWAYS_ON.has(x)).join(', '), where });
+        }
+        const npm = added(a.npmDependencies, b.npmDependencies);
+        if (npm.length)
+            out.push({ severity: 'notable', category: 'package', change: 'added', title: `${who} bundles ${npm.length} new npm package${npm.length === 1 ? '' : 's'}${versionNote}`, detail: npm.join(', '), where });
+        const bins = added(a.nativeBinaries, b.nativeBinaries);
+        if (bins.length)
+            out.push({ severity: 'notable', category: 'code', change: 'added', title: `${who} ships new native code${versionNote}`, detail: bins.join(', '), where });
+        const domains = added(a.domains, b.domains);
+        if (domains.length)
+            out.push({ severity: 'notable', category: 'host', change: 'added', title: `${who} mentions new domains${versionNote}`, detail: domains.join(', '), where });
+    }
+    if (a.version !== b.version)
+        out.push({ severity: 'info', category: 'identity', change: 'changed', title: `${who} ${a.version} → ${b.version}`, where });
+}
+/** What changed among installed extensions between two snapshots. */
+export function diffExtensions(a, b) {
+    const findings = [];
+    const before = new Map(a.extensions.map((e) => [extensionKey(e), e]));
+    for (const e of b.extensions) {
+        const old = before.get(extensionKey(e));
+        before.delete(extensionKey(e));
+        if (!old) {
+            const broad = [...e.hostPermissions, ...e.contentScriptMatches].some(isBroadPattern);
+            const pulls = (e.extensionPack?.length ?? 0) + (e.extensionDependencies?.length ?? 0) > 0;
+            findings.push({
+                severity: broad || pulls ? 'high' : 'notable',
+                category: 'install',
+                change: 'added',
+                title: `New extension: ${label(e)}${broad ? ' with access to all websites' : ''}`,
+                detail: describeNew(e),
+                where: [`${e.hostName} ${e.id}`],
+            });
+            continue;
+        }
+        diffOne(old, e, findings);
+    }
+    for (const gone of before.values())
+        findings.push({ severity: 'info', category: 'install', change: 'removed', title: `Removed extension: ${label(gone)}` });
+    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]++;
+    const side = (s) => ({ version: `${s.extensions.length} extensions`, build: '', takenAt: s.takenAt, path: '' });
+    return {
+        app: { name: 'Browser and editor extensions', bundleId: '' },
+        from: side(a),
+        to: side(b),
+        findings,
+        counts,
+        identical: findings.length === 0,
+    };
+}
+/** A readable list of installed extensions with what each one can reach. */
+export function renderExtensions(list, options = {}) {
+    const warn = (s) => (options.color ? `\x1b[33m${s}\x1b[39m` : s);
+    const dim = (s) => (options.color ? `\x1b[2m${s}\x1b[22m` : s);
+    const bold = (s) => (options.color ? `\x1b[1m${s}\x1b[22m` : s);
+    const lines = [];
+    let group = '';
+    for (const e of list) {
+        const g = `${e.hostName}${e.profile ? ` · ${e.profile}` : ''}`;
+        if (g !== group) {
+            lines.push('', bold(g));
+            group = g;
+        }
+        const notes = [];
+        if (e.kind === 'browser') {
+            if ([...e.hostPermissions, ...e.contentScriptMatches].some(isBroadPattern))
+                notes.push(warn('all websites'));
+            else if (e.hostPermissions.length + e.contentScriptMatches.length) {
+                const n = e.hostPermissions.length + e.contentScriptMatches.length;
+                notes.push(`${n} site${n === 1 ? '' : 's'}`);
+            }
+            const sensitive = e.permissions.filter((p) => SENSITIVE_PERMISSIONS.has(p));
+            if (sensitive.length)
+                notes.push(warn(sensitive.join(', ')));
+            if (e.active === false)
+                notes.push(dim('disabled'));
+        }
+        else {
+            if (e.activationEvents?.some((x) => ALWAYS_ON.has(x)))
+                notes.push(warn('starts with every window'));
+            if (e.nativeBinaries?.length)
+                notes.push(`${e.nativeBinaries.length} native binar${e.nativeBinaries.length === 1 ? 'y' : 'ies'}`);
+            if (e.domains?.length)
+                notes.push(`${e.domains.length} domains in code`);
+        }
+        lines.push(`  ${e.name.slice(0, 44).padEnd(44)} ${e.version.slice(0, 16).padEnd(16)} ${notes.join(dim(' · '))}`);
+    }
+    if (!list.length)
+        lines.push('', 'No browser or editor extensions found.');
+    lines.push('', dim(`${list.length} extension${list.length === 1 ? '' : 's'}. Browsers: Chrome, Brave, Edge, Arc, Vivaldi, Chromium, Firefox. Editors: VS Code, Cursor, Windsurf, VSCodium.`));
+    return lines.join('\n').replace(/^\n/, '') + '\n';
+}

package/dist/fetch.js

@@ -0,0 +1,81 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { scanBundle } from "./bundle.js";
+import { fetchCask, urlForVersion } from "./cask.js";
+import { caskHistory } from "./cask-history.js";
+import { download, extractApp } from "./installer.js";
+/** Turns an app name into the cask token Homebrew would likely use: "Google Chrome" → "google-chrome". */
+export function guessCaskToken(name) {
+    return name
+        .replace(/\.app$/i, '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9@.+]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** Finds the cask for an app: an explicit token first, then guesses from the names given. */
+export async function resolveCask(candidates) {
+    const tried = [];
+    for (const c of candidates) {
+        const token = guessCaskToken(c);
+        if (!token || tried.includes(token))
+            continue;
+        tried.push(token);
+        try {
+            return await fetchCask(token);
+        }
+        catch {
+            // Try the next guess.
+        }
+    }
+    throw new Error(`No Homebrew cask found for ${tried.map((t) => `"${t}"`).join(' or ')}. Pass the cask's name with --cask (see https://formulae.brew.sh/cask/).`);
+}
+/** The cask's version string matched loosely against an app version ("1.172.0" matches "1.172.0,90280"). */
+export function sameVersion(caskVersion, appVersion) {
+    if (!appVersion)
+        return false;
+    return caskVersion === appVersion || caskVersion.split(',')[0] === appVersion;
+}
+/** Picks the release to fetch: the one asked for, or the one before the installed (or current) version. */
+export function pickRelease(releases, wanted, installedVersion) {
+    if (wanted) {
+        const hit = releases.find((r) => r.version === wanted) ?? releases.find((r) => sameVersion(r.version, wanted));
+        if (!hit)
+            throw new Error(`Version ${wanted} isn't in the cask's recent history. Run with --list to see the versions there are.`);
+        return hit;
+    }
+    const installedAt = releases.findIndex((r) => sameVersion(r.version, installedVersion));
+    const pick = installedAt >= 0 ? releases[installedAt + 1] : releases[1];
+    if (!pick)
+        throw new Error('The cask has no earlier release in its recent history.');
+    return pick;
+}
+/** Downloads a past release, checks it against the cask's checksum, and scans it. Nothing is installed or run. */
+export async function fetchRelease(info, release, options = {}) {
+    const log = options.log ?? (() => { });
+    const url = release.url ?? urlForVersion(info, release.version);
+    if (!url)
+        throw new Error(`Can't work out the download URL for ${info.name} ${release.version} from the cask.`);
+    const work = await mkdtemp(join(tmpdir(), 'updiff-fetch-'));
+    try {
+        log(`Downloading ${info.name} ${release.version} from ${url}`);
+        const dl = await download(url, join(work, 'download'), { maxBytes: options.maxBytes ?? 3 * 1024 ** 3, expectedSha256: release.sha256 });
+        log(release.sha256 ? `Checksum matches the cask (${dl.sha256.slice(0, 12)}…)` : `The cask doesn't pin a checksum for this release (${dl.sha256.slice(0, 12)}…)`);
+        const extracted = await extractApp(dl.file, join(work, 'x'), info.appNames);
+        let snapshot;
+        try {
+            log(`Scanning ${extracted.appPath.slice(extracted.appPath.lastIndexOf('/') + 1)} from the ${extracted.kind}`);
+            snapshot = await scanBundle(extracted.appPath, options.scan);
+        }
+        finally {
+            await extracted.cleanup();
+        }
+        snapshot.app.path = `${info.name} ${release.version} (Homebrew cask ${info.token} at ${release.commit.slice(0, 7)})`;
+        return { snapshot, release, info, url, verified: release.sha256 !== null, bytes: dl.bytes };
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+export { caskHistory };

package/dist/hosts.js

@@ -0,0 +1,137 @@
+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;
+}
+// Only characters that may appear in a URL path: binaries separate strings with NUL bytes.
+const URL_FULL_RE = /\bhttps?:\/\/[a-z0-9.-]+(?::\d+)?\/[A-Za-z0-9._~%\/?=&+:@!$,;#-]*/gi;
+/**
+ * Finds Sparkle update feeds in code: URLs with "appcast" in them, or, when the app
+ * bundles Sparkle, .xml URLs whose path mentions updates or releases.
+ */
+export function extractFeedUrls(text, sparkle, into = new Set()) {
+    for (const m of text.matchAll(URL_FULL_RE)) {
+        const url = m[0].replace(/[.,;:]+$/, '');
+        const lower = url.toLowerCase();
+        const isAppcast = lower.includes('appcast');
+        const isUpdateXml = sparkle && /\.xml(\?|$)/.test(lower) && /(update|sparkle|release)/.test(lower);
+        if ((isAppcast || isUpdateXml) && !isIgnoredHost(new URL(url).hostname))
+            into.add(url);
+    }
+    return into;
+}