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

package/src/errors.mjs

@@ -0,0 +1,158 @@
+// What went wrong and how to fix it. Every error the CLI throws on purpose says both, in one line: «what: how».
+
+/** An error the person can fix: `what` happened, `fix` says how. Its message is «what: fix», the voice of tools/. */
+export class IasError extends Error {
+  constructor(what, { fix, code, details } = {}) {
+    super(fix ? `${what}: ${fix}` : what);
+    this.name = 'IasError';
+    this.what = what;
+    this.fix = fix;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/** A command line that does not parse: an unknown command or option, or a missing argument. Exits with 2. */
+export class UsageError extends IasError {
+  constructor(what, options) {
+    super(what, options);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * An answer of the server that is not a success. Its message is the one tools/ always printed («POST /updates: 422
+ * code message (platform)»), and so is its name, Error; `hint` adds how to fix it, from the code of the answer (HINTS).
+ */
+export class ApiError extends Error {
+  constructor(message, { status, code, data } = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.data = data;
+    this.hint = hintFor(status, code, data);
+  }
+}
+
+/** How to fix the answers of the OTA (API.md §36) and distribution (§37) APIs that a person can do something about. */
+export const HINTS = {
+  ota_token_invalid: 'the token is not the publishing token of this OTA project, or there is no such OTA project: check IAS_TOKEN or updates.token in ias.json, and updates.url in app.json (php artisan ota:token <project> makes a new token)',
+  distribution_token_invalid: 'the token is not the publishing token of this distribution project, or there is no such distribution project: check distribution.project (or app) and distribution.token in ias.json, or IAS_TOKEN (php artisan dist:token <project> makes a new token)',
+  project_not_found: 'there is no OTA project with this code: check updates.url in app.json, or create it with php artisan ota:project',
+  signature_key_mismatch: 'the update is signed for another keyid: updates.codeSigningMetadata.keyid in app.json must be the one of the project (php artisan ota:project … --keyid)',
+  signature_invalid: 'the signature does not verify with the project\'s certificate: the private key must be the one of updates.codeSigningCertificate in app.json',
+  created_at_not_newer: 'the server already serves something newer: to go back, republish an older group (it signs a new createdAt) or retire the bad one',
+  created_at_in_future: 'the clock of this Mac is ahead: set the date and time automatically and publish again',
+  update_group_not_found: 'ias update list shows the groups of the project',
+  update_archived: 'an archived group cannot be served again: republish its commit with ias update republish <group>',
+  channel_not_found: 'the project has no such channel: check --channel, or create it with its own certificate (php artisan ota:project <project> --channel=<channel> --certificate=… --keyid=…)',
+  rollout_in_progress: 'a group is rolling out to part of the installations there: complete it (ias update rollout <group> complete) or retire it before publishing another',
+  rollout_not_found: 'the group was published to everyone at once: it has no rollout to change',
+  rollout_completed: 'the rollout was completed and the group reaches every installation: to stop serving it, retire it (ias update retire <group>)',
+  update_retired: 'the group is retired: ias update restore <group> serves it again',
+  assets_missing: 'publish again: ias update publish uploads the files the server does not have',
+  build_not_found: 'ias dist list shows the builds of the project',
+  build_not_uploaded: 'upload it again: ias dist upload <file>',
+  build_size_mismatch: 'the file changed or the upload was cut: upload it again with ias dist upload <file>',
+  build_hash_mismatch: 'the file changed or the upload was cut: upload it again with ias dist upload <file>',
+  build_too_large: 'the server takes builds of up to 1 GiB (DISTRIBUTION_MAX_BUILD_BYTES)',
+  icon_invalid: 'expo.icon in app.json must be an image sips can turn into a PNG',
+  icon_too_large: 'expo.icon in app.json must stay under 512 KB once shrunk to 180 px',
+  // The management API (docs/technical/manage-api.md §10).
+  token_invalid: 'the token does not exist, expired or was revoked: run ias login again, or check IAS_TOKEN',
+  scope_missing: 'the token lacks that scope: a robot token has the scopes chosen in the panel (the application › Settings › Access); ias login gives a personal one',
+  role_forbidden: 'it needs an owner of the team, or a personal token (ias login) instead of a robot one',
+  application_not_found: 'ias apps lists the applications this token can see; check app in ias.json or --app',
+  credential_not_found: 'ias credentials list shows the credentials of the application and the team',
+  variable_not_found: 'ias env list shows the variables of each environment',
+  approval_not_found: 'the approval expired or was asked by another token: run the command again',
+  token_not_found: 'the token was already revoked',
+  vault_keys_exist: 'the vault already has its keys: ias vault status compares them with the ones in 1Password',
+  vault_not_ready: 'the vault has no keys yet: an owner of the team runs ias vault init',
+  credential_exists: 'a credential with this id exists: ias credentials rotate <id> replaces its material',
+  credential_version_conflict: 'someone replaced it meanwhile: run the command again, which seals the next version',
+  envelope_invalid: 'the server did not take the envelope (the reason is the check of docs/technical/vault.md §6 that failed): nothing was stored; update ias, and if it goes on, report it',
+  recovery_key_missing: 'the envelope is not sealed for the team\'s current recovery key: ias vault status compares the keys of 1Password with the server\'s',
+  recipient_unknown: 'the envelope is sealed for a key the server does not know (a runner revoked meanwhile?): run the command again; ias vault status shows the keys',
+  signature_key_unknown: 'the envelope is signed with a key that is not the team\'s registered one: ias vault status compares the signing key of 1Password with the server\'s',
+  variable_must_be_plain: 'EXPO_PUBLIC_ variables end up in the bundle, so they are always plain: set it without --secret',
+  credential_type_invalid: 'ias credentials import --help lists the types',
+  // Builds, runners and store submissions (docs/technical/runner-api.md §8). build_not_found of a build of IAS gets its own hint in
+  // commands/build/follow.mjs: the one above is for ias dist.
+  build_number_backwards: 'build numbers only go up on the server: ias version get shows the last ones',
+  build_number_used: 'a store build already used that build number: raise expo.ios.buildNumber or expo.android.versionCode in app.json, or give the profile autoIncrement (ias version get shows the server\'s)',
+  build_not_cancelable: 'the build has ended already: there is nothing to cancel',
+  build_not_submittable: 'only a store build that succeeded, with its IPA or AAB and not being sent already, goes to a store: ias builds view <id> shows how it is',
+  approvers_version_backwards: 'someone signed a newer version of the approvers meanwhile: run ias vault approvers again, which signs the next one',
+  runner_list_serial_backwards: 'someone signed a newer runner list meanwhile: run the command again, which signs the next one',
+  source_not_uploaded: 'the code did not reach the bucket: run ias build again',
+  source_mismatch: 'the code in the bucket is not the one described (its size or SHA-256): run ias build again',
+  artifact_mismatch: 'the artifact in the bucket is not the one described: run the build again, and if it goes on, check the runner',
+  artifact_not_found: 'ias builds view <id> lists the artifacts of the build',
+  profile_invalid: 'the build profile does not follow the schema of ias.json, or the runners cannot build it yet (developmentClient and ios.simulator: ias build --local); ias doctor checks ias.json',
+  credentials_missing: 'the vault has no usable credential of those types for this build: import them with ias credentials import, and check that they are not retired or expired (ias credentials list)',
+  document_invalid: 'the server did not take the signed document (the reason is the check of docs/technical/vault.md that failed): nothing was stored; update ias, and if it goes on, report it',
+  runner_not_found: 'ias vault status and the panel (System › Runners) list the runners',
+  runner_not_authorized: 'the runner is pending, revoked or not in the list the team signed: an owner runs ias vault grant <runner>',
+  runner_signature_invalid: 'the runner signed with a key the server does not have, or the clock of its Mac is wrong: set the time automatically, or register the runner again',
+  registration_code_invalid: 'the code expired (30 minutes), was used or does not exist: an owner makes another in the panel (System › Runners › Add runner)',
+  job_not_found: 'the job is not this runner\'s, or it ended: ias builds view <id> shows the build',
+  // Push notifications (docs/technical/manage-api.md §14.6).
+  push_not_enabled: 'the application does not use push notifications: turn the service on in the panel (the application › Settings)',
+  push_credentials_missing: 'load the APNs key or the FCM service account first: ias push credentials ios <AuthKey_….p8>, or android <service-account.json>',
+  message_not_found: 'ias push messages lists the notifications of the application',
+  message_not_cancelable: 'only a scheduled notification can be canceled: this one already went out or was canceled',
+  audience_not_found: 'some id of the audience is not a user, organization, space, group or device of the application: nothing was sent',
+  push_credential_invalid: 'the file is not a usable APNs key (.p8) or FCM service account (JSON): nothing was stored',
+  // Testers' devices and resigns (docs/technical/manage-api.md §15).
+  device_not_found: 'ias devices list shows the devices of the application',
+  device_not_approved: 'only an approved device goes into Apple: approve it in the panel (Distribución › Dispositivos) and run ias devices sync again',
+  resign_source_missing: 'there is no internal iOS build of IAS to sign again: make one with ias build --platform ios --profile preview',
+  resign_in_progress: 'the application is being signed again already: wait for it to end (the panel, Distribución › Dispositivos, has its log)',
+  resign_not_found: 'the panel (Distribución › Dispositivos) lists the latest resigns of the application',
+  build_not_resignable: 'only an internal iOS build that succeeded, with its IPA, is signed again: ias builds list --platform ios shows them',
+  profile_not_current: 'the builds use another ad hoc profile of the application (one that expires later): retire the one you do not want with ias credentials retire',
+  // Webhooks, GitHub and workflows (docs/technical/manage-api.md §16).
+  integrations_key_missing: 'the server has no IAS_INTEGRATIONS_KEY (or not the one that sealed the secret): whoever runs the server sets it (.env.example) and loads the secrets again',
+  webhook_not_found: 'ias webhooks list shows the webhooks of the application',
+  webhook_disabled: 'the webhook was turned off after too many failures: fix its address and turn it on in the panel (the application › Integraciones)',
+  delivery_not_found: 'the panel (the application › Integraciones) lists the deliveries of each webhook',
+  github_not_linked: 'link the repository first: ias github link <owner/name>',
+  github_token_missing: 'an owner loads the token of GitHub in the panel, with a passkey (the application › Integraciones)',
+  github_token_refused: 'GitHub does not take the token (expired, revoked or without access to the repository): an owner loads a new one in the panel',
+  github_refused: 'GitHub refused the request: check the repository, the ref and that the token reads its contents',
+  github_unreachable: 'the server could not reach GitHub: try again in a minute',
+  workflow_not_found: 'ias workflows list shows the workflows of ias.json at that commit',
+  workflow_invalid: 'the workflows of ias.json do not follow its schema: ias doctor checks the file',
+  workflow_run_not_found: 'the panel (the application › Integraciones) lists the latest runs',
+  ias_json_invalid: 'the commit has no valid ias.json at the root of the repository: commit it, or run the workflow at another ref',
+  app_mismatch: 'the app of ias.json must be the application the repository is linked to',
+  profile_not_found: 'the workflow names a build profile that ias.json does not have: ias.json › build lists them',
+  app_json_missing: 'the build reads the version and build numbers from app.json at the root of the repository (an app.config.js is not read)',
+  platform_not_configured: 'give the application its bundle id and Android package in the panel (the application › Ajustes)',
+  limit_exceeded: 'the team used its monthly limit of that metric (ias usage shows where it is): it starts over on the first day of next month, or a platform administrator raises it in the panel (Plataforma › Uso)',
+  rate_limited: 'too many requests: wait a minute and run it again',
+  access_denied: 'a member rejected the authorization in the panel: run ias login again if it was a mistake',
+  expired_token: 'the code expired (10 minutes) or was already used: run ias login again',
+};
+
+function hintFor(status, code, data) {
+  if (code && HINTS[code]) return HINTS[code];
+  const message = String(data?.message ?? '');
+  if (status === 404 && message.includes('OtaProject')) return HINTS.project_not_found;
+  if (status === 404 && message.includes('DistributionProject')) return 'there is no distribution project with this code: check distribution.project (or app) in ias.json, or create it with php artisan dist:project';
+  if (status === 401) return 'the server did not take the token: check IAS_TOKEN or the token in ias.json';
+  if (status >= 500) return 'the server failed: try again in a minute, and if it goes on, look at its logs';
+  return undefined;
+}
+
+/** The parts of an error for --json: what happened, how to fix it and the code, if any. */
+export function describeError(error) {
+  return {
+    message: error.what ?? error.message,
+    ...(error.fix || error.hint ? { fix: error.fix ?? error.hint } : {}),
+    ...(error.code ? { code: error.code } : {}),
+    ...(error.status ? { status: error.status } : {}),
+    ...(error.details ? { details: error.details } : {}),
+  };
+}

package/src/http.mjs

@@ -0,0 +1,45 @@
+// Requests to the publishing APIs of IAS (API.md §36 and §37) with a project's token.
+import { ApiError } from './errors.mjs';
+
+const wait = (seconds) => new Promise((done) => setTimeout(done, seconds * 1000));
+
+/**
+ * A request to `settings.base` + `path` with the token; waits out one 429. Returns the parsed JSON. An answer that is
+ * not a success throws an ApiError with its status and code; an error page that is not JSON (a proxy's 502) still
+ * gives its status.
+ */
+export async function api(settings, token, method, path, { json, body, headers = {} } = {}) {
+  for (let attempt = 0; ; attempt += 1) {
+    const response = await fetch(`${settings.base}${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(json ? { 'content-type': 'application/json' } : {}), ...headers },
+      body: json ? JSON.stringify(json) : body,
+    });
+    if (response.status === 429 && attempt === 0) {
+      await wait(Number(response.headers.get('retry-after')) || 10);
+      continue;
+    }
+    const text = await response.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      if (response.ok) throw new ApiError(`${method} ${path}: ${response.status}, but the answer is not JSON: ${text.slice(0, 300)}`, { status: response.status });
+    }
+    if (!response.ok) {
+      throw new ApiError(`${method} ${path}: ${response.status} ${data?.code ?? ''} ${data?.message ?? text.slice(0, 300)}${data?.platform ? ` (${data.platform})` : ''}`, { status: response.status, code: data?.code, data });
+    }
+    return data;
+  }
+}
+
+/** A GET that waits out each 429: the asset route allows 60 requests a minute per IP, phones on this network included. */
+export async function download(url, headers, output) {
+  for (;;) {
+    const response = await fetch(url, { headers });
+    if (response.status !== 429) return response;
+    const seconds = Number(response.headers.get('retry-after')) || 60;
+    output.progress(`  the server asks to wait ${seconds} s (429)…`);
+    await wait(seconds);
+  }
+}

package/src/legacy.mjs

@@ -0,0 +1,73 @@
+// The command lines of tools/expo-ota/publish.mjs and tools/expo-dist/upload.mjs, kept word for word on top of ias
+// update and ias dist while jscheduler-app and jero-invoices-app still call them: the same arguments (an option
+// nobody knows is ignored, as it always was), the same configuration files and the same output, «expo-ota: …» and
+// «expo-dist: …» included. ias.json, if the app has one, is read first, as ias does.
+import process from 'node:process';
+import { resolve } from 'node:path';
+import { distSettings, loadProject, updateSettings } from './config.mjs';
+import { createOutput } from './output.mjs';
+import { cleanup } from './process.mjs';
+import * as dist from './commands/dist/index.mjs';
+import * as update from './commands/update/index.mjs';
+
+/** The loose parsing of tools/: `command target` are the first words that are not options or the value of one. */
+function parseLegacy(args, valued) {
+  const option = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  const [command, target] = args.filter((arg, index) => !arg.startsWith('--') && !valued.includes(args[index - 1]));
+  return { option, command, target, flag: (name) => args.includes(name) };
+}
+
+/** tools/expo-ota/publish.mjs: publish | republish | rollback-to-embedded | retire | restore | list | check. */
+export async function expoOta(args = process.argv.slice(2), { env = process.env, cwd = process.cwd(), stdout, stderr } = {}) {
+  const { option, command, target, flag } = parseLegacy(args, ['--message', '--ref', '--platform', '--channel', '--project']);
+  const output = createOutput({ prefix: 'expo-ota', hints: false, stdout, stderr });
+  const platforms = option('--platform') ? [option('--platform')] : update.PLATFORMS;
+  const options = { message: option('--message'), platforms, channel: option('--channel'), dryRun: flag('--dry-run') };
+  const COMMANDS = {
+    publish: (settings) => update.publish(settings, { ...options, ref: option('--ref') ?? 'HEAD' }, output),
+    republish: (settings) => update.republish(settings, { ...options, group: target }, output),
+    'rollback-to-embedded': (settings) => update.rollbackToEmbedded(settings, options, output),
+    retire: (settings) => update.setServing(settings, 'retire', { group: target }, output),
+    restore: (settings) => update.setServing(settings, 'restore', { group: target }, output),
+    list: (settings) => update.list(settings, { channel: option('--channel') }, output),
+    check: (settings) => update.check(settings, { platforms }, output),
+  };
+  const interrupted = () => (stderr ?? process.stderr).write('\nexpo-ota: interrupted, cleaning up\n');
+  process.on('SIGINT', interrupted);
+  let status = 1;
+  try {
+    if (!Object.hasOwn(COMMANDS, command ?? '')) throw new Error(`usage: node publish.mjs ${Object.keys(COMMANDS).join(' | ')} [--project <app folder>] (tools/expo-ota/README.md)`);
+    if (platforms.some((platform) => !update.PLATFORMS.includes(platform))) throw new Error('--platform is ios or android');
+    await COMMANDS[command](updateSettings(loadProject(resolve(cwd, option('--project') ?? '.')), env));
+    status = 0;
+  } catch (error) {
+    output.fail(error);
+  } finally {
+    process.off('SIGINT', interrupted);
+    cleanup();
+  }
+  return status;
+}
+
+/** tools/expo-dist/upload.mjs: upload | list | retire | restore. */
+export async function expoDist(args = process.argv.slice(2), { env = process.env, cwd = process.cwd(), stdout, stderr } = {}) {
+  const { option, command, target } = parseLegacy(args, ['--notes', '--project']);
+  const output = createOutput({ prefix: 'expo-dist', hints: false, stdout, stderr });
+  const COMMANDS = {
+    upload: (settings) => dist.upload(settings, { file: target, notes: option('--notes'), cwd }, output),
+    list: (settings) => dist.list(settings, output),
+    retire: (settings) => dist.setOffered(settings, 'retire', { id: target }, output),
+    restore: (settings) => dist.setOffered(settings, 'restore', { id: target }, output),
+  };
+  let status = 1;
+  try {
+    if (!Object.hasOwn(COMMANDS, command ?? '')) throw new Error(`usage: node upload.mjs ${Object.keys(COMMANDS).join(' | ')} [--project <app folder>] (tools/expo-dist/README.md)`);
+    await COMMANDS[command](distSettings(loadProject(resolve(cwd, option('--project') ?? '.')), env));
+    status = 0;
+  } catch (error) {
+    output.fail(error);
+  } finally {
+    cleanup();
+  }
+  return status;
+}

package/src/manage.mjs

@@ -0,0 +1,120 @@
+// The management API of IAS (/api/manage/v1, docs/technical/manage-api.md): which server, which token, and the requests. The
+// token is IAS_TOKEN (the token or an op:// reference), or the one ias login kept for the server; it is never printed.
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { ApiError, IasError } from './errors.mjs';
+import { readSecret, tokenKind } from './secrets.mjs';
+import { serverOf } from './config.mjs';
+import { storeKind, storeLabel, storedToken } from './token-store.mjs';
+
+export const MANAGE_PATH = '/api/manage/v1';
+
+export const sleep = (seconds) => new Promise((done) => setTimeout(done, seconds * 1000));
+
+/** The origin of the server for the management API: https, or localhost and .test to try it locally. */
+export function serverOrigin(project, env = process.env) {
+  const text = serverOf(project ?? {}, env);
+  const url = URL.canParse(text) ? new URL(text) : undefined;
+  if (!url) throw new IasError(`the server (${text}) is not a URL`, { fix: 'set server in ias.json or IAS_SERVER to the origin of IAS, such as https://ias.imagina.build' });
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.hostname.endsWith('.test');
+  if (url.protocol !== 'https:' && !local) throw new IasError(`the server (${url.origin}) is not https`, { fix: 'the token goes in every request: use the https origin of IAS' });
+  return url.origin;
+}
+
+/**
+ * The token for `server` and where it comes from: IAS_TOKEN first, then the one ias login kept. Robot tokens of the
+ * old projects (ota_, dist_) do not work in this API.
+ */
+export function manageToken(server, env = process.env) {
+  let token;
+  let source;
+  if (env.IAS_TOKEN) {
+    token = readSecret(env.IAS_TOKEN, { env });
+    source = 'IAS_TOKEN';
+  } else {
+    const kind = storeKind(env);
+    token = storedToken(server, { env, kind });
+    source = storeLabel(kind, env);
+  }
+  if (!token) throw new IasError(`not logged in to ${server}`, { fix: 'run ias login (or set IAS_TOKEN to a robot token on CI)', code: 'not_logged_in' });
+  const kind = tokenKind(token);
+  if (kind === 'ota' || kind === 'dist') throw new IasError(`the token is a publishing token of a project (${kind}_…), which the management API does not take`, { fix: 'run ias login, or use a robot token of the application (iasr_…, the panel: the application › Settings › Access)' });
+  return { token, source };
+}
+
+/**
+ * A client of the management API: { server, request(method, path, { json, auth }) }. request returns { status, data }
+ * for a success (204 has no data, 202 is an approval) and throws an ApiError, with the hint of its code, otherwise.
+ */
+export function manageClient(server, token, { fetch: fetchImpl = fetch, wait = sleep } = {}) {
+  async function request(method, path, { json, auth = true } = {}) {
+    for (let attempt = 0; ; attempt += 1) {
+      const response = await fetchImpl(`${server}${MANAGE_PATH}${path}`, {
+        method,
+        headers: { accept: 'application/json', ...(auth ? { authorization: `Bearer ${token}` } : {}), ...(json !== undefined ? { 'content-type': 'application/json' } : {}) },
+        body: json !== undefined ? JSON.stringify(json) : undefined,
+      });
+      if (response.status === 429 && attempt < 3) {
+        await wait(Number(response.headers.get('retry-after')) || 10);
+        continue;
+      }
+      const text = await response.text();
+      let data = null;
+      try {
+        data = text ? JSON.parse(text) : null;
+      } catch {
+        throw new ApiError(`${method} ${MANAGE_PATH}${path}: ${response.status}, but the answer is not JSON: ${text.slice(0, 200)}`, { status: response.status });
+      }
+      if (!response.ok) {
+        const reason = data?.reason ? ` (reason: ${data.reason})` : '';
+        throw new ApiError(`${method} ${MANAGE_PATH}${path}: ${response.status} ${data?.code ?? ''} ${data?.message ?? ''}${reason}`.trimEnd(), { status: response.status, code: data?.code, data });
+      }
+      return { status: response.status, data };
+    }
+  }
+  return { server, request };
+}
+
+/** The server and a client with the token of this machine, for a command. */
+export function connect(context, project) {
+  const server = serverOrigin(project, context.env);
+  const { token, source } = manageToken(server, context.env);
+  return { ...manageClient(server, token, { wait: context.sleep ?? sleep }), tokenSource: source };
+}
+
+/** Opens `url` in the browser: $BROWSER if set (none to skip), open on macOS, xdg-open elsewhere. Never fails. */
+export function openUrl(url, env = process.env) {
+  const command = env.BROWSER ?? (process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? undefined : 'xdg-open');
+  if (!command || command === 'none') return false;
+  try {
+    const child = spawn(command, [url], { detached: true, stdio: 'ignore', env });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Waits for a member to approve an action with a passkey (docs/technical/manage-api.md §6): asks GET /approvals/{id} every 3 s
+ * and returns its result. Throws if it is rejected or expires.
+ */
+export async function waitForApproval(client, approval, { wait = sleep, interval = 3, output } = {}) {
+  for (;;) {
+    const { data } = await client.request('GET', `/approvals/${approval.id}`);
+    if (data.status === 'approved') return data.result;
+    if (data.status === 'rejected') throw new IasError(`a member rejected the approval of ${data.action}`, { fix: 'run the command again if it was a mistake', code: 'approval_rejected' });
+    if (data.status === 'expired') throw new IasError(`the approval of ${data.action} expired`, { fix: 'approve it within 10 minutes: run the command again', code: 'approval_expired' });
+    output?.progress?.('  waiting for the approval…');
+    await wait(interval);
+  }
+}
+
+/** The code of the application of a command: --app, or app of ias.json. */
+export function applicationOf(context, project) {
+  const code = context.values.app ?? project?.config?.app;
+  if (!code) throw new IasError('which application?', { fix: 'pass --app <code>, or run it in the folder of an app with an ias.json (ias apps lists them)' });
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(code)) throw new IasError(`«${code}» is not the code of an application`, { fix: 'ias apps lists them' });
+  return code;
+}

package/src/ota.mjs

@@ -0,0 +1,122 @@
+// The parts of an OTA update that need no network, git or 1Password: manifests, signatures and the multipart answer.
+import { Buffer } from 'node:buffer';
+import { createHash, createPublicKey, createSign, createVerify, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Content types of the files expo export writes, by extension; the bundle is application/javascript. */
+export const MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', ttf: 'font/ttf', otf: 'font/otf', woff: 'font/woff', woff2: 'font/woff2', json: 'application/json', mp3: 'audio/mpeg', wav: 'audio/wav', mp4: 'video/mp4' };
+
+/** The lockfile of the app and the install that reproduces it in the export copy. */
+export const INSTALLS = [
+  ['package-lock.json', 'npm', ['ci', '--no-audit', '--no-fund']],
+  ['yarn.lock', 'yarn', ['install', '--frozen-lockfile']],
+  ['pnpm-lock.yaml', 'pnpm', ['install', '--frozen-lockfile']],
+  ['bun.lock', 'bun', ['install', '--frozen-lockfile']],
+  ['bun.lockb', 'bun', ['install', '--frozen-lockfile']],
+];
+
+/** The hash expo-updates gives a file: SHA-256 in base64url. */
+export const sha256 = (data) => createHash('sha256').update(data).digest('base64url');
+
+/** The variables `names` of a dotenv file (KEY=value lines; quotes are dropped). */
+export function readEnvFile(path, names) {
+  const values = {};
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (match && names.includes(match[1])) values[match[1]] = match[2].replace(/^(['"])(.*)\1$/, '$2');
+  }
+  return values;
+}
+
+/**
+ * One manifest per platform from an expo export folder: the same createdAt, the runtime of each platform, relative
+ * asset URLs, metadata {} (filters could make phones load an older update) and the public config as extra.expoClient.
+ * Returns the manifests and the files to upload, by hash. Throws if a bundle lacks a value it must carry.
+ */
+export function buildManifests({ dist, metadata, platforms, runtimes, expoClient, assetPath, createdAt, mustContain = [] }) {
+  const files = new Map();
+  const entry = (path, ext, contentType) => {
+    const contents = readFileSync(join(dist, path));
+    const hash = sha256(contents);
+    files.set(hash, { path: join(dist, path), contentType });
+    return { hash, key: createHash('md5').update(contents).digest('hex'), contentType, fileExtension: `.${ext}`, url: `${assetPath}${hash}` };
+  };
+  const manifests = {};
+  for (const platform of platforms) {
+    const { bundle, assets } = metadata.fileMetadata[platform];
+    const code = readFileSync(join(dist, bundle));
+    for (const [name, value] of mustContain) if (!code.includes(value)) throw new Error(`the ${platform} bundle does not carry ${name}`);
+    manifests[platform] = {
+      id: randomUUID(),
+      createdAt,
+      runtimeVersion: runtimes[platform],
+      launchAsset: entry(bundle, 'bundle', 'application/javascript'),
+      assets: assets.map((asset) => entry(asset.path, asset.ext, MIME[asset.ext] ?? 'application/octet-stream')),
+      metadata: {},
+      extra: { expoClient },
+    };
+  }
+  return { manifests, files };
+}
+
+/** The expo-signature header of `body`: RSA-SHA256 of its exact bytes. */
+export const signatureHeader = (body, privateKeyPem, keyid) => `sig="${createSign('RSA-SHA256').update(body).sign(privateKeyPem, 'base64')}", keyid="${keyid}"`;
+
+/** Whether `header` is a valid expo-signature of `body` for this public key and keyid. */
+export function verifySignature(publicKey, keyid, body, header) {
+  const sig = header?.match(/sig="([^"]+)"/)?.[1];
+  return Boolean(sig) && header.match(/keyid="([^"]+)"/)?.[1] === keyid && createVerify('RSA-SHA256').update(body).verify(publicKey, sig, 'base64');
+}
+
+/** The first part of a multipart/mixed body: its name, its expo-signature header and its exact bytes. */
+export function firstPart(buffer, boundary) {
+  const start = buffer.indexOf(`--${boundary}\r\n`) + boundary.length + 4;
+  const headersEnd = buffer.indexOf('\r\n\r\n', start);
+  const end = buffer.indexOf(`\r\n--${boundary}`, headersEnd);
+  const headers = buffer.subarray(start, headersEnd).toString('utf8');
+  return { name: headers.match(/name="([^"]+)"/)?.[1], signature: headers.match(/^expo-signature: (.+)$/im)?.[1]?.trim(), body: buffer.subarray(headersEnd + 4, end) };
+}
+
+/**
+ * The platforms of a publication that sends the phones back to the JavaScript of their build: one signed
+ * rollBackToEmbedded directive, with the runtime of each platform.
+ */
+export function rollbackDirectives({ platforms, runtimes, privateKeyPem, keyid, commitTime }) {
+  const body = JSON.stringify({ type: 'rollBackToEmbedded', parameters: { commitTime } });
+  const signature = signatureHeader(body, privateKeyPem, keyid);
+  return Object.fromEntries(platforms.map((platform) => [platform, { directive: Buffer.from(body).toString('base64'), signature, runtime_version: runtimes[platform] }]));
+}
+
+/**
+ * Where an installation falls in the gradual rollout of a group, from 0 to 99, as the server decides it (API.md §36.9):
+ * the first 32 bits of SHA-256("<group>:<EAS-Client-ID>"), both in lowercase. It gets the group below the share.
+ */
+export const rolloutBucket = (group, installation) => createHash('sha256').update(`${group.toLowerCase()}:${installation.toLowerCase()}`).digest().readUInt32BE(0) % 100;
+
+/** An EAS-Client-ID that falls inside the share of a group, to ask for the manifest as one of those phones. */
+export function installationInside(group, percent) {
+  for (;;) {
+    const installation = randomUUID();
+    if (rolloutBucket(group, installation) < percent) return installation;
+  }
+}
+
+/** The SPKI of a certificate (X509Certificate), a public key object or a PEM, to compare two of them. */
+export function publicKeyOf(key) {
+  const object = key.publicKey ?? key;
+  return (object.type === 'public' ? object : createPublicKey(object)).export({ type: 'spki', format: 'der' }).toString('base64');
+}
+
+/**
+ * The manifest (or directive) of an earlier group signed again for another channel: the same contents with a new id and
+ * createdAt (a new commitTime), since the phones only take what is newer than what they run. Refuses what the Mac must
+ * never sign: metadata other than {} (filters could force an older update).
+ */
+export function promoted(kind, body, now = new Date().toISOString()) {
+  const document = JSON.parse(body);
+  if (kind === 'directive') return { ...document, parameters: { ...document.parameters, commitTime: now } };
+  if (JSON.stringify(document.metadata) !== '{}') throw new Error('the manifest has metadata other than {}: it is not signed again (filters could make phones load an older update)');
+  return { ...document, id: randomUUID(), createdAt: now };
+}
+

package/src/output.mjs

@@ -0,0 +1,36 @@
+// Where a command writes. For people, lines as it goes; with --json, one JSON document on stdout at the end and the
+// progress on stderr, so a script can read stdout whole.
+import process from 'node:process';
+import { describeError } from './errors.mjs';
+
+/** A result with this key exits with its value (ias doctor exits with 1 when a check fails); JSON leaves it out. */
+export const EXIT_CODE = Symbol('exit code');
+
+/**
+ * The output of one run. `prefix` starts warnings and errors (ias, or expo-ota and expo-dist in the tools/ wrappers);
+ * `hints` adds how to fix an answer of the server, which the wrappers leave out to print what they always printed.
+ */
+export function createOutput({ json = false, prefix = 'ias', hints = true, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const write = (stream, line) => stream.write(`${line}\n`);
+  return {
+    json,
+    prefix,
+    /** A line of the result, for people. With --json the result goes in the document instead. */
+    log: (line) => (json ? undefined : write(stdout, line)),
+    /** A step of a long command: on stdout for people, on stderr with --json. */
+    progress: (line) => write(json ? stderr : stdout, line),
+    /** Something to look at that does not stop the command. */
+    warn: (line) => write(stderr, `${prefix}: ${line}`),
+    /** The result of a command with --json. */
+    result: (value) => (json && value !== undefined ? write(stdout, JSON.stringify(value, null, 2)) : undefined),
+    /** An error: «prefix: what: how», and the hint of the server's answer on the next line. */
+    fail(error) {
+      if (json) {
+        write(stdout, JSON.stringify({ error: describeError(error) }, null, 2));
+        return;
+      }
+      write(stderr, `${prefix}: ${error.message}`);
+      if (hints && error.hint) write(stderr, `${prefix}: ${error.hint}`);
+    },
+  };
+}

package/src/process.mjs

@@ -0,0 +1,45 @@
+// Other programs (git, op, npx, unzip…) and the temporary folders of a run.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+
+const temporaries = [];
+
+/** A new temporary folder, removed by cleanup() when the run ends. */
+export function temporary(prefix = 'ias-') {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  temporaries.push(dir);
+  return dir;
+}
+
+/** Removes the temporary folders of this run: they may hold a private key or a copy of the app. */
+export function cleanup() {
+  for (const dir of temporaries.splice(0)) rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Runs a command and returns its stdout. On failure it prints the last lines the command wrote (`tail`: its stdout and
+ * stderr, or only its stderr) and throws with `label`, never with the arguments, which may hold a secret.
+ */
+export function run(command, commandArgs, { label = `${command} ${commandArgs[0]}`, tail = 'all', lines = 30, ...options } = {}) {
+  const result = spawnSync(command, commandArgs, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['inherit', 'pipe', 'inherit'], ...options });
+  if (result.error || result.status !== 0) {
+    if (typeof result.stderr === 'string') {
+      const output = tail === 'stderr' ? result.stderr : [result.stdout, result.stderr].join('\n');
+      process.stderr.write(`${output.trimEnd().split('\n').slice(-lines).join('\n')}\n`);
+    }
+    throw new Error(`${label} failed${result.error ? `: ${result.error.message}` : ` (exit ${result.status})`}`);
+  }
+  return result.stdout;
+}
+
+/** Heavy steps (install, export) at a low priority, mostly on the efficiency cores: the Mac stays usable. */
+export const gently = (command, commandArgs, options) => run('taskpolicy', ['-c', 'utility', 'nice', '-n', '15', command, ...commandArgs], { label: `${command} ${commandArgs[0]}`, ...options });
+
+/** Whether a program answers, and what it says (for ias doctor): { ok, output }. Never throws. */
+export function probe(command, commandArgs = [], options = {}) {
+  const result = spawnSync(command, commandArgs, { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'], ...options });
+  return { ok: !result.error && result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() };
+}