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

package/src/commands/version/index.mjs

@@ -0,0 +1,71 @@
+// ias version get and set: the build numbers the server keeps for each platform of an application (docs/technical/runner-api.md
+// §4.1), as appVersionSource: remote of EAS. A build with autoIncrement takes the next one; set brings them from EAS or
+// app.json (owner), and they only go up.
+import { resolve } from 'node:path';
+import { loadProject, readExpo } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { buildNumberOf } from '../build/source.mjs';
+
+const NUMBER = /^[1-9][0-9]{0,9}$/;
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const shown = (numbers) => `iOS ${numbers.ios ?? 'none yet'}, Android ${numbers.android ?? 'none yet'}`;
+
+async function get(context) {
+  const project = projectOf(context);
+  const application = applicationOf(context, project);
+  const { data } = await connect(context, project).request('GET', `/apps/${application}/build-numbers`);
+  context.output.log(`${application}: the last build numbers are ${shown(data)}`);
+  return { app: application, ...data };
+}
+
+/** The numbers to set: --ios and --android, or those of app.json with --from-app-json. */
+function wanted(context, project) {
+  const { values } = context;
+  if (values['from-app-json']) {
+    if (values.ios || values.android) throw new IasError('--from-app-json takes both numbers from app.json', { fix: 'leave out --ios and --android, or leave out --from-app-json' });
+    const expo = readExpo(project.dir);
+    if (!expo) throw new IasError(`there is no app.json in ${project.dir}`, { fix: 'run it in the folder of the app, or give the numbers with --ios and --android' });
+    const numbers = Object.fromEntries(['ios', 'android'].map((platform) => [platform, buildNumberOf(expo, platform)]).filter(([, number]) => number !== null));
+    if (Object.keys(numbers).length === 0) throw new IasError('app.json has neither expo.ios.buildNumber nor expo.android.versionCode', { fix: 'give the numbers with --ios and --android' });
+    return numbers;
+  }
+  const numbers = {};
+  for (const platform of ['ios', 'android']) {
+    if (values[platform] === undefined) continue;
+    if (!NUMBER.test(values[platform])) throw new IasError(`--${platform} takes a whole number from 1, not «${values[platform]}»`, { fix: 'the last build number used, such as the one of the newest build in the store' });
+    numbers[platform] = Number(values[platform]);
+  }
+  if (Object.keys(numbers).length === 0) throw new IasError('which numbers?', { fix: 'ias version set --ios 4 --android 4, or --from-app-json' });
+  return numbers;
+}
+
+async function set(context) {
+  const project = projectOf(context);
+  const application = applicationOf(context, project);
+  const numbers = wanted(context, project);
+  const { data } = await connect(context, project).request('PUT', `/apps/${application}/build-numbers`, { json: numbers });
+  context.output.log(`${application}: the last build numbers are now ${shown(data)}; the next build with autoIncrement takes the one after.`);
+  return { app: application, ...data };
+}
+
+const app = { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } };
+
+export default {
+  name: 'version',
+  summary: 'The build numbers the server keeps for each platform (autoIncrement takes the next)',
+  subcommands: [
+    { name: 'get', summary: 'The last build number used on iOS and on Android', options: app, run: get },
+    {
+      name: 'set',
+      summary: 'Set the last build numbers, to bring them from EAS or app.json (owner); they only go up',
+      options: {
+        ...app,
+        ios: { type: 'string', value: '<number>', description: 'The last build number of iOS (CFBundleVersion).' },
+        android: { type: 'string', value: '<number>', description: 'The last version code of Android.' },
+        'from-app-json': { type: 'boolean', description: 'Take them from expo.ios.buildNumber and expo.android.versionCode of app.json.' },
+      },
+      run: set,
+    },
+  ],
+};

package/src/commands/webhooks/index.mjs

