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

package/src/commands/credentials/index.mjs

@@ -0,0 +1,256 @@
+// ias credentials 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/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
+// metadata, never a secret; nothing here prints one.
+import { randomUUID } from 'node:crypto';
+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 { publicKeysOf, sealingKeys, vaultItem } from '../../team-vault.mjs';
+import { MATERIAL_OPTIONS, defaultName, inferType, materialFromEas, materialFromOptions, sameMaterial } from './material.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 = [];
+  if (application) found.push(...(await client.request('GET', `/apps/${application}/credentials`)).data.data);
+  try {
+    found.push(...(await client.request('GET', '/team/credentials')).data.data);
+  } catch (error) {
+    if (!(error instanceof ApiError) || error.code !== 'role_forbidden') throw error; // a robot token sees no team credentials
+  }
+  return found;
+}
+
+/** One credential by its id, from the lists (the API has no route for a single one). */
+async function findCredential(client, id, application) {
+  const credential = (await visibleCredentials(client, application)).find((candidate) => candidate.id === id);
+  if (!credential) throw new IasError(`there is no credential ${id}${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' });
+  return credential;
+}
+
+const optionalApplication = (context, project) => (context.values.app || project?.config?.app ? applicationOf(context, project) : undefined);
+
+async function importCredentials(context) {
+  const { values, env, cwd, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  if (values.eas && context.positionals[0]) throw new IasError('--eas imports every credential of credentials.json', { fix: 'leave out the type, or import one with its own options' });
+  const type = values.eas ? undefined : (context.positionals[0] ?? inferType(values));
+  const materials = values.eas ? materialFromEas(resolve(cwd, values.eas)) : [{ type, ...materialFromOptions(type, values, { env, cwd }) }];
+  if (values.name && materials.length > 1) throw new IasError('--name names one credential, and credentials.json has several', { fix: 'import them without --name, and rename them in the panel' });
+  const needsApplication = materials.some(({ type }) => !ofTeam(type));
+  const application = needsApplication ? applicationOf(context, project) : optionalApplication(context, project);
+  const described = materials.map((material) => ({ ...material, metadata: metadataOf(material.type, material) }));
+  if (values.eas) {
+    const app = application ? (await client.request('GET', `/apps/${application}`)).data : null;
+    const certificate = described.find((entry) => entry.type === 'apple_distribution_certificate')?.metadata;
+    const profile = described.find((entry) => entry.type === 'apple_provisioning_profile')?.metadata;
+    const keystore = described.find((entry) => entry.type === 'android_upload_keystore')?.metadata;
+    const problems = [
+      ...(certificate && profile ? inspect.checkIos({ certificate, profile }, { teamId: app?.ios?.team_id ?? undefined, bundleId: app?.ios?.bundle_id ?? undefined, type: profile.type }) : []),
+      ...(keystore ? inspect.checkAndroid(keystore) : []),
+    ];
+    if (problems.length > 0 && !values.force) throw new IasError(`credentials.json has problems: ${problems.join('; ')}`, { fix: 'fix them in EAS or Apple Developer, or pass --force to import it anyway', code: 'credential_problems', details: problems });
+    for (const problem of problems) output.warn(problem);
+  }
+  const sealing = await sealingKeys(client, vaultItem(context, project, client.server), env, output);
+  const existing = await visibleCredentials(client, application);
+  const results = [];
+  for (const { type, metadata, ...material } of described) {
+    const name = values.name ?? defaultName(type, metadata);
+    const same = existing.find((credential) => sameMaterial(credential, type, metadata));
+    if (same && !values.force) {
+      output.log(`${type} «${name}» is already in the vault as ${same.id} (version ${same.version}): skipped. ias credentials rotate ${same.id} replaces it.`);
+      results.push({ skipped: true, id: same.id, type, name });
+      continue;
+    }
+    const id = randomUUID();
+    const envelope = sealCredential(plaintextOf(type, material, metadata, application), { id, type, version: 1 }, sealing);
+    const body = { id, type, name, metadata, envelope };
+    const recipients = envelope.recipients.length;
+    if (values['dry-run']) {
+      output.log(`dry run: ${type} «${name}» (${id}) sealed for ${recipients} key${recipients === 1 ? '' : 's'}, digest ${digest(envelope)}; nothing sent`);
+      results.push({ dry_run: true, id, type, name, metadata, digest: digest(envelope), recipients: envelope.recipients.map((wrap) => wrap.kid) });
+      continue;
+    }
+    const { data } = await client.request('POST', ofTeam(type) ? '/team/credentials' : `/apps/${application}/credentials`, { json: body });
+    output.log(`imported ${type} «${data.name}» as ${data.id}, version ${data.version}${data.expires_at ? `, until ${data.expires_at}` : ''} (${ofTeam(type) ? 'the team' : data.application})`);
+    expiryWarning(`«${data.name}»`, metadata, output);
+    results.push(data);
+  }
+  return { credentials: results };
+}
+
+async function list(context) {
+  const { output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = optionalApplication(context, project);
+  const found = (await visibleCredentials(client, application)).filter((credential) => context.values.all || !credential.retired_at);
+  if (found.length === 0) output.log(`No credentials${application ? ` in ${application} or the team` : ' in the team'}: ias credentials import adds them.`);
+  const now = Date.now();
+  for (const credential of found) {
+    const until = credential.expires_at ? `until ${credential.expires_at.slice(0, 10)} (${Math.floor((Date.parse(credential.expires_at) - now) / DAY)} days)` : 'no expiry';
+    output.log(`${credential.id}  ${credential.type.padEnd(30)}  v${credential.version}  ${until}${credential.retired_at ? '  retired' : ''}  ${credential.application ?? 'team'}  «${credential.name}»`);
+  }
+  return { credentials: found };
+}
+
+async function show(context) {
+  const { values, env, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const credential = await findCredential(client, context.positionals[0], optionalApplication(context, project));
+  const { data } = await client.request('GET', `/credentials/${credential.id}/envelope`);
+  const { envelope } = data;
+  const { data: vault } = await client.request('GET', '/vault');
+  const names = new Map([[vault.recovery_key?.kid, 'recovery key'], ...(vault.runners ?? []).map((runner) => [runner.kid, `runner ${runner.name ?? ''}`.trim()])]);
+  output.log(`${credential.id}  ${credential.type}  «${credential.name}» (${credential.application ?? 'the team'})`);
+  output.log(`  version     ${credential.version}${credential.retired_at ? `, retired on ${credential.retired_at}` : ''}`);
+  output.log(`  expires     ${credential.expires_at ?? 'never'}`);
+  output.log(`  digest      ${credential.digest}${digest(envelope) === credential.digest ? '' : ' (NOT the digest of the envelope the server gives)'}`);
+  for (const [key, value] of Object.entries(credential.metadata ?? {})) if (key !== 'entitlements') output.log(`  ${key.padEnd(11)} ${Array.isArray(value) ? value.join(', ') : value}`);
+  output.log(`  sealed for  ${envelope.recipients.map((wrap) => `${names.get(wrap.kid) ?? 'an unknown key'} (${wrap.kid})`).join(', ')}`);
+  let verified = null;
+  if (values.verify) {
+    const keys = publicKeysOf(vaultItem(context, project, client.server), env);
+    if (!keys) throw new IasError('there is no item of the vault in 1Password to verify with', { fix: 'pass --item, or ask an owner to share the item with you' });
+    try {
+      verifyEnvelope(envelope, keys.signing.publicKey);
+      verified = true;
+    } catch (error) {
+      verified = false;
+      output.warn(`the envelope does NOT verify with the team's signing key of 1Password (${error.code})`);
+    }
+  }
+  output.log(`  signed by   ${envelope.signature?.kid === vault.signing_key?.kid ? 'the team' : 'an unknown key'} (${envelope.signature?.kid})${verified === true ? ', verified with 1Password' : ''}`);
+  return { ...credential, recipients: envelope.recipients.map((wrap) => wrap.kid), signature_kid: envelope.signature?.kid ?? null, verified };
+}
+
+async function rotate(context) {
+  const { values, env, cwd, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const credential = await findCredential(client, context.positionals[0], optionalApplication(context, project));
+  if (credential.retired_at) throw new IasError(`${credential.id} is retired`, { fix: 'import the new material as a new credential: ias credentials import' });
+  const { type } = credential;
+  const material = materialFromOptions(type, values, { env, cwd });
+  const metadata = metadataOf(type, material);
+  const sealing = await sealingKeys(client, vaultItem(context, project, client.server), env, output);
+  const version = credential.version + 1;
+  const envelope = sealCredential(plaintextOf(type, material, metadata, credential.application), { id: credential.id, type, version }, sealing);
+  if (values['dry-run']) {
+    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 } });
+  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`);
+  return data;
+}
+
+const credentialId = { name: 'id', description: 'The id of the credential, from ias credentials list.', pattern: CREDENTIAL_ID };
+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 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',
+  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: 'import',
+      summary: 'Seal a credential and upload it, with its metadata',
+      description: 'Name the type and give its files (paths or op:// references) and passwords (op://…, env:NAME or -), or --eas with the folder of an EAS credentials.json. The type can be left out when the options say it. A credential already in the vault (the same certificate, profile or key) is skipped; ias credentials rotate replaces it.',
+      positionals: [{ name: 'type', optional: true, description: `One of ${types.join(', ')}.`, pattern: /^[a-z][a-z0-9_]{0,63}$/ }],
+      options: {
+        ...common,
+        ...MATERIAL_OPTIONS,
+        eas: { type: 'string', value: '<folder>', description: 'The folder of an EAS credentials.json: imports its certificate, profile and keystore.' },
+        name: { type: 'string', value: '"…"', description: 'The name the panel shows (from the material by default).' },
+        force: { type: 'boolean', description: 'Import even if it is already in the vault or EAS\'s material has problems.' },
+        'dry-run': { type: 'boolean', description: 'Read, check and seal, but send nothing.' },
+        ...item,
+      },
+      run: importCredentials,
+    },
+    {
+      name: 'list',
+      summary: 'The credentials of the application and the team, with their expiry',
+      options: { ...common, all: { type: 'boolean', description: 'Also the retired ones.' } },
+      run: list,
+    },
+    {
+      name: 'show',
+      summary: 'One credential: its metadata, version, digest, who can open it and who signed it',
+      positionals: [credentialId],
+      options: { ...common, verify: { type: 'boolean', description: 'Check the signature of its envelope with the team\'s signing key of 1Password.' }, ...item },
+      run: show,
+    },
+    {
+      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.',
+      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,
+    },
+    {
+      name: 'retire',
+      summary: 'Stop using a credential (owner); it stays in the inventory',
+      positionals: [credentialId],
+      run: retire,
+    },
+  ],
+};

package/src/commands/credentials/material.mjs

@@ -0,0 +1,159 @@
+// The material of each type of credential, from the options of ias credentials import and rotate or from an EAS
+// credentials.json: what inspect needs for the metadata (paths and passwords) and the fields of the plaintext that is
+// sealed (docs/technical/vault.md §3.5). Passwords come as op://…, env:NAME or -; files as paths or op:// references.
+import { readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { IasError } from '../../errors.mjs';
+import { filePath, secretValue } from '../../secret-input.mjs';
+import { PLAINTEXT_TYPES } from '../../shared.mjs';
+
+/** The options that give the material, by type. */
+export const MATERIAL_OPTIONS = {
+  p12: { type: 'string', value: '<file|op://…>', description: 'apple_distribution_certificate: the .p12.' },
+  password: { type: 'string', value: '<op://…|env:NAME|->', description: 'The password of the .p12 (never the password itself).' },
+  profile: { type: 'string', value: '<file|op://…>', description: 'apple_provisioning_profile: the .mobileprovision.' },
+  keystore: { type: 'string', value: '<file|op://…>', description: 'android_upload_keystore: the .jks or PKCS12 keystore.' },
+  'store-password': { type: 'string', value: '<op://…|env:NAME|->', description: 'The password of the keystore.' },
+  'key-alias': { type: 'string', value: '<alias>', description: 'The alias of the upload key in the keystore.' },
+  'key-password': { type: 'string', value: '<op://…|env:NAME|->', description: 'The password of the key (the keystore\'s by default).' },
+  p8: { type: 'string', value: '<file|op://…>', description: 'apns_key or asc_api_key: the .p8 (AuthKey_<id>.p8 names its key id).' },
+  'key-id': { type: 'string', value: '<id>', description: 'The key id of the .p8 (10 characters), if its file name does not say it.' },
+  'team-id': { type: 'string', value: '<id>', description: 'The Apple team of the .p8 (10 characters).' },
+  'issuer-id': { type: 'string', value: '<uuid>', description: 'asc_api_key: the issuer id of App Store Connect.' },
+  'service-account': { type: 'string', value: '<file|op://…>', description: 'google_service_account: the JSON key of the service account.' },
+};
+
+/** The type a set of options gives, when the command line does not name it. */
+export function inferType(values) {
+  const found = [];
+  if (values.p12) found.push('apple_distribution_certificate');
+  if (values.profile) found.push('apple_provisioning_profile');
+  if (values.keystore) found.push('android_upload_keystore');
+  if (values.p8) found.push(values['issuer-id'] ? 'asc_api_key' : 'apns_key');
+  if (values['service-account']) found.push('google_service_account');
+  if (found.length === 1) return found[0];
+  throw new IasError(found.length === 0 ? 'which credential?' : `the options give ${found.length} credentials (${found.join(', ')})`, { fix: 'name the type and its files, such as ias credentials import android_upload_keystore --keystore upload.jks --store-password op://… --key-alias upload; or --eas <folder>' });
+}
+
+const need = (values, name, type) => {
+  if (!values[name]) throw new IasError(`${type} needs --${name}`, { fix: `ias credentials import --help lists the options of each type` });
+  return values[name];
+};
+
+/**
+ * The material of `type` from the options: { inspect, fields, name } with `inspect` the input of metadataOf and
+ * `fields` those of encodePlaintext (without application, which the caller adds for the types of an application).
+ */
+export function materialFromOptions(type, values, { env, cwd }) {
+  const secret = (name) => secretValue(need(values, name, type), { env, option: `--${name}` });
+  const file = (name, as) => filePath(need(values, name, type), { env, cwd, name: as });
+  switch (type) {
+    case 'apple_distribution_certificate': {
+      const p12 = file('p12', 'certificate.p12');
+      const password = secret('password');
+      return { inspect: { p12, password }, fields: { p12: readFileSync(p12), password } };
+    }
+    case 'apple_provisioning_profile': {
+      const profile = file('profile', 'profile.mobileprovision');
+      return { inspect: { mobileprovision: profile }, fields: { mobileprovision: readFileSync(profile) } };
+    }
+    case 'android_upload_keystore': {
+      const keystore = file('keystore', 'upload.keystore');
+      const storePassword = secret('store-password');
+      const keyPassword = values['key-password'] ? secret('key-password') : storePassword;
+      const alias = need(values, 'key-alias', type);
+      return { inspect: { keystore, storePassword, alias, keyPassword }, fields: { keystore: readFileSync(keystore), store_password: storePassword, key_alias: alias, key_password: keyPassword } };
+    }
+    case 'apns_key':
+    case 'asc_api_key': {
+      const given = need(values, 'p8', type);
+      const p8 = filePath(given, { env, cwd, name: /^AuthKey_[A-Z0-9]{10}\.p8$/.test(basename(given)) ? basename(given) : 'key.p8' });
+      const issuerId = type === 'asc_api_key' ? need(values, 'issuer-id', type) : undefined;
+      return { inspect: { p8, keyId: values['key-id'], teamId: need(values, 'team-id', type), issuerId }, fields: { p8: readFileSync(p8) }, completes: (metadata) => (type === 'apns_key' ? { key_id: metadata.keyId, team_id: metadata.teamId } : { key_id: metadata.keyId, issuer_id: metadata.issuerId }) };
+    }
+    case 'google_service_account': {
+      const json = file('service-account', 'service-account.json');
+      return { inspect: { json }, fields: { json: readFileSync(json) } };
+    }
+    default:
+      throw new IasError(`there is no credential type ${type}`, { fix: `one of ${Object.keys(PLAINTEXT_TYPES).filter((name) => name !== 'environment_variable').join(', ')}` });
+  }
+}
+
+/**
+ * The material of an EAS credentials.json (eas credentials › Download credentials from EAS) in `dir`: the iOS
+ * distribution certificate, the profile and the Android keystore that it has. The passwords in the file are used and
+ * never shown.
+ */
+export function materialFromEas(dir) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(join(dir, 'credentials.json'), 'utf8'));
+  } catch {
+    throw new IasError(`no readable credentials.json in ${dir}`, { fix: 'download it with eas credentials › Download credentials from EAS, into a folder outside the repository' });
+  }
+  const found = [];
+  let ios = json.ios;
+  if (ios && !ios.distributionCertificate) {
+    const targets = Object.keys(ios);
+    if (targets.length !== 1) throw new IasError(`credentials.json has iOS credentials for ${targets.length} targets`, { fix: 'only one target is supported: import the others with --p12 and --profile' });
+    ios = ios[targets[0]];
+  }
+  if (ios?.distributionCertificate) {
+    const p12 = resolve(dir, ios.distributionCertificate.path);
+    const password = String(ios.distributionCertificate.password ?? '');
+    found.push({ type: 'apple_distribution_certificate', inspect: { p12, password }, fields: { p12: readFileSync(p12), password } });
+  }
+  if (ios?.provisioningProfilePath) {
+    const profile = resolve(dir, ios.provisioningProfilePath);
+    found.push({ type: 'apple_provisioning_profile', inspect: { mobileprovision: profile }, fields: { mobileprovision: readFileSync(profile) } });
+  }
+  const keystore = json.android?.keystore;
+  if (keystore) {
+    const path = resolve(dir, keystore.keystorePath);
+    const storePassword = String(keystore.keystorePassword ?? '');
+    const keyPassword = String(keystore.keyPassword ?? keystore.keystorePassword ?? '');
+    found.push({ type: 'android_upload_keystore', inspect: { keystore: path, storePassword, alias: keystore.keyAlias, keyPassword }, fields: { keystore: readFileSync(path), store_password: storePassword, key_alias: keystore.keyAlias, key_password: keyPassword } });
+  }
+  if (found.length === 0) throw new IasError('credentials.json has neither iOS nor Android credentials', { fix: 'download it again with eas credentials' });
+  return found;
+}
+
+/** The name a credential gets when --name does not give one. */
+export function defaultName(type, metadata) {
+  switch (type) {
+    case 'apple_distribution_certificate':
+      return metadata.commonName ?? `Apple certificate ${metadata.serial}`;
+    case 'apple_provisioning_profile':
+      return metadata.name ?? `Provisioning profile ${metadata.uuid}`;
+    case 'android_upload_keystore':
+      return `Upload keystore (${metadata.alias})`;
+    case 'apns_key':
+      return `APNs key ${metadata.keyId}`;
+    case 'asc_api_key':
+      return `App Store Connect API key ${metadata.keyId}`;
+    case 'google_service_account':
+      return `Google Play service account ${metadata.clientEmail}`;
+    default:
+      return type;
+  }
+}
+
+/** Whether a stored credential is the same material as `metadata` (the same certificate, profile, key…). */
+export function sameMaterial(credential, type, metadata) {
+  if (credential.type !== type || credential.retired_at) return false;
+  const stored = credential.metadata ?? {};
+  switch (type) {
+    case 'apple_distribution_certificate':
+    case 'android_upload_keystore':
+      return Boolean(metadata.sha256) && stored.sha256 === metadata.sha256;
+    case 'apple_provisioning_profile':
+      return Boolean(metadata.uuid) && stored.uuid === metadata.uuid;
+    case 'apns_key':
+    case 'asc_api_key':
+    case 'google_service_account':
+      return Boolean(metadata.publicKeySha256) && stored.publicKeySha256 === metadata.publicKeySha256;
+    default:
+      return false;
+  }
+}

package/src/commands/devices/asc.mjs

@@ -0,0 +1,116 @@
+// 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
+// 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';
+
+export const ASC_API = 'https://api.appstoreconnect.apple.com';
+
+/** The address of the API: IAS_APPLE_API_URL for tests (https, or a local address), or Apple's. */
+export function ascBase(env = {}) {
+  const text = env.IAS_APPLE_API_URL ?? ASC_API;
+  const url = URL.canParse(text) ? new URL(text) : null;
+  const local = url && (['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.hostname.endsWith('.test'));
+  if (!url || (url.protocol !== 'https:' && !local)) throw new IasError(`IAS_APPLE_API_URL (${text}) is not an https address`, { fix: 'leave it unset to talk to Apple' });
+  return url.origin;
+}
+
+const base64url = (value) => Buffer.from(value).toString('base64url');
+
+/** A JWT of the App Store Connect API for this key: { key_id, issuer_id, p8 } (the .p8 as bytes or text). */
+export function ascToken({ key_id: keyId, issuer_id: issuerId, p8 }, { now = Date.now, lifetime = 1200 } = {}) {
+  const issuedAt = Math.floor(now() / 1000);
+  const unsigned = `${base64url(JSON.stringify({ alg: 'ES256', kid: keyId, typ: 'JWT' }))}.${base64url(JSON.stringify({ iss: issuerId, iat: issuedAt, exp: issuedAt + Math.min(lifetime, 1200), aud: 'appstoreconnect-v1' }))}`;
+  let key;
+  try {
+    key = createPrivateKey({ key: Buffer.isBuffer(p8) ? p8 : Buffer.from(String(p8)), format: 'pem' });
+  } catch {
+    throw new IasError('the App Store Connect API key of the vault is not a .p8 key', { fix: 'import the right one with ias credentials import asc_api_key', code: 'asc_key_invalid' });
+  }
+  return `${unsigned}.${sign('sha256', Buffer.from(unsigned), { key, dsaEncoding: 'ieee-p1363' }).toString('base64url')}`;
+}
+
+/** What Apple answered, in one line: its status and the title and detail of its first error. Never the token. */
+function appleProblem(status, body) {
+  const error = Array.isArray(body?.errors) ? body.errors[0] : null;
+  return [`${status}`, error?.code, error?.title, error?.detail].filter(Boolean).join(' · ');
+}
+
+/**
+ * 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() }.
+ * A token lasts 20 minutes; a new one is made before it ends.
+ */
+export function ascClient(key, { env = {}, fetch: fetchImpl = fetch, now = Date.now } = {}) {
+  const origin = ascBase(env);
+  let token = null;
+  let expires = 0;
+
+  async function request(method, path, json) {
+    if (!token || now() > expires - 60_000) {
+      token = ascToken(key, { now });
+      expires = now() + 1_200_000;
+    }
+    const url = path.startsWith('http') ? path : `${origin}${path}`;
+    if (new URL(url).origin !== origin) throw new IasError(`App Store Connect pointed at another server (${new URL(url).origin})`, { fix: 'nothing was sent there; try again', code: 'apple_api_error' });
+    let response;
+    try {
+      response = await fetchImpl(url, { method, headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(json ? { 'content-type': 'application/json' } : {}) }, body: json ? JSON.stringify(json) : undefined });
+    } catch (error) {
+      throw new IasError(`App Store Connect did not answer (${error.cause?.code ?? error.message})`, { fix: 'check the connection and run it again: what was done stays done', code: 'apple_api_unreachable' });
+    }
+    const text = await response.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
+    if (!response.ok) {
+      const fix = response.status === 401 ? 'the API key was revoked or is not this team\'s: import a valid one with ias credentials import asc_api_key' : response.status === 403 ? 'the API key needs the Admin or App Manager role in App Store Connect' : 'see what Apple said; what was done before stays done';
+      throw new IasError(`App Store Connect refused ${method} ${new URL(url).pathname}: ${appleProblem(response.status, body)}`, { fix, code: 'apple_api_error', details: { status: response.status, errors: body?.errors ?? null } });
+    }
+    return body;
+  }
+
+  /** Every item of a list, following links.next. */
+  async function all(path) {
+    const items = [];
+    for (let next = path, pages = 0; next && pages < 50; pages += 1) {
+      const page = await request('GET', next);
+      items.push(...(page?.data ?? []));
+      next = page?.links?.next ?? null;
+    }
+    return items;
+  }
+
+  return {
+    request,
+    all,
+    /** The team's iOS devices (iPhone, iPad, iPod). */
+    devices: () => all('/v1/devices?filter[platform]=IOS&limit=200'),
+    registerDevice: async ({ name, udid }) => (await request('POST', '/v1/devices', { data: { type: 'devices', attributes: { name, platform: 'IOS', udid } } })).data,
+    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,
+    certificates: () => all('/v1/certificates?filter[certificateType]=DISTRIBUTION,IOS_DISTRIBUTION&limit=200'),
+    profilesOf: (bundleIdId) => all(`/v1/bundleIds/${encodeURIComponent(bundleIdId)}/profiles?limit=200`),
+    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 }) =>
+      (
+        await request('POST', '/v1/profiles', {
+          data: {
+            type: 'profiles',
+            attributes: { name, profileType: 'IOS_APP_ADHOC' },
+            relationships: {
+              bundleId: { data: { type: 'bundleIds', id: bundleIdId } },
+              certificates: { data: [{ type: 'certificates', id: certificateId }] },
+              devices: { data: deviceIds.map((id) => ({ type: 'devices', id })) },
+            },
+          },
+        })
+      ).data,
+  };
+}

package/src/commands/devices/index.mjs

@@ -0,0 +1,65 @@
+// ias devices list and sync (docs/technical/manage-api.md §15): the iPhones and iPads of the testers of an application. A tester
+// registers one with the link of the application (Distribución › Dispositivos in the panel), a member approves it with
+// a passkey, and ias devices sync, here, registers the approved ones in Apple, makes the ad hoc profile again with
+// them, seals and signs it into the vault and asks a runner to sign the newest internal build again (sync.mjs).
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { UsageError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { sync } from './sync.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const STATUSES = ['pending', 'approved', 'registered', 'rejected'];
+const LABELS = { pending: 'pending', approved: 'approved', registered: 'in Apple', rejected: 'rejected' };
+
+async function list(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  if (values.status && !STATUSES.includes(values.status)) throw new UsageError(`--status ${values.status} is not a status`, { fix: STATUSES.join(', ') });
+  const code = applicationOf(context, project);
+  const client = connect(context, project);
+  const query = values.status ? `?status=${encodeURIComponent(values.status)}` : '';
+  const { data } = await client.request('GET', `/apps/${code}/devices${query}`);
+  if (data.link) output.log(`Registration link: ${data.link.url}`);
+  else output.log('No registration link yet: make it in the panel (Distribución › Dispositivos).');
+  if (data.data.length === 0) output.log(values.status ? `No ${LABELS[values.status]} devices.` : 'No devices have registered yet.');
+  for (const device of data.data) {
+    const profile = device.profile ? `profile v${device.profile.version}` : 'not in a profile';
+    output.log(`${device.udid.padEnd(40)}  ${LABELS[device.status].padEnd(9)}  ${(device.model ?? '?').padEnd(11)}  ${profile.padEnd(16)}  «${device.owner_name ?? device.name ?? 'no name'}»`);
+  }
+  const approved = data.data.filter((device) => device.status === 'approved').length;
+  if (approved > 0) output.log(`${approved} approved device${approved === 1 ? '' : 's'} wait${approved === 1 ? 's' : ''} for ias devices sync.`);
+  return { link: data.link, devices: data.data };
+}
+
+const common = {
+  app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+};
+
+export default {
+  name: 'devices',
+  summary: 'The testers\' iPhones and iPads: list them, and register the approved ones in Apple and sign again',
+  description: 'A tester registers a device with the link of the application (the panel: Distribución › Dispositivos) and a member approves it with a passkey. ias devices sync, on this computer, opens the App Store Connect API key of the vault with the recovery key of 1Password, registers the approved devices in Apple, makes the ad hoc profile again with them, seals and signs it into the vault and asks a runner to sign the newest internal iOS build again, without building it.',
+  subcommands: [
+    {
+      name: 'list',
+      summary: 'The devices of the application, with their status and the registration link',
+      options: { ...common, status: { type: 'string', value: `<${STATUSES.join('|')}>`, description: 'Only the devices in this status.' } },
+      run: list,
+    },
+    {
+      name: 'sync',
+      summary: 'Register the approved devices in Apple, make the ad hoc profile again and sign the newest internal build again',
+      description: 'It shows what it will do in Apple and in the vault and asks to confirm it. The team\'s keys come from the 1Password item of ias vault init; the App Store Connect API key, from the vault (ias credentials import asc_api_key).',
+      options: {
+        ...common,
+        yes: { type: 'boolean', description: 'Do not ask: the devices were checked in the panel.' },
+        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>).' },
+      },
+      run: (context) => sync(context, projectOf(context)),
+    },
+  ],
+};