crossbind 2.0.0-beta.64 → 2.0.0-beta.66

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "crossbind",
-    "version": "2.0.0-beta.64",
+    "version": "2.0.0-beta.66",
     "license": "MIT",
     "homepage": "https://crossbind.dev",
     "repository": "https://github.com/crossbind/crossbind.git",
@@ -16,6 +16,10 @@
     "exports": {
         ".": "./src/index.js",
         "./node/dev": "./src/node/dev.mjs",
+        "./app": {
+            "types": "./src/app/index.d.ts",
+            "default": "./src/app/index.js"
+        },
         "./*": "./*"
     },
     "scripts": {
@@ -37,6 +41,7 @@
         "glob": "^13.0.6",
         "log-update": "^8.0.0",
         "picocolors": "^1.1.1",
+        "pngjs": "^7.0.0",
         "replace": "^1.2.2",
         "rollup": "^4.63.4",
         "spdx-expression-parse": "^5.0.0",

package/src/actions/androidDevice.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { ANDROID_ABIS } from './gradleProject.js';
+import { EXEC_MAX_BUFFER } from './run.js';
+
+const ACTIVITY = 'dev.crossbind.app.CrossbindActivity';
+
+// The adb that reaches the device: the one on PATH, else the platform tools of ANDROID_HOME's SDK or Android Studio's.
+// crossbind installs none.
+export function adbPath() {
+    const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT
+        || path.join(os.homedir(), process.platform === 'darwin' ? 'Library/Android/sdk' : 'Android/Sdk');
+    const found = [...(process.env.PATH ?? '').split(path.delimiter).map((dir) => path.join(dir, 'adb')), path.join(sdk, 'platform-tools', 'adb')]
+        .find((file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile());
+    if (!found) {
+        throw new Error('crossbind: an Android app runs on a device through adb, which is not on PATH nor in an Android SDK. Install Android\'s platform tools: `brew install --cask android-platform-tools` on macOS, `sudo apt install adb` on Debian and Ubuntu, or Android Studio.');
+    }
+    return found;
+}
+
+function tool(program, args, options = {}) {
+    const result = spawnSync(program, args, { encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER, ...options });
+    if (result.status !== 0) {
+        throw new Error(`crossbind: ${path.basename(program)} ${args.join(' ')} failed: ${`${result.stdout ?? ''}${result.stderr ?? ''}`.trim() || result.error?.message}`);
+    }
+    return result.stdout;
+}
+
+const adb = (args) => tool(adbPath(), args);
+// adb shell hands the device's shell one line, which splits it again.
+const quoted = (text) => `'${String(text).replace(/'/g, "'\\''")}'`;
+
+// The device an app runs on in development and in tests: the one ANDROID_SERIAL names, else the only one attached, and
+// the ABI of it the app builds for. crossbind starts no emulator.
+export function attachedDevice() {
+    const serials = adb(['devices']).split('\n').slice(1).map((line) => line.trim().split('\t'))
+        .filter(([, status]) => status === 'device').map(([serial]) => serial);
+    const serial = process.env.ANDROID_SERIAL || (serials.length === 1 ? serials[0] : null);
+    if (!serial) {
+        throw new Error(serials.length === 0
+            ? 'crossbind: no Android device is attached. Start an emulator, in Android Studio\'s Device Manager or with `emulator -avd <name>`, or connect a phone with USB debugging on.'
+            : `crossbind: ${serials.length} Android devices are attached (${serials.join(', ')}). Set ANDROID_SERIAL to the one the app runs on.`);
+    }
+    const abis = adb(['-s', serial, 'shell', 'getprop', 'ro.product.cpu.abilist']).trim().split(',');
+    const abi = abis.find((one) => ANDROID_ABIS.includes(one));
+    if (!abi) throw new Error(`crossbind: the Android device ${serial} runs ${abis.join(', ')}, and apps build for ${ANDROID_ABIS.join(' and ')}.`);
+    return { serial, abi };
+}
+
+// Installs an APK on the attached device and opens it, with `env` as the activity's extras; a dev server's page on this
+// machine reaches the device through adb reverse. The process returned carries the app's log, its page's console among
+// it, and ends with the app; close() ends the app.
+export default function openOnDevice(apk, { env = {}, stdio = 'pipe' } = {}) {
+    const { serial } = attachedDevice();
+    const id = JSON.parse(fs.readFileSync(path.join(path.dirname(apk), 'output-metadata.json'), 'utf8')).applicationId;
+    try {
+        adb(['-s', serial, 'install', '-r', '-d', apk]);
+    } catch (error) {
+        if (!error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')) throw error;
+        // As the one Google Play installs: only an uninstall replaces it, which takes its data, so the developer runs it.
+        throw new Error(`crossbind: ${id} on ${serial} is signed with another key than this build, so it cannot be updated; \`adb -s ${serial} uninstall ${id}\` removes it, with its data, and the next run installs this one.`, { cause: error });
+    }
+    const devPort = env.CROSSBIND_APP_URL && new URL(env.CROSSBIND_APP_URL).port;
+    if (devPort) adb(['-s', serial, 'reverse', `tcp:${devPort}`, `tcp:${devPort}`]);
+    const extras = Object.entries(env).flatMap(([key, value]) => ['--es', key, quoted(value)]);
+    adb(['-s', serial, 'shell', 'am', 'start', '-S', '-W', '-n', `${id}/${ACTIVITY}`, ...extras]);
+    const pid = spawnSync(adbPath(), ['-s', serial, 'shell', 'pidof', id], { encoding: 'utf8' }).stdout?.trim();
+    if (!pid) throw new Error(`crossbind: ${id} stopped as it started on ${serial}; its log is in \`adb logcat\`.`);
+    // The log of the app's process alone, without the divider logcat starts with, until the process ends. The pattern
+    // that ends logcat names it first, so it matches not the shell whose command line holds it too.
+    const logcat = `logcat -v raw --pid=${pid} -s Crossbind:V`;
+    const child = spawn(adbPath(), ['-s', serial, 'shell',
+        `${logcat} | grep -v '^--------- ' & while [ -d /proc/${pid} ]; do sleep 1; done; pkill -f '^${logcat}'`], { stdio });
+    return { child, close: () => spawnSync(adbPath(), ['-s', serial, 'shell', 'am', 'force-stop', id]) };
+}

package/src/actions/androidGradle.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import state from '../state/index.js';
+import getOsUserAndGroupId from '../utils/getOsUserAndGroupId.js';
+import pullDockerImage, { getDockerImage } from '../utils/pullDockerImage.js';
+import { DOCKER_BASE, isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import { DOCKER_RUN_SECURITY_ARGS } from '../utils/dockerSecurity.js';
+import { getContentHash } from '../utils/hash.js';
+
+const ROLE = 'android-app';
+const PLATFORM = 'linux/amd64';
+const KEYSTORE = '/tmp/crossbind/keystore';
+const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q'];
+const OUTPUT_LIMIT = 64 * 1024 * 1024;
+const FAILURE_LINES = 40;
+
+// The upload key a release is signed with, named by the environment alone so that no secret reaches a file.
+export const SIGNING = {
+    keystore: 'CROSSBIND_ANDROID_KEYSTORE',
+    alias: 'CROSSBIND_ANDROID_KEY_ALIAS',
+    password: 'CROSSBIND_ANDROID_KEYSTORE_PASSWORD',
+    keyPassword: 'CROSSBIND_ANDROID_KEY_PASSWORD',
+};
+
+const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+
+// The keystore of the upload key, or null for none: a release is then signed with the debug key.
+export function releaseSigning(env = process.env) {
+    if (!env[SIGNING.keystore]) {
+        const stray = [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]);
+        if (stray.length) throw new Error(`crossbind: ${listed(stray)} set without ${SIGNING.keystore}, the keystore of the upload key.`);
+        return null;
+    }
+    const missing = [SIGNING.alias, SIGNING.password].filter((name) => !env[name]);
+    if (missing.length) throw new Error(`crossbind: ${SIGNING.keystore} is set, but ${listed(missing)} not.`);
+    const file = path.resolve(env[SIGNING.keystore]);
+    if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`crossbind: ${SIGNING.keystore} names ${file}, which is no file.`);
+    return { file, names: [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]) };
+}
+
+// Gradle's caches and the Android tools' home outlive a container; the second keeps the debug key, which a new one would
+// replace, so that a later build still installs over the last.
+function homes() {
+    const root = path.join(os.homedir(), '.crossbind', 'android');
+    return [[path.join(root, 'gradle'), '/var/cache/crossbind/gradle'], [path.join(root, 'home'), '/var/cache/crossbind/android']];
+}
+
+// A container of crossbind's android-app image, with no network: the project under the build's base, the homes, and
+// the keystore read-only, its passwords passed by name from this environment.
+function containerArgs(signing) {
+    return [
+        ...DOCKER_RUN_SECURITY_ARGS, '--network', 'none', '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
+        '-v', `${state.config.paths.base}:${DOCKER_BASE}`,
+        ...homes().flatMap(([host, container]) => {
+            fs.mkdirSync(host, { recursive: true });
+            return ['-v', `${host}:${container}`];
+        }),
+        ...(signing ? ['-v', `${signing.file}:${KEYSTORE}:ro`, '-e', `${SIGNING.keystore}=${KEYSTORE}`, ...signing.names.flatMap((name) => ['-e', name])] : []),
+    ];
+}
+
+function docker(args, what) {
+    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT });
+    if (result.error) throw new Error(`crossbind: cannot run docker for ${what}: ${result.error.message}`, { cause: result.error });
+    if (result.status !== 0) {
+        const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split('\n').slice(-FAILURE_LINES).join('\n');
+        throw new Error(`crossbind: ${what} failed in the android-app image with exit code ${result.status}:\n${output}`);
+    }
+}
+
+// The container sees the project's base alone, under its own POSIX path whatever the host's separators.
+function inContainer(project) {
+    const dir = path.resolve(project);
+    if (!isUnderBase(dir, state.config.paths.base)) {
+        throw new Error(`crossbind: the Android project ${dir} is outside ${state.config.paths.base}, the project's base and all the android-app container sees. Build the app into a directory under it.`);
+    }
+    return path.posix.join(DOCKER_BASE, ...path.relative(state.config.paths.base, dir).split(path.sep));
+}
+
+// An Android app as the files it ships: its release APK, and with an upload key also the bundle Google Play takes, beside
+// the Gradle project as <project>.apk and <project>.aab.
+export function packageAndroidRelease(project) {
+    const signing = releaseSigning();
+    pullDockerImage(ROLE, PLATFORM);
+    docker(['run', '--rm', ...containerArgs(signing), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`);
+    const outputs = `${project}/app/build/outputs`;
+    fs.copyFileSync(`${outputs}/apk/release/app-release.apk`, `${project}.apk`);
+    fs.rmSync(`${project}.aab`, { force: true });
+    if (signing) {
+        fs.copyFileSync(`${outputs}/bundle/release/app-release.aab`, `${project}.aab`);
+    } else {
+        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. Set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with your upload key and make the bundle too.`);
+    }
+}
+
+// During development one container per project, whose Gradle daemon stays warm from one build to the next; it goes with
+// the process.
+let devContainer = null;
+
+function startDevContainer() {
+    const name = `crossbind-android-app-${getContentHash(state.config.paths.project).slice(0, 12)}`;
+    pullDockerImage(ROLE, PLATFORM);
+    // One a crashed session left behind holds the name.
+    spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' });
+    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null), getDockerImage(ROLE, PLATFORM), 'sleep', 'infinity'],
+        'starting the development container');
+    process.once('exit', () => spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' }));
+    // A closed terminal ends the session through its exit hooks, as Ctrl-C does.
+    process.once('SIGHUP', () => process.exit(129));
+    return name;
+}
+
+// Builds an Android app's Gradle project as a debug APK, signed with the debug key the homes keep, and returns the APK.
+export function buildApk(project) {
+    devContainer ??= startDevContainer();
+    docker(['exec', '-w', inContainer(project), devContainer, ...GRADLE, 'assembleDebug'], `building ${path.basename(project)}`);
+    return path.join(project, 'app', 'build', 'outputs', 'apk', 'debug', 'app-debug.apk');
+}

