@imagina-build/ias-cli 0.2.2 → 0.3.1

package/shared/vault/policy.mjs

@@ -0,0 +1,427 @@
+// The signed approval policy of the team (ias-policy-1, docs/plans/gaps/06-politica-aprobacion.md §3.2–§3.5 and
+// docs/technical/vault.md §2.5): which passkeys may approve which store job and how many of them, for every combination
+// of application, platform, build profile, job type and, for a submission, target and Google Play track. The team signs
+// it with the same Ed25519 key as the envelopes, the runner list and the approvers; the server stores it, verifies its
+// signature (the one deliberate difference with the other documents) and serves it, and the runner verifies it again.
+//
+// This module only defines the document, its canonical text, its signature and the matching: it does not approve jobs
+// nor gate anything. Without a policy the platform behaves as before (one passkey of an owner). Only node:crypto.
+import { Buffer } from 'node:buffer';
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+import { KEY_BYTES, LIMITS, SIGNATURE_BYTES, VaultError, decode, encode, keyId, signingKeyFromPrivateKey } from './index.mjs';
+
+export const POLICY_FORMAT = 'ias-policy-1';
+
+/** The limits of the format. The server enforces the same ones; changing them changes the format. */
+export const POLICY_LIMITS = Object.freeze({
+  /** The JSON text of the whole document, signature included. */
+  bytes: 64 * 1024,
+  rules: 64,
+  members: 64,
+  /** The most approvals a rule may ask for: more is a sign that the rule is wrong. */
+  count: 8,
+});
+
+/** What a job has to match: the only fields of the canonical text of a job that choose a rule (§3.3). */
+export const POLICY_FIELDS = Object.freeze(['app', 'platform', 'profile', 'type', 'target', 'track']);
+
+export const POLICY_PLATFORMS = Object.freeze(['ios', 'android', '*']);
+export const POLICY_TYPES = Object.freeze(['build', 'submit', '*']);
+export const POLICY_TARGETS = Object.freeze(['app_store_connect', 'google_play', '*']);
+
+const DOCUMENT_FIELDS = ['format', 'version', 'rules', 'signature'];
+const RULE_FIELDS = ['id', 'app', 'platform', 'profile', 'type', 'target', 'track', 'require'];
+const REQUIRE_FIELDS = ['members', 'count'];
+const RULE_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const APP = RULE_ID;
+/**
+ * A Google Play track as Google names it: production, beta, alpha, internal, a closed one or a form factor's
+ * (wear:production, automotive:production). One pattern for the policy document, the CLI and the runner, so the `:` of
+ * a form factor is accepted everywhere the identifier travels.
+ */
+export const PLAY_TRACK = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+const PROFILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,49}$/;
+const TRACK = PLAY_TRACK;
+const MEMBER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const NOT_AFTER = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const sameKeys = (object, keys) => {
+  const own = Object.keys(object).sort();
+  return own.length === keys.length && [...keys].sort().every((key, index) => own[index] === key);
+};
+
+/** A UTC timestamp exactly as the format writes it: YYYY-MM-DDTHH:MM:SSZ, and a day that exists. */
+export function isNotAfter(value) {
+  if (typeof value !== 'string' || !NOT_AFTER.test(value)) return false;
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z') === value;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Shape and semantics (§3.2 and §3.3).
+
+/** The first problem of one rule, as [code, message], or null. */
+function ruleProblem(rule) {
+  if (!isRecord(rule) || !sameKeys(rule, RULE_FIELDS)) return ['policy.rule', `each rule must be an object with exactly ${RULE_FIELDS.join(', ')}`];
+  if (typeof rule.id !== 'string' || !RULE_ID.test(rule.id)) return ['policy.rule.id', 'rule.id must be 1 to 32 characters of a-z 0-9 - and start with a letter or digit'];
+  if (rule.app !== '*' && (typeof rule.app !== 'string' || !APP.test(rule.app))) return ['policy.rule.app', 'rule.app must be * or the code of an application: 1 to 32 characters of a-z 0-9 - that start with a letter or digit'];
+  if (!POLICY_PLATFORMS.includes(rule.platform)) return ['policy.rule.platform', 'rule.platform must be ios, android or *'];
+  if (rule.profile !== '*' && (typeof rule.profile !== 'string' || !PROFILE.test(rule.profile))) return ['policy.rule.profile', 'rule.profile must be * or the name of a profile: 1 to 50 characters of A-Z a-z 0-9 . _ - that start with a letter or digit'];
+  if (!POLICY_TYPES.includes(rule.type)) return ['policy.rule.type', 'rule.type must be build, submit or * (resign is reserved: no rule may name it yet)'];
+  if (!POLICY_TARGETS.includes(rule.target)) return ['policy.rule.target', 'rule.target must be app_store_connect, google_play or *'];
+  if (rule.target !== '*' && rule.type !== 'submit') return ['policy.rule.target', 'rule.target must be * unless rule.type is submit: a build does not go to a store'];
+  if (rule.track !== '*' && (typeof rule.track !== 'string' || !TRACK.test(rule.track))) return ['policy.rule.track', 'rule.track must be * or a Google Play track: 1 to 64 characters of A-Z a-z 0-9 . _ : - that start with a letter or digit'];
+  if (rule.track !== '*' && (rule.type !== 'submit' || rule.target !== 'google_play')) return ['policy.rule.track', 'rule.track must be * unless rule.type is submit and rule.target is google_play'];
+  if (!isRecord(rule.require) || !sameKeys(rule.require, REQUIRE_FIELDS)) return ['policy.rule.require', `each rule.require must be an object with exactly ${REQUIRE_FIELDS.join(', ')}`];
+  const members = rule.require.members;
+  if (!Array.isArray(members) || members.length === 0 || members.length > POLICY_LIMITS.members) return ['policy.rule.members', `rule.require.members must be a list of 1 to ${POLICY_LIMITS.members} member ids`];
+  const seen = new Set();
+  for (const member of members) {
+    if (typeof member !== 'string' || !MEMBER.test(member)) return ['policy.rule.member', 'each member must be the id of a member: 1 to 128 characters of A-Z a-z 0-9 . _ - that start with a letter or digit'];
+    if (seen.has(member)) return ['policy.rule.member', `${member} is in the members of a rule twice`];
+    seen.add(member);
+  }
+  const { count } = rule.require;
+  if (!Number.isInteger(count) || count < 1 || count > POLICY_LIMITS.count) return ['policy.rule.count', `rule.require.count must be an integer from 1 to ${POLICY_LIMITS.count}: never 0`];
+  if (count > members.length) return ['policy.rule.count', `rule.require.count (${count}) is more than the members of the rule (${members.length})`];
+  return null;
+}
+
+/** How many fields of a rule are not *: 0 to 6 (§3.3). */
+export function specificityOf(rule) {
+  return POLICY_FIELDS.filter((field) => rule[field] !== '*').length;
+}
+
+/** Whether two rules can match the same job: no field has a different concrete value in each one. */
+function compatible(first, second) {
+  return POLICY_FIELDS.every((field) => first[field] === second[field] || first[field] === '*' || second[field] === '*');
+}
+
+/** The two rules that tie, as [code, message], or null: the document would not be deterministic (§3.1, rule 5). */
+function ambiguityProblem(rules) {
+  for (let index = 0; index < rules.length; index += 1) {
+    for (let other = index + 1; other < rules.length; other += 1) {
+      if (!compatible(rules[index], rules[other])) continue;
+      if (specificityOf(rules[index]) !== specificityOf(rules[other])) continue;
+      return ['policy.rule.ambiguous', `the rules ${rules[index].id} and ${rules[other].id} both match the same job with specificity ${specificityOf(rules[index])}: no rule wins, so the document is invalid`];
+    }
+  }
+  return null;
+}
+
+/** The first problem of a policy document, as [code, message], or null. The signature is checked last, as in the others. */
+function documentProblem(document, { signingKid } = {}) {
+  if (!isRecord(document)) return ['policy', 'the policy must be a JSON object'];
+  if (document.format !== POLICY_FORMAT) return ['policy.format', `the format must be ${POLICY_FORMAT}`];
+  const fields = [...DOCUMENT_FIELDS, ...('not_after' in document ? ['not_after'] : [])];
+  if (!sameKeys(document, fields)) return ['policy.fields', `a policy must have exactly ${DOCUMENT_FIELDS.join(', ')} and, optionally, not_after`];
+  if (!Number.isInteger(document.version) || document.version < 1 || document.version > LIMITS.version) return ['policy.version', `version must be an integer from 1 to ${LIMITS.version}`];
+  if ('not_after' in document && !isNotAfter(document.not_after)) return ['policy.not_after', 'not_after must be a UTC timestamp as YYYY-MM-DDTHH:MM:SSZ, such as 2027-04-28T00:00:00Z'];
+  const { rules } = document;
+  if (!Array.isArray(rules) || rules.length === 0 || rules.length > POLICY_LIMITS.rules) return ['policy.rules', `rules must be a list of 1 to ${POLICY_LIMITS.rules} rules`];
+  const ids = new Set();
+  for (const rule of rules) {
+    const problem = ruleProblem(rule);
+    if (problem) return problem;
+    if (ids.has(rule.id)) return ['policy.rule.duplicate', `${rule.id} is the id of two rules`];
+    ids.add(rule.id);
+  }
+  const ambiguity = ambiguityProblem(rules);
+  if (ambiguity) return ambiguity;
+  const { signature } = document;
+  if (!isRecord(signature) || !sameKeys(signature, ['kid', 'sig'])) return ['signature', 'signature must be an object with exactly kid and sig'];
+  if (decode(signature.kid)?.length !== KEY_BYTES) return ['signature.kid', `signature.kid must be ${KEY_BYTES} bytes in unpadded base64url`];
+  if (decode(signature.sig)?.length !== SIGNATURE_BYTES) return ['signature.sig', `signature.sig must be ${SIGNATURE_BYTES} bytes in unpadded base64url`];
+  if (signingKid !== undefined && signature.kid !== signingKid) return ['signature.unknown', `the policy must be signed with the team's key ${signingKid}`];
+  return null;
+}
+
+/**
+ * Checks the shape and the semantics of a policy (an object or its JSON) without verifying its signature:
+ * { valid: true } or { valid: false, code, message } for the first problem. With `signingKid`, the signature must carry
+ * it. The codes are the ones of docs/technical/vault.md §6.5, and PHP gives the same ones.
+ */
+export function validatePolicy(document, { signingKid } = {}) {
+  let value = document;
+  if (typeof document === 'string') {
+    if (Buffer.byteLength(document, 'utf8') > POLICY_LIMITS.bytes) return { valid: false, code: 'policy.too_large', message: `the policy must not exceed ${POLICY_LIMITS.bytes} bytes` };
+    try {
+      value = JSON.parse(document);
+    } catch {
+      return { valid: false, code: 'policy', message: 'the policy is not JSON' };
+    }
+  }
+  const problem = documentProblem(value, { signingKid });
+  return problem ? { valid: false, code: problem[0], message: problem[1] } : { valid: true };
+}
+
+/** The placeholder signature of a document that is not signed yet: 32 bytes of kid and 64 of signature. */
+export const DRAFT_SIGNATURE = Object.freeze({ kid: 'A'.repeat(43), sig: 'A'.repeat(86) });
+
+/**
+ * Checks the shape and the semantics of a policy that has not been signed yet (the file ias policy init
+ * writes and ias policy check reads): the same checks as validatePolicy, with a placeholder signature.
+ * It does not verify any signature.
+ */
+export function validatePolicyDraft(document) {
+  return validatePolicy({ format: POLICY_FORMAT, ...document, signature: { ...DRAFT_SIGNATURE } });
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Canonical text and signature (§3.2 and docs/technical/vault.md §5.4).
+
+/**
+ * What the team signs in a policy: the format, the purpose word `policy`, the kid and the version; the optional
+ * not_after or `-`; the number of rules; and then nine lines per rule in order (id, app, platform, profile, type,
+ * target, track, count and the number of members) plus one line per member, in the order written. There is no rule
+ * encoding beyond that: every value is one line exactly as the JSON has it, and no value can hold a newline (the
+ * patterns forbid it), so the text reads back one way only.
+ */
+export function policyText(document, signingKid) {
+  const lines = [POLICY_FORMAT, 'policy', signingKid, String(document.version), document.not_after ?? '-', String(document.rules.length)];
+  for (const rule of document.rules) {
+    lines.push(rule.id, rule.app, rule.platform, rule.profile, rule.type, rule.target, rule.track, String(rule.require.count), String(rule.require.members.length), ...rule.require.members);
+  }
+  return Buffer.from(lines.join('\n'), 'utf8');
+}
+
+/** The SHA-256 of the canonical text, in base64url: what the panel and the CLI show as the hash of a policy. */
+export function policyHash(document) {
+  const kid = document?.signature?.kid ?? '-';
+  return encode(createHash('sha256').update(policyText(withoutSignature(document), kid)).digest());
+}
+
+/** The team's Ed25519 key from its seed or pair, for signing: { kid, object }. */
+function signerOf(signingKey) {
+  const seed = typeof signingKey === 'string' ? signingKey : signingKey?.privateKey;
+  if (typeof seed !== 'string') throw new VaultError('signing-key', 'the policy is signed with the team\'s signing key (its private key)');
+  const pair = signingKeyFromPrivateKey(seed);
+  return { kid: pair.kid, object: createPrivateKey({ key: { kty: 'OKP', crv: 'Ed25519', d: seed, x: pair.publicKey }, format: 'jwk' }) };
+}
+
+/** The team's public key the CLI or the runner pinned (base64url or { publicKey, kid? }): { kid, object }. */
+function verifierOf(signedBy) {
+  const publicKey = typeof signedBy === 'string' ? signedBy : signedBy?.publicKey;
+  const raw = typeof publicKey === 'string' ? decode(publicKey) : null;
+  if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('signing-key', 'the policy is checked against the team\'s signing public key (32 bytes in base64url)');
+  if (isRecord(signedBy) && signedBy.kid !== undefined && signedBy.kid !== keyId(raw)) throw new VaultError('signing-key', 'the kid does not match the signing public key');
+  let object = null;
+  try {
+    object = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey }, format: 'jwk' });
+  } catch {
+    object = null; // bytes that are no point of the curve: nothing verifies against them
+  }
+  return { kid: keyId(raw), object };
+}
+
+/** The fields of a document in their order, without the signature: format, version, not_after (if any) and rules. */
+function withoutSignature(document) {
+  const unsigned = { format: document.format, version: document.version, ...('not_after' in document ? { not_after: document.not_after } : {}), rules: document.rules };
+  return unsigned;
+}
+
+/** A rule with its fields in their order, and its require with members and count. */
+function normalizedRule(rule) {
+  const require = isRecord(rule.require)
+    ? { members: Array.isArray(rule.require.members) ? [...rule.require.members] : rule.require.members, count: rule.require.count }
+    : rule.require;
+
+  return {
+    id: rule.id,
+    app: rule.app,
+    platform: rule.platform,
+    profile: rule.profile,
+    type: rule.type,
+    target: rule.target,
+    track: rule.track,
+    require,
+  };
+}
+
+/**
+ * The policy of `version` and `rules`, signed with the team's `signingKey` (its seed or pair):
+ * { format, version, not_after?, rules, signature }. The order of the rules and of their members is kept and covered by
+ * the signature. Throws a VaultError with the code of validatePolicy for the first problem.
+ */
+export function signPolicy({ version, not_after: notAfter, rules }, signingKey) {
+  const signer = signerOf(signingKey);
+  const unsigned = {
+    format: POLICY_FORMAT,
+    version,
+    ...(notAfter === undefined ? {} : { not_after: notAfter }),
+    rules: Array.isArray(rules) ? rules.map((rule) => (isRecord(rule) ? normalizedRule(rule) : rule)) : rules,
+  };
+  const problem = documentProblem({ ...unsigned, signature: { kid: signer.kid, sig: encode(Buffer.alloc(SIGNATURE_BYTES)) } }, {});
+  if (problem) throw new VaultError(...problem);
+  return { ...unsigned, signature: { kid: signer.kid, sig: encode(sign(null, policyText(unsigned, signer.kid), signer.object)) } };
+}
+
+/**
+ * The policy checked against `signedBy`, the team's public signing key (base64url or { kid, publicKey }): its shape and
+ * semantics, that it is signed with that key, that the signature verifies, that it has not expired with `now` (a Date,
+ * by default now; `checkExpiry: false` checks only the signature, which is what reading an expired policy to replace
+ * it needs) and, with `minimumVersion` (the highest version a runner has seen), that it is not older. Returns the
+ * document parsed; throws a VaultError otherwise (policy.signature, policy.expired, policy.version, or a code of
+ * validatePolicy). It does not approve anything: the runner does that in its step 1b.
+ */
+export function verifyPolicy(document, signedBy, { minimumVersion, now = new Date(), checkExpiry = true } = {}) {
+  const verifier = verifierOf(signedBy);
+  let value = document;
+  if (typeof document === 'string') {
+    if (Buffer.byteLength(document, 'utf8') > POLICY_LIMITS.bytes) throw new VaultError('policy.too_large', `the policy must not exceed ${POLICY_LIMITS.bytes} bytes`);
+    try {
+      value = JSON.parse(document);
+    } catch {
+      throw new VaultError('policy', 'the policy is not JSON');
+    }
+  }
+  const problem = documentProblem(value, { signingKid: verifier.kid });
+  if (problem) throw new VaultError(...problem);
+  let verified = false;
+  try {
+    verified = verifier.object !== null && verify(null, policyText(value, value.signature.kid), verifier.object, decode(value.signature.sig));
+  } catch {
+    verified = false;
+  }
+  if (!verified) throw new VaultError('policy.signature', `the policy does not verify with the team's signing key ${verifier.kid}: it was altered, or made by someone without that key`);
+  if (checkExpiry && 'not_after' in value && Date.parse(value.not_after) <= now.getTime()) throw new VaultError('policy.expired', `the policy expired on ${value.not_after}`);
+  if (minimumVersion !== undefined && value.version < minimumVersion) throw new VaultError('policy.version', `the policy is version ${value.version}, older than version ${minimumVersion}, which this machine has already seen`);
+  return structuredClone(value);
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Matching (§3.3).
+
+/**
+ * What a job gives the matching (§3.3): its type decides target and track. A build has neither. A TestFlight action is
+ * a submission to App Store Connect with no track, and a release is a submission to Google Play with the track it moves:
+ * the rule types stay build, submit and *, so a submit rule covers them with its target and track.
+ */
+export function jobOf({ app, platform, profile, type = 'build', target, track } = {}) {
+  if (typeof type !== 'string' || type === '') throw new VaultError('policy.type', 'a job names its type: build, submit, testflight or release');
+  if (type === 'testflight') return { app, platform, profile, type: 'submit', target: 'app_store_connect', track: '*' };
+  if (type === 'release') {
+    if (typeof track !== 'string' || track === '') throw new VaultError('policy.track', 'a release names the Google Play track it moves: production, beta or a closed one');
+    return { app, platform, profile, type: 'submit', target: 'google_play', track };
+  }
+  const submit = type === 'submit';
+  if (submit && target !== 'app_store_connect' && target !== 'google_play') throw new VaultError('policy.target', 'a submit names its target: app_store_connect or google_play');
+  if (submit && target === 'google_play' && (typeof track !== 'string' || !TRACK.test(track))) throw new VaultError('policy.track', 'a submit to Google Play names its track: internal, alpha, beta, production or a closed one');
+  return { app, platform, profile, type, target: submit ? target : '*', track: submit && target === 'google_play' ? track : '*' };
+}
+
+/** Whether one rule matches a job: each of its six fields is * or exactly the job's. */
+function matches(rule, job) {
+  return POLICY_FIELDS.every((field) => rule[field] === '*' || rule[field] === job[field]);
+}
+
+/**
+ * The rule that decides a job: the one that matches with the greatest specificity (the number of fields that are not
+ * *). Throws VaultError policy.unmatched when none matches and policy.rule.ambiguous when two match with the same
+ * specificity: there is no implicit rule and no first one wins.
+ */
+export function ruleFor(policy, job) {
+  const wanted = jobOf(job);
+  const candidates = policy.rules.filter((rule) => matches(rule, wanted));
+  if (candidates.length === 0) throw new VaultError('policy.unmatched', `no rule of the policy matches ${POLICY_FIELDS.map((field) => `${field}:${wanted[field]}`).join(' ')}`);
+  const best = Math.max(...candidates.map(specificityOf));
+  const winners = candidates.filter((rule) => specificityOf(rule) === best);
+  if (winners.length > 1) throw new VaultError('policy.rule.ambiguous', `the rules ${winners.map((rule) => rule.id).join(' and ')} all match this job with specificity ${best}`);
+  return winners[0];
+}
+
+/** The specificity of the rule that decides a job, with the rule: { rule, specificity }. */
+export function ruleAndSpecificityFor(policy, job) {
+  const rule = ruleFor(policy, job);
+  return { rule, specificity: specificityOf(rule) };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Summary and simulation: what a policy covers, what it leaves out and what it would decide (§5 and §3.8).
+
+/** The destinations to check for uncovered rules: the stores each job type and platform can reach. */
+function destinationsOf(apps, profiles) {
+  if (apps.length === 0 || profiles.length === 0) return [];
+  const destinations = [];
+  for (const app of apps) {
+    for (const platform of ['ios', 'android']) {
+      for (const profile of profiles) {
+        destinations.push({ app, platform, profile, type: 'build', target: '*', track: '*' });
+        if (platform === 'ios') {
+          destinations.push({ app, platform, profile, type: 'submit', target: 'app_store_connect', track: '*' });
+        } else {
+          for (const track of ['internal', 'production']) destinations.push({ app, platform, profile, type: 'submit', target: 'google_play', track });
+        }
+      }
+    }
+  }
+  return destinations;
+}
+
+const appCodeOf = (app) => (typeof app === 'string' ? app : app?.code);
+const profileNameOf = (profile) => (typeof profile === 'string' ? profile : profile?.name);
+
+/**
+ * What a policy is and what it leaves out. `apps` are application codes (or { code }), `profiles` profile names (or
+ * { name }) and `members` the ids of the members with a passkey in the current ias-approvers-1 (null to skip the check:
+ * with an empty list every rule is unsatisfiable). Returns:
+ *   rules:         every rule, with its specificity and whether it has enough members with a passkey;
+ *   uncovered:     the app · platform · profile · type · target · track combinations of the default matrix that no rule
+ *                  matches (a build, and the submit of each platform to its store; Google Play on internal and
+ *                  production). Empty without apps or profiles;
+ *   unsatisfiable: the rules whose count is more than their members with a passkey;
+ *   expiring:      null without not_after, or { not_after, days, expired, warning } (warning inside warnDays).
+ */
+export function summary(policy, { apps = [], profiles = [], members = null, now = new Date(), warnDays = 30 } = {}) {
+  const holders = members === null ? null : new Set(members);
+  const rules = policy.rules.map((rule) => {
+    const available = holders === null ? null : rule.require.members.filter((member) => holders.has(member)).length;
+    return { ...normalizedRule(rule), specificity: specificityOf(rule), unsatisfiable: available !== null && available < rule.require.count };
+  });
+  const uncovered = [];
+  for (const destination of destinationsOf(apps.map(appCodeOf).filter(Boolean), profiles.map(profileNameOf).filter(Boolean))) {
+    try {
+      ruleFor(policy, destination);
+    } catch (error) {
+      uncovered.push({ ...destination, code: error.code });
+    }
+  }
+  const unsatisfiable = rules.filter((rule) => rule.unsatisfiable).map((rule) => ({ id: rule.id, reason: 'policy.member.passkey', count: rule.require.count, members: rule.require.members }));
+  const expiring = 'not_after' in policy && policy.not_after !== undefined
+    ? (() => {
+        const time = Date.parse(policy.not_after);
+        const expired = time <= now.getTime();
+        const days = Math.ceil((time - now.getTime()) / DAY_MS);
+        return { not_after: policy.not_after, days: Math.max(days, 0), expired, warning: !expired && days <= warnDays };
+      })()
+    : null;
+  return { rules, uncovered, unsatisfiable, expiring };
+}
+
+/**
+ * What a policy would decide for a job, without approving or denying anything yet: { allowed, code, message, rule,
+ * specificity, version }. `allowed` is false when no rule matches (policy.unmatched), when two tie
+ * (policy.rule.ambiguous), when the policy expired (policy.expired) or, with `members`, when the rule cannot reach its
+ * count (policy.unsatisfiable). A job of type testflight or release matches as the submission it is: to App Store
+ * Connect without a track, or to Google Play with the track it moves.
+ */
+export function simulate(policy, job, { now = new Date(), members = null } = {}) {
+  const result = { allowed: false, code: null, message: null, rule: null, specificity: null, version: policy.version };
+  let matched;
+  try {
+    matched = ruleAndSpecificityFor(policy, job);
+  } catch (error) {
+    return { ...result, code: error.code, message: error.message };
+  }
+  result.rule = matched.rule;
+  result.specificity = matched.specificity;
+  if ('not_after' in policy && Date.parse(policy.not_after) <= now.getTime()) return { ...result, code: 'policy.expired', message: `the policy expired on ${policy.not_after}` };
+  if (members !== null) {
+    const available = matched.rule.require.members.filter((member) => members.includes(member)).length;
+    if (available < matched.rule.require.count) return { ...result, code: 'policy.unsatisfiable', message: `the rule ${matched.rule.id} needs ${matched.rule.require.count} approvals and only ${available} of its members have a passkey` };
+  }
+  return { ...result, allowed: true };
+}