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

package/src/commands/usage/index.mjs

@@ -0,0 +1,57 @@
+// ias usage: what the team of the token used in a month, metric by metric, with its limits and how its applications share
+// it (docs/technical/manage-api.md §17, docs/technical/phase-5.md §2). A personal token only: the use belongs to the team, not to an application.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { UsageError } from '../../errors.mjs';
+import { connect } from '../../manage.mjs';
+
+const MONTH = /^\d{4}-(0[1-9]|1[0-2])$/;
+
+/** «1.5 GiB», «12 KiB», «800 B». */
+export function bytesText(bytes) {
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(value >= 100 ? 0 : 1)} ${units[unit]}`;
+}
+
+/** An amount in the unit of its metric: minutes, bytes or a plain count. */
+export function amountText(figure, value) {
+  if (figure.unit === 'bytes') return bytesText(value);
+  return figure.unit === 'minutes' ? `${value.toLocaleString('en-US')} min` : value.toLocaleString('en-US');
+}
+
+/** The lines that describe the month for people. */
+export function describeUsage(report) {
+  const lines = [`${report.team.slug} (${report.team.name}) · ${report.month}${report.through ? ` · complete through ${report.through}` : ''}`];
+  const width = Math.max(...report.metrics.map((figure) => figure.metric.length));
+  for (const figure of report.metrics) {
+    const limit = figure.limit === null ? (figure.limitable ? 'no limit' : '') : `of ${amountText(figure, figure.limit)}${figure.limit === 0 ? ' (closed)' : ` (${Math.round((figure.value / figure.limit) * 100)} %)`}`;
+    const over = figure.limit !== null && figure.value >= figure.limit ? '  LIMIT REACHED' : '';
+    lines.push(`  ${figure.metric.padEnd(width)}  ${amountText(figure, figure.value).padStart(10)}  ${limit}${over}`.trimEnd());
+    for (const share of figure.applications) lines.push(`      ${(share.application?.code ?? 'no application').padEnd(32)} ${amountText(figure, share.value).padStart(10)}`);
+  }
+  if (report.current) lines.push('The metrics with a limit count today as it is now; the rest are complete up to yesterday.');
+  return lines;
+}
+
+async function usage(context) {
+  const { values, output } = context;
+  if (values.month !== undefined && !MONTH.test(values.month)) throw new UsageError(`«${values.month}» is not a month`, { fix: 'write it as YYYY-MM, such as --month 2026-10' });
+  const client = connect(context, loadProject(resolve(context.cwd, values.project ?? '.')));
+  const { data } = await client.request('GET', `/team/usage${values.month ? `?month=${values.month}` : ''}`);
+  for (const line of describeUsage(data)) output.log(line);
+  return data;
+}
+
+export default {
+  name: 'usage',
+  summary: 'What the team used in a month, with its limits',
+  description: 'Builds (minutes per platform, artifacts), updates (OTA), notifications, synchronization and testers\' devices, per application. A limit is set by a platform administrator; at 100 % the builds, notifications or devices it covers are refused with 409 limit_exceeded.',
+  options: { month: { type: 'string', value: '<YYYY-MM>', description: 'The month (the current one by default).' } },
+  run: usage,
+};

package/src/commands/vault/approvers.mjs

@@ -0,0 +1,129 @@
+// ias vault approvers: the passkeys that may approve a store build, signed by the team (ias-approvers-1, docs/technical/vault.md
+// §2.4 and docs/technical/runner-api.md §1). It reads the owners' passkeys from the server, shows each one (member, passkey and
+// fingerprint, worked out here) and what changes from the version the team signed before, which it verifies with the
+// team key of 1Password; a person confirms, and it signs the next version and uploads it. The server is not trusted:
+// a passkey it added would show up here as new, and a document it changed would not verify.
+import { isDeepStrictEqual } from 'node:util';
+import { IasError } from '../../errors.mjs';
+import { APPROVERS_FORMAT, approverAlgorithm, approverFingerprint, signApprovers, validateApprovers, verifyApprovers } from '../../shared.mjs';
+import { confirm, teamKeys } from './team.mjs';
+
+const ALGORITHMS = { '-7': 'ES256', '-257': 'RS256' };
+const day = (iso) => (typeof iso === 'string' ? iso.slice(0, 10) : 'unknown date');
+
+/**
+ * The passkeys the server lists, as approvers of the document: the algorithm and fingerprint worked out here (the
+ * server's are only compared), and those that cannot be one left out with a warning.
+ */
+function candidates(listed, output) {
+  const approvers = [];
+  for (const entry of listed) {
+    const label = `the passkey «${entry.passkey ?? '?'}» of ${entry.name ?? entry.member}`;
+    if (approvers.some((found) => found.approver.credential_id === entry.credential_id)) {
+      output.warn(`the server lists ${label} twice: kept once`);
+      continue;
+    }
+    const alg = approverAlgorithm(entry.public_key);
+    if (alg === null) {
+      output.warn(`${label} is not a P-256 or RSA (2048+) key: left out, it cannot approve a store build`);
+      continue;
+    }
+    if (entry.alg !== alg) output.warn(`the server says ${label} uses alg ${entry.alg}, but its key is ${ALGORITHMS[alg]} (${alg}): signing ${alg}`);
+    const fingerprint = approverFingerprint(entry.public_key);
+    if (entry.fingerprint !== undefined && entry.fingerprint !== fingerprint) output.warn(`the server gives ${label} the fingerprint ${entry.fingerprint}, but its key has ${fingerprint}: the one shown here is worked out from the key`);
+    const approver = { credential_id: entry.credential_id, public_key: entry.public_key, alg, member: entry.member, name: entry.name };
+    const problem = validateApprovers({ format: APPROVERS_FORMAT, version: 1, rp_id: 'example.com', origins: ['https://example.com'], approvers: [approver], signature: { kid: 'A'.repeat(43), sig: 'A'.repeat(86) } });
+    if (!problem.valid) {
+      output.warn(`${label} cannot go in the document (${problem.code}): left out`);
+      continue;
+    }
+    approvers.push({ approver, passkey: entry.passkey ?? null, fingerprint, registeredAt: entry.registered_at ?? null, lastUsedAt: entry.last_used_at ?? null });
+  }
+  return approvers;
+}
+
+/**
+ * The document the team signed before, verified with its key: { previous, version } (previous null if there is none).
+ * One that does not verify stops the command, unless --replace.
+ */
+function previousDocument(current, keys, context) {
+  const document = current?.document ?? null;
+  if (document === null) return { previous: null, version: 0 };
+  try {
+    const previous = verifyApprovers(document, keys.signing.publicKey);
+    return { previous, version: previous.version };
+  } catch (error) {
+    if (!context.values.replace) {
+      throw new IasError(`the approvers document of the server does not verify with the team's signing key (${error.code})`, {
+        fix: 'nothing was signed: someone may have changed it on the server; check the passkeys of the owners in the panel, and ias vault approvers --replace signs a new version over it',
+        code: 'approvers_document_invalid',
+      });
+    }
+    context.output.warn(`the approvers document of the server does not verify (${error.code}): --replace signs a new version over it, compared with nothing`);
+    return { previous: null, version: Number.isInteger(document.version) ? document.version : 0 };
+  }
+}
+
+export async function approvers(context, client, item) {
+  const { env, output } = context;
+  const { keys, signingKey } = await teamKeys(client, item, env);
+  const { data: listed } = await client.request('GET', '/team/approvers');
+  const { data: current } = await client.request('GET', '/team/approvers-document');
+  const { previous, version: previousVersion } = previousDocument(current, keys, context);
+  const found = candidates(listed.data ?? [], output);
+  if (found.length === 0) throw new IasError('no owner of the team has a passkey that can approve', { fix: 'an owner registers a passkey in the panel (System › Team), and then ias vault approvers signs it', code: 'no_approvers' });
+
+  const before = new Map((previous?.approvers ?? []).map((approver) => [approver.credential_id, approver]));
+  const rows = found.map((entry) => {
+    const signed = before.get(entry.approver.credential_id);
+    return { ...entry, change: !signed ? 'new' : isDeepStrictEqual(signed, entry.approver) ? 'signed' : 'changed' };
+  });
+  const listedIds = new Set(found.map((entry) => entry.approver.credential_id));
+  const removed = [...before.values()].filter((approver) => !listedIds.has(approver.credential_id));
+  const rpId = listed.rp_id;
+  const origins = listed.origins ?? [];
+  const sameTarget = previous !== null && previous.rp_id === rpId && isDeepStrictEqual([...previous.origins].sort(), [...origins].sort());
+  const unchanged = sameTarget && removed.length === 0 && rows.every((row) => row.change === 'signed');
+
+  output.progress(`rp_id    ${rpId}${previous && previous.rp_id !== rpId ? `  (CHANGES: it was ${previous.rp_id})` : ''}`);
+  output.progress(`origins  ${origins.join(', ')}${previous && !sameTarget && previous.rp_id === rpId ? `  (CHANGES: they were ${previous.origins.join(', ')})` : ''}`);
+  output.progress(previous ? `signed   version ${previous.version}, verified with the team's key (uploaded ${day(current.uploaded_at)})` : 'signed   nothing yet');
+  output.progress('');
+  for (const row of rows) {
+    const mark = { new: '+ NEW    ', changed: '! CHANGED', signed: '  signed ' }[row.change];
+    output.progress(`${mark}  ${row.approver.name} (${row.approver.member})  passkey «${row.passkey ?? '?'}», registered ${day(row.registeredAt)}${row.lastUsedAt ? `, last used ${day(row.lastUsedAt)}` : ''}`);
+    output.progress(`           fingerprint ${row.fingerprint}  ${ALGORITHMS[row.approver.alg]}  credential ${row.approver.credential_id}`);
+  }
+  for (const approver of removed) output.progress(`- REMOVED  ${approver.name} (${approver.member})  fingerprint ${approverFingerprint(approver.public_key)}`);
+
+  const result = {
+    rp_id: rpId,
+    origins,
+    previous_version: previous?.version ?? null,
+    approvers: rows.map(({ approver, passkey, fingerprint, change }) => ({ credential_id: approver.credential_id, alg: approver.alg, member: approver.member, name: approver.name, passkey, fingerprint, change })),
+    removed: removed.map((approver) => ({ credential_id: approver.credential_id, member: approver.member, name: approver.name, fingerprint: approverFingerprint(approver.public_key) })),
+  };
+  if (unchanged) {
+    output.log(`\nThe team already signed these ${rows.length} passkey${rows.length === 1 ? '' : 's'} (version ${previous.version}): nothing to sign.`);
+    return { ...result, version: previous.version, signed: false, in_sync: current.in_sync ?? null };
+  }
+
+  const version = Math.max(previousVersion, Number.isInteger(listed.document_version) ? listed.document_version : 0) + 1;
+  output.progress('');
+  output.progress('Check that each passkey is one of an owner you know, above all the NEW and CHANGED ones: from now on, the runners');
+  output.progress('build for the stores only what one of these passkeys approves. The server could have added one of its own.');
+  // Signed in memory first, so that a target the document cannot hold stops it before asking; uploaded after the yes.
+  let document;
+  try {
+    document = signApprovers({ version, rp_id: rpId, origins, approvers: rows.map((row) => row.approver) }, signingKey);
+  } catch (error) {
+    if (!/^approvers\.(rp_id|origins?)$/.test(error.code)) throw error;
+    throw new IasError(`the server gives an rp_id or origins that cannot be signed (${error.code})`, { fix: `the document takes a domain and https origins exactly as the browser writes them: check APP_URL on the server (it gives ${rpId} and ${origins.join(', ')})`, code: 'approvers_target_invalid' });
+  }
+  verifyApprovers(document, keys.signing.publicKey);
+  await confirm(context, `Sign version ${version} with these ${rows.length} passkey${rows.length === 1 ? '' : 's'}?`);
+  const { data: stored } = await client.request('PUT', '/team/approvers-document', { json: document });
+  if (!isDeepStrictEqual(stored.document, document)) output.warn('the server answered with another document than the one signed here: ias vault approvers again compares them');
+  output.log(`Signed version ${version} of the approvers with the team's key (${keys.signing.kid}) and uploaded it: the runners take it with their next store job.`);
+  return { ...result, version, signed: true, in_sync: stored.in_sync ?? null };
+}

