@imagina-build/ias-cli 0.0.0 → 0.1.1

package/src/commands/devices/sync.mjs

@@ -0,0 +1,223 @@
+// ias devices sync (docs/technical/manage-api.md §15, docs/technical/runner-api.md §11), on a member's computer, because it is the one
+// thing that touches Apple and the vault at once: the server cannot open the vault nor sign, and the runner has no
+// team signing key. In this order:
+//   1. the team's keys from 1Password, checked against the server's (vault/team.mjs), and the App Store Connect API
+//      key of the vault opened in memory with the recovery key, after checking the team's signature;
+//   2. the approved devices registered in Apple (the API, a JWT of node:crypto), and the server told;
+//   3. a new ad hoc profile of the bundle id with the team's certificate and every device that belongs in it: those
+//      of the current profile still enabled in Apple, and the approved ones, without the rejected ones;
+//   4. the profile sealed for the recovery key and the runners of the list the team signed, signed by the team
+//      (ias-vault-2), and uploaded as the next version of the credential of the profile; the server told which
+//      devices it lists;
+//   5. a resign of the newest internal iOS build, followed until its IPA is on the install pages (--detach does not
+//      wait; --no-resign skips it).
+// What it does in Apple and in the vault, it shows and asks to confirm first (--yes in a script). Nothing it opens
+// is printed or written to disk.
+import { createHash, randomUUID } from 'node:crypto';
+import { ApiError, IasError } from '../../errors.mjs';
+import { applicationOf, connect, sleep } from '../../manage.mjs';
+import { credentials as inspect, decodePlaintext, digest, encodePlaintext, open, seal, verifyEnvelope } from '../../shared.mjs';
+import { signedRunners, vaultItem } from '../../team-vault.mjs';
+import { confirm, teamKeys } from '../vault/team.mjs';
+import { ascClient } from './asc.mjs';
+
+const DAY = 24 * 60 * 60 * 1000;
+const FINISHED = ['succeeded', 'failed', 'rejected', 'canceled', 'expired'];
+
+/** A UDID as Apple writes it (the old form in lowercase, the new one in uppercase), to compare them. */
+export const normalizeUdid = (udid) => (String(udid).trim().length === 40 ? String(udid).trim().toLowerCase() : String(udid).trim().toUpperCase());
+
+/** The latest expiring of `list`, by expires_at (none last). */
+const latestExpiring = (list) => [...list].sort((a, b) => (Date.parse(b.expires_at ?? '9999') || 0) - (Date.parse(a.expires_at ?? '9999') || 0))[0] ?? null;
+
+/** The name Apple keeps a device with: the tester's, or iOS's, and its model, within 50 characters. */
+export function appleDeviceName(device) {
+  const model = device.model ? ` (${device.model})` : '';
+  const name = (device.owner_name || device.name || 'Dispositivo').normalize('NFKD').replace(/[^\x20-\x7e]/g, '');
+  return `${name.slice(0, 50 - model.length).trim() || 'Device'}${model}`;
+}
+
+/** The credentials sync needs: the team's App Store Connect key and distribution certificate, and the app's ad hoc profile. */
+async function vaultCredentials(client, code, app) {
+  const team = (await client.request('GET', '/team/credentials')).data.data.filter((credential) => !credential.retired_at);
+  const own = (await client.request('GET', `/apps/${code}/credentials`)).data.data.filter((credential) => !credential.retired_at);
+  const now = Date.now();
+  const usable = (credential) => !credential.expires_at || Date.parse(credential.expires_at) > now;
+  const ascKey = team.filter((credential) => credential.type === 'asc_api_key').sort((a, b) => (b.updated_at ?? '').localeCompare(a.updated_at ?? ''))[0];
+  if (!ascKey) throw new IasError('the vault has no App Store Connect API key', { fix: 'import the team\'s with ias credentials import asc_api_key --p8 <AuthKey_….p8> --key-id <id> --issuer-id <uuid>', code: 'credentials_missing' });
+  const certificate = latestExpiring(team.filter((credential) => credential.type === 'apple_distribution_certificate' && usable(credential) && credential.metadata?.kind === 'distribution' && (!app.ios.team_id || credential.metadata?.team === app.ios.team_id)));
+  if (!certificate) throw new IasError(`the vault has no usable distribution certificate of the team ${app.ios.team_id ?? ''}`.trim(), { fix: 'import it with ias credentials import apple_distribution_certificate', code: 'credentials_missing' });
+  const sha1 = String(certificate.metadata.sha1 ?? '').toUpperCase();
+  const profile = latestExpiring(own.filter((credential) => credential.type === 'apple_provisioning_profile' && credential.metadata?.type === 'ad-hoc' && credential.metadata?.bundleId === app.ios.bundle_id && (credential.metadata?.certificates ?? []).map((value) => String(value).toUpperCase()).includes(sha1)));
+  return { ascKey, certificate, profile };
+}
+
+/** The App Store Connect key of the vault, opened with the recovery key after checking the team signed it. */
+async function openAscKey(client, credential, { recoveryKey, keys }) {
+  const { data } = await client.request('GET', `/credentials/${credential.id}/envelope`);
+  if (data.envelope?.credential?.id !== credential.id || data.envelope?.credential?.type !== 'asc_api_key') throw new IasError('the server gives the envelope of another credential for the App Store Connect key', { fix: 'nothing was opened: ias credentials show checks it', code: 'envelope_of_another_credential' });
+  let bytes;
+  try {
+    bytes = open(data.envelope, recoveryKey.privateKey, { signedBy: keys.signing.publicKey });
+    return decodePlaintext('asc_api_key', bytes);
+  } catch (error) {
+    throw new IasError(`the envelope of the App Store Connect key does not verify with the team's key or does not open (${error.code ?? error.message})`, { fix: 'nothing was sent to Apple: ias credentials show --verify checks it', code: 'envelope_invalid' });
+  } finally {
+    bytes?.fill?.(0);
+  }
+}
+
+/** The Apple id of the team's certificate of the vault: the one whose DER has its SHA-1. */
+async function appleCertificate(asc, certificate) {
+  const sha1 = String(certificate.metadata.sha1 ?? '').toUpperCase();
+  const found = (await asc.certificates()).find((item) => item.attributes?.certificateContent && createHash('sha1').update(Buffer.from(item.attributes.certificateContent, 'base64')).digest('hex').toUpperCase() === sha1);
+  if (!found) throw new IasError(`Apple has no distribution certificate with the SHA-1 ${sha1} of the vault`, { fix: 'it was revoked or is of another team: import the current one with ias credentials import apple_distribution_certificate', code: 'certificate_not_in_apple' });
+  return found;
+}
+
+/** Follows a resign until it ends, as ias build follows a build. */
+async function followResign(client, code, resign, { output, wait }) {
+  let current = resign;
+  let said = null;
+  while (!FINISHED.includes(current.status)) {
+    const step = `${current.status}${current.step ? ` (${current.step})` : ''}`;
+    if (step !== said) output.progress(`  resign ${current.id}: ${step}`);
+    said = step;
+    await wait(5);
+    current = (await client.request('GET', `/apps/${code}/resigns/${current.id}`)).data;
+  }
+  for (let tries = 0; current.status === 'succeeded' && !current.distribution && !current.publish_error && tries < 24; tries += 1) {
+    await wait(5);
+    current = (await client.request('GET', `/apps/${code}/resigns/${current.id}`)).data;
+  }
+  return current;
+}
+
+export async function sync(context, project) {
+  const { values, env, output } = context;
+  const wait = context.sleep ?? sleep;
+  const client = connect(context, project);
+  const code = applicationOf(context, project);
+  const { data: app } = await client.request('GET', `/apps/${code}`);
+  if (!app.ios?.bundle_id) throw new IasError(`${code} has no iOS bundle id`, { fix: 'set it in the panel (the application › Settings)', code: 'application_without_ios' });
+  const { data: listed } = await client.request('GET', `/apps/${code}/devices`);
+  const devices = listed.data;
+  const approved = devices.filter((device) => device.status === 'approved');
+  const wanted = devices.filter((device) => device.status === 'approved' || device.status === 'registered');
+  const rejected = new Set(devices.filter((device) => device.status === 'rejected').map((device) => normalizeUdid(device.udid)));
+
+  const item = vaultItem(context, project, client.server);
+  const { vault, keys, signingKey, recoveryKey } = await teamKeys(client, item, env, { recovery: true });
+  const material = await vaultCredentials(client, code, app);
+  const key = await openAscKey(client, material.ascKey, { recoveryKey, keys });
+  const asc = ascClient(key, { env, fetch: context.fetch ?? fetch });
+  try {
+    output.progress(`App Store Connect: key ${key.key_id}, from the vault (${material.ascKey.id} v${material.ascKey.version})`);
+    const inApple = new Map((await asc.devices()).map((device) => [normalizeUdid(device.attributes.udid), device]));
+
+    // What the new profile lists: the current profile's devices still enabled, and the approved ones, never the rejected ones.
+    const bundle = await asc.bundleId(app.ios.bundle_id);
+    if (!bundle) throw new IasError(`Apple has no App ID ${app.ios.bundle_id}`, { fix: 'register it in Apple Developer › Identifiers (ias build does it for a store build)', code: 'bundle_id_not_in_apple' });
+    const current = material.profile ? (await asc.profilesOf(bundle.id)).find((profile) => String(profile.attributes?.uuid).toUpperCase() === String(material.profile.metadata.uuid).toUpperCase()) : null;
+    if (material.profile && !current) output.warn(`the profile of the vault (${material.profile.metadata.uuid}) is not in Apple any more: the new one lists only the devices of IAS`);
+    const inProfile = current ? await asc.devicesOf(current.id) : [];
+    const kept = inProfile.filter((device) => device.attributes?.status === 'ENABLED' && !rejected.has(normalizeUdid(device.attributes.udid)));
+    // A device IAS has as registered that Apple no longer has (deleted in Apple Developer) is registered again.
+    const toRegister = wanted.filter((device) => !inApple.has(normalizeUdid(device.udid)));
+    const toEnable = wanted.filter((device) => inApple.get(normalizeUdid(device.udid))?.attributes?.status === 'DISABLED');
+    const listedUdids = new Set([...kept.map((device) => normalizeUdid(device.attributes.udid)), ...wanted.map((device) => normalizeUdid(device.udid))]);
+    const before = new Set(kept.map((device) => normalizeUdid(device.attributes.udid)));
+    const added = wanted.filter((device) => !before.has(normalizeUdid(device.udid)));
+    const leaving = inProfile.filter((device) => rejected.has(normalizeUdid(device.attributes.udid)));
+    const unchanged = material.profile && current && added.length === 0 && leaving.length === 0 && toRegister.length === 0 && toEnable.length === 0;
+
+    output.progress(`${app.name} (${app.ios.bundle_id}): ${devices.length} device${devices.length === 1 ? '' : 's'} in IAS, ${approved.length} approved and not yet in Apple`);
+    if (unchanged && !values.force) {
+      output.log(`The ad hoc profile v${material.profile.version} already lists every approved device (${listedUdids.size}): nothing to do. --force makes it again.`);
+      return { changed: false, profile: { credential: material.profile.id, version: material.profile.version, devices: listedUdids.size }, registered: [], resign: null };
+    }
+    for (const device of toRegister) output.progress(`  register in Apple  ${appleDeviceName(device)}  ${device.udid}`);
+    for (const device of toEnable) output.progress(`  enable in Apple    ${appleDeviceName(device)}  ${device.udid}`);
+    for (const device of added) output.progress(`  add to the profile ${appleDeviceName(device)}  ${device.udid}`);
+    for (const device of leaving) output.progress(`  leave the profile  ${device.attributes.name}  ${device.attributes.udid} (rejected in IAS)`);
+    output.progress(`The new ad hoc profile of ${app.ios.bundle_id} will list ${listedUdids.size} device${listedUdids.size === 1 ? '' : 's'}, signed with «${material.certificate.name}», and replace ${material.profile ? `version ${material.profile.version} of «${material.profile.name}»` : 'nothing (it is the first)'} in the vault.`);
+    output.progress('Check the devices: the server says which ones were approved, and whatever goes into the profile can install the internal builds.');
+    await confirm(context, `Register them in Apple and make the new profile of ${app.ios.bundle_id}?`);
+
+    // 2. Apple: register and enable, then tell the server.
+    const registered = [];
+    for (const device of [...toRegister, ...toEnable]) {
+      const done = inApple.has(normalizeUdid(device.udid)) ? await asc.enableDevice(inApple.get(normalizeUdid(device.udid)).id) : await asc.registerDevice({ name: appleDeviceName(device), udid: device.udid });
+      inApple.set(normalizeUdid(device.udid), done);
+      output.progress(`  ${toRegister.includes(device) ? 'registered' : 'enabled'} ${appleDeviceName(device)} as ${done.id}`);
+    }
+    const report = wanted
+      .filter((device) => inApple.has(normalizeUdid(device.udid)) && (device.status === 'approved' || device.apple_device_id !== inApple.get(normalizeUdid(device.udid)).id))
+      .map((device) => ({ id: device.id, apple_device_id: inApple.get(normalizeUdid(device.udid)).id }));
+    if (report.length > 0) {
+      await client.request('POST', `/apps/${code}/devices/registered`, { json: { devices: report } });
+      registered.push(...report);
+    }
+
+    // 3. The new profile, made by Apple with every device that belongs in it.
+    const deviceIds = [...new Set([...kept.map((device) => device.id), ...wanted.map((device) => inApple.get(normalizeUdid(device.udid))?.id).filter(Boolean)])];
+    if (deviceIds.length === 0) throw new IasError('no device would go into the profile', { fix: 'approve a device in the panel (Distribución › Dispositivos) first', code: 'no_devices' });
+    const certificate = await appleCertificate(asc, material.certificate);
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '').replace('T', '-');
+    const made = await asc.createProfile({ name: `IAS ad hoc ${app.ios.bundle_id} ${stamp}`, bundleIdId: bundle.id, certificateId: certificate.id, deviceIds });
+    const bytes = Buffer.from(made.attributes?.profileContent ?? '', 'base64');
+    let metadata;
+    try {
+      metadata = inspect.metadataOf('apple_provisioning_profile', { mobileprovision: bytes });
+    } catch (error) {
+      throw new IasError(`Apple gave a profile that does not read (${error.message})`, { fix: 'run it again; the profile stays in Apple Developer and can be deleted there', code: 'profile_unreadable' });
+    }
+    const problems = inspect.checkIos({ certificate: material.certificate.metadata, profile: metadata }, { type: 'ad-hoc', teamId: app.ios.team_id ?? undefined, bundleId: app.ios.bundle_id });
+    if (metadata.devices !== deviceIds.length) problems.push(`it lists ${metadata.devices} devices, not ${deviceIds.length}`);
+    if (problems.length > 0) throw new IasError(`the profile Apple made is not the one asked for: ${problems.join('; ')}`, { fix: 'nothing was stored in the vault: check the App ID and the certificate in Apple Developer', code: 'profile_unexpected' });
+    output.progress(`profile «${metadata.name}» ${metadata.uuid}: ${metadata.devices} devices, until ${metadata.expires}`);
+
+    // 4. Sealed for the recovery key and the signed runners, signed by the team, as the next version.
+    const { runners } = signedRunners(vault, keys.signing, output);
+    const id = material.profile?.id ?? randomUUID();
+    const version = (material.profile?.version ?? 0) + 1;
+    const plaintext = encodePlaintext('apple_provisioning_profile', { application: code, mobileprovision: bytes });
+    let envelope;
+    try {
+      envelope = seal(plaintext, { credential: { id, type: 'apple_provisioning_profile', version }, recipients: [keys.recovery, ...runners], signingKey });
+      verifyEnvelope(envelope, keys.signing.publicKey);
+    } finally {
+      plaintext.fill(0);
+    }
+    const { data: stored } = material.profile
+      ? await client.request('PUT', `/credentials/${id}`, { json: { metadata, envelope } })
+      : await client.request('POST', `/apps/${code}/credentials`, { json: { id, type: 'apple_provisioning_profile', name: `Perfil ad hoc de ${app.name}`, metadata, envelope } });
+    output.log(`stored «${stored.name}» (${stored.id}) version ${stored.version}, digest ${digest(envelope)}, sealed for ${envelope.recipients.length} key${envelope.recipients.length === 1 ? '' : 's'}`);
+    await client.request('POST', `/apps/${code}/devices/registered`, { json: { profile: { credential: stored.id, version: stored.version, devices: [...listedUdids].sort() } } });
+    if (metadata.expires && Date.parse(metadata.expires) - Date.now() < 30 * DAY) output.warn(`the new profile expires on ${metadata.expires}: the certificate expires soon`);
+
+    // 5. Sign the newest internal iOS build again with it.
+    let resign = null;
+    if (!values['no-resign']) {
+      try {
+        resign = (await client.request('POST', `/apps/${code}/resigns`, { json: { profile: stored.id } })).data;
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.code !== 'resign_source_missing') throw error;
+        output.warn('there is no internal iOS build of IAS to sign again: the next ias build --platform ios --profile preview uses the new profile');
+      }
+      if (resign && resign.profile?.version !== stored.version) throw new IasError(`the server signs again with version ${resign.profile?.version} of the profile, not ${stored.version}`, { fix: 'someone replaced it meanwhile: run ias devices sync again', code: 'profile_not_current' });
+      if (resign) {
+        output.log(`resign ${resign.id} of ${resign.version} (${resign.build_number ?? '?'}) queued for a runner`);
+        if (!values.detach) {
+          resign = await followResign(client, code, resign, { output, wait });
+          if (resign.status !== 'succeeded') throw new IasError(`the resign ${resign.id} ended ${resign.status}${resign.error ? `: ${resign.error.message ?? resign.error.code}` : ''}`, { fix: 'the profile is in the vault: the panel (Distribución › Dispositivos) has its log; ias devices sync --force asks again', code: 'resign_failed', details: resign });
+          if (resign.distribution) output.log(`signed again and published: ${resign.distribution.install_url}${resign.distribution.stable_url ? ` (the stable link ${resign.distribution.stable_url} gives it)` : ''}`);
+          else if (resign.publish_error) output.warn(`signed again, but not published in Distribution: ${resign.publish_error}`);
+        }
+      }
+    }
+    return { changed: true, registered, profile: { credential: stored.id, version: stored.version, uuid: metadata.uuid, devices: metadata.devices, expires: metadata.expires }, resign };
+  } finally {
+    key.p8?.fill?.(0);
+  }
+}