@@ -0,0 +1,104 @@
+// ias webhooks list, create, delete and test (docs/technical/manage-api.md §16.1): the outgoing webhooks of an application, which
+// get a POST signed with IAS-Signature for each event they subscribe to. The secret that signs them comes in the
+// answer that makes the webhook and nowhere else, so create prints it once and the CLI keeps nothing.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError, UsageError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const 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 day = (iso) => (iso ? iso.slice(0, 16).replace('T', ' ') : '—');
+
+const common = {
+  app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+};
+
+async function list(context) {
+  const { output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const { data } = await connect(context, project).request('GET', `/apps/${code}/webhooks`);
+  if (data.data.length === 0) output.log(`${code} has no webhooks: ias webhooks create <url> --events build.failed,device.pending`);
+  for (const webhook of data.data) {
+    const state = webhook.active ? 'on ' : 'OFF';
+    const events = webhook.events.length === data.events.length ? 'all events' : webhook.events.join(', ');
+    output.log(`${webhook.id}  ${state}  ${webhook.url}  ${events}${webhook.description ? `  «${webhook.description}»` : ''}`);
+    if (!webhook.active) output.log(`  turned off ${day(webhook.disabled_at)} after ${webhook.failures} failed attempts in a row: fix the address and turn it on in the panel (the application › Integraciones)`);
+    else if (webhook.failures > 0) output.log(`  ${webhook.failures} failed attempts in a row (it is turned off at 20)`);
+  }
+  return { webhooks: data.data, events: data.events };
+}
+
+/** The events of --events: «all», or names separated by commas (and repeated options). */
+export function eventsOf(values, known = []) {
+  const given = (values.events ?? []).flatMap((text) => text.split(',')).map((name) => name.trim()).filter(Boolean);
+  if (given.length === 0) throw new UsageError('--events says which events the webhook gets', { fix: '--events all, or a list such as --events build.succeeded,build.failed,device.pending' });
+  const events = given.includes('all') ? known : [...new Set(given)];
+  if (events.length === 0) throw new IasError('the server did not say which events there are', { fix: 'ias webhooks list shows them; pass them by name' });
+  return events;
+}
+
+async function create(context) {
+  const { values, positionals, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const client = connect(context, project);
+  const url = positionals[0];
+  if (!url.startsWith('https://')) throw new UsageError(`the address of a webhook is https (not «${url}»)`, { fix: 'the server only calls https addresses of public servers' });
+  const known = values.events?.some((text) => text.split(',').includes('all')) ? (await client.request('GET', `/apps/${code}/webhooks`)).data.events : [];
+  const events = eventsOf(values, known);
+  const { data: webhook } = await client.request('POST', `/apps/${code}/webhooks`, { json: { url, events, ...(values.description ? { description: values.description } : {}) } });
+  output.log(`${webhook.id}  ${webhook.url}  ${webhook.events.join(', ')}`);
+  output.log(`secret  ${webhook.secret}`);
+  output.log('  This is the only time the secret is shown. Each event arrives as a POST with the header IAS-Signature: t=<time>,v1=<hex of HMAC-SHA256(secret, "<time>.<body>")>;');
+  output.log('  keep the secret in 1Password and reject a time more than 5 minutes from your clock. ias webhooks test checks that the address answers.');
+  return webhook;
+}
+
+async function remove(context) {
+  const { positionals, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  await connect(context, project).request('DELETE', `/apps/${code}/webhooks/${positionals[0].toLowerCase()}`);
+  output.log(`Deleted the webhook ${positionals[0]} of ${code}, with its deliveries.`);
+  return { deleted: positionals[0].toLowerCase() };
+}
+
+async function test(context) {
+  const { positionals, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const { data: delivery } = await connect(context, project).request('POST', `/apps/${code}/webhooks/${positionals[0].toLowerCase()}/test`);
+  if (delivery.status === 'succeeded') {
+    output.log(`The test arrived: the server answered ${delivery.status_code}.`);
+    return delivery;
+  }
+  output.log(`The test failed${delivery.status_code ? ` (the server answered ${delivery.status_code})` : ''}: ${delivery.error ?? 'no answer'}.`);
+  return { ...delivery, [EXIT_CODE]: 1 };
+}
+
+const webhookId = { name: 'webhook', description: 'The id of the webhook (ias webhooks list).', pattern: ID };
+
+export default {
+  name: 'webhooks',
+  summary: 'The outgoing webhooks of an application: list, create, delete and test them',
+  description: 'A webhook gets a POST signed with IAS-Signature (HMAC-SHA256 with its secret, as Stripe signs) for each event it subscribes to: builds, store submissions, updates, rollouts, credentials, notifications and testers\' devices. Only owners create, delete and test them; the secret is shown once.',
+  subcommands: [
+    { name: 'list', summary: 'The webhooks of the application, with their events and whether they are on', options: common, run: list },
+    {
+      name: 'create',
+      summary: 'Make a webhook and print its secret, once',
+      positionals: [{ name: 'url', description: 'An https address of a public server.' }],
+      options: {
+        ...common,
+        events: { type: 'string', multiple: true, value: '<events>', description: 'The events it gets, separated by commas, or «all»: build.queued, build.awaiting_approval, build.succeeded, build.failed, submission.succeeded, submission.failed, update.published, update.rollout_paused, update.rollout_completed, credential.expiring, push.message.finished, device.pending.' },
+        description: { type: 'string', value: '"…"', description: 'What it is for (up to 100 characters).' },
+      },
+      run: create,
+    },
+    { name: 'delete', summary: 'Delete a webhook and its deliveries', positionals: [webhookId], options: common, run: remove },
+    { name: 'test', summary: 'Send a test event now and say how the server answered', positionals: [webhookId], options: common, run: test },
+  ],
+};

package/src/commands/workflows/index.mjs

@@ -0,0 +1,88 @@
+// ias workflows list and run (docs/technical/manage-api.md §16.3): the workflows of ias.json that GitHub starts, read from a
+// commit of the linked repository, and a manual run. Steps go in order (build, submit); the first that fails stops the
+// run; store builds and submissions still wait for an owner's passkey.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { applicationOf, connect, sleep } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const FINISHED = ['succeeded', 'failed', 'canceled', 'skipped'];
+
+const common = {
+  app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+  ref: { type: 'string', value: '<ref>', description: 'A branch, tag or commit of the repository (its default branch by default).' },
+};
+
+/** «tag v*», «branch main», «pull requests» for the `on` of a workflow. */
+function triggers(on) {
+  return [on.tag && `tag ${on.tag}`, on.branch && `branch ${on.branch}`, on.pull_request && 'pull requests'].filter(Boolean).join(', ');
+}
+
+/** «build production (all)» or «submit ios, android» for a step. */
+function stepText(step) {
+  if (step.build) return `build ${step.build.profile} (${step.build.platform ?? 'all'})`;
+  return `submit ${Object.keys(step.submit).join(', ')}`;
+}
+
+async function list(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const path = `/apps/${code}/workflows${values.ref ? `?ref=${encodeURIComponent(values.ref)}` : ''}`;
+  const { data } = await connect(context, project).request('GET', path);
+  if (data.data.length === 0) output.log(`ias.json at ${data.commit.slice(0, 10)} has no workflows: add workflows to it (packages/cli/README.md).`);
+  for (const workflow of data.data) {
+    output.log(`${workflow.name.padEnd(12)}  on ${triggers(workflow.on)}${workflow.description ? `  «${workflow.description}»` : ''}`);
+    workflow.steps.forEach((step, index) => output.log(`  ${index + 1}. ${stepText(step)}`));
+  }
+  return data;
+}
+
+function show(output, run) {
+  output.log(`${run.id}  ${run.workflow}  ${run.status}  ${run.commit.slice(0, 10)}${run.message ? `  ${run.message}` : ''}`);
+  for (const step of run.steps) {
+    const items = step.items.map((item) => `${item.platform}${item.build ? ` build ${item.build}` : ''}${item.submission ? ` submission ${item.submission}` : ''}${item.status ? ` (${item.status})` : ''}`).join(', ');
+    output.log(`  ${step.position}. ${step.kind.padEnd(6)} ${step.status.padEnd(9)} ${items}${step.error ? ` — ${step.error.message ?? step.error.code}` : ''}`);
+  }
+  if (run.error) output.log(`  ${run.error.code}${run.error.message ? `: ${run.error.message}` : ''}`);
+}
+
+async function run(context) {
+  const { values, positionals, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const client = connect(context, project);
+  const { data: started } = await client.request('POST', `/apps/${code}/workflows/${positionals[0]}/runs`, { json: values.ref ? { ref: values.ref } : {} });
+  let current = started;
+  show(output, current);
+  if (current.steps.some((step) => step.items.some((item) => item.status === 'awaiting_approval'))) output.log('  A store build waits for an owner\'s passkey: ias builds view <build> says where to approve it.');
+  if (!values.wait) {
+    output.log(`  ias workflows run --wait follows a run; the panel (the application › Integraciones) shows it too.`);
+    return current;
+  }
+  const wait = context.sleep ?? sleep;
+  while (!FINISHED.includes(current.status)) {
+    output.progress('  waiting for the workflow…');
+    await wait(5);
+    ({ data: current } = await client.request('GET', `/workflow-runs/${started.id}`));
+  }
+  show(output, current);
+  return current.status === 'succeeded' ? current : { ...current, [EXIT_CODE]: 1 };
+}
+
+export default {
+  name: 'workflows',
+  summary: 'The workflows of ias.json that GitHub starts: list them and run one by hand',
+  description: 'A workflow is a list of steps, build and submit, that a tag, a branch or a pull request of the linked repository starts (ias github link). There is no step that publishes an OTA update: its signing key lives on a Mac. The code is the commit\'s tarball from GitHub; store builds and submissions wait for an owner\'s passkey as always.',
+  subcommands: [
+    { name: 'list', summary: 'The workflows of ias.json at a commit of the repository, with their triggers and steps', options: { ...common }, run: list },
+    {
+      name: 'run',
+      summary: 'Start a workflow by hand at a ref of the repository',
+      positionals: [{ name: 'workflow', description: 'The name of the workflow (ias workflows list).', pattern: /^[A-Za-z0-9][A-Za-z0-9._-]{0,49}$/ }],
+      options: { ...common, wait: { type: 'boolean', description: 'Follow the run until it ends; the exit code is 1 if it did not succeed.' } },
+      run,
+    },
+  ],
+};

package/src/config.mjs

@@ -0,0 +1,261 @@
+// The configuration of an app: ias.json (schema/ias.schema.json) or, while the apps move to it, the files of tools/:
+// ota.config.json and dist.config.json. Secrets are only op:// references or variables of the environment.
+import { X509Certificate } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+import { IasError } from './errors.mjs';
+import { validate } from './schema.mjs';
+import { writtenSecrets } from './secrets.mjs';
+import { storedToken } from './token-store.mjs';
+
+export const CONFIG_FILE = 'ias.json';
+export const LEGACY_FILES = { updates: 'ota.config.json', distribution: 'dist.config.json' };
+export const DEFAULT_SERVER = 'https://ias.imagina.build';
+
+/** The path of an OTA manifest, the URL the builds carry in updates.url: /api/v1/ota/<project>/manifest. */
+export const MANIFEST_PATH = /^\/api\/v1\/ota\/([^/]+)\/manifest$/;
+
+/** The names the config plugin of @imagina/ias (packages/sdk/app.plugin.cjs) goes by in the plugins of app.json. */
+export const IAS_PLUGINS = ['@imagina/ias', '@imagina/ias/plugin', '@imagina/ias/app.plugin.cjs'];
+/** The app configs Expo runs as code: ias cannot read nor rewrite them. */
+export const DYNAMIC_CONFIGS = ['app.config.js', 'app.config.ts', 'app.config.mjs', 'app.config.cjs'];
+
+/**
+ * The updates.url the config plugin of @imagina/ias gives the builds of an app.json that has none: the server of
+ * ias.json and the application. Not IAS_SERVER: the plugin never reads it, so the builds do not ask there.
+ */
+export const pluginManifestUrl = (config) => `${(config.server ?? DEFAULT_SERVER).replace(/\/+$/, '')}/api/v1/ota/${config.app}/manifest`;
+
+/** Whether the builds run the config plugin: app.json names it, or an app.config.* may add it (ias cannot read it). */
+function runsIasPlugin(dir, expo) {
+  if (DYNAMIC_CONFIGS.some((name) => existsSync(join(dir, name)))) return true;
+  return (Array.isArray(expo.plugins) ? expo.plugins : []).some((entry) => IAS_PLUGINS.includes(Array.isArray(entry) ? entry[0] : entry));
+}
+
+/** A JSON file, or an error that says which file and how to fix it. */
+export function readJson(path, name, fix) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new IasError(`${name} is not valid JSON (${error.message})`, { fix });
+  }
+}
+
+/** The expo object of the app's app.json, or undefined if there is no app.json. */
+export function readExpo(dir) {
+  const file = join(dir, 'app.json');
+  if (!existsSync(file)) return undefined;
+  const appJson = readJson(file, 'app.json', 'fix app.json: ias reads updates, the identifiers and the icon from it');
+  if (!appJson?.expo || typeof appJson.expo !== 'object') throw new IasError('app.json has no expo object', { fix: 'ias reads the configuration of the Expo app from app.json › expo' });
+  return appJson.expo;
+}
+
+/**
+ * The project in `dir`. With ias.json, its configuration, checked: no secret written in it and valid against the
+ * schema. Without it, `source` is legacy and the settings come from ota.config.json and dist.config.json, as in tools/.
+ */
+export function loadProject(dir) {
+  const file = join(dir, CONFIG_FILE);
+  if (!existsSync(file)) return { dir, source: 'legacy', file: undefined, config: undefined };
+  const config = readJson(file, CONFIG_FILE, 'fix it, or write it again with ias init --force');
+  const secrets = writtenSecrets(config);
+  if (secrets.length > 0) {
+    throw new IasError(`ias.json has a secret written in it (${secrets.join(', ')})`, {
+      fix: 'keep it in 1Password (an op:// reference) or in IAS_TOKEN, never in the repository; if it was committed, rotate it',
+      code: 'secret_in_config',
+    });
+  }
+  const errors = validate(config);
+  if (errors.length > 0) {
+    throw new IasError(`ias.json is not valid: ${errors[0]}${errors.length > 1 ? ` (and ${errors.length - 1} more)` : ''}`, {
+      fix: 'fix it as packages/cli/schema/ias.schema.json says, or check it with ias doctor',
+      code: 'config_invalid',
+      details: errors,
+    });
+  }
+  return { dir, source: CONFIG_FILE, file, config };
+}
+
+/** The project of an ias command for `service`: ias.json or, without it, the old file of the service. */
+export function projectFor(dir, service) {
+  const project = loadProject(dir);
+  if (project.source === 'legacy' && !existsSync(join(dir, LEGACY_FILES[service]))) {
+    throw new IasError(`no ias.json in ${dir}`, { fix: 'run ias init there (it reads app.json, eas.json, ota.config.json and dist.config.json), or pass --project <app folder>', code: 'config_missing' });
+  }
+  return project;
+}
+
+/** Whether the project has a configuration for `service` (updates or distribution): ias.json or its old file. */
+export function hasConfig(project, service) {
+  return project.source === CONFIG_FILE ? Boolean(project.config[service]) : existsSync(join(project.dir, LEGACY_FILES[service]));
+}
+
+/** The origin of IAS for everything but the OTA updates: IAS_SERVER, then ias.json › server, then ias.imagina.build. */
+export const serverOf = (project, env = process.env) => env.IAS_SERVER || project.config?.server || DEFAULT_SERVER;
+
+/**
+ * The personal token ias login kept for the server of the project (token-store.mjs), the last source of a publishing
+ * token: IAS_TOKEN and the token of ias.json win over it. Read only when a command needs a token and has no other.
+ */
+export function loggedInToken(project, env = process.env) {
+  const server = serverOf(project, env);
+  return URL.canParse(server) ? storedToken(new URL(server).origin, { env }) : undefined;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// OTA updates (ias update).
+
+/**
+ * What publishing needs: the update URL, certificate and keyid the builds carry, and where the key and token are, the
+ * environment file and the variables the bundle must carry. From ias.json, the key and the token are checked when a
+ * command needs them (check needs neither); from ota.config.json, all at once, as tools/expo-ota always did.
+ */
+export function updateSettings(project, env = process.env) {
+  return project.source === CONFIG_FILE ? iasUpdateSettings(project, env) : legacyUpdateSettings(project.dir, env);
+}
+
+/**
+ * The URL, certificate and keyid of app.json or, where it has none, what the config plugin of @imagina/ias writes into
+ * the builds from ias.json (packages/sdk/app.plugin.cjs), by the same rules: updates.url from the server and the
+ * application, the certificate and keyid of the default channel from updates.signing. A value of ias.json that
+ * contradicts app.json is an error, as in the plugin.
+ */
+function iasUpdateSettings({ dir, config }, env) {
+  const expo = readExpo(dir);
+  if (!expo) throw new IasError(`no app.json in ${dir}`, { fix: 'ias update reads updates.url and the certificate from the app.json of the app: run it from the app\'s folder or pass --project' });
+  const updates = expo.updates ?? {};
+  const signing = config.updates?.signing ?? {};
+  const fromPlugin = [];
+
+  if (updates.url === undefined) fromPlugin.push('updates.url');
+  const url = updates.url ?? pluginManifestUrl(config);
+  const manifestUrl = URL.canParse(url) ? new URL(url) : undefined;
+  if (!manifestUrl || !MANIFEST_PATH.test(manifestUrl.pathname)) {
+    throw new IasError(`updates.url in app.json (${updates.url}) is not the manifest of an IAS OTA project`, { fix: `it must be ${serverOf({ config }, env).replace(/\/$/, '')}/api/v1/ota/<project>/manifest, and changing it needs a new build; without it, the config plugin of @imagina/ias writes ${pluginManifestUrl(config)}` });
+  }
+
+  const appKeyid = updates.codeSigningMetadata?.keyid;
+  if (signing.keyId && appKeyid && signing.keyId !== appKeyid) {
+    throw new IasError(`updates.signing.keyId of ias.json (${signing.keyId}) is not the keyid of app.json (${appKeyid})`, { fix: 'the builds check the keyid of app.json: write the same one in ias.json' });
+  }
+  const keyid = appKeyid ?? signing.keyId;
+  if (!keyid) throw new IasError('there is no keyid for the certificate', { fix: 'set updates.signing.keyId in ias.json (or updates.codeSigningMetadata.keyid in app.json): the builds carry it, and the server only takes signed updates (docs/ota-code-signing.md)' });
+  if (!appKeyid) fromPlugin.push('updates.codeSigningMetadata.keyid');
+
+  const appCertificate = updates.codeSigningCertificate;
+  if (appCertificate && signing.certificate && resolve(dir, appCertificate) !== resolve(dir, signing.certificate)) {
+    throw new IasError(`updates.signing.certificate of ias.json (${signing.certificate}) is not updates.codeSigningCertificate of app.json (${appCertificate})`, { fix: 'the builds carry the one of app.json: write the same file in ias.json, or leave it only there' });
+  }
+  const certificatePath = appCertificate ?? signing.certificate;
+  if (!certificatePath) throw new IasError('there is no certificate for the default channel', { fix: 'set updates.signing.certificate in ias.json (or updates.codeSigningCertificate in app.json) to the public certificate the builds carry: the server only takes signed updates, and a new one needs a new build (docs/ota-code-signing.md)' });
+  if (!appCertificate) fromPlugin.push('updates.codeSigningCertificate');
+
+  if (fromPlugin.length > 0 && !runsIasPlugin(dir, expo)) {
+    throw new IasError(`app.json has no ${fromPlugin.join(', ')}, and its plugins do not have @imagina/ias, which writes ${fromPlugin.length === 1 ? 'it' : 'them'} into the builds from ias.json`, { fix: 'ias sdk install adds "@imagina/ias" to the plugins of app.json (packages/sdk/README.md §10), for a new build; or write them in app.json' });
+  }
+  const certificateFile = join(dir, certificatePath);
+  if (!existsSync(certificateFile)) throw new IasError(`no certificate at ${certificatePath} (${appCertificate ? 'updates.codeSigningCertificate of app.json' : 'updates.signing.certificate of ias.json'})`, { fix: 'it is the public certificate the builds carry: restore it from git' });
+  const base = manifestUrl.href.replace(/\/manifest$/, '');
+  return {
+    source: CONFIG_FILE,
+    projectDir: dir,
+    manifestUrl: manifestUrl.href,
+    base,
+    project: manifestUrl.pathname.match(MANIFEST_PATH)[1],
+    assetPath: `${new URL(base).pathname}/assets/`,
+    keyid,
+    certificate: new X509Certificate(readFileSync(certificateFile)),
+    signingSource: appCertificate ? 'app.json' : 'updates.signing of ias.json',
+    privateKey: env.IAS_UPDATES_PRIVATE_KEY || env.OTA_PRIVATE_KEY || signing.privateKey,
+    token: env.OTA_TOKEN || env.IAS_TOKEN || config.updates?.token,
+    loggedIn: () => loggedInToken({ config }, env),
+    envFile: config.updates?.envFile,
+    bundleEnv: config.updates?.bundleEnv ?? [],
+    needs: {
+      privateKey: new IasError('no private key', { fix: 'set updates.signing.privateKey in ias.json (an op:// reference) or IAS_UPDATES_PRIVATE_KEY' }),
+      token: new IasError('no publishing token', { fix: 'set updates.token in ias.json (an op:// reference) or IAS_TOKEN, or run ias login' }),
+    },
+    names: { config: CONFIG_FILE, envFile: 'updates.envFile of ias.json', bundleEnv: 'updates.bundleEnv of ias.json' },
+  };
+}
+
+/** tools/expo-ota's settings, word for word: from app.json and ota.config.json, overridden by OTA_PRIVATE_KEY and OTA_TOKEN. */
+function legacyUpdateSettings(projectDir, env) {
+  const { updates } = JSON.parse(readFileSync(join(projectDir, 'app.json'), 'utf8')).expo;
+  if (!updates?.codeSigningCertificate || !updates.codeSigningMetadata?.keyid) {
+    throw new Error('app.json has no updates.codeSigningCertificate and codeSigningMetadata.keyid: the server only takes signed updates');
+  }
+  const manifestUrl = new URL(updates.url ?? '');
+  if (!MANIFEST_PATH.test(manifestUrl.pathname)) throw new Error(`updates.url (${updates.url}) is not a sync-service OTA manifest URL`);
+  const certificate = new X509Certificate(readFileSync(join(projectDir, updates.codeSigningCertificate)));
+  const configFile = join(projectDir, LEGACY_FILES.updates);
+  const config = existsSync(configFile) ? JSON.parse(readFileSync(configFile, 'utf8')) : {};
+  const privateKey = env.OTA_PRIVATE_KEY || config.privateKey;
+  const token = env.OTA_TOKEN || env.IAS_TOKEN || config.token;
+  if (!privateKey) throw new Error('no private key: set privateKey in ota.config.json (an op:// reference) or OTA_PRIVATE_KEY');
+  if (!token) throw new Error('no publishing token: set token in ota.config.json (an op:// reference) or OTA_TOKEN');
+  if (config.token && !config.token.startsWith('op://')) throw new Error('ota.config.json has the token itself: keep it in 1Password (an op:// reference) or in OTA_TOKEN, never in the repository');
+  const base = manifestUrl.href.replace(/\/manifest$/, '');
+  return {
+    source: 'legacy',
+    projectDir,
+    manifestUrl: manifestUrl.href,
+    base,
+    project: manifestUrl.pathname.match(MANIFEST_PATH)[1],
+    assetPath: `${new URL(base).pathname}/assets/`,
+    keyid: updates.codeSigningMetadata.keyid,
+    certificate,
+    privateKey,
+    token,
+    envFile: config.envFile,
+    bundleEnv: config.bundleEnv ?? [],
+    names: { config: LEGACY_FILES.updates, envFile: 'envFile of ota.config.json', bundleEnv: 'ota.config.json' },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Internal distribution (ias dist).
+
+/**
+ * Where to upload: the server, the project and the publishing token. From ias.json, the server is IAS_SERVER or its
+ * server and the project distribution.project or app; from dist.config.json, as tools/expo-dist always did.
+ */
+export function distSettings(project, env = process.env) {
+  return project.source === CONFIG_FILE ? iasDistSettings(project, env) : legacyDistSettings(project.dir, env);
+}
+
+/** Install pages need https: iOS only installs from https. localhost and *.test are for trying it locally. */
+const installable = (url) => url.protocol === 'https:' || ['localhost', '127.0.0.1'].includes(url.hostname) || url.hostname.endsWith('.test');
+
+function iasDistSettings({ dir, config }, env) {
+  if (!config.distribution) throw new IasError('ias.json has no distribution', { fix: 'add "distribution": { "token": "op://…" } with the token of php artisan dist:token (ias init writes it from dist.config.json)' });
+  const origin = env.DIST_SERVER || serverOf({ config }, env);
+  const server = URL.canParse(origin) ? new URL(origin) : undefined;
+  if (!server) throw new IasError(`the server (${origin}) is not a URL`, { fix: 'set server in ias.json or IAS_SERVER to the origin of IAS, such as https://ias.imagina.build' });
+  if (!installable(server)) throw new IasError(`the server (${server.href}) is not https`, { fix: 'iOS only installs from https: use an https server (or localhost or a .test domain to try it locally)' });
+  const code = config.distribution.project ?? config.app;
+  return {
+    source: CONFIG_FILE,
+    projectDir: dir,
+    base: `${server.origin}/api/v1/distribution/${code}`,
+    project: code,
+    token: env.DIST_TOKEN || env.IAS_TOKEN || config.distribution.token,
+    loggedIn: () => loggedInToken({ config }, env),
+    needs: { token: new IasError('no publishing token', { fix: 'set distribution.token in ias.json (an op:// reference) or IAS_TOKEN, or run ias login' }) },
+  };
+}
+
+/** tools/expo-dist's settings, word for word: dist.config.json, overridden by DIST_TOKEN and DIST_SERVER. */
+function legacyDistSettings(projectDir, env) {
+  const configFile = join(projectDir, LEGACY_FILES.distribution);
+  if (!existsSync(configFile)) throw new Error(`no dist.config.json in ${projectDir} (tools/expo-dist/README.md)`);
+  const config = JSON.parse(readFileSync(configFile, 'utf8'));
+  const server = new URL(env.DIST_SERVER || config.server || '');
+  if (!installable(server)) throw new Error(`server (${server.href}) must be https: iOS only installs from https`);
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(config.project ?? '')) throw new Error('dist.config.json needs project, the code of dist:project');
+  const token = env.DIST_TOKEN || env.IAS_TOKEN || config.token;
+  if (!token) throw new Error('no publishing token: set token in dist.config.json (an op:// reference) or DIST_TOKEN');
+  if (config.token && !config.token.startsWith('op://')) throw new Error('dist.config.json has the token itself: keep it in 1Password (an op:// reference) or in DIST_TOKEN, never in the repository');
+  return { source: 'legacy', projectDir, base: `${server.origin}/api/v1/distribution/${config.project}`, project: config.project, token };
+}

package/src/dist.mjs

@@ -0,0 +1,99 @@
+// What an internal build is, read from the file: an ad hoc IPA (unzip, plutil, security) or an APK (aapt2).
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { readJson } from './config.mjs';
+import { run, temporary } from './process.mjs';
+
+export const MAX_ICON_BYTES = 512 * 1024;
+
+/** The tools of macOS and the Android SDK print their own errors on stderr: only those, the last 20 lines. */
+const tool = (command, commandArgs, options) => run(command, commandArgs, { stdio: ['inherit', 'pipe', 'pipe'], tail: 'stderr', lines: 20, ...options });
+
+/** The fields of `aapt2 dump badging` the server needs. */
+export function parseBadging(output) {
+  const field = (pattern) => output.match(pattern)?.[1];
+  const badging = {
+    identifier: field(/^package: name='([^']+)'/m),
+    build_number: field(/versionCode='([^']+)'/),
+    version: field(/versionName='([^']+)'/),
+    name: field(/^application-label:'([^']*)'/m) ?? field(/^application: label='([^']*)'/m),
+  };
+  for (const [key, value] of Object.entries(badging)) if (!value) throw new Error(`aapt2 dump badging gave no ${key}`);
+  return badging;
+}
+
+/** The SHA-256 (hex) and size of a file, read as a stream. */
+export async function digest(path) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return { sha256: hash.digest('hex'), bytes: statSync(path).size };
+}
+
+/** Name, identifier, versions and the ad hoc profile of an IPA, with unzip, plutil and security cms. */
+export function readIpa(file) {
+  const dir = temporary();
+  tool('unzip', ['-q', '-o', file, 'Payload/*.app/Info.plist', 'Payload/*.app/embedded.mobileprovision', '-d', dir], { label: 'unzip the IPA' });
+  const [app] = readdirSync(join(dir, 'Payload')).filter((entry) => entry.endsWith('.app'));
+  if (!app) throw new Error('the IPA has no Payload/*.app');
+  const info = JSON.parse(tool('plutil', ['-convert', 'json', '-o', '-', join(dir, 'Payload', app, 'Info.plist')]));
+  const profileFile = join(dir, 'profile.plist');
+  const provision = join(dir, 'Payload', app, 'embedded.mobileprovision');
+  if (!existsSync(provision)) throw new Error('the IPA has no embedded.mobileprovision: it is not an ad hoc build (use the preview profile with distribution internal)');
+  tool('security', ['cms', '-D', '-i', provision, '-o', profileFile], { label: 'security cms (provisioning profile)' });
+  const extract = (key) => {
+    const result = spawnSync('plutil', ['-extract', key, 'raw', '-o', '-', profileFile], { encoding: 'utf8' });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+  };
+  if (extract('ProvisionsAllDevices') === 'true') throw new Error('this IPA is signed for enterprise distribution, not ad hoc');
+  const devices = extract('ProvisionedDevices');
+  if (devices === undefined) throw new Error('the profile lists no devices: this IPA is for the App Store, not ad hoc');
+  return {
+    platform: 'ios',
+    name: info.CFBundleDisplayName || info.CFBundleName,
+    identifier: info.CFBundleIdentifier,
+    version: info.CFBundleShortVersionString,
+    build_number: String(info.CFBundleVersion),
+    provisioned_devices: Number(devices),
+    profile_expires_at: extract('ExpirationDate'),
+  };
+}
+
+/** Where the Android SDK is: ANDROID_HOME, ANDROID_SDK_ROOT or the place Android Studio puts it on a Mac. */
+export const androidSdk = (env = process.env) => env.ANDROID_HOME || env.ANDROID_SDK_ROOT || join(homedir(), 'Library/Android/sdk');
+
+/** aapt2 of the newest build tools of the Android SDK, or undefined. */
+export function findAapt2(env = process.env) {
+  const tools = join(androidSdk(env), 'build-tools');
+  const versions = existsSync(tools) ? readdirSync(tools).sort((a, b) => a.localeCompare(b, undefined, { numeric: true })) : [];
+  return versions.map((version) => join(tools, version, 'aapt2')).filter((candidate) => existsSync(candidate)).pop();
+}
+
+/** aapt2 of the newest build tools of the Android SDK; throws with how to get it. */
+export function aapt2(env = process.env) {
+  const path = findAapt2(env);
+  if (!path) throw new Error(`no aapt2 in ${join(androidSdk(env), 'build-tools')}: install the Android SDK build tools or set ANDROID_HOME`);
+  return path;
+}
+
+export const readApk = (file) => ({ platform: 'android', ...parseBadging(tool(aapt2(), ['dump', 'badging', file], { label: 'aapt2 dump badging' })) });
+
+/** The app's icon from app.json, shrunk with sips to a PNG of at most 180 px, in base64; none if there is none. */
+export function icon(projectDir) {
+  const appJson = join(projectDir, 'app.json');
+  const source = existsSync(appJson) ? readJson(appJson, 'app.json', 'fix app.json').expo?.icon : undefined;
+  if (!source || !existsSync(join(projectDir, source))) return undefined;
+  const out = join(temporary(), 'icon.png');
+  tool('sips', ['-s', 'format', 'png', '-Z', '180', join(projectDir, source), '--out', out], { label: 'sips (icon)' });
+  const png = readFileSync(out);
+  return png.length <= MAX_ICON_BYTES ? png.toString('base64') : undefined;
+}
+
+/** The commit the app's folder is at, if it is a git repository. */
+export function gitCommit(projectDir) {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: projectDir, encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.trim() : undefined;
+}