crossbind 2.0.0-beta.65 → 2.0.0-beta.66

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "crossbind",
-    "version": "2.0.0-beta.65",
+    "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

@@ -9,7 +9,7 @@ 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.
-function adbPath() {
+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')]

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 });
+    }
+}

package/src/actions/buildApp.js

@@ -20,17 +20,25 @@ import writeXcodeProject, { HERMES_SLICES, IOS_SDKS } from './xcodeProject.js';
 import writeGradleProject, { ANDROID_ABIS } from './gradleProject.js';
 import { attachedDevice } from './androidDevice.js';
 import { packageAndroidRelease } from './androidGradle.js';
+import writeInstaller, { assertUnderBase } from './appInstaller.js';
+import writeUpdate from './appUpdate.js';
+import { APPLE_SIGNING, appleSigning, notarizeApp } from './appleSigning.js';
+import { WINDOWS_SIGNING, signWindows, windowsSigning } from './windowsSigning.js';
 import state from '../state/index.js';
 import logger from '../utils/logger.js';
 import findFiles from '../utils/findFiles.js';
 import { getContentHash, getFilesFingerprint } from '../utils/hash.js';
 import { xmlPlist } from '../utils/plist.js';
+import {
+    appBackgroundColor, appDisplayName, appHeader, appId, appPermissions, appUrlSchemes, usageDescriptions,
+} from '../utils/appOptions.js';
+import { androidIcons, iosIcon, linuxIcon, macIcon, readAppIcon, windowsIcon } from '../utils/appIcon.js';
+import writeIfChanged from '../utils/writeIfChanged.js';
 import { writeNativeSourceStamp } from '../utils/nativeSourceStamp.js';
 import resetCMakeCacheForSource from '../utils/resetCMakeCacheForSource.js';
 import resolveAppHostRoot, { resolveAppEmbindJsiRoot } from '../utils/resolveAppHost.js';
 import resolveHermes, { HERMES } from '../utils/hermes.js';
 import { getDockerImage, imageRoleFor } from '../utils/pullDockerImage.js';
-import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
 import { chosenRunner } from '../utils/selectRunner.js';
 import { DARWIN_DEPLOYMENT_TARGET } from '../utils/darwinToolchain.js';
 
@@ -102,15 +110,6 @@ export function appTargetParams({ dev = false } = {}, env = process.env) {
     return getTargetParams({ platform: ['ios'], arch: dev ? ['iphonesimulator'] : IOS_SDKS, runtime: ['mt'], runtimeEnv: ['app'] }, true);
 }
 
