@intincrab/updiff 0.1.1 → 0.2.0

package/README.md

@@ -16,10 +16,14 @@ camera, register something that starts at login, ship a new helper that runs as
 bundle a new analytics package, or start talking to a new service. updiff takes a
 snapshot of each app and, after every update, shows you exactly what changed inside it.
 
-- **Read-only.** It never runs the app, never changes it and never touches the network.
-- **Local.** Snapshots and reports stay in `~/.updiff`. Nothing is uploaded.
-- **Fast.** The first snapshot of 28 apps took 11 s on an Apple Silicon Mac; later checks
-  skip unchanged apps and take about 0.1 s.
+It also covers what updates without asking: **browser and editor extensions**, and
+**installer packages** you're about to run.
+
+- **Read-only.** It never runs the app, an installer or its scripts, and never changes them.
+- **Local.** Snapshots and reports stay in `~/.updiff`. Nothing is uploaded. Only `fetch`
+  downloads anything, and Gatekeeper may ask Apple whether an app is notarized.
+- **Fast.** The first snapshot of 28 apps takes about 40 s on an Apple Silicon Mac (11 s
+  with `--no-gatekeeper`); later checks skip unchanged apps and take about 0.1 s.
 
 ## What it looks like
 
@@ -131,7 +135,27 @@ updiff agent install     # runs `updiff check` whenever your app folders change
 
 The agent waits until an update has finished writing, then posts a notification titled
 "Updiff: Google Chrome 156.0.8078.80" that says "0 high, 2 notable changes". The full
-report is saved in `~/.updiff/reports/`.
+report is saved in `~/.updiff/reports/`. It also checks your browser and editor extensions.
+
+No baseline yet? Compare an installed app with its previous release, downloaded from
+Homebrew's history and checked against the checksum Homebrew recorded:
+
+```bash
+updiff fetch Ghostty     # Ghostty 1.3.0 → 1.3.1: 0 high · 0 notable · 2 info
+```
+
+Before running an installer, see what it would do:
+
+```bash
+updiff pkg ~/Downloads/Installer.pkg
+```
+
+And see what your extensions can reach, or what changed since last time:
+
+```bash
+updiff extensions
+updiff extensions check
+```
 
 ## Commands
 
@@ -143,6 +167,9 @@ report is saved in `~/.updiff/reports/`.
 | `updiff diff <app>` | If the installed app changed since its newest snapshot, compare the two; otherwise compare its two newest snapshots. |
 | `updiff diff <a> <b>` | Compare any two things: `.app` bundles, snapshot `.json` files or stored apps. Good for a downloaded beta against the installed version. |
 | `updiff list [app]` | List stored apps, or one app's snapshots. |
+| `updiff fetch <app> [version]` | Download an earlier release from the app's Homebrew cask history, verify it against the checksum Homebrew pinned, store it as a snapshot and compare it with the installed app. With no version, the release before the installed one. `--list` shows the history. |
+| `updiff pkg <installer.pkg> [older.pkg]` | Show what an installer package would do before you run it: scripts with their text, installer JavaScript, apps, launch daemons and agents (including ones apps register from inside their bundle), privileged helpers, system extensions, everything written outside /Applications, signature and Gatekeeper's verdict. With two packages, what changed. Nothing is installed or run. |
+| `updiff extensions [check]` | List browser and editor extensions with what they can reach. `check` reports what changed since the last check. |
 | `updiff agent install \| uninstall \| status` | Manage the LaunchAgent that runs `check` after updates. |
 
 `<app>` can be a path (`/Applications/Slack.app`), a name from your Applications folders
@@ -162,6 +189,10 @@ report is saved in `~/.updiff/reports/`.
 | `--home <dir>` | all | Data folder. Default `~/.updiff`, or `$UPDIFF_HOME`. |
 | `--keep <n>` | `snapshot`, `check` | Snapshots kept per app (default 10). |
 | `--notify` | `check` | Post a notification for each updated app. |
