@imagina-build/ias-cli 0.0.0-stage → 0.1.0

package/src/commands/submit/index.mjs

@@ -0,0 +1,85 @@
+// ias submit: sends a store build that succeeded to App Store Connect or Google Play (docs/technical/runner-api.md §6, decision
+// D7). The runner does it, with the keys sealed in the vault, after an owner approves it with a passkey: always as a
+// draft, to send for review in the store. It opens the approval and, with --wait, follows the submission to its end.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { connect, openUrl, sleep } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildsClient, isFinished } from '../build/follow.mjs';
+
+const BUILD_ID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+const TRACK = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const DEFAULT_TRACK = 'internal';
+
+/** What the store says of a submission that ended: the delivery of App Store Connect, or the edit of Google Play. */
+function outcome(submission) {
+  const result = submission.result ?? {};
+  const parts = [result.deliveryUuid && `delivery ${result.deliveryUuid}`, result.editId && `edit ${result.editId}`, result.versionCode && `version code ${result.versionCode}`].filter(Boolean);
+  if (submission.error) parts.push(`${submission.error.code}${submission.error.message ? `: ${submission.error.message}` : ''}`);
+  return parts.length > 0 ? ` (${parts.join(', ')})` : '';
+}
+
+/** The body of POST /builds/{id}/submit for `build`, from the options and the submit profile of ias.json. */
+function targetOf(context, build, config) {
+  const { values, output } = context;
+  const profile = config?.submit?.[build.profile] ?? {};
+  if (build.platform === 'ios') {
+    if (values.track) throw new IasError('--track is for Google Play', { fix: 'an iOS build goes to App Store Connect (TestFlight), without a track' });
+    const ascAppId = values['asc-app-id'] ?? profile.ios?.ascAppId;
+    if (ascAppId !== undefined && !/^[0-9]{1,20}$/.test(ascAppId)) throw new IasError(`«${ascAppId}» is not the Apple ID of an app`, { fix: 'it is the number App Store Connect shows in App Information' });
+    return { target: 'app_store_connect', ...(ascAppId ? { asc_app_id: ascAppId } : {}) };
+  }
+  if (values['asc-app-id']) throw new IasError('--asc-app-id is for App Store Connect', { fix: 'an Android build goes to Google Play: --track production, beta, alpha or internal' });
+  const track = values.track ?? profile.android?.track ?? DEFAULT_TRACK;
+  if (!TRACK.test(track)) throw new IasError(`«${track}» is not a track of Google Play`, { fix: 'production, beta, alpha, internal or the name of a closed track' });
+  if (profile.android?.releaseStatus && profile.android.releaseStatus !== 'draft') output.warn(`submit.${build.profile}.android.releaseStatus is ${profile.android.releaseStatus}, but IAS always sends a draft (D7): send it for review in Play Console`);
+  return { target: 'google_play', track, release_status: 'draft' };
+}
+
+async function submit(context) {
+  const { values, env, output } = context;
+  const project = loadProject(resolve(context.cwd, values.project ?? '.'));
+  const client = buildsClient(connect(context, project));
+  const { data: build } = await client.request('GET', `/builds/${context.positionals[0]}`);
+  if (build.distribution !== 'store') throw new IasError(`${build.id} is an internal build (${build.profile})`, { fix: 'only a store build goes to the stores: ias build --profile production', code: 'build_not_submittable' });
+  const body = targetOf(context, build, project.config);
+  const { data: submission } = await client.request('POST', `/builds/${build.id}/submit`, { json: body });
+  const where = body.target === 'google_play' ? `Google Play (${body.track}, draft)` : 'App Store Connect';
+  output.progress(`${build.platform} ${build.version} (${build.build_number}) to ${where}: submission ${submission.id}, ${submission.status}`);
+  if (submission.approval_url) {
+    const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(submission.approval_url);
+    output.progress(`${opened ? 'Opened' : 'Open'} ${submission.approval_url}: an owner approves it with a passkey (the panel shows the hash ${submission.hash}).`);
+  }
+  if (!values.wait) {
+    output.log(`ias builds view ${build.id} shows how it goes; the runner sends it once it is approved.`);
+    return submission;
+  }
+  const wait = context.sleep ?? sleep;
+  let current = submission;
+  let said = current.status;
+  while (!isFinished(current.status)) {
+    await wait(5);
+    const { data } = await client.request('GET', `/builds/${build.id}`);
+    current = (data.submissions ?? []).find((candidate) => candidate.id === submission.id) ?? current;
+    if (current.status !== said) {
+      said = current.status;
+      output.progress(`  ${current.status}${current.step ? ` (${current.step})` : ''}${current.runner?.name ? ` on ${current.runner.name}` : ''}`);
+    }
+  }
+  output.log(`submission ${current.id} to ${where}: ${current.status}${outcome(current)}`);
+  return current.status === 'succeeded' ? current : { ...current, [EXIT_CODE]: 1 };
+}
+
+export default {
+  name: 'submit',
+  summary: 'Send a store build to App Store Connect or Google Play, as a draft, after an owner approves it',
+  description: 'The runner sends it with the keys of the vault (asc_api_key, google_service_account), and always as a draft: the review is asked in the store. The track and the Apple ID of the app come from the options or from submit.<profile> of ias.json; Google Play goes to the internal track by default.',
+  positionals: [{ name: 'build', description: 'The id of a store build that succeeded, from ias builds list.', pattern: BUILD_ID }],
+  options: {
+    track: { type: 'string', value: '<track>', description: 'Google Play: production, beta, alpha, internal (the default) or a closed track.' },
+    'asc-app-id': { type: 'string', value: '<id>', description: 'App Store Connect: the Apple ID of the app (submit.<profile>.ios.ascAppId by default).' },
+    wait: { type: 'boolean', description: 'Wait until the runner has sent it, and say what the store answered.' },
+  },
+  run: submit,
+};