-// An app's bundle id: the project's app.id, else one made from the project's name.
-function appId() {
-    const id = state.config.app.id ?? `dev.crossbind.${state.config.general.name.replace(/[^A-Za-z0-9.-]/g, '-')}`;
-    if (!/^[A-Za-z0-9.-]+$/.test(id)) {
-        throw new Error(`crossbind: app.id ${JSON.stringify(id)} is no bundle id, which takes letters, digits, hyphens and dots, as com.example.app does.`);
-    }
-    return id;
-}
-
 // The Apple team that signs an iOS app: the project's app.team, else the machine's XCODE_DEVELOPMENT_TEAM, else none.
 function appTeam() {
     const team = state.config.app.team ?? state.config.system.XCODE_DEVELOPMENT_TEAM ?? '';
@@ -182,16 +181,24 @@ async function bundle(input, file, plugins) {
     await build.close();
 }
 
-const infoPlist = (name, version) => xmlPlist({
+// A development build claims no scheme: the built app, of the same id, owns them, and a link it opens shows its own page.
+const urlSchemesOf = (target) => (target.buildType === 'release' ? appUrlSchemes(state.config) : []);
+
+const infoPlist = (name, version, hasIcon, urlSchemes) => xmlPlist({
+    CFBundleDisplayName: appDisplayName(state.config),
     CFBundleExecutable: name,
-    CFBundleIdentifier: appId(),
-    CFBundleName: name,
+    // Contents/Resources/icon.icns.
+    ...(hasIcon ? { CFBundleIconFile: 'icon' } : {}),
+    CFBundleIdentifier: appId(state.config),
+    CFBundleName: appDisplayName(state.config),
     CFBundlePackageType: 'APPL',
     CFBundleShortVersionString: version,
+    ...(urlSchemes.length > 0 ? { CFBundleURLTypes: [{ CFBundleURLName: appId(state.config), CFBundleURLSchemes: urlSchemes }] } : {}),
     CFBundleVersion: version,
     LSMinimumSystemVersion: DARWIN_DEPLOYMENT_TARGET,
     NSPrincipalClass: 'NSApplication',
     NSHighResolutionCapable: true,
+    ...usageDescriptions(state.config, 'darwin'),
 });
 
 // The host's bytecode and the data the packages ship, beside the page's folder.
@@ -203,8 +210,9 @@ function copyAppFiles(dir, hbc, target) {
     });
 }
 
-// Everything but the page: the host and the app's files, and on macOS Hermes beside them.
-function assembleApp(target, { executable, hbc, hermes }) {
+// Everything but the page: the host and the app's files, its icon, and on macOS Hermes beside them. A Windows host
+// carries its icon itself.
+function assembleApp(target, { executable, hbc, hermes, icon }) {
     const app = `${state.config.paths.build}/${target.appName}`;
     const { name } = state.config.general;
     const layout = appLayout(target);
@@ -212,8 +220,10 @@ function assembleApp(target, { executable, hbc, hermes }) {
     fs.mkdirSync(path.dirname(`${app}/${layout.executable}`), { recursive: true });
     fs.copyFileSync(executable, `${app}/${layout.executable}`);
     copyAppFiles(`${app}/${layout.resources}`, hbc, target);
+    if (target.platform === 'linux' && icon) fs.writeFileSync(`${app}/${layout.resources}/icon.png`, linuxIcon(icon));
     if (target.platform !== 'darwin') return;
-    fs.writeFileSync(`${app}/Contents/Info.plist`, infoPlist(name, appVersion()));
+    fs.writeFileSync(`${app}/Contents/Info.plist`, infoPlist(name, appVersion(), Boolean(icon), urlSchemesOf(target)));
+    if (icon) fs.writeFileSync(`${app}/Contents/Resources/icon.icns`, macIcon(icon));
     const framework = `${app}/Contents/Frameworks/hermesvm.framework`;
     fs.cpSync(`${hermes}/Library/Frameworks/macosx/hermesvm.framework`, framework, { recursive: true, verbatimSymlinks: true });
     // The release carries Intel and Apple silicon; an app of one arch needs its own half.
@@ -266,9 +276,7 @@ const appParts = (target) => state.targets
 // image.
 function archiveApp(app, target) {
     if (target.platform === 'win32') {
-        if (!isUnderBase(app, state.config.paths.base)) {
-            throw new Error(`crossbind: the Windows app ${app} is outside ${state.config.paths.base}, the project's base and all the windows container sees. Build the app into a directory under it.`);
-        }
+        assertUnderBase(app, target);
         fs.rmSync(`${app}.zip`, { force: true });
         run(null, ['zip', '-q', '-r', '-X', `${path.basename(app)}.zip`, path.basename(app)], null, target, { workdir: path.dirname(app) });
         return;
@@ -280,11 +288,40 @@ function archiveApp(app, target) {
     if (result.status !== 0) throw new Error(`crossbind: cannot archive ${app}: ${result.stderr || result.error?.message}`);
 }
 
+const ENTITLEMENTS = {
+    camera: 'com.apple.security.device.camera',
+    microphone: 'com.apple.security.device.audio-input',
+    location: 'com.apple.security.personal-information.location',
+};
+
 // Apple silicon runs signed code only, and a bundle's signature covers every file in it, so an app is signed once the
-// page is in: ad hoc, which runs on the machine that built it.
-function signApp(app, target) {
-    run(null, ['codesign', '--force', '--sign', '-', '--timestamp=none', `${app}/Contents/Frameworks/hermesvm.framework`], null, target);
-    run(null, ['codesign', '--force', '--sign', '-', '--timestamp=none', app], null, target);
+// page is in: with the Developer ID the environment names, in the hardened runtime notarizing asks for, or else ad hoc,
+// which runs on the machine that built it.
+function signApp(app, target, signing) {
+    const sign = signing ? ['--sign', signing.identity, '--options', 'runtime', '--timestamp'] : ['--sign', '-', '--timestamp=none'];
+    run(null, ['codesign', '--force', ...sign, `${app}/Contents/Frameworks/hermesvm.framework`], null, target);
+    // The hardened runtime keeps the app from the devices of app.permissions unless its signature claims them.
+    const claims = Object.keys(appPermissions(state.config)).map((name) => ENTITLEMENTS[name]);
+    const entitlements = claims.length > 0 ? `${state.config.paths.build}/${path.basename(app)}.entitlements` : null;
+    if (entitlements) fs.writeFileSync(entitlements, xmlPlist(Object.fromEntries(claims.map((claim) => [claim, true]))));
+    run(null, ['codesign', '--force', ...sign, ...(entitlements ? ['--entitlements', entitlements] : []), app], null, target);
+}
+
+// A Windows app is signed before its zip and its setup program are made of it; one with its page that is not, the build
+// says SmartScreen warns of.
+function signWindowsApp(app, target, page) {
+    assertUnderBase(app, target);
+    const signing = windowsSigning();
+    if (signing) signWindows([`${app}/${appLayout(target).executable}`], signing);
+    else if (page) console.warn(`crossbind: ${path.basename(app)} is not signed, so SmartScreen warns of it and of its setup program once they are downloaded. Set ${WINDOWS_SIGNING.storetype} and the key it names to sign them with Authenticode.`);
+}
+
+// A macOS app with its page is the one that ships: Apple notarizes it, or the build says why another Mac refuses it.
+function shipMacApp(app, signing) {
+    const notarize = `${APPLE_SIGNING.key}, ${APPLE_SIGNING.keyId} and ${APPLE_SIGNING.issuer} to have Apple notarize it`;
+    if (signing?.notary) notarizeApp(app, signing.notary);
+    else if (signing) console.warn(`crossbind: ${path.basename(app)} is signed with your Developer ID but not notarized, so another Mac opens it only once its user allows it in System Settings. Set ${notarize}.`);
+    else console.warn(`crossbind: ${path.basename(app)} is signed ad hoc, which opens it on this Mac alone. Set ${APPLE_SIGNING.identity} to sign it with your Developer ID, and ${notarize}.`);
 }
 
 // Where a build without a bundler puts an app: under its own name, or for iOS and Android as the project of its build
@@ -301,9 +338,17 @@ export function publishApp(target, { to = appOutputPath(target), page = null } =
     const built = `${state.config.paths.build}/${target.appName}`;
     if (target.platform === 'ios') {
         const parts = appParts(target).map(({ arch, dir }) => ({ sdk: arch, dir }));
-        writeXcodeProject(to, { parts, identity: { id: appId(), team: appTeam() }, version: appVersion() });
+        const icon = readAppIcon(state.config);
+        writeXcodeProject(to, {
+            parts, identity: { id: appId(state.config), team: appTeam() }, label: appDisplayName(state.config), version: appVersion(), icon: icon && iosIcon(icon),
+            urlSchemes: appUrlSchemes(state.config), background: appBackgroundColor(state.config), usage: usageDescriptions(state.config, 'ios'),
+        });
     } else if (target.platform === 'android') {
-        writeGradleProject(to, { parts: appParts(target), id: androidAppId(), version: androidVersion() });
+        const icon = readAppIcon(state.config);
+        writeGradleProject(to, {
+            parts: appParts(target), id: androidAppId(), label: appDisplayName(state.config), version: androidVersion(), icons: icon && androidIcons(icon),
+            urlSchemes: appUrlSchemes(state.config), background: appBackgroundColor(state.config), permissions: Object.keys(appPermissions(state.config)),
+        });
     } else if (path.resolve(to) !== path.resolve(built)) {
         fs.rmSync(to, { recursive: true, force: true });
         fs.cpSync(built, to, { recursive: true, verbatimSymlinks: true });
@@ -311,15 +356,29 @@ export function publishApp(target, { to = appOutputPath(target), page = null } =
     if (page) {
         // The app may land inside the page's own directory, which it then leaves out, with every app built there and what
         // packages it.
-        const apps = new Set([path.basename(to), ...state.targets.filter((t) => t.runtimeEnv === 'app').map(appOutputName)]);
-        const isApp = (entry) => entry.endsWith('.app') || apps.has(entry.replace(/\.(tar\.gz|zip|apk|aab)$/, ''));
+        const apps = new Set([path.basename(to), ...state.targets.filter((t) => t.runtimeEnv === 'app')
+            .flatMap((t) => [appOutputName(t), `${state.config.general.name}-${t.platform}-${t.arch}`])]);
+        const isApp = (entry) => entry.endsWith('.app') || apps.has(entry.replace(/\.dmg$/, '.app'))
+            || apps.has(entry.replace(/(\.tar\.gz|\.app\.zip|\.zip|\.apk|\.aab|\.deb|-setup\.exe|\.update\.json)$/, ''));
         fs.readdirSync(page).filter((entry) => !isApp(entry)).forEach((entry) => {
             fs.cpSync(`${page}/${entry}`, `${to}/${appLayout(target).resources}/page/${entry}`, { recursive: true });
         });
     }
-    if (target.platform === 'darwin') signApp(to, target);
-    else if (target.platform === 'android' && target.buildType === 'release') packageAndroidRelease(to);
-    else if (!['ios', 'android'].includes(target.platform)) archiveApp(to, target);
+    if (target.platform === 'darwin') {
+        const signing = appleSigning();
+        signApp(to, target, signing);
+        if (page) shipMacApp(to, signing);
+    } else if (target.platform === 'android' && target.buildType === 'release') {
+        packageAndroidRelease(to);
+    } else if (!['ios', 'android'].includes(target.platform)) {
+        if (target.platform === 'win32') signWindowsApp(to, target, page);
+        archiveApp(to, target);
+    }
+    // A desktop app with its page ships with what installs it, and with an updater's key with its update too.
+    if (page && ['darwin', 'linux', 'win32'].includes(target.platform)) {
+        writeInstaller(to, target);
+        writeUpdate(to, target);
+    }
     return to;
 }
 
@@ -334,6 +393,10 @@ export default async function buildApp(target, { bridges = [], force = false } =
         logger.info(`[${target.path}] app skipped (cargo package - staticlib only)`);
         return false;
     }
+    // Where the page opens files, a desktop host's title and window, a Windows one's version, and the app's icon: a bad
+    // app section stops the build before anything compiles.
+    const header = appHeader(state.config, target.platform);
+    const icon = readAppIcon(state.config);
 
     const buildType = target.buildType === 'release' ? 'Release' : 'Debug';
     const { build } = state.config.paths;
@@ -355,7 +418,12 @@ export default async function buildApp(target, { bridges = [], force = false } =
 
     const fingerprintFile = `${build}/${target.appName}.fingerprint`;
     const fingerprint = getContentHash(JSON.stringify({
-        builder: getFilesFingerprint([fileURLToPath(import.meta.url)]),
+        builder: getFilesFingerprint([fileURLToPath(import.meta.url), fileURLToPath(new URL('../utils/appIcon.js', import.meta.url))]),
+        header,
+        // A desktop app carries its icon; an iOS or Android one gets it as its project is written.
+        icon: ['ios', 'android'].includes(target.platform) ? null : icon?.hash ?? null,
+        // A macOS app's bundle takes its id, name and version from it.
+        infoPlist: target.platform === 'darwin' ? infoPlist(state.config.general.name, appVersion(), Boolean(icon), urlSchemesOf(target)) : null,
         hermes: HERMES.version,
         inputs,
         linkArgs,
@@ -386,6 +454,13 @@ export default async function buildApp(target, { bridges = [], force = false } =
     const hostName = target.platform === 'android' ? 'crossbind_app' : name;
     logger.startStep(target, 'app');
     resetCMakeCacheForSource(workDir, `${appHostRoot}/cpp`, target);
+    // The host includes it from its build directory; written only when it changed, it recompiles nothing otherwise.
+    writeIfChanged(`${workDir}/crossbind_app.h`, header);
+    // A Windows host's executable carries the app's icon, which its resource script takes from beside the header.
+    if (target.platform === 'win32') {
+        if (icon) writeIfChanged(`${workDir}/icon.ico`, windowsIcon(icon));
+        else fs.rmSync(`${workDir}/icon.ico`, { force: true });
+    }
     run(null, [
         // An iOS host builds with crossbind's iOS toolchain file rather than as an Xcode project of its own.
         target.platform === 'ios' ? 'ios-cmake' : 'cmake', `${appHostRoot}/cpp`,
@@ -414,7 +489,7 @@ export default async function buildApp(target, { bridges = [], force = false } =
     } else if (target.platform === 'android') {
         assembleAndroidPart(target, { libDir: workDir, sharedLibs: libs.filter((lib) => lib.endsWith('.so')), hbc: `${workDir}/host.hbc` });
     } else {
-        assembleApp(target, { executable: `${workDir}/${path.basename(appLayout(target).executable)}`, hbc: `${workDir}/host.hbc`, hermes });
+        assembleApp(target, { executable: `${workDir}/${path.basename(appLayout(target).executable)}`, hbc: `${workDir}/host.hbc`, hermes, icon });
     }
     logger.doneStep(target, 'app');