+| `--extensions` | `check` | Also check browser and editor extensions (the agent does). |
+| `--no-gatekeeper` | scanning | Skip the Gatekeeper/notarization check (faster). |
+| `--cask <name>` | `fetch` | The Homebrew cask, when it isn't the app's name. |
+| `--list` | `fetch` | List the releases in the cask's history. |
 | `--settle <seconds>` | `check` | Wait until no app has changed for this long before scanning. |
 | `--quiet`, `--no-color` | all | Print less; plain text. `NO_COLOR` is respected too. |
 | `--interval <seconds>` | `agent install` | Fallback timer between checks (default 21600, i.e. 6 hours). |
@@ -174,17 +205,26 @@ Exit codes: `0` success, `2` usage error (unknown app, bad option), `1` unexpect
 
 | | High | Notable | Info |
 |---|---|---|---|
-| **Signing** | different developer team; no longer developer-signed; hardened runtime removed | signing certificate changed | hardened runtime added |
+| **Signing** | different developer team; no longer developer-signed; hardened runtime removed; no longer notarized; Gatekeeper rejects it or can't verify its signature | signing certificate changed; distribution changed (Developer ID ↔ App Store) | hardened runtime added; notarization ticket stapled or unstapled |
 | **Entitlements**, for every executable in the bundle | camera, microphone, location, contacts, calendars, photos, Apple Events, USB, Bluetooth, library validation off, debugging, Endpoint Security, network extensions, sandbox exceptions; sandbox removed | any other new entitlement; new values in app groups, keychain groups or associated domains | removals |
 | **Privacy prompts** (`NS…UsageDescription`) | a new prompt | | reworded or removed prompts |
 | **Background** | new LaunchAgent or LaunchDaemon, login item, privileged helper, system extension | changed background item | removals |
-| **Updater** (Sparkle) | update feed moved; update signing key changed | feed added or removed | |
+| **Updater** (Sparkle) | update feed moved; update signing key changed | feed added or removed; feed set in the code changed | |
 | **Network** | App Transport Security allows plain HTTP | new ATS exception domains | |
 | **Code** | | new helper apps, XPC services, app extensions, plug-ins, executables, native Node modules, frameworks | framework versions; removals |
 | **Electron** | | Electron version; new bundled npm packages | package version changes and removals |
 | **Hostnames** | | new domains | new hosts under domains already present; domains no longer mentioned |
 | **URL schemes** | | new `scheme://` handlers | removals |
-| **Identity** | the two sides are different apps | Dock icon shown or hidden | version, minimum macOS, size |
+| **Identity** | the two sides are different apps | Dock icon shown or hidden; moved to or from the Mac App Store | version, minimum macOS, size |
+| **Browser extensions** | access to all websites; sensitive APIs (cookies, history, webRequest, debugger, nativeMessaging, proxy…); a different update server; a new extension with access to all websites | other new permissions; access to specific new sites; a new extension | low-reach permissions (storage, alarms…); optional permissions; removals; versions |
+| **Editor extensions** (VS Code, Cursor, Windsurf, VSCodium) | starts installing other extensions | now starts with every window; new npm packages; new native code; new domains in the code; a new extension | removals; versions |
+
+Gatekeeper's verdict comes from `spctl`, which may contact Apple for apps without a
+stapled notarization ticket. Sparkle feeds are read from `Info.plist` and, for apps that
+set them in code (Ghostty, ChatGPT), from URLs in the binary; `scan` also shows this Mac's
+update settings for the app. Binaries that are FairPlay-encrypted (iPhone and iPad apps)
+are flagged, because their strings can't be read. Mac App Store apps for macOS are not
+encrypted, so their hostnames are read like any other app's.
 
 Code inside a bundle is matched between versions by its path and, if that fails, by its
 bundle id. So a renamed helper isn't reported as removed plus added, and Chrome's
@@ -217,6 +257,8 @@ Framework binaries are only searched with `--deep`. Electron apps keep their own
 ~/.updiff/
 ├── snapshots/<bundle id>/<time>__<version>__<build>.json   one JSON file per snapshot
 ├── reports/<bundle id>/<time>__<from>__to__<to>.md         one report per detected update