package/src/commands/vault/index.mjs

@@ -0,0 +1,159 @@
+// ias vault init and status: the team's keys of the sealed vault (docs/technical/vault.md §2, docs/technical/manage-api.md §7). init makes
+// the recovery key (X25519) and the signing key (Ed25519), keeps both private keys in a new 1Password item without ever
+// printing them, and registers the public ones on the server, which waits for a member's approval with a passkey.
+// status compares the keys of the server with the ones of 1Password and checks the signed list of runners. approvers,
+// grant and revoke sign with the team's key what the runners trust (docs/technical/runner-api.md §1 and §2): approvers.mjs and
+// runners.mjs.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { connect, openUrl, sleep, waitForApproval } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { generateRecipient, generateSigningKey, recipientFromPrivateKey } from '../../shared.mjs';
+import { ITEM_FIELDS, compareKeys, createItem, publicKeysOf, readField, signedRunners, signingKeyOf, vaultItem } from '../../team-vault.mjs';
+import { approvers } from './approvers.mjs';
+import { grant, revoke } from './runners.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+/** Checks that the private keys of the item match its public keys, without keeping or showing them. */
+function checkPrivateKeys(item, keys, env) {
+  const recovery = readField(item, ITEM_FIELDS.recoveryPrivateKey, env);
+  let recoveryKid;
+  try {
+    recoveryKid = recovery === undefined ? undefined : recipientFromPrivateKey(recovery).kid;
+  } catch {
+    recoveryKid = undefined;
+  }
+  if (recoveryKid !== keys.recovery.kid) throw new IasError(`the recovery private key of ${item.reference} is missing or does not match its public key`, { fix: 'restore the item from 1Password\'s history, or move it away and run ias vault init again' });
+  signingKeyOf(item, keys, env);
+}
+
+async function init(context) {
+  const { env, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const item = vaultItem(context, project, client.server);
+  const { data: vault } = await client.request('GET', '/vault');
+  if (vault.recovery_key || vault.signing_key) {
+    throw new IasError(`the vault of ${client.server} already has its keys`, { fix: 'ias vault status compares them with the ones in 1Password (changing them is not in v1 of the API)', code: 'vault_keys_exist' });
+  }
+  let keys = publicKeysOf(item, env);
+  if (keys) {
+    output.progress(`${item.reference} already has the keys of the vault (an earlier ias vault init that was not approved): registering those.`);
+  } else {
+    const recovery = generateRecipient('recovery');
+    const signing = generateSigningKey();
+    createItem(item, { recovery, signing, server: client.server }, env);
+    keys = publicKeysOf(item, env);
+    if (!keys || keys.recovery.kid !== recovery.kid || keys.signing.kid !== signing.kid) throw new IasError(`1Password did not keep the keys in ${item.reference} as they were written`, { fix: 'look at the item in 1Password and run ias vault init again' });
+    output.progress(`Created ${item.reference} with the recovery key and the signing key of the team. Their private keys are only there.`);
+  }
+  checkPrivateKeys(item, keys, env);
+  output.log(`recovery key  ${keys.recovery.kid}`);
+  output.log(`signing key   ${keys.signing.kid}`);
+  const { status, data } = await client.request('POST', '/vault/keys', { json: { recovery_key: { public_key: keys.recovery.publicKey }, signing_key: { public_key: keys.signing.publicKey } } });
+  let registered = data;
+  if (status === 202) {
+    const { approval } = data;
+    const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(approval.url);
+    output.progress(`${opened ? 'Opened' : 'Open'} ${approval.url}: check that the panel shows these two kids, and approve it with a passkey (until ${approval.expires_at}).`);
+    registered = await waitForApproval(client, approval, { wait: context.sleep ?? sleep, output });
+  }
+  const remote = compareKeys(registered, keys);
+  if (remote.some((entry) => !entry.ok)) throw new IasError('the server registered other keys than the ones of 1Password', { fix: 'do not seal anything: ias vault status shows both, and someone may be tampering with the server', code: 'vault_keys_mismatch' });
+  output.log(`The vault of ${client.server} has its keys: credentials are sealed for the recovery key and signed by the team from now on.`);
+  return { server: client.server, item: item.reference, recovery_key: keys.recovery, signing_key: keys.signing, format: registered.format };
+}
+
+async function status(context) {
+  const { env, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const item = vaultItem(context, project, client.server);
+  const { data: vault } = await client.request('GET', '/vault');
+  const keys = publicKeysOf(item, env);
+  const rows = compareKeys(vault, keys);
+  output.log(`server  ${client.server} (${vault.format})`);
+  output.log(`item    ${item.reference}${keys ? '' : ' (not in 1Password)'}`);
+  for (const row of rows) {
+    const label = `${row.name} key`.padEnd(13);
+    if (row.ok) output.log(`${label} ok        ${row.local.kid}`);
+    else if (!row.server && !row.local) output.log(`${label} missing   neither on the server nor in 1Password: ias vault init`);
+    else if (!row.server) output.log(`${label} missing   not on the server (1Password has ${row.local.kid}): ias vault init registers it`);
+    else if (!row.local) output.log(`${label} unknown   the server has ${row.server.kid}, and 1Password has none to compare`);
+    else output.log(`${label} MISMATCH  the server has ${row.server.kid}, 1Password has ${row.local.kid}`);
+  }
+  let runners = { serial: null, runners: [], signed: false, problem: null };
+  if (keys && rows.every((row) => row.ok)) {
+    try {
+      const verified = signedRunners(vault, keys.signing, output);
+      runners = { serial: verified.serial, runners: verified.runners.map((runner) => runner.kid), signed: verified.serial !== null, problem: null };
+      output.log(verified.serial === null ? 'runners       none signed by the team yet (ias vault grant, Phase 2)' : `runners       ${verified.runners.length} in the list the team signed (serial ${verified.serial})`);
+      for (const runner of verified.runners) output.log(`  ${runner.kid}`);
+    } catch (error) {
+      runners.problem = error.code ?? 'runner_list_invalid';
+      output.log(`runners       NOT VERIFIED  ${error.what ?? error.message}`);
+    }
+  }
+  const ok = rows.every((row) => row.ok) && runners.problem === null;
+  const result = { server: client.server, item: item.reference, format: vault.format, ok, keys: rows.map(({ name, server, local, ok: same }) => ({ name, server_kid: server?.kid ?? null, local_kid: local?.kid ?? null, ok: same })), runners };
+  if (!ok) result[EXIT_CODE] = 1;
+  return result;
+}
+
+const itemOption = { 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 yesOption = { yes: { type: 'boolean', short: 'y', description: 'Do not ask: you have already compared what it prints (without a terminal it is needed).' } };
+const runnerArgument = { name: 'runner', description: 'The runner: its id, its name (in quotes if it has spaces) or its vault kid, as ias vault status and the panel list them.' };
+
+/** Runs a command that signs with the team's key: the client, the 1Password item and then `run`. */
+const signing = (run) => (context) => {
+  const project = projectOf(context);
+  const client = connect(context, project);
+  return run(context, client, vaultItem(context, project, client.server));
+};
+
+export default {
+  name: 'vault',
+  summary: 'The keys of the sealed vault, and what the team signs with them: the approvers and the runners',
+  description: 'The recovery key opens every sealed credential and the signing key signs each envelope (docs/technical/vault.md), the passkeys that may approve a store build and the list of runners. Their private keys live only in 1Password; the server has the public ones.',
+  subcommands: [
+    {
+      name: 'init',
+      summary: 'Create the recovery and signing keys in 1Password and register them (owner, with a passkey)',
+      description: 'Makes both keys, creates the 1Password item with op (the private keys go through stdin and are never printed), and asks the server to register the public keys. A member approves it with a passkey in the panel, after checking that it shows the two kids printed here. If the item already exists from an attempt that was not approved, its keys are registered.',
+      options: itemOption,
+      run: init,
+    },
+    {
+      name: 'status',
+      summary: 'Compare the keys of the server with the ones of 1Password, and check the signed list of runners',
+      description: 'Reads only the public keys of 1Password. Exits with 1 if a key does not match or the list of runners does not verify.',
+      options: itemOption,
+      run: status,
+    },
+    {
+      name: 'approvers',
+      summary: 'Sign the passkeys of the owners that may approve a store build (owner)',
+      description: 'Reads the owners\' passkeys from the server and shows each one with its member and fingerprint, marking what changes from the version the team signed before (verified with the team\'s key). After you confirm, it signs the next version of the ias-approvers-1 document with the team\'s key of 1Password and uploads it: the runners only build for the stores what one of these passkeys approved. Run it again after an owner adds or removes a passkey; the panel says so in Today.',
+      options: { ...itemOption, ...yesOption, replace: { type: 'boolean', description: 'Sign over a document of the server that does not verify with the team\'s key (after checking why).' } },
+      run: signing(approvers),
+    },
+    {
+      name: 'grant',
+      summary: 'Let a registered runner open the team\'s credentials: the signed list and a wrap in each envelope',
+      description: 'Shows the runner\'s vault kid for you to compare with the one ias-runner register printed on its Mac. Then it signs a runner list with it, uploads it, and wraps every envelope of the team (credentials and secret variables) for it, opening each one with the recovery key of 1Password and signing it again. Envelopes that do not verify are never signed again: it says which.',
+      positionals: [runnerArgument],
+      options: { ...itemOption, ...yesOption },
+      run: signing(grant),
+    },
+    {
+      name: 'revoke',
+      summary: 'Take a runner revoked in the panel out of the signed list and of every envelope',
+      description: 'Revoke it in the panel first (System › Runners): the server stops serving it at once. This signs a runner list without it and removes its wrap from every envelope, signing each one again, and lists what it could read, which is what to renew if its Mac may have been compromised (docs/technical/vault.md §10).',
+      positionals: [runnerArgument],
+      options: { ...itemOption, ...yesOption },
+      run: signing(revoke),
+    },
+  ],
+};

package/src/commands/vault/runners.mjs

@@ -0,0 +1,115 @@
+// ias vault grant and revoke: which runners can open the team's envelopes (docs/technical/vault.md §2.3 and §10, docs/technical/runner-api.md
+// §2). grant shows the runner's kid for the person to compare with the one ias-runner register printed on that Mac, signs
+// a runner list with it, uploads it, and wraps each envelope for it with the recovery key, signed again. revoke signs a
+// list without it and removes its wrap from each envelope, after the panel has revoked it. Both check every signature
+// with the team key of 1Password first: a list or an envelope that does not verify is never signed again.
+import { isDeepStrictEqual } from 'node:util';
+import { ApiError, IasError } from '../../errors.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { VaultError, recipientsOf, removeRecipient, rewrap, signRunnerList, verifyEnvelope, verifyRunnerList } from '../../shared.mjs';
+import { confirm, findRunner, sealedEnvelopes, signedList, teamKeys } from './team.mjs';
+
+/** Prints the runner for the person to compare with what its Mac says. */
+function showRunner(runner, output) {
+  output.progress(`runner      ${runner.name ?? '(the server does not list it)'}${runner.id ? `  ${runner.id}` : ''}`);
+  output.progress(`status      ${runner.status}${runner.platforms.length > 0 ? `, ${runner.platforms.join(' and ')}` : ''}${runner.registeredAt ? `, registered ${runner.registeredAt.slice(0, 10)}` : ''}`);
+  output.progress(`vault kid   ${runner.kid}`);
+}
+
+/** Signs and uploads the runner list `runners` with the next serial; checks what the server keeps. */
+async function uploadList(client, { serial, runners }, signingKey, keys, output) {
+  const list = signRunnerList({ serial: (serial ?? 0) + 1, runners }, signingKey);
+  verifyRunnerList(list, keys.signing.publicKey);
+  const { data } = await client.request('PUT', '/vault/runner-list', { json: list });
+  if (!isDeepStrictEqual(data.runner_list, list)) output.warn('the server answered with another runner list than the one signed here: ias vault status checks it');
+  return list;
+}
+
+/**
+ * Changes each envelope with `change(envelope)` (which returns the new envelope, or null to leave it) and sends it with
+ * PATCH /credentials/{id}/recipients. A failure of one does not stop the others: { changed, kept, problems }.
+ */
+async function changeEnvelopes(client, sealed, change, keys, output, verb) {
+  const changed = [];
+  const kept = [];
+  const problems = [];
+  for (const entry of sealed) {
+    const where = `${entry.label}${entry.application ? ` (${entry.application})` : ' (the team)'}`;
+    try {
+      const { data } = await client.request('GET', `/credentials/${entry.id}/envelope`);
+      if (data.envelope?.credential?.id !== entry.id) {
+        problems.push({ ...entry, code: 'envelope_of_another_credential', reason: null });
+        output.warn(`${where}: the server gives the envelope of another credential (${data.envelope?.credential?.id ?? 'none'}): not signed again`);
+        continue;
+      }
+      const next = change(data.envelope);
+      if (next === null) {
+        kept.push(entry);
+        continue;
+      }
+      verifyEnvelope(next, keys.signing.publicKey);
+      await client.request('PATCH', `/credentials/${entry.id}/recipients`, { json: { envelope: next } });
+      changed.push(entry);
+      output.progress(`  ${verb}  ${where}`);
+    } catch (error) {
+      const code = error.code ?? 'error';
+      if (!(error instanceof ApiError) && !(error instanceof VaultError)) throw error;
+      problems.push({ ...entry, code, reason: error.data?.reason ?? null });
+      output.warn(`${where}: ${error instanceof VaultError ? `its envelope does not verify with the team's key or does not open (${code}): not signed again` : error.message}`);
+    }
+  }
+  return { changed, kept, problems };
+}
+
+const describe = (entries) => entries.map(({ id, kind, label, application }) => ({ id, kind, label, application }));
+
+export async function grant(context, client, item) {
+  const { env, output } = context;
+  const { vault, keys, signingKey, recoveryKey } = await teamKeys(client, item, env, { recovery: true });
+  const signed = signedList(vault, keys, output);
+  const runner = findRunner(vault, signed, context.positionals[0]);
+  if (!runner.server) throw new IasError(`the server does not list the runner ${runner.kid}`, { fix: 'register it on its Mac with ias-runner register first', code: 'runner_not_found' });
+  if (runner.status === 'revoked') throw new IasError(`«${runner.name}» is revoked`, { fix: 'a revoked runner comes back registered again, with new keys: ias-runner register --force on its Mac', code: 'runner_revoked' });
+  showRunner(runner, output);
+  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);
+  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);
+  const target = [{ kid: runner.kid, publicKey: runner.publicKey }];
+  const { changed, kept, problems } = await changeEnvelopes(client, sealed, (envelope) => (recipientsOf(envelope).includes(runner.kid) ? null : rewrap(envelope, recoveryKey.privateKey, target, { signingKey })), keys, output, 'wrapped');
+  output.log(`«${runner.name}» can open ${changed.length + kept.length} of ${sealed.length} envelope${sealed.length === 1 ? '' : 's'} (${changed.length} wrapped now)${problems.length > 0 ? `; ${problems.length} could not be wrapped` : ''}.`);
+  const result = { runner: { id: runner.id, name: runner.name, kid: runner.kid }, runner_list: { serial: list?.serial ?? signed.serial, changed: list !== null }, wrapped: describe(changed), already: describe(kept), problems };
+  if (problems.length > 0) result[EXIT_CODE] = 1;
+  return result;
+}
+
+export async function revoke(context, client, item) {
+  const { env, output } = context;
+  const { vault, keys, signingKey } = await teamKeys(client, item, env);
+  const signed = signedList(vault, keys, output);
+  const runner = findRunner(vault, signed, context.positionals[0]);
+  if (runner.server && runner.status !== 'revoked') {
+    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);
+  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);
+  const { changed, problems } = await changeEnvelopes(client, sealed, (envelope) => (recipientsOf(envelope).includes(runner.kid) ? removeRecipient(envelope, runner.kid, { signingKey }) : null), keys, output, 'removed');
+  output.log(`Removed its wrap from ${changed.length} envelope${changed.length === 1 ? '' : 's'}${problems.length > 0 ? `; ${problems.length} could not be changed` : ''}.`);
+  if (changed.length > 0) {
+    output.log('It could read these (their current versions). If its Mac may have been compromised, renew them (docs/technical/vault.md §10):');
+    for (const entry of changed) output.log(`  ${entry.label}${entry.application ? ` (${entry.application})` : ' (the team)'}`);
+  }
+  const result = { runner: { id: runner.id, name: runner.name, kid: runner.kid }, runner_list: { serial: list?.serial ?? signed.serial, changed: list !== null }, removed: describe(changed), problems };
+  if (problems.length > 0) result[EXIT_CODE] = 1;
+  return result;
+}

package/src/commands/vault/team.mjs

@@ -0,0 +1,111 @@
+// What ias vault approvers, grant and revoke share: the team's keys read from 1Password and checked against the
+// server's, the confirmation of a person before signing, the runners the server lists and every sealed envelope of the
+// team (credentials and secret variables). The private keys stay in memory; nothing here prints or writes one.
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+import { ApiError, IasError } from '../../errors.mjs';
+import { publicRecipient, recipientFromPrivateKey } from '../../shared.mjs';
+import { ITEM_FIELDS, compareKeys, publicKeysOf, readField, signedRunners, signingKeyOf } from '../../team-vault.mjs';
+
+/**
+ * GET /vault and the keys of 1Password, checked against each other: { vault, keys, signingKey, recovery? }. With
+ * `recovery`, also the recovery key pair (its private key, to rewrap envelopes). Stops if the vault has no keys or the
+ * server's are not the item's.
+ */
+export async function teamKeys(client, item, env, { recovery = false } = {}) {
+  const { data: vault } = await client.request('GET', '/vault');
+  if (!vault.recovery_key || !vault.signing_key) throw new IasError('the vault has no keys yet', { fix: 'an owner of the team runs ias vault init', code: 'vault_not_ready' });
+  const keys = publicKeysOf(item, env);
+  if (!keys) throw new IasError(`there is no ${item.reference} in 1Password`, { fix: 'signing needs the item of the vault: ask an owner to share it with you, or point --item (IAS_VAULT_ITEM, vault.item of ias.json) at it' });
+  const mismatched = compareKeys(vault, keys).filter((entry) => !entry.ok);
+  if (mismatched.length > 0) {
+    throw new IasError(`the ${mismatched.map((entry) => entry.name).join(' and ')} key of the server is not the one in ${item.reference}`, {
+      fix: 'nothing was signed: ias vault status shows both; if the server changed them, someone may be trying to slip in a key of their own',
+      code: 'vault_keys_mismatch',
+    });
+  }
+  const signingKey = signingKeyOf(item, keys, env);
+  if (!recovery) return { vault, keys, signingKey };
+  const seed = readField(item, ITEM_FIELDS.recoveryPrivateKey, env);
+  let pair;
+  try {
+    pair = seed === undefined ? undefined : recipientFromPrivateKey(seed, 'recovery');
+  } catch {
+    pair = undefined;
+  }
+  if (!pair || pair.kid !== keys.recovery.kid) throw new IasError(`the recovery private key of ${item.reference} is missing or does not match its public key`, { fix: 'restore the item from 1Password\'s history; wrapping an envelope for a runner opens it with that key' });
+  return { vault, keys, signingKey, recoveryKey: pair };
+}
+
+/**
+ * Asks the person to confirm what the command printed: --yes, or «y» in a terminal. Without a terminal and without
+ * --yes it stops, because the point is that someone looked at the keys before the team signs them.
+ */
+export async function confirm(context, question) {
+  if (context.values.yes) return;
+  const stdin = context.stdin ?? process.stdin;
+  if (!stdin.isTTY) throw new IasError(`${question.replace(/\?$/, '')}: this needs a person to check it`, { fix: 'run it in a terminal, or pass --yes once you have compared what it printed', code: 'confirmation_required' });
+  const reader = createInterface({ input: stdin, output: context.output.json ? process.stderr : process.stdout });
+  try {
+    const answer = (await reader.question(`${question} [y/N] `)).trim();
+    if (!/^(y|yes|s|si|sí)$/i.test(answer)) throw new IasError('nothing was signed', { fix: 'run it again when the list is the one you expect', code: 'not_confirmed' });
+  } finally {
+    reader.close();
+  }
+}
+
+const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/**
+ * The runner `query` names (its id, its name or its vault kid) among the server's runners and the signed list: { id,
+ * name, status, kid, publicKey, platforms, registeredAt, server: true|false }. A kid of the signed list that the server
+ * no longer lists is found too, for revoke.
+ */
+export function findRunner(vault, signed, query) {
+  if (typeof query !== 'string' || query === '') throw new IasError('which runner?', { fix: 'give its id, name or kid: ias vault status and the panel (System › Runners) list them' });
+  const listed = Array.isArray(vault.runners) ? vault.runners : [];
+  const matches = listed.filter((runner) => runner.id === query || runner.kid === query || runner.name === query);
+  if (matches.length > 1) throw new IasError(`«${query}» names ${matches.length} runners`, { fix: `use the id of one: ${matches.map((runner) => `${runner.id} (${runner.name})`).join(', ')}` });
+  if (matches.length === 1) {
+    const [runner] = matches;
+    let checked;
+    try {
+      checked = publicRecipient({ kind: 'runner', kid: runner.kid, publicKey: runner.public_key });
+    } catch {
+      throw new IasError(`the server gives runner ${runner.id} a kid that is not the one of its key`, { fix: 'nothing was signed: the server may be tampered with; register the runner again', code: 'runner_key_mismatch' });
+    }
+    return { id: runner.id, name: runner.name, status: runner.status, kid: checked.kid, publicKey: checked.publicKey, platforms: runner.platforms ?? [], registeredAt: runner.registered_at ?? null, revokedAt: runner.revoked_at ?? null, server: true };
+  }
+  const inList = signed.runners.find((runner) => runner.kid === query);
+  if (inList) return { id: null, name: null, status: 'unknown', kid: inList.kid, publicKey: inList.publicKey, platforms: [], registeredAt: null, revokedAt: null, server: false };
+  throw new IasError(`there is no runner «${query}»${RUNNER_ID.test(query) ? '' : ' (a name with spaces goes in quotes)'}`, { fix: 'ias vault status and the panel (System › Runners) list them', code: 'runner_not_found' });
+}
+
+/** The runner list the team signed, as GET /vault gives it, checked with the team's key: { serial, runners }. */
+export const signedList = (vault, keys, output) => signedRunners(vault, keys.signing, output);
+
+/**
+ * Every envelope of the team that a runner may need: the credentials of each application the token sees and the
+ * team's, and the secret variables of each environment. Retired credentials are left out: no build uses them.
+ * [{ id, kind: 'credential'|'variable', label, application }].
+ */
+export async function sealedEnvelopes(client) {
+  const sealed = [];
+  const { data: apps } = await client.request('GET', '/apps');
+  for (const app of apps.data) {
+    for (const credential of (await client.request('GET', `/apps/${app.code}/credentials`)).data.data) {
+      if (!credential.retired_at) sealed.push({ id: credential.id, kind: 'credential', label: `${credential.type} «${credential.name}» v${credential.version}`, application: app.code });
+    }
+    for (const variable of (await client.request('GET', `/apps/${app.code}/env`)).data.data) {
+      if (variable.visibility === 'secret') sealed.push({ id: variable.id, kind: 'variable', label: `${variable.environment} ${variable.name} v${variable.version}`, application: app.code });
+    }
+  }
+  try {
+    for (const credential of (await client.request('GET', '/team/credentials')).data.data) {
+      if (!credential.retired_at) sealed.push({ id: credential.id, kind: 'credential', label: `${credential.type} «${credential.name}» v${credential.version}`, application: null });
+    }
+  } catch (error) {
+    if (!(error instanceof ApiError) || error.code !== 'role_forbidden') throw error;
+  }
+  return sealed;
+}