crossbind 2.0.0-beta.66 → 2.0.0-beta.68

package/src/utils/appOptions.js

@@ -11,6 +11,16 @@ const WINDOWS_VERSION = /^(\d+(?:\.\d+){0,3})(?:[-+][0-9A-Za-z.+-]*)?$/;
 // What app.openPath can let the page's shell.openPath open: the app's folders as app.paths() names them, and what a
 // dialog picked during this run.
 const OPEN_PATH_PLACES = ['data', 'cache', 'logs', 'picked'];
+// Apple's app categories, which macOS shows an app under, each with the main categories of the freedesktop menu
+// specification a Linux menu shows it under. An audio or a video app is in AudioVideo as well, as the specification asks.
+const GAMES = ['', 'action-', 'adventure-', 'arcade-', 'board-', 'card-', 'casino-', 'dice-', 'educational-', 'family-', 'kids-', 'music-', 'puzzle-',
+    'racing-', 'role-playing-', 'simulation-', 'sports-', 'strategy-', 'trivia-', 'word-'].map((kind) => `${kind}games`);
+const APP_CATEGORIES = {
+    business: 'Office', 'developer-tools': 'Development', education: 'Education', entertainment: 'AudioVideo', finance: 'Office',
+    'graphics-design': 'Graphics', 'healthcare-fitness': 'Utility', lifestyle: 'Utility', medical: 'Science', music: 'Audio;AudioVideo', news: 'Network',
+    photography: 'Graphics', productivity: 'Office', reference: 'Education', 'social-networking': 'Network', sports: 'Utility', travel: 'Utility',
+    utilities: 'Utility', video: 'Video;AudioVideo', weather: 'Utility', ...Object.fromEntries(GAMES.map((category) => [category, 'Game'])),
+};
 
 // An app's bundle id, which also names its folders on the desktop: app.id, else one made from the project's name.
 export function appId(config) {
@@ -38,6 +48,28 @@ export function appDisplayName(config) {
     return name;
 }
 
+// The copyright line a macOS app's About panel and a Windows executable's details show: app.copyright, else none. The
+// host takes it as a C string and a Windows resource string, as it takes the name.
+export function appCopyright(config) {
+    const copyright = config.app.copyright;
+    if (copyright === undefined) return null;
+    if (typeof copyright !== 'string' || !copyright.trim() || /["\\\p{Cc}]/u.test(copyright)) {
+        throw new Error(`crossbind: app.copyright ${JSON.stringify(copyright)} is no copyright line, which is text without a quotation mark, a backslash or a control character, as '© 2026 Example Inc.' is.`);
+    }
+    return copyright;
+}
+
+// The category app.category names, under which macOS shows the app, and the ones a Linux menu shows it under; none
+// without app.category.
+export function appCategory(config) {
+    const category = config.app.category;
+    if (category === undefined) return null;
+    if (!Object.hasOwn(APP_CATEGORIES, category)) {
+        throw new Error(`crossbind: app.category ${JSON.stringify(category)} is none of Apple's app categories, which are ${Object.keys(APP_CATEGORIES).join(', ')}.`);
+    }
+    return { darwin: `public.app-category.${category}`, linux: APP_CATEGORIES[category] };
+}
+
 // The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes and
 // whether it opens full screen. Its backgroundColor, which a phone takes as well, is appBackgroundColor's.
 export function appWindow(config) {
@@ -114,6 +146,46 @@ export function usageDescriptions(config, platform) {
     return Object.fromEntries(Object.entries(appPermissions(config)).flatMap(([name, reason]) => keys[name].map((key) => [key, reason])));
 }
 
+// Apple's categories of required reason API, each with the type a privacy manifest names it by and the reasons Apple
+// takes for it, from "Describing use of required reason API".
+export const PRIVACY_CATEGORIES = {
+    fileTimestamp: { type: 'NSPrivacyAccessedAPICategoryFileTimestamp', reasons: ['DDA9.1', 'C617.1', '3B52.1', '0A2A.1'] },
+    systemBootTime: { type: 'NSPrivacyAccessedAPICategorySystemBootTime', reasons: ['35F9.1', '8FFB.1', '3D61.1'] },
+    diskSpace: { type: 'NSPrivacyAccessedAPICategoryDiskSpace', reasons: ['85F4.1', 'E174.1', '7D9E.1', 'B728.1'] },
+    activeKeyboards: { type: 'NSPrivacyAccessedAPICategoryActiveKeyboards', reasons: ['3EC4.1', '54BD.1'] },
+    userDefaults: { type: 'NSPrivacyAccessedAPICategoryUserDefaults', reasons: ['CA92.1', '1C8F.1', 'C56D.1', 'AC6B.1'] },
+};
+
+// The reasons an iOS app's privacy manifest gives for the required reason API it calls: app.privacy, each category with
+// Apple's reasons that fit, as { fileTimestamp: ['C617.1'] }.
+export function appPrivacy(config) {
+    const privacy = config.app.privacy ?? {};
+    const names = Object.keys(PRIVACY_CATEGORIES).join(', ');
+    if (typeof privacy !== 'object' || privacy === null || Array.isArray(privacy)) {
+        throw new Error(`crossbind: app.privacy ${JSON.stringify(privacy)} is no object of ${names}, each with Apple's reasons for it, as { fileTimestamp: ['C617.1'] } is.`);
+    }
+    const unknown = Object.keys(privacy).filter((name) => !Object.hasOwn(PRIVACY_CATEGORIES, name));
+    if (unknown.length > 0) throw new Error(`crossbind: app.privacy takes ${names}; ${unknown.join(', ')} is none of them.`);
+    Object.entries(privacy).forEach(([name, reasons]) => {
+        const allowed = PRIVACY_CATEGORIES[name].reasons;
+        if (!Array.isArray(reasons) || reasons.length === 0 || reasons.some((reason) => !allowed.includes(reason))) {
+            throw new Error(`crossbind: app.privacy.${name} ${JSON.stringify(reasons)} is no list of Apple's reasons for it, which are ${allowed.join(', ')}; Apple's "Describing use of required reason API" says what each covers.`);
+        }
+    });
+    return privacy;
+}
+
+// Whether an iOS app uses encryption that export rules do not exempt, which its Info.plist tells App Store Connect so that
+// it stops asking for every build: app.encryption. It is a legal statement, so there is none without it.
+export function appEncryption(config) {
+    const encryption = config.app.encryption;
+    if (encryption === undefined) return null;
+    if (typeof encryption !== 'boolean') {
+        throw new Error(`crossbind: app.encryption ${JSON.stringify(encryption)} is no boolean: set it to false when the app uses no encryption, or only what export rules exempt as the system's HTTPS, and to true when it uses any other.`);
+    }
+    return encryption;
+}
+
 // The version a Windows app's executable carries: package.json's, whose numbers are its file version.
 function windowsVersion(config) {
     const version = config.package?.version ?? '1.0.0';
@@ -249,6 +321,10 @@ export function appHeader(config, platform) {
         ...PERMISSIONS.map((name) => `#define CROSSBIND_APP_PERMISSION_${name.toUpperCase()} ${name in permissions ? 1 : 0}`),
     ];
     if (!['darwin', 'linux', 'win32'].includes(platform)) return [comment, openPath, ...page, ''].join('\n');
+    // The category goes to the Info.plist and the desktop entry, which the build writes later; any desktop refuses a
+    // wrong one here.
+    const copyright = appCopyright(config);
+    appCategory(config);
     const lines = [
         comment,
         openPath,
@@ -277,6 +353,7 @@ export function appHeader(config, platform) {
     if (platform === 'win32') {
         const version = windowsVersion(config);
         lines.push(`#define CROSSBIND_APP_VERSION "${version.text}"`, `#define CROSSBIND_APP_VERSION_NUMBERS ${version.numbers}`);
+        if (copyright) lines.push(`#define CROSSBIND_APP_COPYRIGHT "${copyright}"`);
         // The build writes the icon beside this header.
         if (config.app.icon !== undefined) lines.push('#define CROSSBIND_APP_ICON 1');
     }

package/src/utils/ask.js

@@ -0,0 +1,38 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+
+// Whether someone is at a terminal to answer a question, as no one is in CI or behind a pipe.
+export const hasTerminal = () => Boolean(process.stdin.isTTY && process.stderr.isTTY);
+
+function ask(question, { input, output, isHidden }) {
+    output.write(question);
+    // A hidden answer is echoed into nothing, while the terminal, in raw mode, shows none of it either.
+    const echo = isHidden ? new Writable({ write: (chunk, encoding, done) => done() }) : output;
+    const reader = readline.createInterface({ input, output: echo, terminal: isHidden });
+    return new Promise((resolve, reject) => {
+        let isAnswered = false;
+        reader.once('line', (line) => {
+            isAnswered = true;
+            reader.close();
+            if (isHidden) output.write('\n');
+            resolve(line);
+        });
+        reader.once('SIGINT', () => {
+            reader.close();
+            output.write('\n');
+            reject(new Error('crossbind: stopped at the question.'));
+        });
+        reader.once('close', () => {
+            if (!isAnswered) reject(new Error('crossbind: the terminal closed before an answer.'));
+        });
+    });
+}
+
+// An answer typed on the terminal that the terminal does not show, as a password.
+export const askHidden = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: true });
+
+// An answer typed on the terminal.
+export const askLine = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: false });
+
+// A yes or no typed on the terminal: yes unless it starts with n.
+export const askYesNo = async (question, streams) => !/^\s*n/i.test(await askLine(question, streams));

package/src/utils/configWriter.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import { parseAst } from 'rollup/parseAst';
+
+// The kinds of crossbind.config whose default export can be an object literal to write into.
+const CONFIG_EXTENSIONS = ['js', 'mjs', 'cjs'];
+const DEFAULT_INDENT = '    ';
+
+const indentOf = (source, at) => source.slice(source.lastIndexOf('\n', at - 1) + 1).match(/^[ \t]*/)[0];
+const isOneLine = (source, from, to) => !source.slice(from, to).includes('\n');
+const insert = (source, at, text) => `${source.slice(0, at)}${text}${source.slice(at)}`;
+const propertyOf = (object, name) => object.properties.find((property) => property.type === 'Property' && !property.computed
+    && (property.key.name ?? property.key.value) === name);
+// A spread may carry the key, and would win over one written before it.
+const hasSpread = (object) => object.properties.some((property) => property.type === 'SpreadElement');
+// A value as one writes it in a config by hand: { fileTimestamp: ['C617.1'] }.
+function literal(value) {
+    if (typeof value === 'string') return `'${value.replace(/[\\']/g, '\\$&')}'`;
+    if (Array.isArray(value)) return `[${value.map(literal).join(', ')}]`;
+    if (value !== null && typeof value === 'object') return `{ ${Object.entries(value).map(([key, item]) => `${key}: ${literal(item)}`).join(', ')} }`;
+    return JSON.stringify(value);
+}
+export const entry = (key, value) => `${key}: ${literal(value)}`;
+
+// How far an object's keys sit in from the line it opens on.
+function indentUnit(source, object) {
+    const [first] = object.properties;
+    if (!first || isOneLine(source, object.start, first.start)) return DEFAULT_INDENT;
+    return indentOf(source, first.start).slice(indentOf(source, object.start).length) || DEFAULT_INDENT;
+}
+
+// The config's source with `key: value` first in its app section, which it makes where there is none, or null where it
+// cannot place it safely: the default export must be an object literal, its app one too, without the key or a spread.
+export function withAppOption(source, key, value) {
+    const exported = parseAst(source).body.find((node) => node.type === 'ExportDefaultDeclaration')?.declaration;
+    if (exported?.type !== 'ObjectExpression') return null;
+    const unit = indentUnit(source, exported);
+    const text = entry(key, value);
+    const app = propertyOf(exported, 'app');
+    if (!app) {
+        if (hasSpread(exported)) return null;
+        const [first] = exported.properties;
+        if (!first || isOneLine(source, exported.start, first.start)) return insert(source, exported.start + 1, ` app: { ${text} },`);
+        const indent = indentOf(source, first.start);
+        return insert(source, exported.start + 1, `\n${indent}app: {\n${indent}${unit}${text},\n${indent}},`);
+    }
+    if (app.value.type !== 'ObjectExpression' || propertyOf(app.value, key) || hasSpread(app.value)) return null;
+    const [first] = app.value.properties;
+    if (!first) {
+        const indent = indentOf(source, app.start);
+        return `${source.slice(0, app.value.start)}{\n${indent}${unit}${text},\n${indent}}${source.slice(app.value.end)}`;
+    }
+    if (isOneLine(source, app.value.start, first.start)) return insert(source, app.value.start + 1, ` ${text},`);
+    return insert(source, app.value.start + 1, `\n${indentOf(source, first.start)}${text},`);
+}
+
+// Writes `key: value` into the project's crossbind.config, and says whether it could.
+export function writeAppOption(project, key, value) {
+    const file = CONFIG_EXTENSIONS.map((extension) => `${project}/crossbind.config.${extension}`).find((candidate) => fs.existsSync(candidate));
+    if (!file) return false;
+    const changed = withAppOption(fs.readFileSync(file, 'utf8'), key, value);
+    if (changed === null) return false;
+    fs.writeFileSync(file, changed);
+    return true;
+}

package/src/utils/embindArgumentGuards.js

@@ -26,8 +26,9 @@ const GUARDS = [
     },
 ];
 
-// The release glue spells the bigint conversion `typeof value=="number"`, the debug glue `typeof value == 'number'`.
-const BIGINT_FROM_NUMBER = /if\s*\(\s*typeof value\s*==\s*["']number["']\s*\)\s*\{\s*value\s*=\s*BigInt\(value\)\s*;?\s*\}/g;
+// The release glue spells the bigint conversion `typeof value=="number"`, the debug glue `typeof value == 'number'`;
+// emscripten 6.0.10 and later write `===`, and their release glue drops the braces.
+const BIGINT_FROM_NUMBER = /if\s*\(\s*typeof value\s*===?\s*["']number["']\s*\)\s*(?:\{\s*value\s*=\s*BigInt\(value\)\s*;?\s*\}|value\s*=\s*BigInt\(value\)\s*;?)/g;
 const SAFE_BIGINT_FROM_NUMBER = 'if(typeof value=="number"){if(!Number.isSafeInteger(value))throw new TypeError("a 64-bit integer parameter takes a BigInt or a safe integer Number, got "+value);value=BigInt(value)}';
 
 // Returns the rewritten glue and whether a bigint registration kept a conversion this rewrite does not recognise.
@@ -43,7 +44,7 @@ const DEBUG_GUARDS = [
     {
         registration: '__embind_register_integer',
         end: 'readValueFromPointer: integerReadValueFromPointer(',
-        from: /toWireType: \(destructors, value\) => \{(\s*)(?=if \(typeof value != ["']number["'])/,
+        from: /toWireType: \(destructors, value\) => \{(\s*)(?=if \(typeof value !==? ["']number["'])/,
         to: 'toWireType: (destructors, value) => {$1'
             + 'if (typeof value == "string" && size == 1 && value.length == 1) value = value.charCodeAt(0);$1'
             + 'if (value !== null && typeof value == "object" && typeof value.value == "number") value = value.value;$1',
@@ -72,9 +73,11 @@ function guardDebugRegistration(glue, { registration, end, from, to, applied })
     return { text: glue.slice(0, start) + rewritten + glue.slice(stop), missed: rewritten === code };
 }
 
-// Returns the rewritten glue and the registrations whose code no longer looks the way these rewrites expect.
+// Returns the rewritten glue and the registrations whose code no longer looks the way these rewrites expect. Emscripten
+// 6.0.10 and later write a registration the glue uses once into the wasm imports, as `name:(` rather than `name=(`; a
+// debug glue's wasm imports only name it (`name: __name`).
 export function guardEmbindArguments(glue) {
-    const missed = GUARDS.filter(({ registration, from, to }) => glue.includes(`${registration}=`) && !glue.includes(from) && !glue.includes(to))
+    const missed = GUARDS.filter(({ registration, from, to }) => new RegExp(`${registration}[=:]\\(`).test(glue) && !glue.includes(from) && !glue.includes(to))
         .map(({ registration }) => registration);
     const released = GUARDS.reduce((current, { from, to }) => current.split(from).join(to), glue);
     return DEBUG_GUARDS.reduce(({ text, missed: names }, guard) => {

package/src/utils/embindCallArguments.js

@@ -3,14 +3,14 @@
 // once it returns, or once its promise settles for an async (_JSPI) function, so a call started before
 // then overwrites them and the earlier call frees the later call's arguments instead of its own, which
 // leak: two pending calls of one _JSPI method, or a method called again from a JavaScript callback it
-// runs. Emscripten 6.0.9 builds it this way, as did upstream main on 2026-09-30; this rewrite declares
-// the three inside the invoker, so each call gets its own.
+// runs. Emscripten 6.0.9 and 6.0.13 build it this way, as did upstream main on 2026-09-30; this rewrite
+// declares the three inside the invoker, so each call gets its own.
 
 // The release glue spells it on one line, the debug glue one statement per line with an argument
-// count check first.
-const SHARED = /var argsWired\s*=\s*new Array\(expectedArgCount\);\s*var invokerFuncArgs\s*=\s*\[\];\s*var destructors\s*=\s*\[\];\s*var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{(\s*(?:checkArgCount\([^;]*\);\s*)?)destructors\.length\s*=\s*0;/g;
-const PER_CALL = 'var invokerFn=function(...args){$1var argsWired=new Array(expectedArgCount);var invokerFuncArgs=[];var destructors=[];';
-const SEPARATED = /var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{\s*(?:checkArgCount\([^;]*\);\s*)?var argsWired\s*=/;
+// count check first. Emscripten 6.0.10 and later hand the release invoker straight to createNamedFunction.
+const SHARED = /var argsWired\s*=\s*new Array\(expectedArgCount\);\s*var invokerFuncArgs\s*=\s*\[\];\s*var destructors\s*=\s*\[\];\s*((?:var invokerFn\s*=\s*|return createNamedFunction\(humanName,\s*)function\s*\(\.\.\.args\)\s*\{)(\s*(?:checkArgCount\([^;]*\);\s*)?)destructors\.length\s*=\s*0;/g;
+const PER_CALL = '$1$2var argsWired=new Array(expectedArgCount);var invokerFuncArgs=[];var destructors=[];';
+const SEPARATED = /(?:var invokerFn\s*=\s*|return createNamedFunction\(humanName,\s*)function\s*\(\.\.\.args\)\s*\{\s*(?:checkArgCount\([^;]*\);\s*)?var argsWired\s*=/;
 
 // Returns the rewritten glue and whether it still holds an invoker this rewrite does not recognise.
 export function separateCallArguments(glue) {

package/src/utils/hermes.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import withDirLock from './dirLock.js';
 import downloadAndExtractFile from './downloadAndExtractFile.js';
+import logger from './logger.js';
 
 // The Hermes React Native publishes on Maven Central for Apple platforms: the macOS framework, the iOS xcframework,
 // hermesc and the headers. A new version also moves third_party/jsi of @crossbind/core-app-host to its tag, and the
@@ -25,6 +26,29 @@ export default async function resolveHermes() {
     return `${dir}/source/destroot`;
 }
 
+// The dSYMs of the release's frameworks, with which App Store Connect shows Hermes' frames in an iOS app's crash reports
+// as functions and lines.
+export const HERMES_DSYM = {
+    url: `https://repo1.maven.org/maven2/com/facebook/hermes/hermes-ios/${HERMES.version}/hermes-ios-${HERMES.version}-hermes-framework-dSYM-release.tar.gz`,
+    sha256: '5cea3dd57ecadb42c40d1cc8acf2e178dbfbe6a230410742d997ff3fe313a9c0',
+};
+
+// The dSYM of the device's framework, downloaded once and checked against the pinned sha256. The release's 360 MB hold
+// every Apple platform's, of which only the device's 80 MB are kept.
+export async function resolveHermesDsym() {
+    const dir = `${hermesDir()}-dsym`;
+    const dsym = `${dir}/source/iphoneos/hermesvm.framework.dSYM`;
+    if (!fs.existsSync(dsym)) logger.info(`crossbind: downloading the dSYM of Hermes ${HERMES.version} once, 360 MB of which 80 MB stay, for crash reports.`);
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    await withDirLock(`${dir}.lock`, async () => {
+        await downloadAndExtractFile(HERMES_DSYM.url, dir, HERMES_DSYM.sha256);
+        fs.rmSync(`${dir}/${path.basename(HERMES_DSYM.url)}`, { force: true });
+        fs.readdirSync(`${dir}/source`).filter((entry) => entry !== 'iphoneos')
+            .forEach((entry) => fs.rmSync(`${dir}/source/${entry}`, { recursive: true, force: true }));
+    });
+    return dsym;
+}
+
 // Linux and Windows have no published Hermes, so crossbind's linux and windows images build the release's source, with
 // their static libc++: JSI hands std types across, and the host and the project's archives build there too.
 export const HERMES_SOURCE = {

package/src/utils/keychain.js

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+
+// The keychain names a secret by a service and an account: an upload key's password by this service, with the key's own
+// path as the account.
+const SERVICE = 'crossbind upload key';
+// security -i reads a command line whose quoted words take a backslash before a quote or a backslash.
+const quoted = (word) => `"${word.replace(/[\\"]/g, '\\$&')}"`;
+// Windows PowerShell, which imports its core modules from its own home: a pwsh 7 parent's PSModulePath hides them.
+const powershell = (script) => ['-NoProfile', '-NonInteractive', '-Command', `Import-Module (Join-Path $PSHOME 'Modules\\Microsoft.PowerShell.Security'); ${script}`];
+const STORE_DPAPI = 'ConvertTo-SecureString -String $env:CROSSBIND_KEYCHAIN_SECRET -AsPlainText -Force | ConvertFrom-SecureString | Set-Content -LiteralPath $env:CROSSBIND_KEYCHAIN_FILE -NoNewline';
+const READ_DPAPI = "$secret = Get-Content -LiteralPath $env:CROSSBIND_KEYCHAIN_FILE -Raw | ConvertTo-SecureString; [Console]::Out.Write([System.Net.NetworkCredential]::new('', $secret).Password)";
+
+const run = (program, args, options = {}) => spawnSync(program, args, { encoding: 'utf8', ...options });
+
+// Each system's keychain, given the secret on stdin or in the environment, never on a command line. On Windows it is the
+// user's DPAPI, in a file beside the key that only that user on that machine can read, so the path alone names it.
+const KEYCHAINS = {
+    darwin: {
+        store: (service, key, secret) => run('security', ['-i'], { input: `add-generic-password -U -s ${quoted(service)} -a ${quoted(key)} -w ${quoted(secret)}\n` }),
+        read: (service, key) => run('security', ['find-generic-password', '-s', service, '-a', key, '-w']),
+    },
+    win32: {
+        store: (service, key, secret) => run('powershell.exe', powershell(STORE_DPAPI), {
+            env: { ...process.env, CROSSBIND_KEYCHAIN_SECRET: secret, CROSSBIND_KEYCHAIN_FILE: `${key}.dpapi` },
+        }),
+        read: (service, key) => run('powershell.exe', powershell(READ_DPAPI), { env: { ...process.env, CROSSBIND_KEYCHAIN_FILE: `${key}.dpapi` } }),
+    },
+    linux: {
+        store: (service, key, secret) => run('secret-tool', ['store', '--label', service, 'service', service, 'account', key], { input: secret }),
+        read: (service, key) => run('secret-tool', ['lookup', 'service', service, 'account', key]),
+    },
+};
+
+const keychainOf = (platform) => KEYCHAINS[platform] ?? KEYCHAINS.linux;
+
+// Whether the system has a keychain to keep a password in: macOS and Windows always, Linux where secret-tool is.
+export const hasKeychain = ({ platform = process.platform } = {}) => ['darwin', 'win32'].includes(platform) || !run('secret-tool', ['--help']).error;
+
+// An upload key's password, or another service's secret, from the system's keychain, or null when it keeps none or there
+// is no keychain.
+export function readSecret(key, { platform = process.platform, service = SERVICE } = {}) {
+    const result = keychainOf(platform).read(service, key);
+    if (result.error || result.status !== 0) return null;
+    // security ends what it prints with a newline.
+    return result.stdout.replace(/\n$/, '') || null;
+}
+
+// Keeps an upload key's password, or another service's secret, in the system's keychain, and says whether it did: Linux
+// without secret-tool and its service has none. A secret counts as kept once it reads back, as security -i fails without
+// an exit code.
+export function storeSecret(key, secret, { platform = process.platform, service = SERVICE } = {}) {
+    keychainOf(platform).store(service, key, secret);
+    return readSecret(key, { platform, service }) === secret;
+}

package/src/utils/openUrl.js

@@ -0,0 +1,11 @@
+import { spawn } from 'node:child_process';
+
+const OPENERS = { darwin: ['open'], win32: ['cmd', '/c', 'start', '""'] };
+
+// Opens an address in the user's browser where the system can; whoever calls it prints the address too.
+export default function openUrl(url) {
+    const [program, ...args] = OPENERS[process.platform] ?? ['xdg-open'];
+    const opener = spawn(program, [...args, url], { stdio: 'ignore', detached: true });
+    opener.on('error', () => {});
+    opener.unref();
+}

package/src/utils/overrideDependency.js

@@ -90,9 +90,12 @@ export function getOverrideKey(dep) {
         override,
         (key, value) => (typeof value === 'function' ? `fn:${value.toString()}` : value),
     );
+    // The package version too: a new release of the package can build the same upstream release differently, as one
+    // that adds a patch does, and the rebuild cached under the old one would keep linking the old build.
     const parts = [
         dep.general?.name || '',
         override.nativeVersion || dep.package?.nativeVersion || '',
+        dep.package?.version || '',
         serial,
     ];
     return getContentHash(parts.join(' '));

package/src/utils/password.js

@@ -0,0 +1,34 @@
+import { randomBytes } from 'node:crypto';
+
+// NIST SP 800-63B-4's least length for a password that alone guards what it locks, as an upload key's does.
+export const MIN_PASSWORD_LENGTH = 15;
+// Rows a password can run along, either way and around: the alphabet, the digits, and a keyboard's.
+const ROWS = ['abcdefghijklmnopqrstuvwxyz', '0123456789', 'qwertyuiopasdfghjklzxcvbnm', '1qaz2wsx3edc4rfv5tgb6yhn7ujm8ik9ol0p', 'q1w2e3r4t5y6u7i8o9p0'];
+// Long passwords others try first, which the rules above let through.
+const GUESSED = ['correcthorsebatterystaple', 'thequickbrownfoxjumpsoverthelazydog', 'crossbinduploadkey', 'androiduploadkey'];
+
+// What the user reads before typing an upload key's password.
+export const PASSWORD_RULES = [
+    `${MIN_PASSWORD_LENGTH} characters or more; spaces and any characters are welcome, so a few words make a good one`,
+    'not one part repeated, not a run as 1234, abcd or qwerty, and not a well-known password',
+];
+
+const runsAlong = (text, row) => {
+    const around = row.repeat(Math.ceil(text.length / row.length) + 1);
+    return around.includes(text) || [...around].reverse().join('').includes(text);
+};
+
+// Why a password is too weak to lock an upload key, or null when it is not. NIST asks for no mix of kinds of characters.
+export function passwordProblem(password) {
+    const length = [...password].length;
+    if (length < MIN_PASSWORD_LENGTH) return `it has ${length} characters and needs at least ${MIN_PASSWORD_LENGTH}`;
+    if (/\p{Cc}/u.test(password)) return 'it has a control character, which no terminal types';
+    const plain = password.toLowerCase();
+    if (/^(.+?)\1+$/su.test(plain)) return 'it repeats one part';
+    if (ROWS.some((row) => runsAlong(plain, row))) return 'it runs along a row, as 1234, abcd and qwerty do';
+    if (GUESSED.includes(plain.replace(/\s+/g, ''))) return 'it is a password others guess first';
+    return null;
+}
+
+// A password crossbind makes: 18 random bytes, 144 bits, as 24 characters any terminal and keytool take.
+export const makePassword = () => randomBytes(18).toString('base64url');

package/src/utils/recipePatches.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getContentHash } from './hash.js';
+
+const patchPath = (file) => (file instanceof URL ? fileURLToPath(file) : file);
+
+// Inside the tree, which every extraction replaces whole: a tree says it is patched only once its own patches went in,
+// so neither one a patch failed on nor one a stopped run left behind passes, whatever stamp an earlier tree had.
+const stampOf = (buildPath) => path.join(buildPath, 'source', '.crossbind-patches');
+
+export function recipePatchesFingerprint(patches) {
+    if (!patches?.length) return null;
+    return getContentHash(JSON.stringify(patches.map(({ file }) => fs.readFileSync(patchPath(file), 'utf8'))));
+}
+
+// downloadAndExtractFile keeps a tree whose archive still matches, so a tree patched under another set
+// would keep its old patches or miss the new ones: it is extracted again instead.
+export function refreshPatchedSource(buildPath, patches) {
+    const stamp = stampOf(buildPath);
+    const recorded = fs.existsSync(stamp) ? fs.readFileSync(stamp, 'utf8') : '';
+    if (recorded !== (recipePatchesFingerprint(patches) ?? '')) {
+        fs.rmSync(path.join(buildPath, 'source'), { recursive: true, force: true });
+    }
+}
+
+export function writePatchedSourceStamp(buildPath, patches) {
+    const fingerprint = recipePatchesFingerprint(patches);
+    if (fingerprint) fs.writeFileSync(stampOf(buildPath), fingerprint);
+    else fs.rmSync(stampOf(buildPath), { force: true });
+}
+
+// git apply is atomic and refuses a hunk whose context does not match, so a source the patch no longer
+// fits stops the build instead of shipping unpatched. It works on the files alone: a repository named in the
+// environment, as a git hook passes on, would make it skip every path, and one the downloaded tree carries could run
+// its filters on the host, so GIT_DIR names none. autocrlf, which Git for Windows sets, would give the patched files
+// CRLF endings.
+export function applyRecipePatches(sourcePath, patches) {
+    const env = {
+        ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+        GIT_DIR: `${sourcePath}.no-repository`,
+    };
+    for (const { file } of patches ?? []) {
+        const patch = patchPath(file);
+        try {
+            execFileSync('git', ['-c', 'core.autocrlf=false', 'apply', '--whitespace=nowarn', '--', patch], {
+                cwd: sourcePath,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env,
+            });
+        } catch (error) {
+            if (error.code === 'ENOENT') throw new Error(`crossbind: applying ${path.basename(patch)} needs git on the PATH.`, { cause: error });
+            throw new Error(
+                `crossbind: ${path.basename(patch)} does not apply to the extracted source. A recipe's patches are diffs against the release it pins: `
+                + `drop the patch once a release includes it.\n${String(error.stderr ?? error.message).trim()}`,
+                { cause: error },
+            );
+        }
+    }
+}

package/src/utils/requiredReasonApis.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// The C symbols of Apple's required reason API an iOS archive can import, each with its categories; getattrlist and its
+// kin are in two. A selector, as systemUptime or activeInputModes is, is no symbol, so nm finds none of those.
+const SYMBOLS = {
+    _stat: ['fileTimestamp'],
+    _fstat: ['fileTimestamp'],
+    _fstatat: ['fileTimestamp'],
+    _lstat: ['fileTimestamp'],
+    _getattrlistbulk: ['fileTimestamp'],
+    _getattrlist: ['fileTimestamp', 'diskSpace'],
+    _fgetattrlist: ['fileTimestamp', 'diskSpace'],
+    _getattrlistat: ['fileTimestamp', 'diskSpace'],
+    _statfs: ['diskSpace'],
+    _statvfs: ['diskSpace'],
+    _fstatfs: ['diskSpace'],
+    _fstatvfs: ['diskSpace'],
+    _mach_absolute_time: ['systemBootTime'],
+    '_OBJC_CLASS_$_NSUserDefaults': ['userDefaults'],
+};
+// nm's list of a large library, as GDAL's, runs to megabytes.
+const NM_OUTPUT_LIMIT = 256 * 1024 * 1024;
+
+// The categories that the symbols of `nm -u -j` output call, each with those symbols.
+export function reasonCategories(output) {
+    const categories = new Map();
+    output.split('\n').map((line) => line.trim()).filter((symbol) => Object.hasOwn(SYMBOLS, symbol)).forEach((symbol) => {
+        SYMBOLS[symbol].forEach((category) => categories.set(category, (categories.get(category) ?? new Set()).add(symbol)));
+    });
+    return categories;
+}
+
+// The categories an archive or a linked binary imports, as Xcode's nm lists them, whatever nm comes first on the PATH.
+// Its LLVM bitcode reader stays off: the symbol table tells all, and the bitcode Rust's standard library embeds comes
+// from a newer LLVM than an older Xcode reads.
+function importedCategories(file) {
+    const result = spawnSync('xcrun', ['nm', '--no-llvm-bc', '-u', '-j', file], { encoding: 'utf8', maxBuffer: NM_OUTPUT_LIMIT });
+    if (result.status !== 0) throw new Error(`crossbind: cannot list what ${file} calls: ${result.stderr || result.error?.message}`);
+    return reasonCategories(result.stdout);
+}
+
+// What the archives an iOS app links call of required reason API with no reason in app.privacy: each library, by the
+// name its archive has, with each such category and its symbols.
+export function unreasonedApis(archives, privacy) {
+    const found = new Map();
+    archives.forEach((archive) => {
+        const library = path.basename(archive).replace(/^\d+-/, '').replace(/^lib/, '').replace(/\.a$/, '');
+        importedCategories(archive).forEach((symbols, category) => {
+            if (Object.hasOwn(privacy, category)) return;
+            const key = `${library}\0${category}`;
+            found.set(key, new Set([...(found.get(key) ?? []), ...symbols]));
+        });
+    });
+    return [...found].map(([key, symbols]) => {
+        const [library, category] = key.split('\0');
+        return { library, category, symbols: [...symbols].sort() };
+    }).sort((a, b) => a.library.localeCompare(b.library) || a.category.localeCompare(b.category));
+}
+
+// What an iOS app's linked binary calls of required reason API with no reason in app.privacy, each category with its
+// symbols: what the linker kept of its archives, which App Store Connect checks.
+export const unreasonedImports = (binary, privacy) => [...importedCategories(binary)]
+    .filter(([category]) => !Object.hasOwn(privacy, category))
+    .map(([category, symbols]) => ({ category, symbols: [...symbols].sort() }))
+    .sort((a, b) => a.category.localeCompare(b.category));
+
+// The warning of what the archives of an iOS app reference of required reason API without its reasons, or none. The
+// linker may leave some of it out of the app, as it left _stat, _lstat and _fstatat out of the conformance app, whose
+// Rust references them; the app keeps what it calls.
+export function unreasonedWarning(found) {
+    if (found.length === 0) return null;
+    const uses = new Map();
+    found.forEach(({ library, category, symbols }) => uses.set(library, [...(uses.get(library) ?? []), `${category} (${symbols.join(', ')})`]));
+    const references = [...uses].map(([library, list]) => `${library} references ${list.join(' and ')}`).join('; ');
+    return `crossbind: App Store Connect refuses an iOS app that calls required reason API without its reasons (ITMS-91053), and the archives this app links reference some with no reason in app.privacy: ${references}. The linker may leave some out. Give app.privacy Apple's reasons for what the app calls, as { fileTimestamp: ['C617.1'] }; Apple's "Describing use of required reason API" says what each covers.`;
+}

package/src/utils/secretFile.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+let folder = null;
+
+// Removes the folder of the secrets written, as crossbind does when it exits.
+export function removeSecretFiles() {
+    if (folder) fs.rmSync(folder, { recursive: true, force: true });
+    folder = null;
+}
+
+// A secret the environment holds as its text, as CI's secrets come, written to a file of a folder only this user opens,
+// as the tools that take it read files. The folder goes when crossbind exits.
+export function secretFile(name, data) {
+    if (!folder) {
+        folder = fs.mkdtempSync(path.join(os.tmpdir(), 'crossbind-secrets-'));
+        process.once('exit', removeSecretFiles);
+    }
+    const file = path.join(folder, name);
+    fs.writeFileSync(file, data, { mode: 0o600 });
+    return file;
+}

package/src/utils/sourceFingerprint.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { getContentHash } from './hash.js';
+import { recipePatchesFingerprint } from './recipePatches.js';
 
 // The prebuilt-lib cache in buildLib is existence-only, so a nativeVersion or recipe-sha256 bump
 // would otherwise be served from the previous build - shipping the old upstream under the new
@@ -12,7 +13,13 @@ export function getSourceFingerprint(config, target) {
     // Local-source packages pin neither; buildLib checks their native source inventory instead.
     if (!nativeVersion && !sha256) return null;
     const sourceReplacements = target ? config?.build?.sourceReplaceList?.(target, config.allDependencyPaths?.[target.path] ?? {}) : undefined;
-    return getContentHash(JSON.stringify({ nativeVersion, sha256, ...(sourceReplacements?.length ? { sourceReplacements } : {}) }));
+    const patches = recipePatchesFingerprint(config?.build?.patches);
+    return getContentHash(JSON.stringify({
+        nativeVersion,
+        sha256,
+        ...(sourceReplacements?.length ? { sourceReplacements } : {}),
+        ...(patches ? { patches } : {}),
+    }));
 }
 
 export function isSourceFingerprintStale(libdir, fingerprint) {

package/src/utils/systemConfig.js

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import loadJson from './loadJson.js';
 import systemKeys from './systemKeys.js';
+import writeJson from './writeJson.js';
 
 export const systemConfigPath = () => `${os.homedir()}/.crossbind.json`;
 
@@ -11,3 +12,8 @@ export default function loadSystemConfig() {
         .map(([key, value]) => [key, value.default]);
     return { ...system, ...Object.fromEntries(defaults) };
 }
+
+// Sets keys of ~/.crossbind.json, as `crossbind config set` does, keeping the others.
+export function updateSystemConfig(values) {
+    writeJson(systemConfigPath(), { ...loadSystemConfig(), ...values });
+}