+├── extensions/<time>.json                                  installed extensions (last 10)
+├── reports/extensions/<time>__<from>__to__<to>.md          one report per extension change
 └── agent.log                                               output of background checks
 ```
 
@@ -227,12 +269,14 @@ Delete the folder at any time to start over.
 ## Privacy and safety
 
 - updiff reads files and runs Apple's own tools:
-  - `plutil` to read plists
-  - `codesign` to read signatures and entitlements
-  - `osascript` for notifications
-  - `launchctl` for the agent
-- It never runs app code.
-- It never makes network requests, and nothing it records leaves your Mac.
+  - `plutil` and `defaults` to read plists and an app's update settings
+  - `codesign`, `spctl` and `stapler` to read signatures, Gatekeeper's verdict and
+    notarization tickets
+  - `hdiutil` (read-only) and `pkgutil --expand-full` to open disk images and packages
+  - `osascript` for notifications, `launchctl` for the agent
+- It never runs app code, installer scripts or installer JavaScript.
+- Nothing it records leaves your Mac. `fetch` downloads from Homebrew, GitHub and the
+  app's vendor; `spctl` may ask Apple about notarization. Nothing else uses the network.
 - The agent is a LaunchAgent in your user account (`dev.updiff.check`). It runs with your
   permissions, at low priority. `updiff agent install --dry-run` shows exactly what it
   installs; `updiff agent uninstall` removes it.
@@ -243,10 +287,12 @@ Delete the folder at any time to start over.
   the bundle, so updiff can't see them.
 - **Hostnames are pattern-matched.** Hosts assembled at runtime (`"api." + region + ".x.com"`)
   are missed, and a mentioned host is not necessarily contacted.
-- **The first update needs a baseline.** Run `updiff snapshot` before updating. You can
-  also diff a downloaded copy of the old version against the installed one.
-- **Not covered yet:** Mac App Store receipts, Safari web extension manifests, managed
-  browser policies and installer `.pkg` scripts.
+- **Baselines.** `check` compares with the last snapshot. For an app you never snapshotted,
+  `updiff fetch` gets its previous release, if the app is in Homebrew.
+- **Update feeds built at runtime** (AltTab assembles its URL from pieces) can't be found;
+  `scan` says when Sparkle is bundled but no feed was found.
+- **Not covered yet:** Safari web extensions' permissions, managed browser policies, and
+  extensions for JetBrains IDEs.
 
 ## The ledger
 

package/dist/agent.js

@@ -9,7 +9,7 @@ export function launchAgentsDir() {
     return process.env.UPDIFF_LAUNCH_AGENTS_DIR || join(homedir(), 'Library', 'LaunchAgents');
 }
 export function agentPlist(o) {
-    const args = [o.nodePath, o.cliPath, 'check', '--notify', '--quiet', '--settle', '90', '--home', o.home];
+    const args = [o.nodePath, o.cliPath, 'check', '--extensions', '--notify', '--quiet', '--settle', '90', '--home', o.home];
     for (const d of o.appsDirs)
         args.push('--apps-dir', d);
     return toPlistXml({

package/dist/bundle.js

@@ -2,9 +2,11 @@ import { createHash } from 'node:crypto';
 import { open, readdir, readFile, readlink, lstat, realpath, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { AsarArchive } from "./asar.js";
-import { readEntitlements, readSigning } from "./codesign.js";
-import { extractHosts, mergeHosts } from "./hosts.js";
-import { isDict, readPlistFile, str } from "./plist.js";
+import { readEntitlements, readNotarization, readSigning } from "./codesign.js";
+import { run } from "./exec.js";
+import { extractFeedUrls, extractHosts, mergeHosts } from "./hosts.js";
+import { isEncryptedMachO } from "./macho.js";
+import { isDict, parsePlistXml, readPlistFile, str } from "./plist.js";
 import { SNAPSHOT_SCHEMA, } from "./types.js";
 import { mapLimit, sortedUnique } from "./util.js";
 import { TOOL_NAME, TOOL_VERSION } from "./version.js";
@@ -208,6 +210,35 @@ async function fingerprintOf(appPath, infoPath, mainExe) {
     }
     return hash.digest('hex').slice(0, 32);
 }
+/** This Mac's update settings for an app, from its user defaults domain. */
+async function readLocalSettings(bundleId) {
+    if (!bundleId)
+        return {};
+    const res = await run('/usr/bin/defaults', ['export', bundleId, '-']);
+    if (res.code !== 0)
+        return {};
+    let prefs = {};
+    try {
+        const value = parsePlistXml(res.stdout);
+        if (isDict(value))
+            prefs = value;
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    const feed = str(prefs.SUFeedURL);
+    if (feed)
+        out.sparkleFeedInDefaults = feed;
+    const flag = (v) => v === undefined ? undefined : v === true || v === 1 || v === '1' || v === 'YES';
+    const checks = flag(prefs.SUEnableAutomaticChecks);
+    const auto = flag(prefs.SUAutomaticallyUpdate);
+    if (checks !== undefined)
+        out.sparkleAutomaticChecks = checks;
+    if (auto !== undefined)
+        out.sparkleAutomaticallyUpdate = auto;
+    return out;
+}
 /** Reads the Info.plist identity of a bundle without scanning it. */
 export async function readIdentity(appPath) {
     const info = await readPlistFile(join(appPath, 'Contents/Info.plist'));
@@ -275,6 +306,10 @@ class HostScanner {
     truncatedFiles = [];
     domainLists = [];
     totalLimitHit = false;
+    /** Set once the bundle is known to ship Sparkle; widens what counts as an update feed. */
+    sparkle = false;
+    feeds = new Set();
+    encrypted = [];
     maxFile;
     maxTotal;
     constructor(maxFile, maxTotal) {
@@ -309,7 +344,9 @@ class HostScanner {
     scanBuffer(buf, where, binary) {
         this.filesScanned++;
         this.bytesScanned += buf.length;
-        this.commit(extractHosts(buf.toString(binary ? 'latin1' : 'utf8'), where, new Map(), true), where);
+        const text = buf.toString(binary ? 'latin1' : 'utf8');
+        extractFeedUrls(text, this.sparkle, this.feeds);
+        this.commit(extractHosts(text, where, new Map(), true), where);
     }
     async scanFile(abs, size, where, binary) {
         let fh;
@@ -325,6 +362,12 @@ class HostScanner {
                 if (slice)
                     ({ offset: start, size: length } = slice);
             }
+            if (binary) {
+                const head = Buffer.alloc(Math.min(65536, length));
+                const { bytesRead } = await fh.read(head, 0, head.length, start);
+                if (isEncryptedMachO(head.subarray(0, bytesRead)))
+                    this.encrypted.push(where);
+            }
             const n = this.budget(length, where);
             if (n <= 0)
                 return;
@@ -337,7 +380,9 @@ class HostScanner {
                 const buf = Buffer.alloc(len);
                 const { bytesRead } = await fh.read(buf, 0, len, start + pos);
                 this.bytesScanned += Math.min(bytesRead, CHUNK);
-                extractHosts(buf.toString(binary ? 'latin1' : 'utf8', 0, bytesRead), where, found, true);
+                const text = buf.toString(binary ? 'latin1' : 'utf8', 0, bytesRead);
+                extractFeedUrls(text, this.sparkle, this.feeds);
+                extractHosts(text, where, found, true);
                 if (bytesRead < len)
                     break;
             }
@@ -443,6 +488,8 @@ export async function scanBundle(inputPath, options = {}) {
         return item;
     });
     // Privileged helpers installed through SMJobBless.
+    scanner.sparkle = nestedItems.some((c) => c.kind === 'framework' && c.path.endsWith('/Sparkle.framework'));
+    summary.appStoreReceipt = entries.some((e) => e.rel === 'Contents/_MASReceipt');
     const helperFiles = files.filter((f) => /(^|\/)Contents\/Library\/LaunchServices\/[^/]+$/.test(f.rel));
     const helperItems = await mapLimit(helperFiles, 4, async (f) => {
         bundleExecutables.add(f.rel);
@@ -592,6 +639,14 @@ export async function scanBundle(inputPath, options = {}) {
     for (const list of scanner.domainLists) {
         warnings.push(`Skipped ${list.count} bare hostnames in ${list.where}: it looks like a bundled domain list, not code.`);
     }
+    if (scanner.encrypted.length) {
+        warnings.push(`${scanner.encrypted.length} binar${scanner.encrypted.length === 1 ? 'y is' : 'ies are'} encrypted (an iPhone or iPad app): hostnames inside can't be read (${scanner.encrypted.slice(0, 3).join(', ')}).`);
+    }
+    const feedsInCode = [...scanner.feeds].filter((u) => u !== summary.sparkleFeedUrl).sort();
+    if (feedsInCode.length)
+        summary.sparkleFeedsInCode = feedsInCode.slice(0, 10);
+    const notarization = options.notarization === false ? undefined : await readNotarization(appPath);
+    const local = options.userDefaults ? await readLocalSettings(str(info.CFBundleIdentifier)) : undefined;
     const hosts = {};
     for (const host of [...scanner.hosts.keys()].sort())
         hosts[host] = scanner.hosts.get(host);