package/src/commands/dist/index.mjs

@@ -0,0 +1,108 @@
+// ias dist: internal builds (an ad hoc IPA or an APK) on the install pages of IAS (API.md §37). What the page shows is
+// read from the file; the file goes straight to the bucket and the server checks its size and SHA-256. It was
+// tools/expo-dist.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { distSettings, projectFor } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { api } from '../../http.mjs';
+import { digest, gitCommit, icon, readApk, readIpa } from '../../dist.mjs';
+import { readSecret, tokenKind } from '../../secrets.mjs';
+
+/** The publishing token of the distribution 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) === 'ota') throw new IasError('the token is the one of an OTA project (ota_…)', { fix: 'ias dist needs the publishing token of the distribution project (dist_…, php artisan dist:token): check IAS_TOKEN, DIST_TOKEN or the token of the configuration' });
+  return token;
+}
+
+/** Reads the build from the file, uploads it and prints its link and the stable one. */
+export async function upload(settings, { file: target, notes, cwd }, output) {
+  if (!target) throw new Error('usage: upload <file.ipa|file.apk> [--notes "…"]');
+  const file = resolve(cwd, target);
+  if (!existsSync(file)) throw new Error(`no file at ${target}`);
+  const extension = extname(file).toLowerCase();
+  if (!['.ipa', '.apk'].includes(extension)) throw new Error('upload takes an .ipa (ad hoc) or an .apk; an .aab only installs through Google Play');
+
+  const metadata = extension === '.ipa' ? readIpa(file) : readApk(file);
+  const { sha256, bytes } = await digest(file);
+  if (metadata.profile_expires_at && Date.parse(metadata.profile_expires_at) < Date.now()) throw new Error(`the ad hoc profile expired on ${metadata.profile_expires_at}: iOS will not open this build`);
+  output.progress(`${output.prefix}: ${basename(file)}: ${metadata.name} ${metadata.version} (${metadata.build_number}), ${metadata.identifier}, ${(bytes / 1048576).toFixed(1)} MB${metadata.provisioned_devices !== undefined ? `, ${metadata.provisioned_devices} devices until ${metadata.profile_expires_at}` : ''}`);
+
+  const token = publishingToken(settings);
+  return sendBuild(settings, { token, file, build: { ...metadata, bytes, sha256, notes, git_commit: gitCommit(settings.projectDir), icon: icon(settings.projectDir) } }, output);
+}
+
+/** The network half of upload: creates the build, PUTs the file to the bucket and asks the server to check it. */
+export async function sendBuild(settings, { token, file, build: fields }, output) {
+  const { data: build } = await api(settings, token, 'POST', '/builds', { json: fields });
+
+  const response = await fetch(build.upload.url, { method: build.upload.method ?? 'PUT', headers: { ...build.upload.headers, 'content-length': String(fields.bytes) }, body: readFileSync(file) });
+  if (!response.ok) throw new Error(`uploading the file: ${response.status} ${(await response.text()).slice(0, 300)}`);
+
+  const { data: done } = await api(settings, token, 'POST', `/builds/${build.id}/complete`);
+  const { data: listing } = await api(settings, token, 'GET', '/builds?limit=1');
+  output.log(`${output.prefix}: build ${done.id} ready`);
+  output.log(`  this build:    ${done.install_url}`);
+  output.log(`  latest (both): ${listing.install_url}`);
+  return { build: done, install_url: listing.install_url };
+}
+
+/** The stable link and the last 30 builds, with their id, state and link. */
+export async function list(settings, output) {
+  const { data } = await api(settings, publishingToken(settings), 'GET', '/builds?limit=30');
+  output.log(`latest (both platforms): ${data.install_url}`);
+  for (const build of data.builds) {
+    output.log(`${String(build.id).padStart(5)}  ${build.platform.padEnd(7)}  ${`${build.version} (${build.build_number})`.padEnd(16)}  ${build.status.padEnd(11)}  ${(build.uploaded_at ?? build.created_at ?? '').slice(0, 16)}  ${build.install_url}${build.notes ? `  ${build.notes}` : ''}`);
+  }
+  return data;
+}
+
+/** Stops offering a build (retire) or offers it again (restore); also in the panel. */
+export async function setOffered(settings, action, { id }, output) {
+  if (!/^\d+$/.test(id ?? '')) throw new Error(`usage: ${action} <build id> (see list)`);
+  const { data } = await api(settings, publishingToken(settings), 'POST', `/builds/${id}/${action}`);
+  output.log(`${output.prefix}: build ${data.id} ${data.status}${data.changed ? '' : ' (it already was)'}`);
+  return data;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// The command line: ias dist <subcommand>.
+
+const settingsOf = ({ values, cwd, env }) => distSettings(projectFor(resolve(cwd, values.project ?? '.'), 'distribution'), env);
+
+const buildId = { name: 'id', description: 'The id of the build, from ias dist list.', pattern: /^\d+$/ };
+
+export default {
+  name: 'dist',
+  summary: 'Internal builds on the install pages: upload an ad hoc IPA or an APK, list, retire and restore',
+  description: 'The server and project come from ias.json (server, and distribution.project or app); the token is the distribution project\'s (dist_…): IAS_TOKEN or distribution.token. IPAs need the tools of macOS (unzip, plutil, security, sips); APKs, aapt2 of the Android SDK.',
+  subcommands: [
+    {
+      name: 'upload',
+      summary: 'Upload a build and print its link and the stable one',
+      positionals: [{ name: 'file', description: 'An ad hoc .ipa or an .apk (an .aab only installs through Google Play).' }],
+      options: { notes: { type: 'string', value: '"…"', description: 'What the build brings; the install page shows it.' } },
+      run: (context) => upload(settingsOf(context), { file: context.positionals[0], notes: context.values.notes, cwd: context.cwd }, context.output),
+    },
+    {
+      name: 'list',
+      summary: 'The stable link and the last 30 builds',
+      run: (context) => list(settingsOf(context), context.output),
+    },
+    {
+      name: 'retire',
+      summary: 'Stop offering a build (also in the panel)',
+      positionals: [buildId],
+      run: (context) => setOffered(settingsOf(context), 'retire', { id: context.positionals[0] }, context.output),
+    },
+    {
+      name: 'restore',
+      summary: 'Offer a retired build again',
+      positionals: [buildId],
+      run: (context) => setOffered(settingsOf(context), 'restore', { id: context.positionals[0] }, context.output),
+    },
+  ],
+};

package/src/commands/doctor/index.mjs

@@ -0,0 +1,158 @@
+// ias doctor: whether this Mac and this app have what the commands need: Node, git, the 1Password CLI, Xcode and its
+// tools (plutil, security, sips), aapt2 of the Android SDK, a configuration that loads and, in an app with a
+// package.json, the SDK @imagina-build/ias and its plugin. It reads no secret: an op:// reference is checked for its form,
+// never opened (that would ask for Touch ID).
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+import { VERSION } from '../../cli.mjs';
+import { CONFIG_FILE, LEGACY_FILES, distSettings, hasConfig, loadProject, updateSettings } from '../../config.mjs';
+import { androidSdk, findAapt2 } from '../../dist.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { probe as systemProbe } from '../../process.mjs';
+import { SDK_PACKAGE, compatibleRange, isCompatible, packageManager, sdkState } from '../../sdk.mjs';
+import { isReference } from '../../secrets.mjs';
+
+const MIN_NODE = 22;
+const MAC_TOOLS = ['plutil', 'security', 'sips', 'unzip'];
+
+const where = (value, variable) => (isReference(value) ? 'in 1Password' : `from ${variable}`);
+
+/**
+ * The checks, in order: { name, status (ok, warn, fail or skip), detail, fix }. `probe` runs a program and says whether
+ * it answered (tests pass their own); a fail means a command of ias will not work here.
+ */
+export function diagnose({ dir, env = process.env, platform = process.platform, nodeVersion = process.versions.node, probe = systemProbe, aapt2 = findAapt2, now = Date.now() }) {
+  const checks = [];
+  const add = (name, status, detail, fix) => checks.push({ name, status, detail, ...(fix ? { fix } : {}) });
+
+  let project;
+  let configError;
+  try {
+    project = loadProject(dir);
+  } catch (error) {
+    configError = error;
+  }
+  const uses = (service) => Boolean(project && hasConfig(project, service));
+  const references = project ? JSON.stringify(project.config ?? {}).includes('op://') || Object.values(LEGACY_FILES).some((name) => existsSync(join(dir, name))) : false;
+
+  const major = Number(nodeVersion.split('.')[0]);
+  if (major >= MIN_NODE) add('node', 'ok', `Node ${nodeVersion}`);
+  else add('node', 'fail', `Node ${nodeVersion}`, `ias needs Node ${MIN_NODE} or later (fetch, util.parseArgs and node:test): install it, for instance with brew install node@22`);
+
+  const git = probe('git', ['--version']);
+  if (git.ok) add('git', 'ok', git.output.replace(/^git version /, 'git '));
+  else add('git', uses('updates') ? 'fail' : 'warn', 'git does not answer', 'ias update publishes commits with git: install it (xcode-select --install)');
+
+  const op = probe('op', ['--version']);
+  if (op.ok) add('op', 'ok', `1Password CLI ${op.output}`);
+  else add('op', references ? 'fail' : 'warn', 'the 1Password CLI (op) does not answer', 'the keys and tokens are op:// references: install it (brew install 1password-cli) and turn on its integration with the 1Password app');
+
+  if (platform !== 'darwin') {
+    add('xcode', 'skip', 'Xcode is only on macOS');
+    add('macos-tools', 'skip', `${MAC_TOOLS.join(', ')} are only on macOS: IPAs are uploaded from a Mac`);
+  } else {
+    const developer = probe('xcode-select', ['-p']);
+    const xcode = probe('xcodebuild', ['-version']);
+    if (developer.ok && xcode.ok) add('xcode', 'ok', `${xcode.output.split('\n')[0]} (${developer.output})`);
+    else add('xcode', 'warn', developer.ok ? `${developer.output} has only the command line tools` : 'no Xcode', 'iOS builds need Xcode (phase 2): install it from the App Store and run sudo xcode-select -s /Applications/Xcode.app');
+    const missing = MAC_TOOLS.filter((tool) => !probe('/usr/bin/which', [tool]).ok);
+    if (missing.length === 0) add('macos-tools', 'ok', MAC_TOOLS.join(', '));
+    else add('macos-tools', uses('distribution') ? 'fail' : 'warn', `missing ${missing.join(', ')}`, 'ias dist reads IPAs with them: they come with macOS and its command line tools (xcode-select --install)');
+  }
+
+  const aapt2Path = aapt2(env);
+  if (aapt2Path) add('aapt2', 'ok', aapt2Path);
+  else add('aapt2', 'warn', `no aapt2 in ${join(androidSdk(env), 'build-tools')}`, 'ias dist reads APKs with it: install the build tools of the Android SDK (Android Studio › SDK Manager) or set ANDROID_HOME');
+
+  if (existsSync(join(dir, 'package.json'))) sdkCheck(dir, add);
+
+  if (configError) {
+    add('config', 'fail', configError.what ?? configError.message, configError.fix);
+    return checks;
+  }
+  if (project.source === CONFIG_FILE) {
+    const old = Object.values(LEGACY_FILES).filter((name) => existsSync(join(dir, name)));
+    add('config', 'ok', `${CONFIG_FILE}: app ${project.config.app}, server ${project.config.server ?? 'https://ias.imagina.build (the default)'}${old.length > 0 ? `; ${old.join(' and ')} are no longer read` : ''}`);
+  } else if (uses('updates') || uses('distribution')) {
+    const old = Object.values(LEGACY_FILES).filter((name) => existsSync(join(dir, name)));
+    add('config', 'warn', `no ${CONFIG_FILE}: ${old.join(' and ')}, as tools/ reads them`, 'ias init writes ias.json from them');
+  } else {
+    add('config', 'warn', `no ${CONFIG_FILE} in ${dir}`, 'run ias init in the folder of the app (or pass --project) to check its configuration');
+    return checks;
+  }
+
+  if (uses('updates')) {
+    try {
+      const settings = updateSettings(project, env);
+      const days = Math.floor((Date.parse(settings.certificate.validTo) - now) / 86_400_000);
+      const missing = [!settings.privateKey && settings.needs?.privateKey, !settings.token && settings.needs?.token].filter(Boolean);
+      const detail = `project ${settings.project} on ${new URL(settings.base).origin}, keyid ${settings.keyid}, certificate until ${settings.certificate.validTo} (${days} days)${settings.privateKey ? `, key ${where(settings.privateKey, 'the environment')}` : ''}${settings.token ? `, token ${where(settings.token, 'the environment')}` : ''}`;
+      if (days < 0) add('updates', 'fail', detail, 'the builds that carry this certificate reject every update: a new certificate needs a new build');
+      else if (missing.length > 0) add('updates', 'fail', `${detail}; ${missing.map((error) => error.what).join(' and ')}`, missing.map((error) => error.fix).join('; '));
+      else if (days < 365) add('updates', 'warn', detail, 'rotate the certificate with the next store build');
+      else add('updates', 'ok', detail);
+    } catch (error) {
+      add('updates', 'fail', error.what ?? error.message, error.fix);
+    }
+  }
+  if (uses('distribution')) {
+    try {
+      const settings = distSettings(project, env);
+      const detail = `project ${settings.project} on ${new URL(settings.base).origin}${settings.token ? `, token ${where(settings.token, 'the environment')}` : ''}`;
+      if (!settings.token) add('distribution', 'fail', `${detail}; ${settings.needs.token.what}`, settings.needs.token.fix);
+      else add('distribution', 'ok', detail);
+    } catch (error) {
+      add('distribution', 'fail', error.what ?? error.message, error.fix);
+    }
+  }
+  return checks;
+}
+
+/** The SDK in the app: installed, compatible with this ias and with its plugin in app.json; a warning if the app does not use it. */
+function sdkCheck(dir, add) {
+  let state;
+  try {
+    state = sdkState(dir);
+  } catch (error) {
+    add('sdk', 'fail', error.what ?? error.message, error.fix);
+    return;
+  }
+  const { declared, installed, plugin } = state;
+  if (!declared && !installed) {
+    if (plugin === 'yes') add('sdk', 'fail', `app.json has the plugin of ${SDK_PACKAGE}, but the app does not have the package`, 'ias sdk install installs it: expo config and the builds fail without it');
+    else add('sdk', 'warn', `the app does not use ${SDK_PACKAGE}`, `ias sdk install, if it uses ias.sync, ias.push or ias.updates, or takes its configuration from ias.json`);
+    return;
+  }
+  if (!installed) {
+    add('sdk', 'fail', `${SDK_PACKAGE} ${declared} is in package.json, but not installed`, `${packageManager(dir).name} install`);
+    return;
+  }
+  if (!isCompatible(installed, VERSION)) {
+    add('sdk', 'fail', `${SDK_PACKAGE} ${installed}, and ias ${VERSION} works with ${compatibleRange()}`, `ias sdk install installs ${compatibleRange()}, or install the ias of the same version as the SDK: they must read ias.json the same way`);
+    return;
+  }
+  const detail = `${SDK_PACKAGE} ${installed}, compatible with ias ${VERSION}`;
+  if (plugin === 'yes') add('sdk', 'ok', `${detail}, plugin in app.json`);
+  else if (plugin === 'dynamic') add('sdk', 'warn', `${detail}; ias cannot read ${state.dynamic}`, `check that it adds "${SDK_PACKAGE}" to the plugins: it writes ias.json into the builds`);
+  else add('sdk', 'warn', `${detail}, but app.json does not have its plugin`, `ias sdk install adds "${SDK_PACKAGE}" to the plugins of app.json, in a new build: it writes ias.json into the builds`);
+}
+
+export function doctor(dir, { env, output }) {
+  const checks = diagnose({ dir, env });
+  for (const check of checks) {
+    output.log(`  ${check.status.padEnd(5)} ${check.name.padEnd(13)} ${check.detail}`);
+    if (check.fix && check.status !== 'ok') output.log(`  ${''.padEnd(5)} ${''.padEnd(13)} → ${check.fix}`);
+  }
+  const count = (status) => checks.filter((check) => check.status === status).length;
+  const failures = count('fail');
+  output.log(`${output.prefix}: ${failures === 0 ? 'ready' : `${failures} ${failures === 1 ? 'thing stops' : 'things stop'} a command`}${count('warn') > 0 ? `, ${count('warn')} to look at` : ''}`);
+  return { ok: failures === 0, checks, [EXIT_CODE]: failures > 0 ? 1 : 0 };
+}
+
+export default {
+  name: 'doctor',
+  summary: 'Check Node, git, op, Xcode and its tools, the Android SDK, the app\'s configuration and the SDK @imagina-build/ias',
+  description: 'It reads no secret. A fail means a command of ias will not work here; a warning, that something may be needed later.',
+  run: ({ values, cwd, env, output }) => doctor(resolve(cwd, values.project ?? '.'), { env, output }),
+};