@imagina-build/ias-cli 0.2.1 → 0.3.0

package/src/commands/vault/runners.mjs

@@ -74,9 +74,33 @@ export async function grant(context, client, item) {
   output.progress('');
   output.progress('Compare the vault kid with the one ias-runner register printed on that Mac. If they differ, stop: the server would');
   output.progress('get the team\'s credentials wrapped for a key of its own.');
-  await confirm(context, `Authorize «${runner.name}» to open the team's credentials?`);
 
   const inList = signed.runners.some((entry) => entry.kid === runner.kid);
+  if (context.values['dry-run']) {
+    const sealed = await sealedEnvelopes(client);
+    const wrap = [];
+    const already = [];
+    for (const entry of sealed) {
+      const { data } = await client.request('GET', `/credentials/${entry.id}/envelope`);
+      (recipientsOf(data.envelope ?? {}).includes(runner.kid) ? already : wrap).push(entry);
+    }
+    output.progress('');
+    output.progress(`runner list   ${inList ? `it already has it (serial ${signed.serial})` : `it would be signed as serial ${(signed.serial ?? 0) + 1} and uploaded`}`);
+    output.progress(`envelopes     it would wrap ${wrap.length} of ${sealed.length}; ${already.length} are open to it already`);
+    for (const entry of wrap) output.progress(`  wrap    ${entry.label}${entry.application ? ` (${entry.application})` : ' (the team)'}`);
+    output.progress('dry run: nothing was signed, nothing was uploaded and no envelope changed.');
+    return {
+      dry_run: true,
+      runner: { id: runner.id, name: runner.name, kid: runner.kid },
+      runner_list: { serial: inList ? signed.serial : (signed.serial ?? 0) + 1, changed: !inList },
+      wrapped: describe(wrap),
+      already: describe(already),
+      problems: [],
+    };
+  }
+
+  await confirm(context, `Authorize «${runner.name}» to open the team's credentials?`);
+
   const list = inList ? null : await uploadList(client, { serial: signed.serial, runners: [...signed.runners, { kid: runner.kid, publicKey: runner.publicKey }] }, signingKey, keys, output);
   output.progress(list ? `Signed the runner list ${list.serial} with «${runner.name}» and uploaded it.` : `«${runner.name}» is already in the runner list ${signed.serial}.`);
   const sealed = await sealedEnvelopes(client);
@@ -97,9 +121,31 @@ export async function revoke(context, client, item) {
     throw new IasError(`«${runner.name}» is not revoked on the server`, { fix: 'revoke it in the panel first (System › Runners), so the server stops giving it jobs and envelopes at once; then run ias vault revoke again', code: 'runner_not_revoked' });
   }
   showRunner(runner, output);
-  await confirm(context, `Remove ${runner.name ? `«${runner.name}»` : runner.kid} from the runner list and from every envelope?`);
 
   const inList = signed.runners.some((entry) => entry.kid === runner.kid);
+  if (context.values['dry-run']) {
+    const sealed = await sealedEnvelopes(client);
+    const remove = [];
+    for (const entry of sealed) {
+      const { data } = await client.request('GET', `/credentials/${entry.id}/envelope`);
+      if (recipientsOf(data.envelope ?? {}).includes(runner.kid)) remove.push(entry);
+    }
+    output.progress('');
+    output.progress(`runner list   ${inList ? `it would be signed again as serial ${(signed.serial ?? 0) + 1} without it and uploaded` : 'it does not have it'}`);
+    output.progress(`envelopes     it would remove its wrap from ${remove.length} of ${sealed.length}`);
+    for (const entry of remove) output.progress(`  remove  ${entry.label}${entry.application ? ` (${entry.application})` : ' (the team)'}`);
+    output.progress('dry run: nothing was signed, nothing was uploaded and no envelope changed.');
+    return {
+      dry_run: true,
+      runner: { id: runner.id, name: runner.name, kid: runner.kid },
+      runner_list: { serial: inList ? (signed.serial ?? 0) + 1 : signed.serial, changed: inList },
+      removed: describe(remove),
+      problems: [],
+    };
+  }
+
+  await confirm(context, `Remove ${runner.name ? `«${runner.name}»` : runner.kid} from the runner list and from every envelope?`);
+
   const list = inList ? await uploadList(client, { serial: signed.serial, runners: signed.runners.filter((entry) => entry.kid !== runner.kid).map(({ kid, publicKey }) => ({ kid, publicKey })) }, signingKey, keys, output) : null;
   output.progress(list ? `Signed the runner list ${list.serial} without it and uploaded it.` : 'It is not in the runner list the team signed.');
   const sealed = await sealedEnvelopes(client);

package/src/commands/webhooks/index.mjs

@@ -49,6 +49,14 @@ async function create(context) {
   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);
+  if (values['dry-run']) {
+    output.progress(`dry run: would make a webhook of ${code} to ${url}`);
+    output.progress(`  events        ${events.join(', ')}`);
+    if (values.description) output.progress(`  description   ${values.description}`);
+    output.progress('  the server would answer with the secret that signs it, shown once (IAS-Signature, HMAC-SHA256)');
+    output.progress('nothing was created and no secret was shown.');
+    return { dry_run: true, app: code, url, events, description: values.description ?? null, created: false, secret: null };
+  }
   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}`);
@@ -58,12 +66,17 @@ async function create(context) {
 }
 
 async function remove(context) {
-  const { positionals, output } = context;
+  const { values, 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() };
+  const id = positionals[0].toLowerCase();
+  if (values['dry-run']) {
+    output.progress(`dry run: would delete the webhook ${id} of ${code}, with its deliveries; nothing was deleted`);
+    return { dry_run: true, id, deleted: false };
+  }
+  await connect(context, project).request('DELETE', `/apps/${code}/webhooks/${id}`);
+  output.log(`Deleted the webhook ${id} of ${code}, with its deliveries.`);
+  return { deleted: id };
 }
 
 async function test(context) {
@@ -95,10 +108,11 @@ export default {
         ...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).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would create, without creating it or showing a secret.' },
       },
       run: create,
     },
-    { name: 'delete', summary: 'Delete a webhook and its deliveries', positionals: [webhookId], options: common, run: remove },
+    { name: 'delete', summary: 'Delete a webhook and its deliveries', positionals: [webhookId], options: { ...common, 'dry-run': { type: 'boolean', description: 'Say what it would delete, and delete nothing.' } }, run: remove },
     { name: 'test', summary: 'Send a test event now and say how the server answered', positionals: [webhookId], options: common, run: test },
   ],
 };

package/src/config.mjs

@@ -1,7 +1,7 @@
 // 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 { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import process from 'node:process';
 import { IasError } from './errors.mjs';
@@ -91,6 +91,21 @@ export function hasConfig(project, service) {
   return project.source === CONFIG_FILE ? Boolean(project.config[service]) : existsSync(join(project.dir, LEGACY_FILES[service]));
 }
 
+/**
+ * Writes `config` to the app's ias.json, keeping its indentation. It validates it first and refuses a secret written
+ * in it, as init does. `dryRun` says what it would write and writes nothing.
+ */
+export function saveProjectConfig(dir, config, { dryRun = false } = {}) {
+  const secrets = writtenSecrets(config);
+  const errors = validate(config);
+  if (secrets.length > 0 || errors.length > 0) throw new IasError(`the ias.json for ${dir} is not valid (${[...secrets, ...errors].join('; ')})`, { fix: 'this is a bug of ias: report it with what you ran' });
+  const file = join(dir, CONFIG_FILE);
+  const previous = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const indent = previous.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
+  if (!dryRun) writeFileSync(file, `${JSON.stringify(config, null, indent)}\n`);
+  return file;
+}
+
 /** 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;
 

package/src/errors.mjs

@@ -30,7 +30,10 @@ export class ApiError extends Error {
     this.status = status;
     this.code = code;
     this.data = data;
-    this.hint = hintFor(status, code, data);
+    /** The fix the server wrote for this answer, when it has one. */
+    this.fix = typeof data?.fix === 'string' ? data.fix : undefined;
+    /** How to fix it: the server's own fix wins over the static hints, which cannot know the track or the id. */
+    this.hint = this.fix ?? hintFor(status, code, data);
   }
 }
 
@@ -38,7 +41,8 @@ export class ApiError extends Error {
 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',
+  project_not_found: 'there is no OTA project with this code: check updates.url in app.json, or create it with ias update init (an owner with a personal token)',
+  project_exists: 'the application already has an OTA project with another certificate: rotating it needs a new build (php artisan ota:project --force), so keep the key the builds carry or make a new build',
   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',
@@ -60,9 +64,13 @@ export const HINTS = {
   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',
+  scope_missing: 'the token lacks that scope: ias tokens create --scopes <list> chooses them for a robot token (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',
+  application_exists: 'the code already exists and cannot change: use that application, or choose another code',
+  service_in_use: 'a service still has its pieces (an OTA project, builds…): remove them before turning it off',
+  push_not_enabled: 'push is not on for the application: ias apps <code> --services … with push, or ias setup',
+  install_key_missing: 'push has no install key yet: ias setup next makes it, or POST /apps/{code}/push/install-key',
   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',
@@ -83,6 +91,32 @@ export const HINTS = {
   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',
+  release_policy_required: 'an owner creates the policy of the track: ias releases policy <track> --mode staged --max-percent 50 --step 20, or the panel (application › Ajustes › Google Play); without it a track only takes drafts',
+  release_not_allowed: 'the policy of the track does not allow it: ias releases policy <track> --mode staged (or full)',
+  release_percent_above_cap: 'the ceiling of the policy is lower than that percentage: ias releases policy <track> --max-percent <n>',
+  release_step_too_big: 'one change raises the rollout at most by the step of the policy: ias rollout <track> --percent <n> in smaller steps',
+  release_too_soon: 'the policy waits a minimum between changes: ias releases view <track> shows when, and ias releases policy <track> --min-minutes <n> changes it',
+  release_percent_invalid: 'a rollout serves a whole percentage from 1 to 99; 100 is --complete or ias submit --release-status completed',
+  release_state_changed: 'Play is not what you expected: ias releases view <track> --refresh reads it again',
+  release_in_flight: 'a submission or a release of that track has not ended: ias builds list shows it; wait for it or cancel it',
+  release_in_review: 'there is a review in progress: wait for it, or cancel it in Play Console',
+  release_not_found: 'send a store Android build to that track first: ias submit <build> --track <track>; ias releases view <track> --refresh reads what Play has',
+  release_not_published: 'Play does not stage the first release of an app: complete it in Play Console, or read the state if the app published before IAS (ias releases view <track> --refresh)',
+  release_halt_unavailable: 'Play only pauses a completed release when another completed release remains: check the releases of the track in Play Console',
+  release_managed_publishing: 'Play retains the change until someone publishes it: publish in Play Console; IAS does not simulate a publication',
+  testflight_not_ready: 'TestFlight needs a store iOS build that succeeded whose ias submit reached App Store Connect: ias submit <build> --wait sends it first',
+  testflight_in_progress: 'the build has a TestFlight job of that action that has not ended: ias testflight status <build> shows it; wait for it or cancel it',
+  testflight_already_reviewed: 'the build is already in Beta App Review: ias testflight status <build> shows the state; a rejected build needs a new submission, not another review',
+  testflight_plan_invalid: 'the plan has a group, a locale or a note App Store Connect does not take: ias testflight <build> --help lists the limits (20 groups, 8 locales of its list, 4000 characters)',
+  testflight_groups_missing: 'no group was given and ias.json has none: pass the name of a group that exists in App Store Connect › TestFlight with --groups "<name>"; IAS does not create groups',
+  testflight_group_unknown: 'a group of the plan does not exist in App Store Connect: ias testflight status <build> lists the ones the app has; add the build to one of them',
+  testflight_group_ambiguous: 'App Store Connect has more than one group with that name: rename one there, or choose another',
+  testflight_info_missing: 'Beta App Review needs the app test information first (beta app description, feedback email, contact, demo account if it needs a login): complete it in App Store Connect › TestFlight',
+  testflight_export_compliance: 'Apple has not been told whether the build uses encryption, so it does not distribute it: answer export compliance in App Store Connect › TestFlight',
+  asc_forbidden: 'the App Store Connect key cannot do this: distributing to external groups and the test information need App Manager or Admin (an Individual Key does not work)',
+  asc_unauthorized: 'App Store Connect did not take the key: it was revoked or its JWT was refused; import a current asc_api_key with ias credentials import asc_api_key',
+  asc_rate_limited: 'App Store Connect is rate-limiting the key: wait a few minutes and run it again',
+  asc_unavailable: 'App Store Connect did not answer: run it again in a minute',
   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',
@@ -90,12 +124,24 @@ export const HINTS = {
   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)',
+  credentials_missing: 'the vault has no usable credential of those types for this build: for iOS, ias credentials generate ios makes or reuses the certificate and the App Store profile; otherwise import them with ias credentials import, and check that they are not retired or expired (ias credentials list)',
+  asc_app_missing: 'App Store Connect has no app record for the bundle id: a person creates it in appstoreconnect.apple.com › Apps; then ias apps store <code> --check saves its Apple ID. The public API cannot create it',
+  asc_app_mismatch: 'the Apple ID saved in IAS is from another app: ias apps store <code> --check reads the right one for the bundle id',
+  asc_unreachable: 'App Store Connect did not answer the check: the submission can be run again when the connection is back',
+  play_app_missing: 'Google Play has no app with that package: a person creates it in play.google.com/console and completes its setup; the API cannot create it',
+  bundle_id_taken: 'Apple already has that bundle id in this team or another: use the existing App ID, or choose another bundle id',
+  bundle_id_not_in_apple: 'Apple has no App ID with that bundle id: ias apps store <code> --register-bundle-id registers it in this team',
+  asc_key_forbidden: 'the App Store Connect key cannot touch identifiers: a team key with the Admin or App Manager role is needed (an Individual Key does not work)',
   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',
+  policy_invalid: 'the server did not take the policy: nothing was stored; ias policy check <file> says which rule or field fails (the checks are in docs/technical/vault.md §2.5)',
+  policy_version_backwards: 'someone stored a newer policy meanwhile: raise the version in ias.policy.json (ias policy init --version <n>) and sign it again with ias policy sign',
+  policy_unmatched: 'no rule of the team\'s policy covers this job, so it is denied: ias policy simulate --app <code> --platform <ios|android> --profile <name> --type <build|submit> [--track <track>] says which rule is missing; add it to ias.policy.json and sign it with ias policy sign',
+  policy_missing: 'the team has no usable policy (it expired or was never signed), so nothing new is approved: ias policy status says what is missing; ias policy init and ias policy sign make a valid one',
+  policy_changed: 'the policy changed while the job waited, so the job expired: run the command again; ias policy show says what the policy is now',
   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)',
+  registration_code_invalid: 'the code expired (30 minutes), was used or does not exist: an owner makes another with ias runners code, or 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)',
@@ -140,7 +186,7 @@ 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 === 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 ias dist init (an owner with a personal token)';
   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;

package/src/op.mjs

@@ -0,0 +1,83 @@
+// 1Password CLI for the provisioning commands: create a secure note with fields (a private key, a token) through stdin,
+// read a field, and add a field to an item that already exists. Nothing here prints a secret: the values travel through
+// stdin or are kept in memory, never as an argument of a process (ps would see them).
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { IasError } from './errors.mjs';
+
+const ITEM = /^op:\/\/([^/\s]+)\/([^/]+)$/;
+
+/** The vault and title of an op:// reference, or an error. */
+export function itemOf(reference) {
+  const match = ITEM.exec(reference);
+  if (!match) throw new IasError(`«${reference}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://Private/My app OTA' });
+  return { reference, vault: match[1], title: match[2] };
+}
+
+const reason = (result) => (result.error ? result.error.message : (result.stderr || '').trim().split('\n').at(-1) || `exit ${result.status}`);
+
+const op = (args, { env, input } = {}) => {
+  const [command, commandArgs] = input === undefined ? ['op', args] : ['/bin/sh', ['-c', 'cat | op "$@"', 'sh', ...args]];
+  return spawnSync(command, commandArgs, { encoding: 'utf8', env, input, maxBuffer: 8 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+};
+
+/** A field of an item, or undefined when it or the item is not there. Throws if op cannot answer for another reason. */
+export function readField(reference, field, env = process.env) {
+  const result = op(['read', '--no-newline', `${reference}/${field}`], { env });
+  if (result.status === 0) return result.stdout;
+  const text = reason(result);
+  if (/isn't an item|isn.t a field|not found|no item|could not find|does not have a field/i.test(text)) return undefined;
+  throw new IasError(`op could not read ${reference}/${field}: ${text}`, { fix: result.error ? 'install the 1Password CLI (brew install 1password-cli) and turn on its integration with the desktop app' : 'unlock 1Password (op signin) and check that the item and its vault exist' });
+}
+
+/** The item as JSON, or undefined when it does not exist. It holds secrets: never print it. */
+export function openItem(reference, env = process.env) {
+  const result = op(['item', 'get', reference, '--format', 'json'], { env });
+  if (result.status === 0) return JSON.parse(result.stdout);
+  const text = reason(result);
+  if (/isn't an item|not found|no item|could not find/i.test(text)) return undefined;
+  throw new IasError(`op could not read ${reference}: ${text}`, { fix: 'unlock 1Password (op signin) and check that the item and its vault exist' });
+}
+
+/**
+ * Creates a secure note with `fields` ([{ label, value, type }]) and `attachments` ([{ label, path }]) through stdin.
+ * The field template never touches the disk nor the arguments; an attachment only passes its path, never its bytes.
+ * `reference` is the op:// item the fields will be read from.
+ */
+export function createItem(reference, { notes, fields, attachments = [] }, env = process.env) {
+  const item = itemOf(reference);
+  const template = {
+    title: item.title,
+    category: 'SECURE_NOTE',
+    fields: [
+      { id: 'notesPlain', type: 'STRING', purpose: 'NOTES', label: 'notesPlain', value: notes ?? '' },
+      ...fields.map(({ label, value, type = 'STRING' }) => ({ id: label, label, type, value })),
+    ],
+  };
+  const args = ['item', 'create', '--vault', item.vault, '--format', 'json', '-', ...attachments.map(({ label, path }) => `${label}[file]=${path}`)];
+  const result = op(args, { env, input: JSON.stringify(template) });
+  if (result.status !== 0) throw new IasError(`op could not create ${reference}: ${reason(result)}`, { fix: 'unlock 1Password (op signin) and check that the vault exists and you can write to it' });
+}
+
+/** Adds or replaces a file attachment of an item that exists; the path is an argument, never the bytes. */
+export function setAttachment(reference, label, path, env = process.env) {
+  const result = op(['item', 'edit', reference, '--format', 'json', `${label}[file]=${path}`], { env });
+  if (result.status !== 0) throw new IasError(`op could not attach ${label} to ${reference}: ${reason(result)}`, { fix: 'unlock 1Password (op signin) and try again' });
+}
+
+/** Adds or replaces a field of an item that exists, through a JSON template on stdin. */
+export function setField(reference, field, value, env = process.env) {
+  const item = openItem(reference, env);
+  if (!item) throw new IasError(`there is no 1Password item ${reference}`, { fix: 'create it again, or write the reference in ias.json by hand' });
+  const fields = Array.isArray(item.fields) ? item.fields : [];
+  const existing = fields.find((candidate) => candidate.label === field || candidate.id === field);
+  if (existing) {
+    existing.value = value;
+    existing.type = existing.type ?? 'CONCEALED';
+  } else {
+    fields.push({ id: field, label: field, type: 'CONCEALED', value });
+  }
+  item.fields = fields;
+  const result = op(['item', 'edit', reference, '--format', 'json'], { env, input: JSON.stringify(item) });
+  if (result.status !== 0) throw new IasError(`op could not edit ${reference}: ${reason(result)}`, { fix: 'unlock 1Password (op signin) and try again' });
+}

package/src/ota-key.mjs

@@ -0,0 +1,53 @@
+// The signing key of an OTA channel, made on the Mac: an RSA key and a self-signed certificate the builds carry. The
+// private key only lives in memory and in the temporary folder of the run (mode 700) until it is written to 1Password;
+// the certificate goes to the repository as a public file. `ias update init` and `ias setup` use it.
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { X509Certificate, createPrivateKey } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { IasError } from './errors.mjs';
+import { temporary } from './process.mjs';
+
+const DAYS = 3650;
+
+/** The certificate at `path`, checked: RSA, in date. */
+export function readCertificate(path) {
+  if (!existsSync(path)) throw new IasError(`no certificate at ${path}`, { fix: 'restore it from git, or run ias update init to make a new key' });
+  const certificate = new X509Certificate(readFileSync(path));
+  if (certificate.publicKey.asymmetricKeyType !== 'rsa') throw new IasError(`the certificate at ${path} is not RSA`, { fix: 'expo-updates signs with RSA-SHA256: make a new key with ias update init' });
+  return certificate;
+}
+
+/**
+ * A new RSA key and self-signed certificate for `app`, written to `certificatePath` (438 days? no: 10 years). Returns
+ * the PEM of both; the private key is also in the temporary folder of the run, which is removed at the end.
+ */
+export function generateKeyPair({ dir, app, certificatePath = 'certs/ota-certificate.pem', dryRun = false, output }) {
+  const folder = temporary('ias-ota-key-');
+  const keyFile = join(folder, 'private-key.pem');
+  const certFile = join(folder, 'certificate.pem');
+  const target = join(dir, certificatePath);
+
+  if (dryRun) {
+    output?.progress(`${output.prefix}: would make an RSA key and a certificate at ${certificatePath}`);
+    return { privateKey: null, certificate: null, certificatePath, target, keyId: `${app}-ota-1` };
+  }
+
+  const result = spawnSync('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-days', String(DAYS), '-subj', `/CN=${app} OTA`, '-keyout', keyFile, '-out', certFile], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.error) throw new IasError('openssl is not here', { fix: 'it comes with macOS and with OpenSSL on Linux: install it, or make the key and certificate by hand (docs/guide/actualizaciones.md)' });
+  if (result.status !== 0) throw new IasError(`openssl could not make the key: ${(result.stderr || '').trim().split('\n').at(-1)}`, { fix: 'check that openssl works, or make the key and certificate by hand' });
+
+  chmodSync(keyFile, 0o600);
+  const privateKey = readFileSync(keyFile, 'utf8');
+  const certificate = readFileSync(certFile, 'utf8');
+  const parsed = new X509Certificate(certificate);
+
+  if (parsed.publicKey.asymmetricKeyType !== 'rsa' || !parsed.checkPrivateKey(createPrivateKey(privateKey))) {
+    throw new IasError('openssl made a key and certificate that do not match', { fix: 'run ias update init again' });
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, certificate);
+  output?.progress(`${output.prefix}: wrote ${certificatePath} (public; the private key goes to 1Password)`);
+  return { privateKey, certificate, certificatePath, target, keyId: `${app}-ota-1`, validTo: parsed.validTo };
+}