@imagina-build/ias-cli 0.2.1 → 0.3.0

package/src/commands/github/index.mjs

@@ -16,12 +16,19 @@ export function repositoryOf(text) {
 }
 
 async function link(context) {
-  const { positionals, output } = context;
+  const { values, positionals, output } = context;
   const project = projectOf(context);
   const code = applicationOf(context, project);
   const repository = repositoryOf(positionals[0]);
-  const { status, data } = await connect(context, project).request('PUT', `/apps/${code}/github`, { json: { repository } });
   const panel = `${serverOrigin(project, context.env)}/admin/applications/${code}/integrations`;
+  if (values['dry-run']) {
+    output.progress(`dry run: would link ${code} to github.com/${repository} (PUT /apps/${code}/github)`);
+    output.progress('  the server would make the secret of the webhook GitHub calls, or keep the one it already has, and show it once');
+    output.progress(`  the token of GitHub is loaded in the panel, with a passkey: ${panel}`);
+    output.progress('nothing was linked and no secret was shown.');
+    return { dry_run: true, app: code, repository, created: false, webhook_url: null, webhook_secret: null, token_set: false };
+  }
+  const { status, data } = await connect(context, project).request('PUT', `/apps/${code}/github`, { json: { repository } });
   output.log(`${code} is linked to github.com/${data.repository}.`);
   if (data.webhook_secret) {
     output.log('In the repository on GitHub (Settings › Webhooks › Add webhook):');
@@ -46,7 +53,10 @@ export default {
       name: 'link',
       summary: 'Link a repository; the first time, print the secret of the webhook GitHub will call',
       positionals: [{ name: 'repository', description: 'owner/name, or its https://github.com URL.' }],
-      options: { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } },
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would link, without linking it or showing the webhook secret.' },
+      },
       run: link,
     },
   ],

package/src/commands/policy/index.mjs

