@imagina-build/ias-cli 0.2.2 → 0.3.0

package/src/commands/credentials/generate.mjs

@@ -0,0 +1,122 @@
+// ias credentials generate android_upload_keystore: a new upload key for Google Play, made on this Mac with keytool.
+// The passwords are random and never touch the command line; the keystore and the passwords go to one 1Password item
+// (the keystore as a file attachment), and then the existing `ias credentials import` seals the same material in the
+// vault. The item stays for recovery; the temporary file is removed at the end of the run.
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, rmSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { createItem, readField, setAttachment, setField } from '../../op.mjs';
+import { temporary } from '../../process.mjs';
+
+const BIN = fileURLToPath(new URL('../../../../bin/ias.mjs', import.meta.url));
+const ALIAS = /^[A-Za-z0-9._-]{1,100}$/;
+
+const password = () => randomBytes(24).toString('base64url');
+
+/** The app folder and code, with a clear error when there is no ias.json. */
+function projectOf(dir) {
+  const project = loadProject(dir);
+  if (!project.config?.app) throw new IasError(`no valid ias.json in ${dir}`, { fix: 'run ias init there first' });
+  return { project, app: project.config.app };
+}
+
+/**
+ * Makes the upload keystore, keeps it and its passwords in 1Password, and imports it into the vault through the same
+ * path as `ias credentials import`. `dryRun` does nothing. `force` replaces an existing item only if it says so.
+ */
+export async function generateAndroidKeystore({ dir, env = process.env, output, values = {} }) {
+  const { app } = projectOf(dir);
+  const alias = values.alias ?? 'upload';
+  const item = values.item ?? `op://IAS/${app} Android upload`;
+  const dryRun = values['dry-run'] === true;
+
+  if (!ALIAS.test(alias)) throw new IasError(`«${alias}» is not a valid alias`, { fix: 'letters, digits, dots, hyphens and underscores, up to 100' });
+  if (!/^op:\/\/[^/\s]+\/[^/]+$/.test(item)) throw new IasError(`«${item}» is not a 1Password item`, { fix: 'it is op://<vault>/<item>, such as op://IAS/jscheduler Android upload' });
+
+  if (dryRun) {
+    output.log(`${output.prefix}: would make a PKCS12 upload key «${alias}» for ${app}, keep it in ${item}, and seal it in the vault`);
+    return { app, alias, item, dry_run: true };
+  }
+
+  const existing = readField(item, 'store-password', env);
+  if (existing !== undefined && values.force !== true) {
+    throw new IasError(`${item} already has an upload key`, { fix: 'it is already the key of this app: use it (ias credentials list), or pass --force to replace it and make a new build' });
+  }
+
+  const folder = temporary('ias-keystore-');
+  const keystore = join(folder, 'upload.p12');
+  const storePassword = password();
+  const keyPassword = storePassword;
+  const keytool = spawnSync('keytool', [
+    '-genkeypair',
+    '-keystore', keystore,
+    '-storetype', 'PKCS12',
+    '-alias', alias,
+    '-keyalg', 'RSA',
+    '-keysize', '2048',
+    '-validity', '10000',
+    '-dname', `CN=${app} upload, O=Imagina, C=ES`,
+    '-storepass:env', 'IAS_KEYSTORE_PASSWORD',
+    '-keypass:env', 'IAS_KEYSTORE_PASSWORD',
+  ], { encoding: 'utf8', env: { ...env, IAS_KEYSTORE_PASSWORD: storePassword }, stdio: ['ignore', 'pipe', 'pipe'] });
+
+  if (keytool.error || keytool.status !== 0) {
+    const reason = keytool.error ? keytool.error.message : (keytool.stderr || '').trim().split('\n').at(-1);
+    throw new IasError(`keytool could not make the upload key: ${reason}`, { fix: 'keytool comes with a JDK: install one (for instance brew install openjdk) and try again' });
+  }
+  chmodSync(keystore, 0o600);
+  if (!existsSync(keystore)) throw new IasError('keytool did not write the keystore', { fix: 'check that keytool works, and try again' });
+
+  if (existing !== undefined) {
+    // --force: the item exists, so add/replace its fields and its attachment instead of creating it.
+    setField(item, 'store-password', storePassword, env);
+    setField(item, 'key-password', keyPassword, env);
+    setField(item, 'key-alias', alias, env);
+    setAttachment(item, 'keystore', keystore, env);
+    output.log(`${output.prefix}: replaced the upload key in ${item}`);
+  } else {
+    createItem(item, {
+      notes: `The upload key of ${app} for Google Play (PKCS12, alias ${alias}), made by ias credentials generate. The keystore is the attachment; the passwords are the concealed fields. It is sealed in the IAS vault too; this item is for recovery.`,
+      fields: [
+        { label: 'store-password', value: storePassword, type: 'CONCEALED' },
+        { label: 'key-password', value: keyPassword, type: 'CONCEALED' },
+        { label: 'key-alias', value: alias },
+        { label: 'application', value: app },
+      ],
+      attachments: [{ label: 'keystore', path: keystore }],
+    }, env);
+    output.log(`${output.prefix}: created ${item} with the keystore and its passwords`);
+  }
+
+  // The import is another ias: the password reaches it through stdin, never by an argument nor the environment.
+  const command = env.IAS_CLI_BIN ?? process.execPath;
+  const args = [...(env.IAS_CLI_BIN ? [] : [BIN]), 'credentials', 'import', 'android_upload_keystore', '--project', resolve(dir), '--keystore', keystore, '--store-password', '-', '--key-alias', alias, '--json'];
+  const child = spawnSync(command, args, {
+    cwd: dir,
+    env,
+    input: `${storePassword}\n`,
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  rmSync(keystore, { force: true });
+  if (child.error || child.status !== 0) {
+    const reason = child.error ? child.error.message : (child.stderr || '').trim().split('\n').slice(-3).join(' ');
+    throw new IasError(`the upload key is in ${item}, but sealing it in the vault failed: ${reason}`, { fix: `unlock 1Password and import it with ias credentials import android_upload_keystore --keystore ${item}/keystore --store-password ${item}/store-password --key-alias ${alias}` });
+  }
+
+  let sealed = null;
+  try {
+    sealed = JSON.parse(child.stdout || 'null');
+  } catch {
+    // The import answered text (it should not with --json): leave it as the child wrote it.
+  }
+  output.log(`${output.prefix}: upload key «${alias}» of ${app} sealed in the vault; the keystore and passwords are in ${item}`);
+  return { app, alias, item, sealed };
+}

package/src/commands/credentials/index.mjs

@@ -1,4 +1,4 @@
-// ias credentials import, list, show, rotate and retire (docs/technical/manage-api.md §8). import reads the material (files,
+// ias credentials generate, import, list, show, rotate and retire (docs/technical/manage-api.md §8). import reads the material (files,
 // op:// references or EAS's credentials.json), takes its metadata with @imagina-build/ias-shared/credentials, makes the id
 // (a UUID) and seals it in ias-vault-2 on this computer: for the recovery key and the runners of the list the team
 // signed, both checked against 1Password, and signed with the team's key. The server gets the envelope and the
@@ -8,49 +8,17 @@ import { resolve } from 'node:path';
 import { loadProject } from '../../config.mjs';
 import { ApiError, IasError } from '../../errors.mjs';
 import { applicationOf, connect } from '../../manage.mjs';
-import { PLAINTEXT_TYPES, credentials as inspect, digest, encodePlaintext, seal, verifyEnvelope } from '../../shared.mjs';
+import { PLAINTEXT_TYPES, credentials as inspect, digest, verifyEnvelope } from '../../shared.mjs';
 import { publicKeysOf, sealingKeys, vaultItem } from '../../team-vault.mjs';
+import { generateAndroidKeystore } from './generate.mjs';
+import { approvalLines, approveCertificateChange, generateDistributionCertificate, generateIos, generateProvisioningProfile, oldCertificate, revokeAppleCertificate } from './apple.mjs';
 import { MATERIAL_OPTIONS, defaultName, inferType, materialFromEas, materialFromOptions, sameMaterial } from './material.mjs';
+import { expiryWarning, metadataOf, ofTeam, plaintextOf, sealCredential } from './seal.mjs';
 
 const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
 const CREDENTIAL_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const ofTeam = (type) => PLAINTEXT_TYPES[type]?.scope === 'team';
 const DAY = 24 * 60 * 60 * 1000;
 
-/** The metadata of `material`, or an IasError that names the file or tool, never a secret. */
-function metadataOf(type, material) {
-  try {
-    return inspect.metadataOf(type, material.inspect);
-  } catch (error) {
-    if (error instanceof inspect.CredentialError) throw new IasError(`${type}: ${error.message}`, { fix: 'check the file and its password or alias', code: 'credential_unreadable' });
-    throw error;
-  }
-}
-
-/** The plaintext to seal: the fields of the material, those that only the metadata knows, and the application. */
-function plaintextOf(type, material, metadata, application) {
-  return encodePlaintext(type, { ...(ofTeam(type) ? {} : { application }), ...material.fields, ...(material.completes?.(metadata) ?? {}) });
-}
-
-/** Seals `plaintext` as version `version` of credential `id`, and checks the signature it just made. */
-function sealCredential(plaintext, { id, type, version }, sealing) {
-  try {
-    const envelope = seal(plaintext, { credential: { id, type, version }, recipients: sealing.recipients, signingKey: sealing.signingKey });
-    verifyEnvelope(envelope, sealing.keys.signing.publicKey);
-    return envelope;
-  } finally {
-    plaintext.fill(0);
-  }
-}
-
-/** Warnings about an expiry within 30 days. */
-function expiryWarning(name, metadata, output, now = Date.now()) {
-  if (!metadata?.expires) return;
-  const days = Math.floor((Date.parse(metadata.expires) - now) / DAY);
-  if (days < 0) output.warn(`${name} expired on ${metadata.expires}`);
-  else if (days <= 30) output.warn(`${name} expires in ${days} days (${metadata.expires})`);
-}
-
 /** The credentials the token can see: those of the application (if any) and the team's (with a personal token). */
 async function visibleCredentials(client, application) {
   const found = [];
@@ -70,6 +38,26 @@ async function findCredential(client, id, application) {
   return credential;
 }
 
+/**
+ * One credential by its id or, when only one is named that way, by its name. Two with the same name are never picked
+ * silently: it lists them and asks for the id.
+ */
+async function credentialNamed(client, wanted, application) {
+  const found = await visibleCredentials(client, application);
+  const byId = found.find((candidate) => candidate.id === wanted);
+  if (byId) return byId;
+  const byName = found.filter((candidate) => candidate.name === wanted);
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    throw new IasError(`«${wanted}» names ${byName.length} credentials`, {
+      fix: `pass the id of one: ${byName.map((candidate) => `${candidate.id} (${candidate.type}, ${candidate.application ?? 'the team'})`).join(', ')}`,
+      code: 'credential_ambiguous',
+      details: { candidates: byName.map((candidate) => ({ id: candidate.id, type: candidate.type, application: candidate.application ?? null })) },
+    });
+  }
+  throw new IasError(`there is no credential «${wanted}»${application ? ` in ${application} or the team` : ' in the team'}`, { fix: 'ias credentials list shows them; pass --app for one of another application', code: 'credential_not_found' });
+}
+
 const optionalApplication = (context, project) => (context.values.app || project?.config?.app ? applicationOf(context, project) : undefined);
 
 async function importCredentials(context) {
@@ -185,30 +173,93 @@ async function rotate(context) {
     output.log(`dry run: version ${version} of «${credential.name}» sealed, digest ${digest(envelope)}; nothing sent`);
     return { dry_run: true, id: credential.id, version, metadata, digest: digest(envelope) };
   }
-  const { data } = await client.request('PUT', `/credentials/${credential.id}`, { json: { ...(values.name ? { name: values.name } : {}), metadata, envelope } });
+  // A new SHA-1 of the team's distribution certificate changes what every build signs with: an owner authorizes it
+  // first, and the server takes the new material only with that approval (docs/plans/gaps/01-certificado-ios.md §3.6).
+  let approval = null;
+  if (type === 'apple_distribution_certificate' && String(credential.metadata?.sha1 ?? '').toUpperCase() !== String(metadata.sha1 ?? '').toUpperCase()) {
+    const team = String(values['team-id'] ?? metadata.team ?? credential.metadata?.team ?? '').trim().toUpperCase();
+    if (!/^[A-Z0-9]{10}$/.test(team)) throw new IasError(`the new certificate has no Apple team`, { fix: 'the .p12 names its team in the OU: check it with openssl, or pass --team-id <id>', code: 'team_missing' });
+    const old = oldCertificate(credential.metadata);
+    approval = await approveCertificateChange(context, client, {
+      action: 'replace',
+      credential: credential.id,
+      team,
+      old,
+      new: { sha1: String(metadata.sha1).toUpperCase() },
+      revoke_before_create: false,
+      applications: [],
+    }, approvalLines({ what: 'replace the distribution certificate with an imported .p12', old, team, material: `SHA-1 importado ${String(metadata.sha1).toUpperCase()}`, applications: [] }));
+  }
+  const { data } = await client.request('PUT', `/credentials/${credential.id}`, { json: { ...(values.name ? { name: values.name } : {}), metadata, envelope, ...(approval ? { approval } : {}) } });
   output.log(`replaced «${data.name}» (${data.id}): version ${data.version}${data.expires_at ? `, until ${data.expires_at}` : ''}`);
   expiryWarning(`«${data.name}»`, metadata, output);
   return data;
 }
 
 async function retire(context) {
-  const { data } = await connect(context, projectOf(context)).request('POST', `/credentials/${context.positionals[0]}/retire`);
-  context.output.log(`retired «${data.name}» (${data.id}) on ${data.retired_at}: it is no longer used and stays in the inventory`);
+  const { values, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const credential = await credentialNamed(client, context.positionals[0], optionalApplication(context, project));
+  if (values['dry-run']) {
+    output.progress(`dry run: would retire «${credential.name}» (${credential.id}, ${credential.type}) on ${client.server}: it would stop being used and stay in the inventory`);
+    return { dry_run: true, id: credential.id, name: credential.name, type: credential.type, version: credential.version, retired: false };
+  }
+  const { data } = await client.request('POST', `/credentials/${credential.id}/retire`);
+  output.log(`retired «${data.name}» (${data.id}) on ${data.retired_at}: it is no longer used and stays in the inventory`);
   return data;
 }
 
 const credentialId = { name: 'id', description: 'The id of the credential, from ias credentials list.', pattern: CREDENTIAL_ID };
+const credentialNamedArgument = { name: 'credential', description: 'The id of the credential (ias credentials list), or its name when only one has it.', pattern: /^[^«»]+$/ };
 const common = {
   app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
 };
-const item = { item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://Private/IAS vault <host>).' } };
+const item = { item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://IAS/IAS vault <host>).' } };
 const types = Object.keys(PLAINTEXT_TYPES).filter((type) => type !== 'environment_variable');
 
 export default {
   name: 'credentials',
-  summary: 'The signing credentials in the sealed vault: import, list, show, replace and retire',
+  summary: 'The signing credentials in the sealed vault: generate, import, list, show, rotate, retire and revoke',
   description: `Credentials are sealed on this computer (ias-vault-2, docs/technical/vault.md) for the team's recovery key and the authorised runners, and signed by the team; the keys come from the 1Password item of ias vault init. Types: ${types.join(', ')}.`,
   subcommands: [
+    {
+      name: 'generate',
+      summary: 'Make signing material on this Mac: the Android upload key, the iOS certificate and the App Store profile',
+      description: [
+        'ias credentials generate ios (the short path): reuses the team\'s distribution certificate and the App Store profile of the bundle id when they are valid, and makes what is missing — the RSA-2048 key, the CSR and the .p12 here, the certificate and the profile in App Store Connect — sealing them in the vault and keeping a recovery copy in 1Password. It never revokes anything and never picks among several certificates without --certificate. --rotate replaces the certificate with an owner\'s passkey approval and keeps the credential id; --no-profiles leaves the App Store profile for later.',
+        'The granular forms: android_upload_keystore makes a PKCS12 upload key with keytool; apple_distribution_certificate makes only the certificate; apple_provisioning_profile makes only the profile (app-store, or ad-hoc through ias devices sync). With several App Store profiles of the bundle id it never picks one: --profile names it. --sync-capabilities enables in the App ID what app.json › expo › ios › entitlements asks for (and Apple invalidates every profile of the App ID, the ad hoc one too). --delete-previous removes in Apple the App Store profile the new one replaces, after it is sealed and uploaded, and only with the flag.',
+        'Nothing prints a password. It needs openssl (macOS has it), a JDK for the keystore, a Team API key of App Store Connect with the Admin role (or App Manager with Certificates) and an owner of the team for the vault.',
+      ].join('\n'),
+      positionals: [{ name: 'type', description: 'ios, apple_distribution_certificate, apple_provisioning_profile or android_upload_keystore.', pattern: /^(ios|apple_distribution_certificate|apple_provisioning_profile|android_upload_keystore)$/ }],
+      options: {
+        ...common,
+        alias: { type: 'string', value: '<alias>', description: 'android_upload_keystore: the key alias in the keystore (upload by default).' },
+        item: { type: 'string', value: 'op://vault/item', description: 'The 1Password item for the material: the keystore, or the certificate (.p12) and its password. Defaults to op://IAS/<app> Android upload or op://IAS/<team> Apple Distribution <serial>.' },
+        name: { type: 'string', value: '"…"', description: 'The team name written in the CSR subject (the app name by default).' },
+        force: { type: 'boolean', description: 'Replace the key and the item if they already exist; the old key stops working in a new upload.' },
+        reuse: { type: 'boolean', description: 'Reuse the current distribution certificate, even when it expires within --if-expiring days.' },
+        rotate: { type: 'boolean', description: 'Make a new distribution certificate even when the current one is valid (Apple\'s limit may refuse it; nothing is revoked automatically).' },
+        certificate: { type: 'string', value: '<sha1|id>', description: 'Which distribution certificate of the team to use, when there are several (its SHA-1, its credential id or Apple\'s id).' },
+        profile: { type: 'string', value: '<uuid|name>', description: 'apple_provisioning_profile and ios: which App Store profile of Apple to reuse, when there are several (its UUID or its exact name). Never guessed.' },
+        'sync-capabilities': { type: 'boolean', description: 'apple_provisioning_profile and ios: enable in the App ID the capabilities that app.json › expo › ios › entitlements asks for and Apple lacks, then make the profile again. Apple invalidates every profile of the App ID, the ad hoc one too: run ias devices sync --force after it.' },
+        'delete-previous': { type: 'boolean', description: 'apple_provisioning_profile and ios: after a new profile is sealed and uploaded, delete in Apple the App Store profile it replaces (only that one; never the ad hoc one, a dry run or another credential\'s). It asks first.' },
+        type: { type: 'string', value: 'app-store|ad-hoc', description: 'apple_provisioning_profile and ios: app-store (the default) or ad-hoc (which runs ias devices sync).' },
+        'bundle-id': { type: 'string', value: '<id>', description: 'The bundle id of the profile (the app\'s by default).' },
+        'team-id': { type: 'string', value: '<id>', description: 'The Apple team (the app\'s, or the key\'s, by default).' },
+        'if-expiring': { type: 'string', value: '<days>', description: 'Renew the certificate only when it expires within these days (30 by default; 0 never renews).' },
+        'no-profiles': { type: 'boolean', description: 'ios: make or reuse the certificate and leave the App Store profile for later; a store build needs it, so ias credentials generate ios finishes it.' },
+        yes: { type: 'boolean', description: 'Do not ask before writing in Apple and the vault.' },
+        'dry-run': { type: 'boolean', description: 'Show the inventory and exactly what would be sealed, and make nothing.' },
+      },
+      run: (context) => {
+        const type = context.positionals[0];
+        if (type === 'android_upload_keystore') return generateAndroidKeystore({ dir: resolve(context.cwd, context.values.project ?? '.'), env: context.env, output: context.output, values: context.values });
+        if (type === 'ios') return generateIos(context);
+        if (type === 'apple_distribution_certificate') return generateDistributionCertificate(context);
+        return generateProvisioningProfile(context);
+      },
+    },
     {
       name: 'import',
       summary: 'Seal a credential and upload it, with its metadata',
@@ -241,7 +292,7 @@ export default {
     {
       name: 'rotate',
       summary: 'Replace the material of a credential with a new version',
-      description: 'Takes the options of import for the type of the credential, and seals the next version.',
+      description: 'Takes the options of import for the type of the credential, and seals the next version. When the credential is an apple_distribution_certificate and the new .p12 changes its SHA-1, it asks an owner for a passkey approval first: the server only accepts the new material with it.',
       positionals: [credentialId],
       options: { ...common, ...MATERIAL_OPTIONS, name: { type: 'string', value: '"…"', description: 'A new name.' }, 'dry-run': { type: 'boolean', description: 'Read, check and seal, but send nothing.' }, ...item },
       run: rotate,
@@ -249,8 +300,27 @@ export default {
     {
       name: 'retire',
       summary: 'Stop using a credential (owner); it stays in the inventory',
-      positionals: [credentialId],
+      description: 'Takes its id, or its name when only one credential has it: two with the same name are never picked silently, it lists them and asks for the id. --dry-run says what it would retire and changes nothing.',
+      positionals: [credentialNamedArgument],
+      options: { ...common, 'dry-run': { type: 'boolean', description: 'Say what it would retire, and retire nothing.' } },
       run: retire,
     },
+    {
+      name: 'revoke',
+      summary: 'Revoke the team\'s Apple distribution certificate in Apple and retire it (owner, with a passkey)',
+      description: [
+        'For a compromised certificate, not for renewing: it shows the certificate Apple has, the provisioning profiles and applications that hold it and what happens to the builds, asks an owner to authorize it with a passkey and only then deletes it in App Store Connect (DELETE /v1/certificates) and retires the credential.',
+        'A rejected or expired approval deletes nothing. A certificate Apple no longer has is still retired. The App Store profile of each affected application has to be made again with another certificate: ias credentials generate ios.',
+      ].join('\n'),
+      positionals: [credentialId],
+      options: {
+        ...common,
+        'team-id': { type: 'string', value: '<id>', description: 'The Apple team of the certificate (the app\'s, or the App Store Connect key\'s, by default).' },
+        yes: { type: 'boolean', description: 'Do not ask before revoking; the owner\'s approval with a passkey is still needed.' },
+        'dry-run': { type: 'boolean', description: 'Show the certificate, the profiles and the impact; ask nothing and change nothing.' },
+        ...item,
+      },
+      run: revokeAppleCertificate,
+    },
   ],
 };

package/src/commands/credentials/seal.mjs

@@ -0,0 +1,44 @@
+// The pieces that ias credentials import, rotate and generate share (docs/technical/vault.md §3.5): the metadata of a
+// type from its material, the plaintext to seal, the sealed envelope checked with the team's key just after signing it,
+// and the warning of an expiry within 30 days. Nothing here prints or writes a secret.
+import { PLAINTEXT_TYPES, credentials as inspect, encodePlaintext, seal, verifyEnvelope } from '../../shared.mjs';
+import { IasError } from '../../errors.mjs';
+
+const DAY = 24 * 60 * 60 * 1000;
+
+/** Whether the type belongs to the team (a certificate, a key) instead of an application. */
+export const ofTeam = (type) => PLAINTEXT_TYPES[type]?.scope === 'team';
+
+/** The metadata of `material`, or an IasError that names the file or tool, never a secret. */
+export function metadataOf(type, material) {
+  try {
+    return inspect.metadataOf(type, material.inspect);
+  } catch (error) {
+    if (error instanceof inspect.CredentialError) throw new IasError(`${type}: ${error.message}`, { fix: 'check the file and its password or alias', code: 'credential_unreadable' });
+    throw error;
+  }
+}
+
+/** The plaintext to seal: the fields of the material, those that only the metadata knows, and the application. */
+export function plaintextOf(type, material, metadata, application) {
+  return encodePlaintext(type, { ...(ofTeam(type) ? {} : { application }), ...material.fields, ...(material.completes?.(metadata) ?? {}) });
+}
+
+/** Seals `plaintext` as version `version` of credential `id`, and checks the signature it just made. */
+export function sealCredential(plaintext, { id, type, version }, sealing) {
+  try {
+    const envelope = seal(plaintext, { credential: { id, type, version }, recipients: sealing.recipients, signingKey: sealing.signingKey });
+    verifyEnvelope(envelope, sealing.keys.signing.publicKey);
+    return envelope;
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+/** Warnings about an expiry within 30 days. */
+export function expiryWarning(name, metadata, output, now = Date.now()) {
+  if (!metadata?.expires) return;
+  const days = Math.floor((Date.parse(metadata.expires) - now) / DAY);
+  if (days < 0) output.warn(`${name} expired on ${metadata.expires}`);
+  else if (days <= 30) output.warn(`${name} expires in ${days} days (${metadata.expires})`);
+}

package/src/commands/devices/asc.mjs

@@ -1,6 +1,7 @@
-// The part of the App Store Connect API (https://developer.apple.com/documentation/appstoreconnectapi) that ias
-// devices sync uses: the team's devices, its bundle ids, certificates and provisioning profiles. Every request carries
-// a JWT of the team's API key (ES256 with node:crypto, 20 minutes at most, as Apple asks). The key comes from the
+// The part of the App Store Connect API (https://developer.apple.com/documentation/appstoreconnectapi) that ias uses from
+// this Mac: the team's devices, its bundle ids, certificates and provisioning profiles, and the same as writes for ias
+// credentials generate (a distribution certificate from a CSR, its revocation, an App Store profile). Every request
+// carries a JWT of the team's API key (ES256 with node:crypto, 20 minutes at most, as Apple asks). The key comes from the
 // sealed vault, opened in memory on this computer; neither the key nor a token is ever printed, written or an argument.
 import { createPrivateKey, sign } from 'node:crypto';
 import { IasError } from '../../errors.mjs';
@@ -39,7 +40,9 @@ function appleProblem(status, body) {
 
 /**
  * A client of the API with the key `key` ({ key_id, issuer_id, p8 }): { request(method, path, json?), all(path),
- * devices(), registerDevice(), enableDevice(), bundleId(), certificates(), profilesOf(), devicesOf(), createProfile() }.
+ * devices(), registerDevice(), enableDevice(), bundleId(), certificates(), certificatesOfTeam(), createCertificate(),
+ * revokeCertificate(), appByBundleId(), bundleIdCapabilities(), enableCapability(), profilesOf(), profile(),
+ * deleteProfile(), devicesOf(), createProfile() }.
  * A token lasts 20 minutes; a new one is made before it ends.
  */
 export function ascClient(key, { env = {}, fetch: fetchImpl = fetch, now = Date.now } = {}) {
@@ -94,20 +97,59 @@ export function ascClient(key, { env = {}, fetch: fetchImpl = fetch, now = Date.
     enableDevice: async (id) => (await request('PATCH', `/v1/devices/${encodeURIComponent(id)}`, { data: { type: 'devices', id, attributes: { status: 'ENABLED' } } })).data,
     /** The bundle id resource of `identifier` (Apple's filter matches parts too: only the exact one counts). */
     bundleId: async (identifier) => (await all(`/v1/bundleIds?filter[identifier]=${encodeURIComponent(identifier)}&filter[platform]=IOS&limit=200`)).find((item) => item.attributes?.identifier === identifier) ?? null,
+    /** A new App ID of `identifier` (docs/plans/gaps/05-bundle-id-app-record.md §3.4): { id, attributes: { identifier, name, platform } }. */
+    createBundleId: async ({ identifier, name }) =>
+      (await request('POST', '/v1/bundleIds', { data: { type: 'bundleIds', attributes: { identifier, name, platform: 'IOS' } } })).data,
+    /** The app record of `identifier`, or null (Apple's filter matches parts too: only the exact bundle id counts). */
+    appByBundleId: async (identifier) =>
+      (await all(`/v1/apps?filter[bundleId]=${encodeURIComponent(identifier)}&fields[apps]=name,bundleId,sku,primaryLocale&limit=200`)).find((item) => item.attributes?.bundleId === identifier) ?? null,
     certificates: () => all('/v1/certificates?filter[certificateType]=DISTRIBUTION,IOS_DISTRIBUTION&limit=200'),
+    /** The team's distribution certificates (Apple Distribution and the old iOS Distribution), with their DER. */
+    certificatesOfTeam: () => all('/v1/certificates?filter[certificateType]=DISTRIBUTION,IOS_DISTRIBUTION&limit=200'),
+    /** One certificate of Apple by its id, re-read right before it is revoked: { id, attributes: { … } }. */
+    certificate: async (id) => (await request('GET', `/v1/certificates/${encodeURIComponent(id)}`)).data,
+    /** A new certificate from the CSR (PEM text): { id, attributes: { certificateContent, serialNumber, expirationDate, … } }. */
+    createCertificate: async ({ certificateType = 'DISTRIBUTION', csr }) =>
+      (
+        await request('POST', '/v1/certificates', {
+          data: { type: 'certificates', attributes: { certificateType, csrContent: csr } },
+        })
+      ).data,
+    /** Revokes the certificate in Apple (DELETE /v1/certificates/{id}). No command of ias calls it on its own. */
+    revokeCertificate: (id) => request('DELETE', `/v1/certificates/${encodeURIComponent(id)}`),
+    /** The capabilities the App ID has in Apple: [{ id, attributes: { capabilityType } }]. */
+    bundleIdCapabilities: (bundleIdId) => all(`/v1/bundleIds/${encodeURIComponent(bundleIdId)}/bundleIdCapabilities?limit=200`),
+    /** Enables a capability of the App ID (POST /v1/bundleIdCapabilities), which invalidates every profile of it. */
+    enableCapability: async (bundleIdId, capabilityType) =>
+      (
+        await request('POST', '/v1/bundleIdCapabilities', {
+          data: {
+            type: 'bundleIdCapabilities',
+            attributes: { capabilityType },
+            relationships: { bundleId: { data: { type: 'bundleIds', id: bundleIdId } } },
+          },
+        })
+      ).data,
     profilesOf: (bundleIdId) => all(`/v1/bundleIds/${encodeURIComponent(bundleIdId)}/profiles?limit=200`),
+    /** One profile of Apple, with its profileContent. */
+    profile: async (id) => (await request('GET', `/v1/profiles/${encodeURIComponent(id)}`)).data,
+    /** Deletes a profile in Apple (DELETE /v1/profiles/{id}). No command of ias calls it on its own. */
+    deleteProfile: (id) => request('DELETE', `/v1/profiles/${encodeURIComponent(id)}`),
     devicesOf: (profileId) => all(`/v1/profiles/${encodeURIComponent(profileId)}/devices?limit=200`),
-    /** A new ad hoc profile of the bundle id with the certificate and the devices: { id, attributes: { profileContent, uuid, … } }. */
-    createProfile: async ({ name, bundleIdId, certificateId, deviceIds }) =>
+    /**
+     * A new profile of the bundle id with the certificate: { id, attributes: { profileContent, uuid, … } }. An App Store
+     * profile has no devices relationship at all (not an empty one); an ad hoc profile lists exactly `deviceIds`.
+     */
+    createProfile: async ({ name, type = 'IOS_APP_ADHOC', bundleIdId, certificateId, deviceIds = [] }) =>
       (
         await request('POST', '/v1/profiles', {
           data: {
             type: 'profiles',
-            attributes: { name, profileType: 'IOS_APP_ADHOC' },
+            attributes: { name, profileType: type },
             relationships: {
               bundleId: { data: { type: 'bundleIds', id: bundleIdId } },
               certificates: { data: [{ type: 'certificates', id: certificateId }] },
-              devices: { data: deviceIds.map((id) => ({ type: 'devices', id })) },
+              ...(type === 'IOS_APP_STORE' ? {} : { devices: { data: deviceIds.map((id) => ({ type: 'devices', id })) } }),
             },
           },
         })

package/src/commands/devices/index.mjs

@@ -57,7 +57,8 @@ export default {
         force: { type: 'boolean', description: 'Make the profile again even if it already lists every approved device.' },
         'no-resign': { type: 'boolean', description: 'Only the devices and the profile: do not sign the internal build again.' },
         detach: { type: 'boolean', description: 'Ask for the resign and do not wait for it.' },
-        item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://Private/IAS vault <host>).' },
+        'dry-run': { type: 'boolean', description: 'Say which devices it would register, which profile it would make and seal and which resign it would queue, and do none of it (no Apple call, no vault write, no job).' },
+        item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://IAS/IAS vault <host>).' },
       },
       run: (context) => sync(context, projectOf(context)),
     },

package/src/commands/devices/sync.mjs

@@ -33,10 +33,43 @@ const latestExpiring = (list) => [...list].sort((a, b) => (Date.parse(b.expires_
 /** The name Apple keeps a device with: the tester's, or iOS's, and its model, within 50 characters. */
 export function appleDeviceName(device) {
   const model = device.model ? ` (${device.model})` : '';
-  const name = (device.owner_name || device.name || 'Dispositivo').normalize('NFKD').replace(/[^\x20-\x7e]/g, '');
+  const name = (device.owner_name || device.name || 'Device').normalize('NFKD').replace(/[^\x20-\x7e]/g, '');
   return `${name.slice(0, 50 - model.length).trim() || 'Device'}${model}`;
 }
 
+/**
+ * What `ias devices sync` would do, from the devices IAS lists and the ad hoc profile of the vault alone: no Apple
+ * call, no 1Password item, no vault write and no job. It cannot know which devices Apple already has, so a device IAS
+ * has no Apple id for is one it would register; the profile it makes would also keep the devices of the current one
+ * that Apple still has enabled.
+ */
+export function syncPlan({ app, devices, material, resign = true }) {
+  const approved = devices.filter((device) => device.status === 'approved');
+  const wanted = devices.filter((device) => device.status === 'approved' || device.status === 'registered');
+  const rejected = new Set(devices.filter((device) => device.status === 'rejected').map((device) => normalizeUdid(device.udid)));
+  const register = approved.filter((device) => !device.apple_device_id);
+  const leave = devices.filter((device) => device.status === 'rejected' && device.apple_device_id);
+  const profile = {
+    action: material.profile ? 'replace' : 'create',
+    credential: material.profile?.id ?? null,
+    name: material.profile?.name ?? null,
+    version: (material.profile?.version ?? 0) + 1,
+    devices: wanted.length,
+    certificate: material.certificate.name,
+  };
+  return {
+    bundle_id: app.ios.bundle_id,
+    devices: devices.length,
+    approved: approved.length,
+    rejected: rejected.size,
+    register: register.map((device) => ({ udid: device.udid, name: appleDeviceName(device), status: device.status })),
+    add_to_profile: wanted.map((device) => ({ udid: device.udid, name: appleDeviceName(device), status: device.status })),
+    leave_profile: leave.map((device) => ({ udid: device.udid, name: appleDeviceName(device), status: device.status })),
+    profile,
+    resign: resign ? { queued: true } : null,
+  };
+}
+
 /** The credentials sync needs: the team's App Store Connect key and distribution certificate, and the app's ad hoc profile. */
 async function vaultCredentials(client, code, app) {
   const team = (await client.request('GET', '/team/credentials')).data.data.filter((credential) => !credential.retired_at);
@@ -46,14 +79,14 @@ async function vaultCredentials(client, code, app) {
   const ascKey = team.filter((credential) => credential.type === 'asc_api_key').sort((a, b) => (b.updated_at ?? '').localeCompare(a.updated_at ?? ''))[0];
   if (!ascKey) throw new IasError('the vault has no App Store Connect API key', { fix: 'import the team\'s with ias credentials import asc_api_key --p8 <AuthKey_….p8> --key-id <id> --issuer-id <uuid>', code: 'credentials_missing' });
   const certificate = latestExpiring(team.filter((credential) => credential.type === 'apple_distribution_certificate' && usable(credential) && credential.metadata?.kind === 'distribution' && (!app.ios.team_id || credential.metadata?.team === app.ios.team_id)));
-  if (!certificate) throw new IasError(`the vault has no usable distribution certificate of the team ${app.ios.team_id ?? ''}`.trim(), { fix: 'import it with ias credentials import apple_distribution_certificate', code: 'credentials_missing' });
+  if (!certificate) throw new IasError(`the vault has no usable distribution certificate of the team ${app.ios.team_id ?? ''}`.trim(), { fix: 'make one with ias credentials generate ios (or import the current one with ias credentials import apple_distribution_certificate)', code: 'credentials_missing' });
   const sha1 = String(certificate.metadata.sha1 ?? '').toUpperCase();
   const profile = latestExpiring(own.filter((credential) => credential.type === 'apple_provisioning_profile' && credential.metadata?.type === 'ad-hoc' && credential.metadata?.bundleId === app.ios.bundle_id && (credential.metadata?.certificates ?? []).map((value) => String(value).toUpperCase()).includes(sha1)));
   return { ascKey, certificate, profile };
 }
 
 /** The App Store Connect key of the vault, opened with the recovery key after checking the team signed it. */
-async function openAscKey(client, credential, { recoveryKey, keys }) {
+export async function openAscKey(client, credential, { recoveryKey, keys }) {
   const { data } = await client.request('GET', `/credentials/${credential.id}/envelope`);
   if (data.envelope?.credential?.id !== credential.id || data.envelope?.credential?.type !== 'asc_api_key') throw new IasError('the server gives the envelope of another credential for the App Store Connect key', { fix: 'nothing was opened: ias credentials show checks it', code: 'envelope_of_another_credential' });
   let bytes;
@@ -93,6 +126,17 @@ async function followResign(client, code, resign, { output, wait }) {
   return current;
 }
 
+/** The lines of a plan for people, before anything is done. */
+function printSyncPlan(plan, output) {
+  output.progress(`dry run: ${plan.bundle_id}: ${plan.devices} device${plan.devices === 1 ? '' : 's'} in IAS, ${plan.approved} approved, ${plan.rejected} rejected`);
+  for (const device of plan.register) output.progress(`  register in Apple  ${device.name}  ${device.udid}`);
+  for (const device of plan.add_to_profile) output.progress(`  add to the profile ${device.name}  ${device.udid}`);
+  for (const device of plan.leave_profile) output.progress(`  leave the profile  ${device.name}  ${device.udid} (rejected in IAS)`);
+  output.progress(`  profile            would ${plan.profile.action} the ad hoc profile of ${plan.bundle_id} with ${plan.profile.devices} device${plan.profile.devices === 1 ? '' : 's'} (and the ones of the current one Apple still has enabled), signed with «${plan.profile.certificate}», and seal it as version ${plan.profile.version}${plan.profile.name ? ` of «${plan.profile.name}»` : ''} in the vault`);
+  output.progress(`  resign             ${plan.resign ? 'would queue a resign of the newest internal iOS build for a runner' : 'none (--no-resign)'}`);
+  output.progress('dry run: nothing was registered in Apple, nothing was sealed and no job was queued.');
+}
+
 export async function sync(context, project) {
   const { values, env, output } = context;
   const wait = context.sleep ?? sleep;
@@ -107,6 +151,15 @@ export async function sync(context, project) {
   const rejected = new Set(devices.filter((device) => device.status === 'rejected').map((device) => normalizeUdid(device.udid)));
 
   const item = vaultItem(context, project, client.server);
+
+  // A dry run reads what IAS keeps and the ad hoc profile of the vault: no Apple call, no 1Password item, no job.
+  if (values['dry-run']) {
+    const material = await vaultCredentials(client, code, app);
+    const plan = syncPlan({ app, devices, material, resign: values['no-resign'] !== true });
+    printSyncPlan(plan, output);
+    return { dry_run: true, ...plan };
+  }
+
   const { vault, keys, signingKey, recoveryKey } = await teamKeys(client, item, env, { recovery: true });
   const material = await vaultCredentials(client, code, app);
   const key = await openAscKey(client, material.ascKey, { recoveryKey, keys });
@@ -117,7 +170,7 @@ export async function sync(context, project) {
 
     // What the new profile lists: the current profile's devices still enabled, and the approved ones, never the rejected ones.
     const bundle = await asc.bundleId(app.ios.bundle_id);
-    if (!bundle) throw new IasError(`Apple has no App ID ${app.ios.bundle_id}`, { fix: 'register it in Apple Developer › Identifiers (ias build does it for a store build)', code: 'bundle_id_not_in_apple' });
+    if (!bundle) throw new IasError(`Apple has no App ID ${app.ios.bundle_id}`, { fix: 'register it with ias apps store --register-bundle-id, or in Apple Developer › Identifiers', code: 'bundle_id_not_in_apple' });
     const current = material.profile ? (await asc.profilesOf(bundle.id)).find((profile) => String(profile.attributes?.uuid).toUpperCase() === String(material.profile.metadata.uuid).toUpperCase()) : null;
     if (material.profile && !current) output.warn(`the profile of the vault (${material.profile.metadata.uuid}) is not in Apple any more: the new one lists only the devices of IAS`);
     const inProfile = current ? await asc.devicesOf(current.id) : [];

package/src/commands/dist/index.mjs

@@ -8,6 +8,7 @@ import { IasError } from '../../errors.mjs';
 import { api } from '../../http.mjs';
 import { digest, gitCommit, icon, readApk, readIpa } from '../../dist.mjs';
 import { readSecret, tokenKind } from '../../secrets.mjs';
+import { provisionDistribution } from '../../provisioning.mjs';
 
 /** The publishing token of the distribution project: the variable or the op:// reference, read now. */
 export function publishingToken(settings) {
@@ -80,6 +81,17 @@ export default {
   summary: 'Internal builds on the install pages: upload an ad hoc IPA or an APK, list, retire and restore',
   description: 'The server and project come from ias.json (server, and distribution.project or app); the token is the distribution project\'s (dist_…): IAS_TOKEN or distribution.token. IPAs need the tools of macOS (unzip, plutil, security, sips); APKs, aapt2 of the Android SDK.',
   subcommands: [
+    {
+      name: 'init',
+      summary: 'Make the distribution project and its publishing token, and write the token reference to ias.json',
+      description: 'Creates the distribution project on the server and keeps its token in 1Password, with its op:// reference in distribution.token of ias.json. It prints the stable install link. It needs an owner\'s personal token (ias login) and the 1Password CLI; a project that already exists is left as it is.',
+      options: {
+        name: { type: 'string', value: '"…"', description: 'The name of the project in the panel (the app name by default).' },
+        item: { type: 'string', value: 'op://vault/item', description: 'The 1Password item for the token (op://IAS/<app> distribution by default).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would make and change, and make nothing.' },
+      },
+      run: (context) => provisionDistribution({ dir: resolve(context.cwd, context.values.project ?? '.'), env: context.env, output: context.output, values: context.values, sleep: context.sleep, dryRun: context.values['dry-run'] }),
+    },
     {
       name: 'upload',
       summary: 'Upload a build and print its link and the stable one',