package/src/actions/appInstaller.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import run from './run.js';
+import { appleSigning } from './appleSigning.js';
+import { updaterSigning } from './appUpdate.js';
+import { inWindowsImage, jsignScript, windowsSigning } from './windowsSigning.js';
+import state from '../state/index.js';
+import { appDisplayName, appId, appUrlSchemes } from '../utils/appOptions.js';
+import { readAppIcon, windowsIcon } from '../utils/appIcon.js';
+import { imageRoleFor } from '../utils/pullDockerImage.js';
+import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+const DEBIAN_ARCH = { x64: 'amd64', arm64: 'arm64' };
+// What a Linux app runs on: WebKitGTK 4.1 from its 2.40 release, and the GTK its window is.
+const DEBIAN_DEPENDS = 'libwebkit2gtk-4.1-0 (>= 2.40), libgtk-3-0';
+
+const packageVersion = () => state.config.package?.version ?? '1.0.0';
+
+// The container that packages a Linux or Windows app sees the project's base alone.
+export function assertUnderBase(app, target) {
+    if (isUnderBase(app, state.config.paths.base)) return;
+    const kind = target.platform === 'win32' ? 'Windows' : 'Linux';
+    throw new Error(`crossbind: the ${kind} app ${app} is outside ${state.config.paths.base}, the project's base and all the ${imageRoleFor(target)} container sees. Build the app into a directory under it.`);
+}
+
+// A Debian package's name: the project's, in lower case, with a hyphen for each underscore and from its first letter
+// or digit.
+export function debianName(name) {
+    const debian = name.toLowerCase().replaceAll('_', '-').replace(/^[^a-z0-9]+/, '');
+    if (!/^[a-z0-9][a-z0-9+.-]+$/.test(debian)) {
+        throw new Error(`crossbind: general.name ${JSON.stringify(name)} makes no Debian package name, which is two or more lowercase letters, digits, +, . and -, starting with a letter or digit. Change general.name in crossbind.config.js.`);
+    }
+    return debian;
+}
+
+// A Debian version sorts the pre-releases of a release before it, as semver does: 1.0.0-beta.1 is 1.0.0~beta.1.
+export const debianVersion = (version) => version.replace('-', '~');
+
+// package.json's author as Debian names a maintainer, by name and email address.
+export function maintainer(author) {
+    if (typeof author === 'string') return author.replace(/\(.*\)/, '').trim() || null;
+    if (!author?.name) return null;
+    return author.email ? `${author.name} <${author.email}>` : author.name;
+}
+
+// The control file of a Linux app's package. dpkg warns of a package without a maintainer in every command it runs
+// afterwards, so without package.json's author the app's name stands for one.
+export function debianControl({ name, version, arch, author, description, label }) {
+    return [
+        `Package: ${name}`,
+        `Version: ${debianVersion(version)}`,
+        `Architecture: ${DEBIAN_ARCH[arch]}`,
+        `Maintainer: ${maintainer(author) ?? label}`,
+        `Depends: ${DEBIAN_DEPENDS}`,
+        `Description: ${(description || label).replace(/\s+/g, ' ').trim()}`,
+        '',
+    ].join('\n');
+}
+
+// The desktop entry a Linux menu shows an app by. GTK names the app's window after the command that started it, and
+// GNOME on Wayland shows the icon of the entry whose file has that name.
+// A link of one of its schemes opens it with the link as its argument, %u.
+export function desktopEntry({ label, command, hasIcon, urlSchemes = [] }) {
+    const isLinked = urlSchemes.length > 0;
+    return [
+        '[Desktop Entry]', 'Type=Application', `Name=${label}`, `Exec=${command}${isLinked ? ' %u' : ''}`, ...(hasIcon ? [`Icon=${command}`] : []),
+        ...(isLinked ? [`MimeType=${urlSchemes.map((scheme) => `x-scheme-handler/${scheme};`).join('')}`] : []), 'Terminal=false', '',
+    ].join('\n');
+}
+
+// A disk image of a macOS app beside a link to /Applications, onto which its user drags it. hdiutil copies a link
+// inside the folder it is given as a link, where it would copy all of /Applications for the link itself. The image is
+// not signed: Gatekeeper would then judge it as well, where the app in it is what Apple notarizes.
+function diskImage(app, target) {
+    const image = app.replace(/\.app$/, '.dmg');
+    const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'crossbind-dmg-'));
+    try {
+        // The image's root takes the folder's permissions, which mkdtemp keeps to its owner.
+        fs.chmodSync(folder, 0o755);
+        fs.cpSync(app, path.join(folder, path.basename(app)), { recursive: true, verbatimSymlinks: true });
+        fs.symlinkSync('/Applications', path.join(folder, 'Applications'));
+        fs.rmSync(image, { force: true });
+        run(null, ['hdiutil', 'create', '-quiet', '-volname', appDisplayName(state.config), '-srcfolder', folder, '-fs', 'HFS+', '-format', 'UDZO', image], null, target);
+    } finally {
+        fs.rmSync(folder, { recursive: true, force: true });
+    }
+}
+
+// A Debian package of a Linux app, which dpkg-deb builds in the linux image: the app in /usr/lib/<name>, its command
+// in /usr/bin, and the desktop entry and icon a menu shows it by.
+function debianPackage(app, target) {
+    assertUnderBase(app, target);
+    const { general, paths } = state.config;
+    const name = debianName(general.name);
+    const label = appDisplayName(state.config);
+    const root = `${paths.build}/${path.basename(app)}.deb`;
+    const dir = (relative) => {
+        fs.mkdirSync(`${root}/${relative}`, { recursive: true });
+        return `${root}/${relative}`;
+    };
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.cpSync(app, `${dir('usr/lib')}/${name}`, { recursive: true, verbatimSymlinks: true });
+    fs.symlinkSync(`../lib/${name}/${general.name}`, `${dir('usr/bin')}/${name}`);
+    const icon = `${app}/resources/icon.png`;
+    const hasIcon = fs.existsSync(icon);
+    if (hasIcon) fs.copyFileSync(icon, `${dir('usr/share/icons/hicolor/512x512/apps')}/${name}.png`);
+    fs.writeFileSync(`${dir('usr/share/applications')}/${name}.desktop`, desktopEntry({ label, command: name, hasIcon, urlSchemes: appUrlSchemes(state.config) }));
+    const { author, description } = state.config.package ?? {};
+    fs.writeFileSync(`${dir('DEBIAN')}/control`, debianControl({ name, version: packageVersion(), arch: target.arch, author, description, label }));
+    run(null, ['dpkg-deb', '--build', '--root-owner-group', root, `${app}.deb`], null, target);
+    fs.rmSync(root, { recursive: true, force: true });
+}
+
+// The name a Windows app's setup program gives its Start menu shortcut and folder, which Windows takes as a file name.
+function windowsName() {
+    const label = appDisplayName(state.config);
+    if (/[<>:/|?*]|[ .]$/.test(label)) {
+        throw new Error(`crossbind: ${JSON.stringify(label)}, the name of a Windows app's Start menu shortcut and folder, is no file name Windows takes, which holds none of < > : / | ? * and ends in neither a space nor a dot. Change app.name in crossbind.config.js.`);
+    }
+    return label;
+}
+
+// A Windows setup program reads a dollar sign in its text as the start of a variable.
+const nsisText = (text) => text.replaceAll('$', () => '$$');
+
+// The schemes a Windows app's setup program registers, as a macro that calls the one it is given on each.
+const schemesMacro = (schemes) => ['!macro CROSSBIND_URL_SCHEMES DO', ...schemes.map((scheme) => `  !insertmacro \${DO} "${scheme}"`), '!macroend', ''].join('\n');
+
+// A Windows app's setup program, which NSIS builds in the windows image from the host's installer.nsi; with a key in
+// the environment, jsign signs it and its uninstaller as NSIS writes them.
+function windowsSetup(app) {
+    const signing = windowsSigning();
+    const icon = readAppIcon(state.config);
+    const iconFile = `${state.config.paths.build}/${path.basename(app)}.ico`;
+    if (icon) fs.writeFileSync(iconFile, windowsIcon(icon));
+    const urlSchemes = appUrlSchemes(state.config);
+    const schemesFile = `${state.config.paths.build}/${path.basename(app)}.schemes.nsh`;
+    if (urlSchemes.length > 0) fs.writeFileSync(schemesFile, schemesMacro(urlSchemes));
+    inWindowsImage([
+        'makensis', '-V2', '-INPUTCHARSET', 'UTF8',
+        `-DNAME=${nsisText(windowsName())}`,
+        `-DEXE=${nsisText(`${state.config.general.name}.exe`)}`,
+        `-DID=${appId(state.config)}`,
+        `-DVERSION=${nsisText(packageVersion())}`,
+        `-DAPP=${app}`,
+        `-DOUTFILE=${app}-setup.exe`,
+        ...(icon ? [`-DICON=${iconFile}`] : []),
+        ...(urlSchemes.length > 0 ? [`-DSCHEMES=${schemesFile}`] : []),
+        ...(signing ? [`-DSIGNER=${jsignScript()}`] : []),
+        `${resolveAppHostRoot()}/windows/installer.nsi`,
+    ], path.dirname(app), signing);
+}
+
+// What an app's installer takes from the app and the environment, checked before anything compiles: the names, the keys
+// that sign a macOS or Windows app, and the one that signs a desktop app's update.
+export function checkInstaller(target) {
+    if (target.platform === 'darwin') appleSigning();
+    else if (target.platform === 'linux') debianName(state.config.general.name);
+    else if (target.platform === 'win32') {
+        windowsName();
+        windowsSigning();
+    }
+    if (['darwin', 'linux', 'win32'].includes(target.platform)) updaterSigning();
+}
+
+// What installs a desktop app, written beside it: a disk image on macOS, a Debian package on Linux and a setup program
+// on Windows.
+export default function writeInstaller(app, target) {
+    if (target.platform === 'darwin') diskImage(app, target);
+    else if (target.platform === 'linux') debianPackage(app, target);
+    else if (target.platform === 'win32') windowsSetup(app);
+}