package/src/commands/update/index.mjs

@@ -0,0 +1,526 @@
+// ias update: signed OTA updates of an Expo app (API.md §36), from the Mac that holds the signing key; the server never
+// sees it. It exports a commit, signs one manifest per platform, uploads only the files the server lacks and publishes;
+// then it asks for the manifest as a phone would and checks the signature and every file. It was tools/expo-ota. Each
+// channel has a key of its own (§36.8: updates.channels of ias.json), a publication can start with a share of the
+// installations (§36.9), and promote signs the contents of a group again for another channel, never copying a signature.
+import { Buffer } from 'node:buffer';
+import { X509Certificate, createPublicKey } from 'node:crypto';
+import { copyFileSync, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+import { gzipSync } from 'node:zlib';
+import { projectFor, updateSettings } from '../../config.mjs';
+import { IasError, UsageError } from '../../errors.mjs';
+import { api, download } from '../../http.mjs';
+import { INSTALLS, buildManifests, firstPart, installationInside, promoted, publicKeyOf, readEnvFile, rollbackDirectives, sha256, signatureHeader, verifySignature } from '../../ota.mjs';
+import { gently, run, temporary } from '../../process.mjs';
+import { readSecret, readSecretFile, isReference, tokenKind } from '../../secrets.mjs';
+
+export const PLATFORMS = ['ios', 'android'];
+
+/** The environment of the app's tools: none of this shell's EXPO_PUBLIC_* (they would go into the bundle) or secrets. */
+function appEnv() {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(EXPO_PUBLIC_|OTA_|IAS_)/.test(key) && !['EXPO_TOKEN', 'NODE_ENV'].includes(key)));
+  return { ...env, CI: '1', EXPO_NO_TELEMETRY: '1' };
+}
+
+/**
+ * The channels of updates.channels in ias.json, each with its keyid, the op:// reference of its private key and the
+ * certificate its builds carry (a file of the repository). The channel of app.json needs none: it signs as always.
+ */
+export function withChannels(settings, project) {
+  const channels = {};
+  for (const [name, channel] of Object.entries(project.config?.updates?.channels ?? {})) {
+    channels[name] = {
+      channel: name,
+      keyid: channel.keyId,
+      privateKey: channel.privateKey,
+      get certificate() {
+        const file = join(settings.projectDir, channel.certificate);
+        if (!existsSync(file)) throw new IasError(`no certificate at ${channel.certificate} (updates.channels.${name}.certificate of ias.json)`, { fix: 'it is the public certificate the builds of that channel carry: keep it in the repository' });
+        return new X509Certificate(readFileSync(file));
+      },
+      source: `updates.channels.${name} of ias.json`,
+      needs: { privateKey: new IasError(`no private key for the channel ${name}`, { fix: `set updates.channels.${name}.privateKey in ias.json (an op:// reference)` }) },
+    };
+  }
+  return { ...settings, channels };
+}
+
+/**
+ * How to sign for a channel: updates.channels.<channel> of ias.json if it has it, or else the certificate, keyid and
+ * key of the default channel (app.json's, or updates.signing of ias.json), the channel its builds ask for. The server
+ * checks it with the channel's own certificate.
+ */
+export function signingFor(settings, channel) {
+  if (channel && settings.channels?.[channel]) return settings.channels[channel];
+  return { channel, keyid: settings.keyid, privateKey: settings.privateKey, certificate: settings.certificate, source: settings.signingSource ?? 'app.json', needs: settings.needs };
+}
+
+/** Stops before signing with a certificate the builds would reject, and warns a year before it expires. */
+export function checkCertificate(settings, output, signing = signingFor(settings)) {
+  const daysLeft = Math.floor((Date.parse(signing.certificate.validTo) - Date.now()) / 86_400_000);
+  if (daysLeft < 0) throw new Error(`the certificate expired on ${signing.certificate.validTo}: the builds that carry it reject every update; a new one needs a new build`);
+  if (daysLeft < 365) output.warn(`the certificate expires in ${daysLeft} days (${signing.certificate.validTo}); rotate it with the next store build`);
+  return daysLeft;
+}
+
+/** The private key (PEM), checked against the certificate; from 1Password or a file outside the project (mode 600). */
+export function privateKeyPem(settings, signing = signingFor(settings)) {
+  if (!signing.privateKey) throw signing.needs?.privateKey ?? settings.needs.privateKey;
+  let path;
+  if (isReference(signing.privateKey)) {
+    path = readSecretFile(signing.privateKey, 'private-key.pem');
+  } else {
+    try {
+      path = realpathSync(resolve(signing.privateKey));
+    } catch {
+      throw new Error(`no private key at ${signing.privateKey}`);
+    }
+    if (!relative(realpathSync(settings.projectDir), path).startsWith('..')) throw new Error('the private key is inside the project: move it out (and never commit it)');
+    if (statSync(path).mode & 0o077) throw new Error(`the private key can be read by other users: chmod 600 ${signing.privateKey}`);
+  }
+  const pem = readFileSync(path, 'utf8');
+  const der = (key) => key.export({ type: 'spki', format: 'der' }).toString('base64');
+  if (der(signing.certificate.publicKey) !== der(createPublicKey(pem))) throw new Error(signing.source === 'app.json' ? 'the private key is not the one of the certificate in app.json' : `the private key is not the one of the certificate of ${signing.source}`);
+  return pem;
+}
+
+/**
+ * Before signing for a channel named on the command line: the server must have it, with the keyid and certificate
+ * this Mac signs with, or every build of the channel would refuse the update. Only compares: what the Mac signs is
+ * never checked against what the server says.
+ */
+export async function checkChannel(settings, token, signing, known = undefined) {
+  if (!signing.channel || settings.source === 'legacy') return undefined;
+  const data = known ?? (await api(settings, token, 'GET', '/channels')).data;
+  const remote = data.channels.find((candidate) => candidate.name === signing.channel);
+  if (!remote) throw new IasError(`the project has no channel ${signing.channel}`, { fix: `create it on the server with its own certificate: php artisan ota:project ${settings.project} --channel=${signing.channel} --certificate=… --keyid=…`, code: 'channel_not_found' });
+  if (remote.key_id !== signing.keyid || publicKeyOf(signing.certificate) !== publicKeyOf(new X509Certificate(remote.certificate.pem))) {
+    throw new IasError(`the channel ${signing.channel} of the server checks signatures with keyid ${remote.key_id} and another certificate than ${signing.source} (keyid ${signing.keyid})`, {
+      fix: `set updates.channels.${signing.channel} in ias.json with its keyId, privateKey and certificate`,
+      code: 'channel_signing_mismatch',
+    });
+  }
+  return remote;
+}
+
+/** The share of installations a publication starts with: 1 to 100 (100, or nothing, is everyone). */
+export function rolloutOf(value) {
+  if (value === undefined) return undefined;
+  const percent = Number(value);
+  if (!Number.isInteger(percent) || percent < 1 || percent > 100) throw new UsageError(`--rollout is a whole number from 1 to 100, not ${value}`, { fix: 'leave it out to publish to every installation' });
+  return percent;
+}
+
+/** The publishing token of the OTA project: the variable or the op:// reference, read now. */
+export function publishingToken(settings) {
+  const source = settings.token || settings.loggedIn?.();
+  if (!source) throw settings.needs.token;
+  const token = readSecret(source);
+  if (tokenKind(token) === 'dist') throw new IasError('the token is the one of a distribution project (dist_…)', { fix: 'ias update needs the publishing token of the OTA project (ota_…, php artisan ota:token): check IAS_TOKEN, OTA_TOKEN or the token of the configuration' });
+  return token;
+}
+
+/**
+ * A copy of `ref` to export from: git archive, a clean install from the lockfile and the environment file. Not a linked
+ * node_modules: with one, expo-router found no routes in the bundle and the app failed to start on the update.
+ */
+function copyOf(settings, ref, output) {
+  const prefix = run('git', ['rev-parse', '--show-prefix'], { cwd: settings.projectDir }).trim();
+  if (prefix) throw new Error('run it from the root of the app\'s git repository (or pass --project <that folder>)');
+  const commit = run('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd: settings.projectDir, label: `git rev-parse ${ref} (no such commit?)` }).trim();
+  const dir = temporary();
+  run('git', ['archive', '--format=tar', '-o', join(dir, 'source.tar'), commit], { cwd: settings.projectDir });
+  const app = join(dir, 'app');
+  run('mkdir', [app]);
+  run('tar', ['-xf', join(dir, 'source.tar'), '-C', app]);
+  const install = INSTALLS.find(([lockfile]) => existsSync(join(app, lockfile)));
+  if (!install) throw new Error('the commit has no lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml or bun.lock): the copy could not install the same dependencies');
+  output.progress(`${install[1]} ${install[2][0]} in a copy of ${commit.slice(0, 10)}…`);
+  gently(install[1], install[2], { cwd: app, env: appEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  const mustContain = [];
+  if (settings.envFile) {
+    const envFile = join(settings.projectDir, settings.envFile);
+    if (!existsSync(envFile)) throw new Error(`no ${settings.envFile} (${settings.names.envFile})`);
+    copyFileSync(envFile, join(app, settings.envFile));
+    const values = readEnvFile(envFile, settings.bundleEnv);
+    for (const name of settings.bundleEnv) {
+      if (!values[name]) throw new Error(`${settings.envFile} has no ${name}, which ${settings.names.bundleEnv} says the bundle must carry`);
+      mustContain.push([name, values[name]]);
+    }
+  } else if (settings.bundleEnv.length > 0) {
+    throw new Error(`${settings.names.config} lists bundleEnv but no envFile to take them from`);
+  }
+  return { app, commit, mustContain };
+}
+
+function runtimeVersion(cwd, platform) {
+  const output = run('npx', ['expo-updates', 'runtimeversion:resolve', '--platform', platform], { cwd, env: appEnv(), label: 'expo-updates runtimeversion:resolve' });
+  return JSON.parse(output.slice(output.indexOf('{'))).runtimeVersion;
+}
+
+/** Publishes a commit (HEAD by default) for the platforms; with dryRun the server checks it all and keeps nothing. */
+export async function publish(settings, { ref = 'HEAD', message, platforms = PLATFORMS, channel, rollout, dryRun = false }, output) {
+  if (!message) throw new Error('--message "…" says what the update changes');
+  const signing = signingFor(settings, channel);
+  checkCertificate(settings, output, signing);
+  const key = privateKeyPem(settings, signing);
+  const token = publishingToken(settings);
+  await checkChannel(settings, token, signing);
+  if (ref === 'HEAD' && run('git', ['status', '--porcelain'], { cwd: settings.projectDir }).trim()) {
+    output.warn('the working tree has changes that are not committed; they are not published, the commit is');
+  }
+  const copy = copyOf(settings, ref, output);
+  const dist = join(dirname(copy.app), 'dist');
+  output.progress(`exporting ${copy.commit.slice(0, 10)} (${platforms.join(', ')})…`);
+  gently('npx', ['expo', 'export', ...platforms.flatMap((platform) => ['--platform', platform]), '--output-dir', dist], { cwd: copy.app, env: appEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  const { manifests, files } = buildManifests({
+    dist,
+    metadata: JSON.parse(readFileSync(join(dist, 'metadata.json'), 'utf8')),
+    platforms,
+    runtimes: Object.fromEntries(platforms.map((platform) => [platform, runtimeVersion(copy.app, platform)])),
+    expoClient: JSON.parse(run('npx', ['expo', 'config', '--type', 'public', '--json'], { cwd: copy.app, env: appEnv(), label: 'expo config' })),
+    assetPath: settings.assetPath,
+    createdAt: new Date().toISOString(),
+    mustContain: copy.mustContain,
+  });
+  return sendUpdate(settings, { token, key, signing, manifests, files, commit: copy.commit, message, channel, rollout, dryRun }, output);
+}
+
+/**
+ * The network half of publish: signs each manifest (and checks the signature with the certificate), warns about a
+ * runtime no phone asks for, uploads with gzip only the files the server lacks, publishes the platforms at once and,
+ * unless it is a dry run, checks what a phone now gets.
+ */
+export async function sendUpdate(settings, { token, key, channel, signing = signingFor(settings, channel), manifests, files, commit, message, rollout, dryRun }, output) {
+  const signed = Object.fromEntries(
+    Object.entries(manifests).map(([platform, manifest]) => {
+      const body = JSON.stringify(manifest);
+      const header = signatureHeader(body, key, signing.keyid);
+      if (!verifySignature(signing.certificate.publicKey, signing.keyid, body, header)) throw new Error('the signature does not verify with the certificate');
+      return [platform, { body, header }];
+    }),
+  );
+
+  const history = (await api(settings, token, 'GET', '/updates?limit=1')).data;
+  for (const [platform, manifest] of Object.entries(manifests)) {
+    if (!history.runtimes.some((seen) => seen.platform === platform && seen.runtime_version === manifest.runtimeVersion)) {
+      output.warn(`no ${platform} phone has asked for runtime ${manifest.runtimeVersion.slice(0, 8)} in 30 days (normal before its build is out)`);
+    }
+  }
+  const { data: missing } = await api(settings, token, 'POST', '/assets/missing', { json: { hashes: [...files.keys()] } });
+  let bytes = 0;
+  for (const hash of missing.missing) {
+    const { path, contentType } = files.get(hash);
+    const gzip = gzipSync(readFileSync(path), { level: 9 });
+    bytes += gzip.length;
+    await api(settings, token, 'PUT', `/assets/${hash}`, { body: gzip, headers: { 'content-type': contentType, 'content-encoding': 'gzip' } });
+  }
+  output.progress(`files: ${files.size}, ${missing.missing.length} uploaded (${(bytes / 1e6).toFixed(2)} MB gzipped)`);
+
+  const body = Object.fromEntries(Object.entries(signed).map(([platform, { body: manifest, header }]) => [platform, { manifest: Buffer.from(manifest).toString('base64'), signature: header }]));
+  const published = await postUpdate(settings, token, { commit, message, channel, rollout, dryRun, platforms: body }, output);
+  const checks = [];
+  if (!dryRun) for (const [platform, manifest] of Object.entries(manifests)) checks.push(await checkServed(settings, platform, manifest.runtimeVersion, manifest.id, output, servedAs(published, signing)));
+  return { ...published, commit, message, files: { total: files.size, uploaded: missing.missing.length, gzipped_bytes: bytes }, checks };
+}
+
+/**
+ * How to ask for what was just published as a phone would: in its channel and, during a rollout, as an installation
+ * inside the share (without EAS-Client-ID, or outside it, a phone gets the update before).
+ */
+const servedAs = (published, signing) => ({
+  channel: published.channel,
+  signing,
+  ...(published.rollout && published.rollout.percent < 100 ? { installation: installationInside(published.group, published.rollout.percent) } : {}),
+});
+
+/** Publishes the signed platforms (manifests or directives) as one group, and prints what the server kept. */
+export async function postUpdate(settings, token, { commit, message, channel, rollout, dryRun, platforms }, output) {
+  const { data } = await api(settings, token, 'POST', '/updates', {
+    json: { ...(channel ? { channel } : {}), message, ...(commit ? { commit: commit.slice(0, 40) } : {}), ...(rollout !== undefined ? { rollout } : {}), dry_run: dryRun, platforms },
+  });
+  output.log(`${dryRun ? 'dry run, nothing published' : `published group ${data.group}`} (channel ${data.channel}${data.rollout ? `, to ${data.rollout.percent} % of the installations` : ''})`);
+  for (const update of data.updates) output.log(`  ${update.platform} ${update.kind} ${update.id ?? ''} runtime ${update.runtime_version.slice(0, 8)} ${update.created_at}`);
+  return data;
+}
+
+/** Publishes the commit of an earlier group again, with another id and createdAt: the way back to older code. */
+export async function republish(settings, { group, message, ...options }, output) {
+  if (!group) throw new Error('republish <group>: the group, from list');
+  const found = (await api(settings, publishingToken(settings), 'GET', '/updates?limit=100')).data.groups.find((candidate) => candidate.group === group);
+  if (!found?.commit) throw new Error(`no group ${group} with a commit among the last 100`);
+  return publish(settings, { ...options, ref: found.commit, message: message ?? `Again: ${found.message ?? found.group} (${found.group.slice(0, 8)})` }, output);
+}
+
+/** Publishes a signed directive: the phones go back to the JavaScript inside their build. */
+export async function rollbackToEmbedded(settings, { platforms = PLATFORMS, message, channel, rollout, dryRun = false }, output) {
+  const signing = signingFor(settings, channel);
+  checkCertificate(settings, output, signing);
+  const key = privateKeyPem(settings, signing);
+  const token = publishingToken(settings);
+  await checkChannel(settings, token, signing);
+  const runtimes = Object.fromEntries(platforms.map((platform) => [platform, runtimeVersion(settings.projectDir, platform)]));
+  const directives = rollbackDirectives({ platforms, runtimes, privateKeyPem: key, keyid: signing.keyid, commitTime: new Date().toISOString() });
+  const commit = run('git', ['rev-parse', 'HEAD'], { cwd: settings.projectDir }).trim();
+  const published = await postUpdate(settings, token, { commit, message: message ?? 'Back to the JavaScript inside the build', channel, rollout, dryRun, platforms: directives }, output);
+  const checks = [];
+  if (!dryRun) for (const platform of platforms) checks.push(await checkServed(settings, platform, runtimes[platform], undefined, output, servedAs(published, signing)));
+  return { ...published, checks };
+}
+
+/**
+ * Publishes an earlier group in another channel: its bytes come from the server and are checked with the certificate
+ * of their channel this Mac trusts (app.json or updates.channels), then their contents are signed again, with a new id
+ * and createdAt, with the key of the channel they go to. A signature is never copied from one channel to another.
+ */
+export async function promote(settings, { group, to, message, rollout, dryRun = false }, output) {
+  if (!group) throw new UsageError('promote <group> --to <channel>: the group, from ias update list');
+  if (!to) throw new UsageError('promote needs --to <channel>: the channel it goes to');
+  const token = publishingToken(settings);
+  const { data: channels } = await api(settings, token, 'GET', '/channels');
+  const { data: source } = await api(settings, token, 'GET', `/updates/${group}`);
+  if (source.channel === to) throw new IasError(`the group ${group} is already in ${to}`, { fix: 'to serve it again, ias update restore <group>; to go back to it, ias update republish <group>' });
+  if (source.archived) throw new IasError(`the group ${group} is archived: its files are gone`, { fix: `publish its commit again in ${to}: ias update republish ${group} --channel ${to}` });
+  if (source.retired_at) output.warn(`the group ${group} is retired in ${source.channel}`);
+
+  const from = trustedSigning(settings, channels, source.channel);
+  const target = signingFor(settings, to);
+  checkCertificate(settings, output, target);
+  const key = privateKeyPem(settings, target);
+  await checkChannel(settings, token, target, channels);
+
+  const now = new Date().toISOString();
+  const platforms = {};
+  const expected = {};
+  for (const update of source.updates) {
+    const body = Buffer.from(update[update.kind], 'base64');
+    if (!verifySignature(from.certificate.publicKey, from.keyid, body, update.signature)) {
+      throw new IasError(`the ${update.platform} ${update.kind} of ${group} does not verify with the certificate of ${source.channel} (${from.source})`, { fix: 'nothing was signed: the server served something its channel never signed; look into it before publishing anything' });
+    }
+    const document = promoted(update.kind, body.toString('utf8'), now);
+    const signed = JSON.stringify(document);
+    const signature = signatureHeader(signed, key, target.keyid);
+    if (!verifySignature(target.certificate.publicKey, target.keyid, signed, signature)) throw new Error('the signature does not verify with the certificate');
+    platforms[update.platform] = update.kind === 'directive'
+      ? { directive: Buffer.from(signed).toString('base64'), signature, runtime_version: update.runtime_version }
+      : { manifest: Buffer.from(signed).toString('base64'), signature };
+    expected[update.platform] = { runtime: update.runtime_version, id: document.id };
+  }
+
+  const published = await postUpdate(settings, token, { commit: source.commit, message: message ?? `${source.message ?? source.group} (from ${source.channel})`, channel: to, rollout, dryRun, platforms }, output);
+  const checks = [];
+  if (!dryRun) for (const [platform, { runtime, id }] of Object.entries(expected)) checks.push(await checkServed(settings, platform, runtime, id, output, servedAs(published, target)));
+  return { ...published, promoted_from: { channel: source.channel, group: source.group }, checks };
+}
+
+/**
+ * The signing this Mac trusts for a channel of the server, to check what it re-signs: the one of updates.channels, or
+ * app.json's when the server's channel has its keyid. Whatever it is, the server's certificate must be the same.
+ */
+function trustedSigning(settings, channels, name) {
+  const remote = channels.channels.find((candidate) => candidate.name === name);
+  const local = settings.channels?.[name] ?? (remote && remote.key_id === settings.keyid ? signingFor(settings) : undefined);
+  if (!local || !remote) {
+    throw new IasError(`this Mac has no certificate of the channel ${name} to check the group with`, { fix: `set updates.channels.${name} in ias.json with its keyId, privateKey and certificate: promote only signs again what it can verify` });
+  }
+  if (remote.key_id !== local.keyid || publicKeyOf(local.certificate) !== publicKeyOf(new X509Certificate(remote.certificate.pem))) {
+    throw new IasError(`the server's certificate of the channel ${name} is not the one of ${local.source}`, { fix: 'compare the keyid and certificate of ias update channels with those of the repository' });
+  }
+  return local;
+}
+
+/** Changes the rollout of a group: a share from 1 to 99, pause, or complete (100 completes too). */
+export async function rollout(settings, { group, action }, output) {
+  if (!group || action === undefined) throw new UsageError('rollout <group> <percent>|pause|complete: the group, from ias update list, and what to do');
+  const percent = /^\d+$/.test(action) ? Number(action) : undefined;
+  if (percent === undefined && !['pause', 'complete'].includes(action)) throw new UsageError(`rollout takes a percentage (1–100), pause or complete, not ${action}`);
+  if (percent !== undefined && (percent < 1 || percent > 100)) throw new UsageError(`the percentage goes from 1 to 100, not ${percent}`, { fix: '100 completes the rollout: every installation gets the group' });
+  const path = percent === undefined ? `/updates/${group}/rollout/${action}` : percent === 100 ? `/updates/${group}/rollout/complete` : `/updates/${group}/rollout`;
+  const { data } = await api(settings, publishingToken(settings), 'POST', path, percent !== undefined && percent < 100 ? { json: { percent } } : {});
+  output.log(`rollout of ${data.group}: ${describeRollout(data.rollout)}`);
+  return data;
+}
+
+/** A rollout in a few words: «25 % (rolling)», «25 % (paused automatically)», «completed». */
+const describeRollout = (state) => (state.state === 'completed' ? 'completed' : `${state.percent} % (${state.state === 'paused' ? (state.paused_reason === 'automatic' ? 'paused automatically: the new update fails to launch more than the one before' : 'paused') : 'rolling'})`);
+
+/** The channels of the project with their keyid and certificate, and whether this Mac signs for each. */
+export async function channels(settings, output) {
+  const { data } = await api(settings, publishingToken(settings), 'GET', '/channels');
+  for (const channel of data.channels) {
+    const local = settings.channels?.[channel.name] ?? (channel.key_id === settings.keyid ? signingFor(settings) : undefined);
+    const signs = local && local.keyid === channel.key_id && publicKeyOf(local.certificate) === publicKeyOf(new X509Certificate(channel.certificate.pem));
+    output.log(`${channel.name}${channel.default ? ' (default)' : ''}: keyid ${channel.key_id}, certificate until ${channel.certificate.valid_until?.slice(0, 10) ?? '?'}, ${signs ? `signed with ${local.source}` : 'this Mac has no key for it'}`);
+  }
+  return data;
+}
+
+/** Stops serving a group (retire) or serves it again (restore): the emergency brake, also in the panel. */
+export async function setServing(settings, action, { group }, output) {
+  if (!group) throw new Error(`${action} <group>: the group, from list`);
+  const { data } = await api(settings, publishingToken(settings), 'POST', `/updates/${group}/${action}`);
+  output.log(`${action === 'retire' ? 'retired' : 'restored'} ${data.group}${data.retired_at ? ` (retired ${data.retired_at})` : ''}`);
+  return data;
+}
+
+/** The last groups and the runtimes the phones asked for in the last 30 days. */
+export async function list(settings, { channel }, output) {
+  const query = channel ? `&channel=${encodeURIComponent(channel)}` : '';
+  const { data } = await api(settings, publishingToken(settings), 'GET', `/updates?limit=20${query}`);
+  output.log(`default channel ${data.default_channel}, keyid ${data.key_id}`);
+  for (const group of data.groups) {
+    const state = group.archived ? 'archived' : group.retired_at ? 'retired' : 'live';
+    output.log(`${group.published_at} ${group.group} ${state} ${group.channel} ${group.commit ?? ''} «${group.message ?? ''}»${group.rollout && group.rollout.state !== 'completed' ? ` rollout ${describeRollout(group.rollout)}` : ''}`);
+    for (const update of group.updates) output.log(`    ${update.platform} ${update.kind} runtime ${update.runtime_version.slice(0, 8)} ${update.created_at}`);
+  }
+  output.log('runtimes asked for in the last 30 days:');
+  for (const seen of data.runtimes) output.log(`  ${seen.platform} ${seen.channel} ${seen.runtime_version.slice(0, 8)}: ${seen.requests} requests, last ${seen.last_seen}`);
+  return data;
+}
+
+/** What a phone with the app's runtime gets now, checked end to end. It needs no key and no token. */
+export async function check(settings, { platforms = PLATFORMS }, output) {
+  const checks = [];
+  for (const platform of platforms) checks.push(await checkServed(settings, platform, runtimeVersion(settings.projectDir, platform), undefined, output));
+  return { checks };
+}
+
+/**
+ * Asks for the manifest as a phone would and checks the signature, the id and every file it points to. `checked`
+ * holds the files already checked in this run (one per settings): the platforms share most of them. `channel` and
+ * `installation` ask as a build of that channel and as that installation (EAS-Client-ID); `signing`, the certificate.
+ */
+export async function checkServed(settings, platform, runtime, expectedId, output, { channel, installation, signing = signingFor(settings, channel), checked = (settings.checkedFiles ??= new Set()) } = {}) {
+  const headers = { 'expo-protocol-version': '1', 'expo-platform': platform, 'expo-runtime-version': runtime, accept: 'multipart/mixed' };
+  if (channel) headers['expo-channel-name'] = channel;
+  if (installation) headers['eas-client-id'] = installation;
+  const response = await fetch(settings.manifestUrl, { headers });
+  if (response.status === 204) {
+    if (expectedId) throw new Error(`${platform}: the server serves nothing for runtime ${runtime.slice(0, 8)}, not ${expectedId}`);
+    output.log(`check ${platform} ${runtime.slice(0, 8)}: nothing (204)`);
+    return { platform, runtime_version: runtime, served: 'nothing' };
+  }
+  if (!response.ok) throw new Error(`${platform}: the manifest answered ${response.status}`);
+  const boundary = response.headers.get('content-type')?.match(/boundary=([^;]+)/)?.[1];
+  const part = firstPart(Buffer.from(await response.arrayBuffer()), boundary);
+  if (!verifySignature(signing.certificate.publicKey, signing.keyid, part.body, part.signature)) throw new Error(`${platform}: the served ${part.name} does not verify with the certificate`);
+  const served = JSON.parse(part.body.toString('utf8'));
+  if (part.name === 'directive') {
+    output.log(`check ${platform} ${runtime.slice(0, 8)}: directive ${served.type}, signature valid`);
+    return { platform, runtime_version: runtime, served: 'directive', type: served.type };
+  }
+  if (expectedId && served.id !== expectedId) throw new Error(`${platform}: the server serves ${served.id}, not ${expectedId}`);
+  const files = [served.launchAsset, ...served.assets];
+  for (const [index, asset] of files.entries()) {
+    if (checked.has(asset.hash)) continue;
+    checked.add(asset.hash);
+    // Each file once, and the bundle also without gzip.
+    for (const encoding of index === 0 ? [undefined, 'identity'] : [undefined]) {
+      const answer = await download(new URL(asset.url, settings.manifestUrl), encoding ? { 'accept-encoding': encoding } : {}, output);
+      if (!answer.ok) throw new Error(`${platform}: ${asset.url} answered ${answer.status}`);
+      if (sha256(Buffer.from(await answer.arrayBuffer())) !== asset.hash) throw new Error(`${platform}: ${asset.url} does not match its hash`);
+    }
+  }
+  output.log(`check ${platform} ${runtime.slice(0, 8)}: ${served.id} (${served.createdAt}), signature valid, ${files.length} files match`);
+  return { platform, runtime_version: runtime, served: 'manifest', id: served.id, created_at: served.createdAt, files: files.length };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// The command line: ias update <subcommand>.
+
+const platformsOf = (values) => {
+  if (values.platform && !PLATFORMS.includes(values.platform)) throw new UsageError(`--platform is ios or android, not ${values.platform}`, { fix: 'leave it out to publish both' });
+  return values.platform ? [values.platform] : PLATFORMS;
+};
+
+const settingsOf = ({ values, cwd, env }) => {
+  const project = projectFor(resolve(cwd, values.project ?? '.'), 'updates');
+  return withChannels(updateSettings(project, env), project);
+};
+
+const OPTIONS = {
+  message: { type: 'string', short: 'm', value: '"…"', description: 'What the update changes; the people who publish read it in list and in the panel.' },
+  ref: { type: 'string', value: '<commit>', description: 'The commit to publish (HEAD by default). Only what is committed is published.' },
+  platform: { type: 'string', value: 'ios|android', description: 'Only one platform (both by default).' },
+  channel: { type: 'string', value: '<channel>', description: 'The channel (the project\'s default one by default), signed with its own key: updates.channels.<channel> of ias.json, or app.json\'s.' },
+  rollout: { type: 'string', value: '<1-100>', description: 'Start with this share of the installations (all by default); ias update rollout raises, pauses or completes it.' },
+  to: { type: 'string', value: '<channel>', description: 'The channel it goes to, signed again with its key.' },
+  'dry-run': { type: 'boolean', description: 'Everything but publishing: the server checks it all and keeps nothing.' },
+};
+
+const pick = (...names) => Object.fromEntries(names.map((name) => [name, OPTIONS[name]]));
+
+export default {
+  name: 'update',
+  summary: 'Signed OTA updates (expo-updates): publish, go back, retire and check',
+  description: 'Signs on this Mac with the key of 1Password (updates.signing.privateKey, or updates.channels.<channel>.privateKey for another channel) and publishes to the server of updates.url in app.json. The token is the OTA project\'s (ota_…): IAS_TOKEN or updates.token.',
+  subcommands: [
+    {
+      name: 'publish',
+      summary: 'Publish a commit (HEAD by default) for both platforms or one',
+      options: pick('message', 'ref', 'platform', 'channel', 'rollout', 'dry-run'),
+      run: (context) => publish(settingsOf(context), { ref: context.values.ref, message: context.values.message, platforms: platformsOf(context.values), channel: context.values.channel, rollout: rolloutOf(context.values.rollout), dryRun: context.values['dry-run'] }, context.output),
+    },
+    {
+      name: 'republish',
+      summary: 'Publish the commit of an earlier group again, with a new id and createdAt: the way back',
+      positionals: [{ name: 'group', description: 'The group, from ias update list.' }],
+      options: pick('message', 'platform', 'channel', 'rollout', 'dry-run'),
+      run: (context) => republish(settingsOf(context), { group: context.positionals[0], message: context.values.message, platforms: platformsOf(context.values), channel: context.values.channel, rollout: rolloutOf(context.values.rollout), dryRun: context.values['dry-run'] }, context.output),
+    },
+    {
+      name: 'rollback-to-embedded',
+      aliases: ['rollback'],
+      summary: 'Publish a signed directive: the phones go back to the JavaScript of their build',
+      options: pick('message', 'platform', 'channel', 'rollout', 'dry-run'),
+      run: (context) => rollbackToEmbedded(settingsOf(context), { message: context.values.message, platforms: platformsOf(context.values), channel: context.values.channel, rollout: rolloutOf(context.values.rollout), dryRun: context.values['dry-run'] }, context.output),
+    },
+    {
+      name: 'promote',
+      summary: 'Publish an earlier group in another channel, signed again on this Mac with that channel\'s key',
+      positionals: [{ name: 'group', description: 'The group, from ias update list --channel <its channel>.' }],
+      options: pick('to', 'message', 'rollout', 'dry-run'),
+      run: (context) => promote(settingsOf(context), { group: context.positionals[0], to: context.values.to, message: context.values.message, rollout: rolloutOf(context.values.rollout), dryRun: context.values['dry-run'] }, context.output),
+    },
+    {
+      name: 'rollout',
+      summary: 'Change the rollout of a group: a share from 1 to 99, pause, or complete',
+      positionals: [
+        { name: 'group', description: 'The group, from ias update list.' },
+        { name: 'percent|pause|complete', description: 'The share of installations (100 completes), pause (nobody new gets it), or complete (everyone does).' },
+      ],
+      run: (context) => rollout(settingsOf(context), { group: context.positionals[0], action: context.positionals[1] }, context.output),
+    },
+    {
+      name: 'channels',
+      summary: 'The channels of the project, each with its keyid and certificate, and whether this Mac signs for it',
+      run: (context) => channels(settingsOf(context), context.output),
+    },
+    {
+      name: 'retire',
+      summary: 'Stop serving a group: the emergency brake (also in the panel)',
+      positionals: [{ name: 'group', description: 'The group, from ias update list.' }],
+      run: (context) => setServing(settingsOf(context), 'retire', { group: context.positionals[0] }, context.output),
+    },
+    {
+      name: 'restore',
+      summary: 'Serve a retired group again',
+      positionals: [{ name: 'group', description: 'The group, from ias update list.' }],
+      run: (context) => setServing(settingsOf(context), 'restore', { group: context.positionals[0] }, context.output),
+    },
+    {
+      name: 'list',
+      summary: 'The last groups, and the runtimes the phones ask for',
+      options: pick('channel'),
+      run: (context) => list(settingsOf(context), { channel: context.values.channel }, context.output),
+    },
+    {
+      name: 'check',
+      summary: 'What a phone with the app\'s runtime gets now, checked end to end',
+      options: pick('platform'),
+      run: (context) => check(settingsOf(context), { platforms: platformsOf(context.values) }, context.output),
+    },
+  ],
+};