@@ -0,0 +1,583 @@
+// ias policy: the signed approval policy of the team (ias-policy-1, docs/plans/gaps/06-politica-aprobacion.md §3.8 and
+// docs/technical/vault.md §2.5). init writes ias.policy.json equivalent to today (one * rule, one approval, every owner
+// with a passkey); sign reads the team's Ed25519 key from 1Password, shows the diff, signs and uploads it, and an owner
+// approves the upload with a passkey. check, diff, simulate, show and status read and compare; they never write. The
+// server evaluates the policy when it creates a store job and when it approves one; the runner verifies it again.
+import { existsSync, writeFileSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError, UsageError } from '../../errors.mjs';
+import { connect, openUrl, sleep, waitForApproval } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { POLICY_FORMAT, policyHash, signPolicy, simulate, summary, verifyPolicy } from '../../shared.mjs';
+import { vaultItem } from '../../team-vault.mjs';
+import { confirm, teamKeys } from '../vault/team.mjs';
+import {
+  MAX_VERSION,
+  POLICY_FILE,
+  daysUntil,
+  defaultNotAfter,
+  diffLine,
+  diffPolicies,
+  holdersOf,
+  membersOf,
+  namesOf,
+  notAfterOf,
+  policyPath,
+  problemOf,
+  readPolicyFile,
+  requirementOf,
+  scopeOf,
+  serverPolicy,
+  signingKeyOfTeam,
+  unsignedOf,
+  verifiedPolicy,
+} from './policy.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+/** The version to write: --version, or the next one above the server's. */
+function versionOf(value, current) {
+  const version = value === undefined ? (current?.version ?? 0) + 1 : Number(value);
+  if (!Number.isInteger(version) || version < 1 || version > MAX_VERSION) {
+    throw new IasError(`«${value}» is not a policy version`, { fix: `an integer from 1 to ${MAX_VERSION}, above the one the server has`, code: 'policy.version' });
+  }
+  if (current?.version !== null && current?.version !== undefined && version <= current.version) {
+    throw new IasError(`the newest policy is version ${current.version}`, { fix: `sign a higher version: ias policy init --version ${current.version + 1}`, code: 'policy_version_backwards', details: { current: current.version } });
+  }
+  return version;
+}
+
+/** The rules an init writes: one * rule equivalent to today, with every owner that has a passkey. */
+const wildcardRule = (members) => ({ id: 'heredado', app: '*', platform: '*', profile: '*', type: '*', target: '*', track: '*', require: { members, count: 1 } });
+
+/** ias policy init: ias.policy.json with a policy equivalent to today. It never signs it. */
+async function init(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const current = await serverPolicy(client);
+  const listed = (await client.request('GET', '/team/approvers')).data;
+  const members = holdersOf(listed);
+
+  if (members.length === 0) {
+    throw new IasError('no owner of the team has a passkey to name in the policy', { fix: 'an owner signs the passkeys of the owners first: ias vault approvers', code: 'no_approvers' });
+  }
+
+  const version = versionOf(values.version, current);
+  const notAfter = values['not-after'] === undefined ? defaultNotAfter() : notAfterOf(values['not-after']);
+  if (Date.parse(notAfter) <= Date.now()) {
+    throw new IasError(`not_after ${notAfter} has already passed`, { fix: 'choose a future date, such as ias policy init --not-after 2027-04-28', code: 'policy.not_after' });
+  }
+
+  const document = { format: POLICY_FORMAT, version, not_after: notAfter, rules: [wildcardRule(members)] };
+  const problem = problemOf(document);
+  if (problem) throw new IasError(`the policy ias would write is not valid (${problem.code}): ${problem.message}`, { fix: 'report it: ias policy init builds it from the same rules the server checks', code: problem.code });
+
+  const path = policyPath(context, values.out);
+  if (existsSync(path) && values.force !== true) {
+    throw new IasError(`${path} already exists`, { fix: `edit it and sign it (ias policy sign ${path === policyPath(context) ? '' : path}), or pass --force to write it again`, code: 'policy_file_exists' });
+  }
+  writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+
+  output.log(`${path}: version ${version}, 1 wildcard rule and ${members.length} member${members.length === 1 ? '' : 's'} with a passkey. It expires on ${notAfter.slice(0, 10)}.`);
+  output.log(`It is not signed yet: ias policy sign${path === policyPath(context) ? '' : ` ${path}`} (an owner, with the 1Password key and a passkey).`);
+  return {
+    file: path,
+    version,
+    not_after: notAfter,
+    rules: 1,
+    members,
+    signed: false,
+    next: `ias policy sign${path === policyPath(context) ? '' : ` ${path}`}`,
+  };
+}
+
+/** A problem the check found, with the command or the place that fixes it. */
+const problem = (code, message, fix) => ({ code, message, fix: fix ?? 'edit the field the message names in the file, or write a new one with ias policy init --force' });
+
+/** The profiles of the ias.json of the project, which the check compares with the rules. */
+const profilesOf = (project) => Object.keys(project?.config?.build ?? {});
+
+/**
+ * ias policy check [file]: the shape and the semantics, the signature if the file has one, the version, the members,
+ * the date and the coverage, against the server. It writes nothing; exits 1 when something must be fixed.
+ */
+async function check(context) {
+  const { output } = context;
+  const [file] = context.positionals;
+  const path = policyPath(context, file);
+  const { document } = readPolicyFile(path);
+  const problems = [];
+  const warnings = [];
+  const local = problemOf(document);
+
+  if (local) {
+    problems.push(problem(local.code, local.message));
+    output.log(`${path}: it cannot be checked beyond its shape (${local.code}).`);
+    for (const entry of problems) output.log(`  · ${entry.code}: ${entry.message}\n    ${entry.fix}`);
+    return { file: path, ok: false, signed: document.signature !== undefined, problems, warnings, next: `ias policy init --force`, [EXIT_CODE]: 1 };
+  }
+
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const team = await signingKeyOfTeam(client, context, project);
+  if (team.warning) warnings.push({ code: 'policy.key', message: team.warning, fix: 'an owner can share the 1Password item: ias vault status compares the keys' });
+  const signed = document.signature !== undefined;
+
+  if (signed) {
+    try {
+      verifyPolicy(document, team.key, { checkExpiry: false });
+    } catch (error) {
+      problems.push(problem(error.code, error.message, 'the signature no longer covers what the file says: ias policy sign signs it again (and if you did not edit it, do not upload it)'));
+    }
+  }
+
+  const listed = (await client.request('GET', '/team/approvers')).data;
+  const holders = holdersOf(listed);
+  const current = await serverPolicy(client);
+  const unsigned = unsignedOf(document);
+  const sameAsServer = current?.document && current.version === unsigned.version && isDeepStrictEqual(unsignedOf(current.document), unsigned);
+
+  if (current?.document && !sameAsServer && unsigned.version <= current.version) {
+    problems.push(problem('policy_version_backwards', `version ${unsigned.version} does not go above the server's ${current.version}`, `raise the version in ${path} (ias policy init --version ${current.version + 1}) and sign it again`));
+  }
+
+  for (const member of membersOf(unsigned)) {
+    if (!holders.includes(member)) {
+      problems.push(problem('policy.member.passkey', `member ${member} has no passkey in the current ias-approvers-1`, 'add their passkey to the approvers document (ias vault approvers), or remove the member from the rule'));
+    }
+  }
+
+  if (unsigned.not_after !== undefined) {
+    const days = daysUntil(unsigned.not_after);
+    if (days <= 0) {
+      problems.push(problem('policy.not_after', `it expired on ${unsigned.not_after}`, `renew not_after in ${path} (ias policy init --not-after ${defaultNotAfter().slice(0, 10)}) and sign it with ias policy sign`));
+    } else if (days <= 30) {
+      warnings.push({ code: 'policy.expiring', message: `it expires in ${days} day${days === 1 ? '' : 's'} (${unsigned.not_after.slice(0, 10)})`, fix: 'renew not_after and sign a new version before it passes' });
+    }
+  }
+
+  let apps = [];
+  try {
+    apps = (await client.request('GET', '/apps')).data.data.map((application) => application.code);
+  } catch (error) {
+    warnings.push({ code: 'policy.apps', message: `the applications could not be read (${error.message})`, fix: 'the rest of the check goes on; ias policy check with a personal token reads them' });
+  }
+  for (const rule of unsigned.rules) {
+    if (rule.app !== '*' && apps.length > 0 && !apps.includes(rule.app)) {
+      warnings.push({ code: 'policy.rule.app', message: `rule ${rule.id} names ${rule.app}, which is not an application of the team`, fix: 'check the code, or create the application before signing' });
+    }
+  }
+
+  const report = summary(unsigned, { apps, profiles: profilesOf(project), members: holders, now: new Date() });
+  for (const entry of report.unsatisfiable) {
+    if (!problems.some((found) => found.code === 'policy.member.passkey')) {
+      problems.push(problem('policy.unsatisfiable', `rule ${entry.id} asks for ${entry.count} approvals and only ${entry.members.filter((member) => holders.includes(member)).length} of its members have a passkey`, 'add passkeys to the members of the rule, or lower its count'));
+    }
+  }
+  if (report.uncovered.length > 0) {
+    warnings.push({ code: 'policy.uncovered', message: `${report.uncovered.length} combinations of app, platform, profile and job have no rule: ${report.uncovered.slice(0, 3).map((entry) => `${entry.app}/${entry.platform}/${entry.profile}/${entry.type}${entry.target === '*' ? '' : `/${entry.target}`}${entry.track === '*' ? '' : `/${entry.track}`}`).join(', ')}${report.uncovered.length > 3 ? '…' : ''}`, fix: 'with a policy, a denial is the default: add a wildcard rule, or the rules that are missing' });
+  }
+
+  const ok = problems.length === 0;
+  output.log(`${path}: ${ok ? 'valid' : `${problems.length} problem${problems.length === 1 ? '' : 's'}`} · version ${unsigned.version} · ${signed ? 'signed' : 'not signed'} · ${unsigned.not_after === undefined ? 'no expiry' : `expires on ${unsigned.not_after.slice(0, 10)}`}`);
+  for (const entry of problems) output.log(`  · ${entry.code}: ${entry.message}\n    ${entry.fix}`);
+  for (const entry of warnings) output.warn(`${entry.code}: ${entry.message}${entry.fix ? ` — ${entry.fix}` : ''}`);
+  if (ok) output.log(`Next: ${signed ? 'ias policy diff' : `ias policy sign${file === undefined ? '' : ` ${file}`}`}.`);
+
+  return {
+    file: path,
+    ok,
+    signed,
+    version: unsigned.version,
+    not_after: unsigned.not_after ?? null,
+    problems,
+    warnings,
+    summary: report,
+    next: ok ? (signed ? 'ias policy diff' : 'ias policy sign') : `ias policy check ${path}`,
+    [EXIT_CODE]: ok ? 0 : 1,
+  };
+}
+
+/** ias policy sign [file]: shows the diff and the hash, asks, signs with the team key of 1Password and uploads it. */
+async function sign(context) {
+  const { values, env, output } = context;
+  const [file] = context.positionals;
+  const path = policyPath(context, file);
+  const { document } = readPolicyFile(path);
+  const local = problemOf(document);
+
+  if (local) {
+    throw new IasError(`${path} is not a valid policy (${local.code}): ${local.message}`, { fix: `ias policy check ${file ?? ''}`.trim() + ' says what to fix', code: local.code });
+  }
+
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const item = vaultItem(context, project, client.server);
+  const { keys, signingKey } = await teamKeys(client, item, env);
+
+  if (document.signature !== undefined) {
+    try {
+      verifyPolicy(document, keys.signing, { checkExpiry: false });
+    } catch (error) {
+      throw new IasError(`${path} has a signature that does not verify (${error.code})`, { fix: 'the file changed after it was signed (or it is another team\'s): restore it, or remove the signature to sign the rules it has now', code: 'policy.signature' });
+    }
+  }
+
+  const current = await serverPolicy(client);
+  const previous = verifiedPolicy(current, keys.signing);
+  const unsigned = unsignedOf(document);
+
+  if (unsigned.not_after !== undefined && Date.parse(unsigned.not_after) <= Date.now()) {
+    throw new IasError(`the policy expires on ${unsigned.not_after}, which has passed`, { fix: `renew not_after in ${path} (ias policy init --not-after ${defaultNotAfter().slice(0, 10)}) and sign it`, code: 'policy.not_after' });
+  }
+
+  const signedDocument = signPolicy(unsigned, signingKey);
+  verifyPolicy(signedDocument, keys.signing);
+
+  if (previous !== null && isDeepStrictEqual(previous, signedDocument)) {
+    output.log(`${path} is already the policy of the server (version ${previous.version}): nothing to sign.`);
+    return { file: path, version: previous.version, hash: policyHash(previous), signed: false, uploaded: false, in_sync: current.in_sync ?? null, next: 'ias policy diff' };
+  }
+  if (current?.version !== null && current?.version !== undefined && signedDocument.version <= current.version) {
+    throw new IasError(`the server already has version ${current.version}`, { fix: `raise the version in ${path} (ias policy init --version ${current.version + 1}) and sign again`, code: 'policy_version_backwards', details: { current: current.version } });
+  }
+
+  const diff = diffPolicies(previous, unsigned);
+  output.progress(`Version    ${signedDocument.version}${current?.version ? `  (the server's is ${current.version})` : '  (the first one)'}`);
+  output.progress(`Expires    ${signedDocument.not_after ?? 'never'}`);
+  output.progress(`Signature  ${signingKey.kid}`);
+  output.progress(`Hash       ${policyHash(signedDocument)}`);
+  output.progress(`Changes    ${previous === null ? 'the first policy of the team' : diffLine(diff)}`);
+  for (const rule of signedDocument.rules) output.progress(`  ${rule.id}: ${scopeOf(rule)} · ${requirementOf(rule)}`);
+  for (const member of diff.members_added) output.progress(`  + member ${member}`);
+  for (const member of diff.members_removed) output.progress(`  − member ${member}`);
+  output.progress('');
+  output.progress('With this policy, from now on every job no rule covers is denied, and each job keeps the version it was approved with.');
+  await confirm(context, `Sign version ${signedDocument.version} and ask an owner to approve it?`);
+
+  const { status, data } = await client.request('PUT', '/team/policy', { json: signedDocument });
+  let stored = data?.document;
+  let inSync = data?.in_sync ?? true;
+  let approval = null;
+
+  if (status === 202) {
+    approval = data.approval;
+    const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(approval.url);
+    output.progress(`${opened ? 'Opened' : 'Open'} ${approval.url}: an owner compares the hash and approves it with a passkey (until ${approval.expires_at}).`);
+    const result = await waitForApproval(client, approval, { wait: context.sleep ?? sleep, output });
+    stored = result?.document ?? null;
+    inSync = result?.in_sync ?? true;
+  }
+
+  if (stored === null || stored === undefined || !isDeepStrictEqual(stored, signedDocument)) {
+    throw new IasError('the server answered with another policy than the one signed here', { fix: 'ias policy show compares the policy of the server with 1Password; ias policy sign again if nothing was stored', code: 'policy_out_of_sync' });
+  }
+
+  output.log(`Signed version ${signedDocument.version} and stored it with an owner's approval. Hash ${policyHash(signedDocument)}.`);
+  output.log('From now on it decides which builds and submissions are approved; the jobs that were waiting with the previous version expire with policy_changed.');
+  return {
+    file: path,
+    version: signedDocument.version,
+    hash: policyHash(signedDocument),
+    kid: signedDocument.signature.kid,
+    document: signedDocument,
+    uploaded: true,
+    approval: approval === null ? null : { id: approval.id, url: approval.url, status: 'approved' },
+    in_sync: inSync,
+    next: 'ias policy status',
+  };
+}
+
+/** The policy of the server verified and printed, or null. */
+async function show(context) {
+  const { output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const team = await signingKeyOfTeam(client, context, project);
+  if (team.warning) output.warn(team.warning);
+  const current = await serverPolicy(client);
+  const policy = verifiedPolicy(current, team.key);
+
+  if (policy === null) {
+    output.log('The team has no policy: builds and submissions still take one owner\'s passkey, as today.');
+    output.log('To settle who approves what: ias policy init and then ias policy sign.');
+    return { policy: null, version: null, next: 'ias policy init' };
+  }
+
+  const names = namesOf((await client.request('GET', '/team/approvers')).data);
+  output.log(`Approval policy · version ${policy.version} · ${policy.not_after === undefined ? 'no expiry' : `expires on ${policy.not_after.slice(0, 10)} (${daysUntil(policy.not_after)} days)${daysUntil(policy.not_after) <= 0 ? ' · EXPIRED: ias policy init and ias policy sign' : ''}`}`);
+  output.log(`Key ${policy.signature.kid} · hash ${policyHash(policy)} · ${current.in_sync ? 'every member has a passkey' : 'THERE ARE MEMBERS WITHOUT A PASSKEY in the approvers'}`);
+  for (const rule of policy.rules) output.log(`  ${rule.id}: ${scopeOf(rule)} · ${requirementOf(rule, names)}`);
+  output.log('It decides the builds and store submissions: with a policy, whatever no rule covers is denied.');
+
+  return {
+    policy,
+    version: policy.version,
+    kid: policy.signature.kid,
+    not_after: policy.not_after ?? null,
+    hash: policyHash(policy),
+    rules: policy.rules.map((rule) => ({ ...rule, text: scopeOf(rule), members: rule.require.members.map((member) => ({ id: member, name: names[member] ?? null })) })),
+    in_sync: current.in_sync ?? null,
+    signed: true,
+    next: 'ias policy status',
+  };
+}
+
+/** ias policy status: what the server has, whether it verifies, how it compares with the file and what is missing. */
+async function status(context) {
+  const { output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const team = await signingKeyOfTeam(client, context, project);
+  if (team.warning) output.warn(team.warning);
+  const current = await serverPolicy(client);
+  const holders = holdersOf((await client.request('GET', '/team/approvers')).data);
+  let policy = null;
+  let verified = false;
+  let verification = null;
+
+  if (current.document) {
+    try {
+      policy = verifiedPolicy(current, team.key);
+      verified = true;
+    } catch (error) {
+      verification = { code: error.code, message: error.what ?? error.message };
+    }
+  }
+
+  const path = policyPath(context);
+  let local = null;
+  if (existsSync(path)) {
+    const read = readPolicyFile(path);
+    const localProblem = problemOf(read.document);
+    local = {
+      file: path,
+      version: read.document.version ?? null,
+      signed: read.document.signature !== undefined,
+      valid: localProblem === null,
+      ...(localProblem === null ? {} : { problem: { code: localProblem.code, message: localProblem.message } }),
+      in_sync: policy !== null && localProblem === null && isDeepStrictEqual(unsignedOf(policy), unsignedOf(read.document)),
+    };
+  }
+
+  let apps = [];
+  try {
+    apps = (await client.request('GET', '/apps')).data.data.map((application) => application.code);
+  } catch {
+    apps = [];
+  }
+  const report = policy === null ? null : summary(policy, { apps, profiles: profilesOf(project), members: holders, now: new Date() });
+  const inSync = policy !== null && verified && report.unsatisfiable.length === 0;
+  const next = policy === null
+    ? 'ias policy init'
+    : verification !== null
+      ? 'ias policy sign'
+      : report.expiring?.expired
+        ? `ias policy init --version ${policy.version + 1}`
+        : local !== null && !local.in_sync
+          ? 'ias policy diff'
+          : null;
+
+  output.log(`Policy      ${current.document === null ? 'none: today\'s behaviour' : policy === null ? `version ${current.version} · SIGNATURE NOT VERIFIED` : `version ${policy.version} · ${verified ? 'signature verified' : 'SIGNATURE NOT VERIFIED'}`}`);
+  if (policy !== null) {
+    output.log(`Expiry      ${policy.not_after === undefined ? 'never' : `${policy.not_after.slice(0, 10)} · ${daysUntil(policy.not_after)} days${report.expiring?.expired ? ' · EXPIRED' : report.expiring?.warning ? ' · renew soon' : ''}`}`);
+    output.log(`Members     ${report.unsatisfiable.length === 0 ? 'all with a passkey' : `${report.unsatisfiable.length} rules without enough passkeys`}`);
+    output.log(`Coverage    ${report.uncovered.length === 0 ? 'the apps and profiles in use have a rule' : `${report.uncovered.length} combinations without a rule`}`);
+  }
+  output.log(`File        ${local === null ? `${path} does not exist` : `${path} · version ${local.version ?? '?'} · ${local.valid ? (local.signed ? 'signed' : 'not signed') : `invalid (${local.problem.code})`}${local.in_sync ? ' · the same as the server\'s' : ''}`}`);
+  if (verification !== null) output.warn(`the policy of the server does not verify (${verification.code}): ${verification.message}`);
+  if (next !== null) output.log(`Next: ${next}.`);
+
+  return {
+    policy: policy === null ? null : { version: policy.version, verified, not_after: policy.not_after ?? null, days: policy.not_after === undefined ? null : daysUntil(policy.not_after), hash: policyHash(policy) },
+    verification,
+    local,
+    in_sync: inSync,
+    unsatisfiable: report?.unsatisfiable.map((entry) => entry.id) ?? [],
+    uncovered: report?.uncovered ?? [],
+    expiring: report?.expiring ?? null,
+    next,
+    ...(current.document && !verified ? { [EXIT_CODE]: 1 } : {}),
+  };
+}
+
+/** ias policy diff [file]: the rules and members that change from the server's policy to the file's. */
+async function diff(context) {
+  const { output } = context;
+  const [file] = context.positionals;
+  const path = policyPath(context, file);
+  const { document } = readPolicyFile(path);
+  const local = problemOf(document);
+  if (local) throw new IasError(`${path} is not a valid policy (${local.code}): ${local.message}`, { fix: `ias policy check ${file ?? ''}`.trim(), code: local.code });
+
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const team = await signingKeyOfTeam(client, context, project);
+  if (team.warning) output.warn(team.warning);
+  const current = await serverPolicy(client);
+  const previous = verifiedPolicy(current, team.key);
+  const changes = diffPolicies(previous, unsignedOf(document));
+
+  output.log(previous === null ? 'The server has no policy: the whole file is new.' : `From the server's (version ${previous.version}) to the file's (version ${document.version}):`);
+  for (const rule of changes.added) output.log(`  + ${rule.id}: ${scopeOf(rule)} · ${requirementOf(rule)}`);
+  for (const change of changes.changed) output.log(`  ~ ${change.after.id}: ${scopeOf(change.before)} → ${scopeOf(change.after)} · ${requirementOf(change.before)} → ${requirementOf(change.after)}`);
+  for (const rule of changes.removed) output.log(`  − ${rule.id}: ${scopeOf(rule)} · ${requirementOf(rule)}`);
+  for (const member of changes.members_added) output.log(`  + member ${member}`);
+  for (const member of changes.members_removed) output.log(`  − member ${member}`);
+  output.log(`  ${diffLine(changes)}`);
+  output.log(`Next: ${changes.added.length + changes.changed.length + changes.removed.length === 0 && changes.members_added.length + changes.members_removed.length === 0 ? 'nothing to sign' : `ias policy sign${file === undefined ? '' : ` ${file}`}`}.`);
+
+  return {
+    file: path,
+    server_version: previous?.version ?? null,
+    local_version: document.version ?? null,
+    added: changes.added.map((rule) => rule.id),
+    changed: changes.changed.map((entry) => entry.after.id),
+    removed: changes.removed.map((rule) => rule.id),
+    members_added: changes.members_added,
+    members_removed: changes.members_removed,
+    in_sync: previous !== null && isDeepStrictEqual(unsignedOf(previous), unsignedOf(document)),
+    next: `ias policy sign${file === undefined ? '' : ` ${file}`}`,
+  };
+}
+
+/** The target a submit goes to unless --target says otherwise. */
+const targetOf = (platform, values) => values.target ?? (platform === 'android' ? 'google_play' : 'app_store_connect');
+
+/** ias policy simulate: what the local policy would decide for a job, without approving anything. */
+function simulateCommand(context) {
+  const { values, output } = context;
+  const [file] = context.positionals;
+  if (file !== undefined && values.file !== undefined && file !== values.file) {
+    throw new UsageError(`the file is «${file}» and --file says «${values.file}»`, { fix: 'give it once: ias policy simulate <file> --platform ios --profile production' });
+  }
+  const path = policyPath(context, file ?? values.file);
+  const { document } = readPolicyFile(path);
+  const local = problemOf(document);
+  if (local) throw new IasError(`${path} is not a valid policy (${local.code}): ${local.message}`, { fix: `ias policy check ${file ?? values.file ?? ''}`.trim(), code: local.code });
+
+  const project = projectOf(context);
+  const app = values.app ?? project.config?.app;
+  if (!app) throw new IasError('which application?', { fix: 'pass --app <code>, or run it in the folder of an app with an ias.json', code: 'application_missing' });
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(app)) throw new IasError(`«${app}» is not the code of an application`, { fix: 'ias apps lists them', code: 'application_invalid' });
+  if (values.platform === undefined) throw new IasError('which platform?', { fix: 'pass --platform ios or --platform android', code: 'policy.platform' });
+  if (!['ios', 'android'].includes(values.platform)) throw new IasError(`«${values.platform}» is not a platform`, { fix: '--platform ios or --platform android', code: 'policy.platform' });
+  if (values.profile === undefined) throw new IasError('which profile?', { fix: 'pass --profile production (the name of a profile of ias.json)', code: 'policy.profile' });
+  const type = values.type ?? 'build';
+  if (!['build', 'submit', 'testflight', 'release'].includes(type)) throw new IasError(`«${type}» is not a job type`, { fix: '--type build, submit, testflight or release', code: 'policy.type' });
+  const submit = type === 'submit';
+  const release = type === 'release';
+  const target = submit ? targetOf(values.platform, values) : type === 'testflight' ? 'app_store_connect' : release ? 'google_play' : undefined;
+  const track = target === 'google_play' ? values.track ?? (release ? 'production' : 'internal') : undefined;
+  const job = { app, platform: values.platform, profile: values.profile, type, ...(target === undefined ? {} : { target, track }) };
+
+  let result;
+  try {
+    result = simulate(document, job, { now: new Date() });
+  } catch (error) {
+    throw new IasError(error.message, { fix: 'check --target and --track: a submit to Google Play names its track, and to App Store Connect has none', code: error.code });
+  }
+
+  output.log(`${app} · ${values.platform === 'ios' ? 'iOS' : 'Android'} · ${values.profile} · ${type}${target === undefined ? '' : ` · ${target}${track ? ` · track ${track}` : ''}`}`);
+  if (result.allowed) {
+    output.log(`Rule ${result.rule.id} (specificity ${result.specificity}): ${scopeOf(result.rule)}`);
+    output.log(`Approved by ${requirementOf(result.rule)}.`);
+  } else {
+    output.log(`Denied (${result.code}): ${result.message}`);
+  }
+  const next = result.allowed ? null : result.code === 'policy.expired' ? 'ias policy sign' : 'ias policy diff';
+  if (next !== null) output.log(`Next: ${next} (or add the rule to ias.policy.json and check it with ias policy check).`);
+
+  return {
+    job,
+    allowed: result.allowed,
+    code: result.code,
+    message: result.message,
+    rule: result.rule === null ? null : { id: result.rule.id, ...result.rule, text: scopeOf(result.rule), requirement: requirementOf(result.rule) },
+    specificity: result.specificity,
+    version: result.version,
+    next,
+    ...(result.allowed ? {} : { [EXIT_CODE]: 1 }),
+  };
+}
+
+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://IAS/IAS vault <host>).' } };
+const yesOption = { yes: { type: 'boolean', short: 'y', description: 'Do not ask: you have already compared the diff and the hash (without a terminal it is needed).' } };
+const fileArgument = { name: 'file', optional: true, description: `The policy file (${POLICY_FILE} in the project by default).` };
+
+export default {
+  name: 'policy',
+  summary: 'The signed policy of who approves which build or submission, and how many',
+  description: `The team signs an ${POLICY_FORMAT} document with the key of 1Password (docs/technical/vault.md §2.5): for each application, platform, profile, job type and, for a submission, store and track, it names the members who may approve and how many of them. Without a policy everything behaves as today; with one, a store job no rule covers is denied and the runner verifies the same signed policy before running it.`,
+  subcommands: [
+    {
+      name: 'init',
+      summary: 'Write ias.policy.json equivalent to today: one * rule, one approval, every owner with a passkey',
+      description: 'Reads the owners with a passkey from the server and writes the source of the policy; it does not sign it. The version is the next above the server\'s unless --version says otherwise, and it expires in 180 days unless --not-after says otherwise. It never overwrites an existing file without --force.',
+      options: {
+        out: { type: 'string', value: '<file>', description: `Where to write it (${POLICY_FILE} in the project by default).` },
+        version: { type: 'string', value: '<n>', description: 'The version to write (the next above the server\'s by default).' },
+        'not-after': { type: 'string', value: '<date>', description: 'When it expires: 2027-04-28 or a whole UTC timestamp (180 days from today by default).' },
+        force: { type: 'boolean', description: 'Write the file even if it already exists.' },
+      },
+      run: init,
+    },
+    {
+      name: 'check',
+      summary: 'Check a policy file against the format, the members, the version and the server; writes nothing',
+      description: 'Validates the shape and the semantics, verifies the signature if the file has one, and compares the version, the members (each needs a passkey in the current ias-approvers-1), the date and the coverage with the server. Exits 1 when something must be fixed and says the exact command or edit for each problem.',
+      positionals: [fileArgument],
+      options: itemOption,
+      run: check,
+    },
+    {
+      name: 'sign',
+      summary: 'Sign the policy with the team key of 1Password and upload it (owner, with a passkey)',
+      description: 'Shows the version, the date, the hash, the diff from the policy the server has and the rules, then asks. It signs with the Ed25519 key of the vault item (read with op, never printed), uploads the document and opens the approval URL: an owner compares the hash and approves it with a passkey before anything is stored.',
+      positionals: [fileArgument],
+      options: { ...itemOption, ...yesOption },
+      run: sign,
+    },
+    {
+      name: 'show',
+      summary: 'Show the policy of the server, verified with the team key, with the rules and their members',
+      description: 'Reads GET /team/policy, verifies the signature with the team\'s signing key (compared with 1Password when it is there) and prints the version, the date, the hash and each rule with the members who may approve it. Exits 1 if the server\'s policy does not verify.',
+      options: itemOption,
+      run: show,
+    },
+    {
+      name: 'status',
+      summary: 'The policy of the server against the local file: verified, expiring, uncovered, in sync',
+      description: 'Says whether there is a policy, whether its signature verifies, when it expires, which rules lack members with a passkey, which app/profile combinations no rule covers, and whether ias.policy.json is the one of the server. Exits 1 only when the server\'s policy does not verify.',
+      options: itemOption,
+      run: status,
+    },
+    {
+      name: 'diff',
+      summary: 'Compare the local policy with the one of the server: rules and members added, changed or removed',
+      description: 'Verifies the policy of the server with the team key, strips the signature from the local file if it has one, and prints the rules that appear, change or go and the members that enter or leave. It writes nothing.',
+      positionals: [fileArgument],
+      options: itemOption,
+      run: diff,
+    },
+    {
+      name: 'simulate',
+      summary: 'What the local policy would decide for a job: the rule that matches, or the denial',
+      description: 'Matches app, platform, profile and type (and, for a submit, target and track) with the rules of the local file, choosing the most specific one, and prints the rule and who may approve it. A testflight matches as a submission to App Store Connect and a release as one to Google Play with its track. Exits 1 when no rule matches: with a policy, the server denies that job.',
+      positionals: [fileArgument],
+      options: {
+        file: { type: 'string', value: '<file>', description: `The policy file (${POLICY_FILE} in the project by default); the positional form is the same.` },
+        app: { type: 'string', value: '<code>', description: 'The application (app in ias.json by default).' },
+        platform: { type: 'string', value: 'ios|android', description: 'The platform of the job (needed, with --profile).' },
+        profile: { type: 'string', value: '<name>', description: 'The build profile of the job (needed, with --platform).' },
+        type: { type: 'string', value: 'build|submit|testflight|release', description: 'The job type (build by default).' },
+        target: { type: 'string', value: 'app_store_connect|google_play', description: 'The store of a submit (its platform\'s by default).' },
+        track: { type: 'string', value: '<track>', description: 'The Google Play track of a submit or a release (internal for a submit, production for a release, by default).' },
+      },
+      run: simulateCommand,
+    },
+  ],
+};