package/src/actions/appUpdate.js

@@ -0,0 +1,68 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import run from './run.js';
+import state from '../state/index.js';
+import { appId, appUpdater } from '../utils/appOptions.js';
+
+// The private key that signs a desktop app's updates, named by the environment alone so that no secret reaches a file.
+export const UPDATER_KEY = 'CROSSBIND_UPDATER_PRIVATE_KEY';
+// The fixed DER around an Ed25519 key's 32 bytes, private and public.
+const PRIVATE_DER = Buffer.from('302e020100300506032b657004220420', 'hex');
+const PUBLIC_DER = Buffer.from('302a300506032b6570032100', 'hex');
+
+const publicKeyOf = (privateKey) => crypto.createPublicKey(privateKey).export({ format: 'der', type: 'spki' }).subarray(PUBLIC_DER.length);
+
+// A new key pair: the public key for app.updater.publicKey, the private one for CROSSBIND_UPDATER_PRIVATE_KEY.
+export function newUpdaterKey() {
+    const { privateKey } = crypto.generateKeyPairSync('ed25519');
+    return {
+        publicKey: publicKeyOf(privateKey).toString('base64'),
+        privateKey: privateKey.export({ format: 'der', type: 'pkcs8' }).subarray(PRIVATE_DER.length).toString('base64'),
+    };
+}
+
+// The key a build signs updates with, or null without CROSSBIND_UPDATER_PRIVATE_KEY. It has to be the private half of
+// app.updater.publicKey, or the app would refuse what it signs.
+export function updaterSigning(env = process.env) {
+    if (!env[UPDATER_KEY]) return null;
+    const updater = appUpdater(state.config);
+    if (!updater) throw new Error(`crossbind: ${UPDATER_KEY} is set, but crossbind.config.js has no app.updater, which tells an app where its updates are.`);
+    const seed = Buffer.from(env[UPDATER_KEY], 'base64');
+    if (seed.length !== 32) throw new Error(`crossbind: ${UPDATER_KEY} is no Ed25519 private key, which \`crossbind app updater-key\` prints.`);
+    const privateKey = crypto.createPrivateKey({ key: Buffer.concat([PRIVATE_DER, seed]), format: 'der', type: 'pkcs8' });
+    if (!publicKeyOf(privateKey).equals(updater.publicKey)) {
+        throw new Error(`crossbind: ${UPDATER_KEY} is not the private key of app.updater.publicKey, so the app would refuse the updates it signs.`);
+    }
+    return { privateKey, version: updater.version };
+}
+
+// What an update's signature covers: the app's id, the platform and arch it is for, its version and its file's SHA-512,
+// so that no file passes for another app's, platform's or version's. The host checks the same text.
+export function signedText(id, target, version, file) {
+    const hash = crypto.createHash('sha512').update(fs.readFileSync(file)).digest('hex');
+    return `crossbind update\n${id}\n${target}\n${version}\n${hash}\n`;
+}
+
+// The file a desktop app updates itself from, beside it: a macOS app as a zip, which keeps its signature and Apple's
+// ticket, a Windows app's setup program and a Linux app's tar.gz.
+function updateFile(app, target) {
+    if (target.platform === 'win32') return `${app}-setup.exe`;
+    if (target.platform === 'linux') return `${app}.tar.gz`;
+    const zip = path.join(path.dirname(app), `${state.config.general.name}-darwin-${target.arch}.app.zip`);
+    fs.rmSync(zip, { force: true });
+    run(null, ['ditto', '-c', '-k', '--keepParent', app, zip], null, target);
+    return zip;
+}
+
+// With a key in the environment, the update a desktop app finds at app.updater.url, beside the app: its file, and the
+// manifest that gives its version, the file's name and its signature, <name>-<platform>-<arch>.update.json.
+export default function writeUpdate(app, target) {
+    const signing = updaterSigning();
+    if (!signing) return;
+    const file = updateFile(app, target);
+    const name = `${target.platform}-${target.arch}`;
+    const signature = crypto.sign(null, Buffer.from(signedText(appId(state.config), name, signing.version, file)), signing.privateKey).toString('base64');
+    const manifest = { version: signing.version, file: path.basename(file), signature };
+    fs.writeFileSync(path.join(path.dirname(app), `${state.config.general.name}-${name}.update.json`), `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/src/actions/appleSigning.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// The Developer ID that signs a macOS app and the App Store Connect API key Apple notarizes it with, named by the
+// environment alone so that no secret reaches a file.
+export const APPLE_SIGNING = {
+    identity: 'CROSSBIND_APPLE_SIGNING_IDENTITY',
+    key: 'CROSSBIND_APPLE_API_KEY',
+    keyId: 'CROSSBIND_APPLE_API_KEY_ID',
+    issuer: 'CROSSBIND_APPLE_API_ISSUER',
+};
+const NOTARY = [APPLE_SIGNING.key, APPLE_SIGNING.keyId, APPLE_SIGNING.issuer];
+
+const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+
+function tool(command, args) {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    if (result.error) throw new Error(`crossbind: cannot run ${command}: ${result.error.message}`, { cause: result.error });
+    if (result.status !== 0) throw new Error(`crossbind: ${command} ${args[0]} failed with exit code ${result.status}:\n${`${result.stdout}${result.stderr}`.trim()}`);
+    return result.stdout;
+}
+
+// The keychain's valid code signing identities, each a SHA-1 hash and a certificate's name.
+function signingIdentities() {
+    return tool('security', ['find-identity', '-v', '-p', 'codesigning']).split('\n')
+        .map((line) => line.match(/^\s*\d+\)\s+([0-9A-F]{40})\s+"(.*)"$/))
+        .filter(Boolean)
+        .map(([, hash, name]) => ({ hash, name }));
+}
+
+// The identity a macOS app is signed with and the key Apple notarizes it with, or null without an identity: the app is
+// then signed ad hoc, which opens it on the Mac that built it alone. codesign takes the identity's hash, which the
+// renewed certificates of one name do not share.
+export function appleSigning(env = process.env) {
+    const notary = NOTARY.filter((name) => env[name]);
+    const identity = env[APPLE_SIGNING.identity];
+    if (!identity) {
+        if (notary.length) throw new Error(`crossbind: ${listed(notary)} set without ${APPLE_SIGNING.identity}, the Developer ID that signs the app Apple notarizes.`);
+        return null;
+    }
+    const found = signingIdentities().filter(({ hash, name }) => hash === identity.toUpperCase() || name.includes(identity));
+    const matches = [...new Map(found.map((match) => [match.hash, match])).values()];
+    if (!matches.length) throw new Error(`crossbind: ${APPLE_SIGNING.identity} names ${JSON.stringify(identity)}, which no valid code signing identity in the keychain is; \`security find-identity -v -p codesigning\` lists them.`);
+    if (matches.length > 1) {
+        throw new Error(`crossbind: ${APPLE_SIGNING.identity} names ${JSON.stringify(identity)}, which ${matches.length} identities in the keychain are: ${matches.map(({ hash, name }) => `${hash} "${name}"`).join(', ')}. Set it to one of their hashes.`);
+    }
+    const [{ hash, name }] = matches;
+    if (!notary.length) return { identity: hash, notary: null };
+    const missing = NOTARY.filter((variable) => !env[variable]);
+    if (missing.length) throw new Error(`crossbind: ${listed(notary)} set, but ${listed(missing)} not: notarizing takes all three.`);
+    if (!name.startsWith('Developer ID Application:')) throw new Error(`crossbind: Apple notarizes an app signed with a Developer ID Application certificate, which ${JSON.stringify(name)} is not.`);
+    const key = path.resolve(env[APPLE_SIGNING.key]);
+    if (!fs.statSync(key, { throwIfNoEntry: false })?.isFile()) throw new Error(`crossbind: ${APPLE_SIGNING.key} names ${key}, which is no file.`);
+    return { identity: hash, notary: { key, keyId: env[APPLE_SIGNING.keyId], issuer: env[APPLE_SIGNING.issuer] } };
+}
+
+// The ticket Apple issues can take a moment to reach the servers stapler asks for it.
+function staple(app) {
+    let result;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        if (attempt > 0) spawnSync('sleep', ['15']);
+        result = spawnSync('xcrun', ['stapler', 'staple', app], { encoding: 'utf8' });
+        if (result.status === 0) return;
+    }
+    throw new Error(`crossbind: xcrun stapler failed with exit code ${result.status}:\n${`${result.stdout ?? ''}${result.stderr ?? ''}`.trim()}`);
+}
+
+// Apple notarizes a signed app sent to it as a zip, which takes a few minutes; the ticket stapled to the app then opens
+// it on any Mac, offline too.
+export function notarizeApp(app, notary) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'crossbind-notary-'));
+    const zip = path.join(dir, `${path.basename(app)}.zip`);
+    const key = ['--key', notary.key, '--key-id', notary.keyId, '--issuer', notary.issuer];
+    try {
+        tool('ditto', ['-c', '-k', '--keepParent', app, zip]);
+        console.log(`crossbind: Apple is notarizing ${path.basename(app)}, which takes a few minutes.`);
+        // notarytool's verdict is in its JSON, whatever its exit code.
+        const submit = spawnSync('xcrun', ['notarytool', 'submit', zip, ...key, '--wait', '--timeout', '2h', '--output-format', 'json'], { encoding: 'utf8' });
+        let verdict;
+        try {
+            verdict = JSON.parse(submit.stdout);
+        } catch (error) {
+            throw new Error(`crossbind: xcrun notarytool failed with exit code ${submit.status}:\n${`${submit.stdout ?? ''}${submit.stderr ?? ''}`.trim() || submit.error?.message}`, { cause: error });
+        }
+        const { id, status, message } = verdict;
+        if (status !== 'Accepted') {
+            const log = spawnSync('xcrun', ['notarytool', 'log', id, ...key], { encoding: 'utf8' }).stdout ?? '';
+            throw new Error(`crossbind: Apple did not notarize ${path.basename(app)} (${status}${message ? `: ${message}` : ''}). Its log:\n${log.trim()}`);
+        }
+        staple(app);
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}