@@ -617,6 +672,9 @@ export async function scanBundle(inputPath, options = {}) {
         backgroundItems,
         electron,
         hosts,
+        ...(notarization ? { notarization } : {}),
+        ...(scanner.encrypted.length ? { encryptedBinaries: [...scanner.encrypted].sort() } : {}),
+        ...(local && Object.keys(local).length ? { local } : {}),
         stats: {
             scanMs: Date.now() - started,
             filesScanned: scanner.filesScanned,

package/dist/cask-history.js

@@ -0,0 +1,216 @@
+import { fetchCask } from "./cask.js";
+import { mapLimit } from "./util.js";
+import { TOOL_VERSION } from "./version.js";
+const OLDER_ONLY = /:or_older/;
+/**
+ * Keeps the lines of a cask that apply to a current Apple silicon Mac: `on_arm` and
+ * `on_<macOS> :or_newer` blocks and top-level stanzas. Drops `on_intel`, blocks for
+ * older macOS versions, and blocks such as `livecheck`, `zap` and `uninstall`.
+ */
+function linesForThisMac(source) {
+    const kept = [];
+    const stack = [];
+    for (const line of source.split('\n')) {
+        const opens = /^\s*(\S+)(.*?)\bdo(\s*\|[^|]*\|)?\s*$/.exec(line);
+        if (opens) {
+            const name = opens[1];
+            const args = opens[2] ?? '';
+            let keep;
+            if (name === 'cask')
+                keep = true;
+            else if (name === 'on_arm')
+                keep = true;
+            else if (name === 'on_intel')
+                keep = false;
+            else if (/^on_[a-z_]+$/.test(name) && name !== 'on_arm')
+                keep = /:or_newer/.test(args) && !OLDER_ONLY.test(args);
+            else
+                keep = false;
+            stack.push(keep);
+            continue;
+        }
+        if (/^\s*end\s*$/.test(line)) {
+            stack.pop();
+            continue;
+        }
+        if (stack.every(Boolean))
+            kept.push(line);
+    }
+    return kept;
+}
+/** The last `version` stanza outside livecheck, for casks that only set it inside OS blocks. */
+function lastVersionAnywhere(source) {
+    const withoutLivecheck = source.replace(/\n\s*livecheck do[\s\S]*?\n\s*end\b/g, '\n');
+    const all = [...withoutLivecheck.matchAll(/^\s*version\s+"([^"]+)"/gm)];
+    return all.at(-1)?.[1];
+}
+/** Reads version, URL template, checksum and arch from a cask's Ruby source. */
+export function parseCaskSource(source) {
+    const text = linesForThisMac(source).join('\n');
+    const version = /^\s*version\s+"([^"]+)"/m.exec(text)?.[1] ?? lastVersionAnywhere(source);
+    const url = /^\s*url\s+"([^"]+)"/m.exec(text)?.[1];
+    const shaArm = /sha256\s+arm:\s*"([0-9a-f]{64})"/i.exec(text)?.[1];
+    const shaOne = /^\s*sha256\s+"([0-9a-f]{64})"/im.exec(text)?.[1];
+    const arch = /^\s*arch\s+arm:\s*"([^"]*)"/m.exec(source)?.[1];
+    return { version, url, sha256: (shaArm ?? shaOne)?.toLowerCase() ?? null, arch };
+}
+/** Applies a chain of Homebrew version methods: `version.csv.first.no_dots`. */
+export function applyVersionMethods(version, chain) {
+    let value = version;
+    for (const method of chain) {
+        const s = Array.isArray(value) ? undefined : value;
+        switch (method) {
+            case 'csv':
+                if (s === undefined)
+                    return undefined;
+                value = s.split(',');
+                break;
+            case 'first':
+            case 'second':
+            case 'third': {
+                if (!Array.isArray(value))
+                    return undefined;
+                const item = value[['first', 'second', 'third'].indexOf(method)];
+                if (item === undefined)
+                    return undefined;
+                value = item;
+                break;
+            }
+            case 'before_comma':
+                if (s === undefined)
+                    return undefined;
+                value = s.split(',')[0];
+                break;
+            case 'after_comma': {
+                const after = s?.split(',')[1];
+                if (after === undefined)
+                    return undefined;
+                value = after;
+                break;
+            }
+            case 'major':
+            case 'minor':
+            case 'patch': {
+                const part = s?.split(/[.,-]/)[['major', 'minor', 'patch'].indexOf(method)];
+                if (part === undefined)
+                    return undefined;
+                value = part;
+                break;
+            }
+            case 'major_minor':
+            case 'major_minor_patch': {
+                if (s === undefined)
+                    return undefined;
+                value = s.split('.').slice(0, method === 'major_minor' ? 2 : 3).join('.');
+                break;
+            }
+            case 'no_dots':
+                if (s === undefined)
+                    return undefined;
+                value = s.replace(/\./g, '');
+                break;
+            case 'dots_to_underscores':
+                if (s === undefined)
+                    return undefined;
+                value = s.replace(/\./g, '_');
+                break;
+            case 'dots_to_hyphens':
+                if (s === undefined)
+                    return undefined;
+                value = s.replace(/\./g, '-');
+                break;
+            case 'no_hyphens':
+                if (s === undefined)
+                    return undefined;
+                value = s.replace(/-/g, '');
+                break;
+            default:
+                return undefined;
+        }
+    }
+    return Array.isArray(value) ? undefined : value;
+}
+/** Fills `#{version…}` and `#{arch}` in a cask URL. Undefined if anything is left unresolved. */
+export function resolveCaskUrl(template, version, arch) {
+    let unresolved = false;
+    const url = template.replace(/#\{([^}]+)\}/g, (_, expr) => {
+        const e = expr.trim();
+        if (e === 'arch') {
+            if (arch === undefined)
+                unresolved = true;
+            return arch ?? '';
+        }
+        const parts = e.split('.');
+        if (parts[0] !== 'version') {
+            unresolved = true;
+            return '';
+        }
+        const value = applyVersionMethods(version, parts.slice(1));
+        if (value === undefined)
+            unresolved = true;
+        return value ?? '';
+    });
+    return unresolved ? undefined : url;
+}
+export function githubApiBase() {
+    return (process.env.UPDIFF_GITHUB_API ?? 'https://api.github.com').replace(/\/$/, '');
+}
+export function githubRawBase() {
+    return (process.env.UPDIFF_GITHUB_RAW ?? 'https://raw.githubusercontent.com').replace(/\/$/, '');
+}
+function githubHeaders() {
+    const headers = { 'user-agent': `updiff/${TOOL_VERSION}`, accept: 'application/vnd.github+json' };
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    return headers;
+}
+/**
+ * Past releases of a cask, newest first: walks the commits that touched the cask
+ * file in Homebrew/homebrew-cask and reads the cask at each one.
+ */
+export async function caskHistory(token, options = {}) {
+    const info = options.info ?? (await fetchCask(token));
+    if (!info.sourcePath)
+        throw new Error(`The Homebrew API did not say where the ${token} cask lives.`);
+    const perPage = Math.min(Math.max(options.commits ?? 60, 1), 100);
+    const res = await fetch(`${githubApiBase()}/repos/Homebrew/homebrew-cask/commits?path=${encodeURIComponent(info.sourcePath)}&per_page=${perPage}`, { headers: githubHeaders(), signal: AbortSignal.timeout(30_000) });
+    if (res.status === 403 || res.status === 429) {
+        throw new Error('GitHub is rate-limiting history lookups (60 an hour without a token). Set GITHUB_TOKEN to raise the limit, or try again later.');
+    }
+    if (!res.ok)
+        throw new Error(`GitHub answered HTTP ${res.status} for the ${token} cask's history.`);
+    const commits = (await res.json());
+    const parsed = await mapLimit(commits, 6, async (c) => {
+        const raw = await fetch(`${githubRawBase()}/Homebrew/homebrew-cask/${c.sha}/${info.sourcePath}`, {
+            headers: { 'user-agent': `updiff/${TOOL_VERSION}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+        // A commit can delete or move the file; skip it.
+        if (!raw.ok)
+            return undefined;
+        const cask = parseCaskSource(await raw.text());
+        if (!cask.version || cask.version === 'latest')
+            return undefined;
+        const release = {
+            version: cask.version,
+            sha256: cask.sha256,
+            commit: c.sha,
+            date: c.commit.committer?.date ?? c.commit.author?.date ?? '',
+        };
+        const url = cask.url ? resolveCaskUrl(cask.url, cask.version, cask.arch) : undefined;
+        if (url)
+            release.url = url;
+        return release;
+    });
+    // Commits come newest first; keep the newest commit for each version.
+    const releases = [];
+    const seen = new Set();
+    for (const r of parsed) {
+        if (!r || seen.has(r.version))
+            continue;
+        seen.add(r.version);
+        releases.push(r);
+    }
+    return { info, releases };
+}

package/dist/cask.js

@@ -0,0 +1,79 @@
+export function caskApiBase() {
+    return (process.env.UPDIFF_CASK_API ?? process.env.LEDGER_CASK_API ?? 'https://formulae.brew.sh/api/cask').replace(/\/$/, '');
+}
+function firstStrings(artifacts, key) {
+    const out = [];
+    for (const a of artifacts) {
+        const v = a[key];
+        if (!Array.isArray(v))
+            continue;
+        // Each entry is ["Name.app"] or ["Name.app", { target: "..." }].
+        for (const item of v) {
+            if (typeof item === 'string')
+                out.push(item);
+            else if (Array.isArray(item) && typeof item[0] === 'string')
+                out.push(item[0]);
+        }
+    }
+    return out;
+}
+/** Turns a cask API document into the fields the ledger needs. */
+export function parseCask(json) {
+    const j = json;
+    if (typeof j?.token !== 'string' || typeof j.version !== 'string' || typeof j.url !== 'string') {
+        throw new Error('Not a Homebrew cask document');
+    }
+    const artifacts = Array.isArray(j.artifacts) ? j.artifacts : [];
+    const names = Array.isArray(j.name) ? j.name : [];
+    const sha = typeof j.sha256 === 'string' && /^[0-9a-f]{64}$/i.test(j.sha256) ? j.sha256.toLowerCase() : null;
+    return {
+        token: j.token,
+        name: typeof names[0] === 'string' ? names[0] : j.token,
+        desc: typeof j.desc === 'string' ? j.desc : undefined,
+        homepage: typeof j.homepage === 'string' ? j.homepage : undefined,
+        version: j.version,
+        url: j.url,
+        sha256: sha,
+        appNames: firstStrings(artifacts, 'app'),
+        pkgNames: firstStrings(artifacts, 'pkg'),
+        sourcePath: typeof j.ruby_source_path === 'string' ? j.ruby_source_path : undefined,
+    };
+}
+export async function fetchCask(token) {
+    if (!/^[a-z0-9@._+-]+$/.test(token))
+        throw new Error(`Invalid cask token "${token}"`);
+    const res = await fetch(`${caskApiBase()}/${token}.json`, { signal: AbortSignal.timeout(30_000) });
+    if (!res.ok)
+        throw new Error(`Cask "${token}": HTTP ${res.status} from the Homebrew API`);
+    return parseCask(await res.json());
+}
+/** The forms a version can take inside a download URL. */
+function versionForms(version) {
+    const forms = [version, version.replace(/\./g, '_'), version.replace(/\./g, '-')];
+    return [...new Set(forms)];
+}
+/**
+ * Best-effort URL of another release: substitutes `version` for the cask's current
+ * version (and each part of comma-separated versions such as "1.2.3,456") in the
+ * current download URL. Returns undefined when the URL does not contain the version.
+ */
+export function urlForVersion(info, version) {
+    const currentParts = info.version.split(',');
+    const nextParts = version.split(',');
+    if (currentParts.length !== nextParts.length)
+        return undefined;
+    let url = info.url;
+    let replaced = false;
+    for (let i = 0; i < currentParts.length; i++) {
+        const from = versionForms(currentParts[i]);
+        const to = versionForms(nextParts[i]);
+        for (let f = 0; f < from.length; f++) {
+            if (from[f] && url.includes(from[f])) {
+                url = url.split(from[f]).join(to[f]);
+                replaced = true;
+                break;
+            }
+        }
+    }
+    return replaced ? url : undefined;
+}

package/dist/codesign.js

@@ -60,3 +60,44 @@ export async function readEntitlements(path) {
         return {};
     }
 }
+/**
+ * Parses `spctl -a -vvv -t exec` output:
+ *   /Applications/X.app: accepted
+ *   source=Notarized Developer ID
+ *   origin=Developer ID Application: Example Inc (TEAMID)
+ */
+export function parseSpctl(output) {
+    const verdict = /:\s*(accepted|rejected)\s*$/m.exec(output)?.[1];
+    const source = /^source=(.+)$/m.exec(output)?.[1]?.trim();
+    const origin = /^origin=(.+)$/m.exec(output)?.[1]?.trim();
+    const assessment = verdict === 'accepted' || verdict === 'rejected' ? verdict : 'unknown';
+    // Without a verdict spctl prints "<path>: <reason>", e.g. a broken seal.
+    const error = assessment === 'unknown' ? /^.*?:\s*(.+)$/m.exec(output.trim())?.[1]?.trim() : undefined;
+    return {
+        assessment,
+        ...(source ? { source } : {}),
+        ...(origin ? { origin } : {}),
+        ...(error ? { error } : {}),
+    };
+}
+/**
+ * Reads `stapler validate` by its message: its exit status is 0 whether or not a
+ * ticket is stapled. Undefined when stapler isn't available (no Xcode tools).
+ */
+export function parseStapler(res) {
+    const text = `${res.stdout}\n${res.stderr}`;
+    if (/The validate action worked/i.test(text))
+        return true;
+    if (/does not have a ticket stapled/i.test(text))
+        return false;
+    return undefined;
+}
+/** Asks Gatekeeper about a bundle and checks for a stapled notarization ticket. */
+export async function readNotarization(path) {
+    const spctl = await run('/usr/sbin/spctl', ['-a', '-vvv', '-t', 'exec', path], 120_000);
+    const info = parseSpctl(`${spctl.stdout}\n${spctl.stderr}`);
+    const stapled = parseStapler((await run('/usr/bin/xcrun', ['stapler', 'validate', path], 60_000)));
+    if (stapled !== undefined)
+        info.stapled = stapled;
+    return info;
+}