@imagina-build/ias-cli 0.2.1 → 0.3.0

package/shared/vault/policy-vectors.mjs

@@ -0,0 +1,237 @@
+// The test vectors of ias-policy-1 (docs/plans/gaps/06-politica-aprobacion.md §5.1 and docs/technical/vault.md §8):
+// test-vectors/ias-policy-1/policy.json, signed with the team's test key of ias-vault-2/keys.json. vectors.mjs writes it
+// with the rest; the tests fail if the file differs. The member ids are the ones of the plan's Anexo A, and the keys are
+// public on purpose: never use them for anything else.
+import { Buffer } from 'node:buffer';
+import { POLICY_FORMAT, POLICY_LIMITS, policyHash, policyText, signPolicy, simulate, summary, validatePolicy, verifyPolicy } from './policy.mjs';
+
+const OWNER_A = '01930000-0000-7000-8000-00000000a001';
+const OWNER_B = '01930000-0000-7000-8000-00000000a002';
+const OWNER_C = '01930000-0000-7000-8000-00000000a003';
+const NOBODY = '01930000-0000-7000-8000-00000000a004';
+
+const rule = (id, fields = {}) => ({
+  id,
+  app: '*',
+  platform: '*',
+  profile: '*',
+  type: '*',
+  target: '*',
+  track: '*',
+  require: { members: [OWNER_A, OWNER_B], count: 1 },
+  ...fields,
+});
+
+/** Copies `document` and lets `change` alter the copy. */
+const altered = (document, change) => {
+  const copy = structuredClone(document);
+  change(copy);
+  return copy;
+};
+
+/** The unsigned part of a document, as signPolicy takes it. */
+const unsigned = ({ version, not_after: notAfter, rules }) => ({ version, ...(notAfter === undefined ? {} : { not_after: notAfter }), rules });
+
+/**
+ * Everything that goes into test-vectors/ias-policy-1/policy.json. `signing` is the one of vectors.mjs: { team,
+ * 'other-team' }.
+ */
+export function policyVectors(signing) {
+  const team = signing.team;
+  const other = signing['other-team'];
+  const inputs = [
+    ['heredado', 'The minimal policy of the plan\'s Anexo A: one * rule with every owner with a passkey, count 1. It decides nothing new.', { version: 1, not_after: '2027-04-28T00:00:00Z', rules: [rule('heredado', { require: { members: [OWNER_A, OWNER_B], count: 1 } })] }],
+    ['two-rules', 'Two rules: iOS production builds need two owners, and the internal track of Google Play one.', {
+      version: 2,
+      not_after: '2027-04-28T00:00:00Z',
+      rules: [
+        rule('ios-production', { platform: 'ios', profile: 'production', type: 'build', require: { members: [OWNER_A, OWNER_B], count: 2 } }),
+        rule('play-internal', { platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'internal', require: { members: [OWNER_A, OWNER_C], count: 1 } }),
+      ],
+    }],
+    ['four-rules', 'Four rules with a date: one owner for everything, two for production, the client app to its owner, and an Android submission to production.', {
+      version: 4,
+      not_after: '2027-10-28T00:00:00Z',
+      rules: [
+        rule('todo', { require: { members: [OWNER_A], count: 1 } }),
+        rule('ios-production', { profile: 'production', type: 'build', require: { members: [OWNER_A, OWNER_B], count: 2 } }),
+        rule('cliente', { app: 'acme', require: { members: [OWNER_C], count: 1 } }),
+        rule('play-production', { platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'production', require: { members: [OWNER_B, OWNER_C], count: 1 } }),
+      ],
+    }],
+  ];
+  const documents = inputs.map(([name, description, input]) => {
+    const document = signPolicy(input, team.privateKey);
+    verifyPolicy(document, team.publicKey, { now: new Date('2026-10-28T00:00:00Z') });
+    return { name, description, signedText: policyText(document, team.kid).toString('utf8'), hash: policyHash(document), document };
+  });
+  const base = documents[0].document;
+  // Not one of the documents above: a policy whose submit rules cover TestFlight and a release of production, the jobs
+  // that name no type of their own in ias-policy-1 (they match as the submission they are, docs/technical/vault.md §2.5).
+  const testflightAndRelease = {
+    name: 'testflight-and-release',
+    description: 'A submit rule to App Store Connect covers TestFlight, and one to Google Play with track production covers a release of that track.',
+    document: signPolicy({
+      version: 5,
+      not_after: '2027-04-28T00:00:00Z',
+      rules: [
+        rule('asc-submit', { type: 'submit', target: 'app_store_connect' }),
+        rule('play-production-release', { platform: 'android', type: 'submit', target: 'google_play', track: 'production' }),
+      ],
+    }, team.privateKey),
+  };
+  const ruleOf = (value, index = 0) => value.rules[index];
+  // A track of a form factor: `:` is a track character (wear:production, automotive:production), and a rule may name it.
+  const formFactor = {
+    name: 'form-factor',
+    description: 'A rule for the production track of a form factor (wear:production), which the track pattern accepts.',
+    document: signPolicy({
+      version: 6,
+      not_after: '2027-04-28T00:00:00Z',
+      rules: [rule('play-wear-production', { platform: 'android', type: 'submit', target: 'google_play', track: 'wear:production' })],
+    }, team.privateKey),
+  };
+  const malformed = [
+    ['array', 'policy', 'A list instead of an object.', { document: [base] }],
+    ['not-json', 'policy', 'Text that is not JSON.', { json: '{"format":"ias-policy-1",' }],
+    ['too-large', 'policy.too_large', `More than ${POLICY_LIMITS.bytes} bytes of JSON.`, { json: `{"format":"ias-policy-1","padding":"${'x'.repeat(POLICY_LIMITS.bytes)}"}` }],
+    ['other-format', 'policy.format', 'Another format.', { document: altered(base, (d) => (d.format = 'ias-policy-2')) }],
+    ['missing-signature', 'policy.fields', 'No signature.', { document: altered(base, (d) => delete d.signature) }],
+    ['extra-field', 'policy.fields', 'A field besides format, version, not_after, rules and signature.', { document: altered(base, (d) => (d.issued_at = '2026-10-28T00:00:00Z')) }],
+    ['not-after-null', 'policy.not_after', 'not_after as null: it is left out or a timestamp.', { document: altered(base, (d) => (d.not_after = null)) }],
+    ['version-zero', 'policy.version', 'Version 0.', { document: altered(base, (d) => (d.version = 0)) }],
+    ['version-string', 'policy.version', 'The version as a string.', { document: altered(base, (d) => (d.version = '1')) }],
+    ['version-decimal', 'policy.version', 'A version with decimals.', { document: altered(base, (d) => (d.version = 1.5)) }],
+    ['not-after-date-only', 'policy.not_after', 'A date without the time, which the format does not take.', { document: altered(base, (d) => (d.not_after = '2027-04-28')) }],
+    ['not-after-impossible-day', 'policy.not_after', 'The 30th of February.', { document: altered(base, (d) => (d.not_after = '2027-02-30T00:00:00Z')) }],
+    ['rules-empty', 'policy.rules', 'No rules: a policy that denies everything is not a policy.', { document: altered(base, (d) => (d.rules = [])) }],
+    ['rules-object', 'policy.rules', 'The rules as an object keyed by id.', { document: altered(base, (d) => (d.rules = Object.fromEntries(d.rules.map((entry) => [entry.id, entry])))) }],
+    ['rules-too-many', 'policy.rules', `More than ${POLICY_LIMITS.rules} rules.`, { document: altered(base, (d) => (d.rules = Array.from({ length: POLICY_LIMITS.rules + 1 }, (_, index) => ({ ...rule(`r${index}`), id: `r${index}` })))) }],
+    ['rule-extra-field', 'policy.rule', 'A rule with a comment: it takes exactly the eight fields.', { document: altered(base, (d) => (d.rules[0].note = 'producción')) }],
+    ['rule-without-require', 'policy.rule', 'A rule without require.', { document: altered(base, (d) => delete d.rules[0].require) }],
+    ['id-uppercase', 'policy.rule.id', 'An id in capitals.', { document: altered(base, (d) => (d.rules[0].id = 'Heredado')) }],
+    ['id-empty', 'policy.rule.id', 'An empty id.', { document: altered(base, (d) => (d.rules[0].id = '')) }],
+    ['id-too-long', 'policy.rule.id', 'An id of 33 characters.', { document: altered(base, (d) => (d.rules[0].id = 'a'.repeat(33))) }],
+    ['id-duplicate', 'policy.rule.duplicate', 'Two rules with the same id.', { document: altered(base, (d) => d.rules.push(structuredClone(d.rules[0]))) }],
+    ['app-uppercase', 'policy.rule.app', 'An application code in capitals.', { document: altered(base, (d) => (d.rules[0].app = 'Acme')) }],
+    ['platform-windows', 'policy.rule.platform', 'A platform the format does not have.', { document: altered(base, (d) => (d.rules[0].platform = 'windows')) }],
+    ['platform-uppercase', 'policy.rule.platform', 'iOS in capitals.', { document: altered(base, (d) => (d.rules[0].platform = 'iOS')) }],
+    ['profile-with-slash', 'policy.rule.profile', 'A profile with a slash, which no profile may have.', { document: altered(base, (d) => (d.rules[0].profile = 'production/eu')) }],
+    ['type-resign', 'policy.rule.type', 'type resign, reserved for a later format.', { document: altered(base, (d) => (d.rules[0].type = 'resign')) }],
+    ['target-unknown', 'policy.rule.target', 'A store the format does not have.', { document: altered(base, (d) => (d.rules[0].target = 'huawei')) }],
+    ['target-with-build', 'policy.rule.target', 'A target with type build.', { document: altered(base, (d) => Object.assign(d.rules[0], { type: 'build', target: 'app_store_connect' })) }],
+    ['track-with-app-store-connect', 'policy.rule.track', 'A track with target app_store_connect.', { document: altered(base, (d) => Object.assign(d.rules[0], { type: 'submit', target: 'app_store_connect', track: 'internal' })) }],
+    ['track-with-build', 'policy.rule.track', 'A track with type build.', { document: altered(base, (d) => Object.assign(d.rules[0], { type: 'build', track: 'internal' })) }],
+    ['track-invalid-char', 'policy.rule.track', 'A track with a percentage, which no track may have.', { document: altered(base, (d) => Object.assign(d.rules[0], { type: 'submit', target: 'google_play', track: 'internal:50%' })) }],
+    ['require-extra-field', 'policy.rule.require', 'require with a role: the document names member ids, not roles.', { document: altered(base, (d) => (d.rules[0].require.roles = ['owner'])) }],
+    ['members-empty', 'policy.rule.members', 'A rule without members: nobody could approve it.', { document: altered(base, (d) => (d.rules[0].require.members = [])) }],
+    ['members-too-many', 'policy.rule.members', `More than ${POLICY_LIMITS.members} members.`, { document: altered(base, (d) => (d.rules[0].require.members = Array.from({ length: POLICY_LIMITS.members + 1 }, (_, index) => `01930000-0000-7000-8000-${String(index).padStart(12, '0')}`))) }],
+    ['member-empty', 'policy.rule.member', 'An empty member id.', { document: altered(base, (d) => (d.rules[0].require.members[0] = '')) }],
+    ['members-duplicate', 'policy.rule.member', 'The same member twice.', { document: altered(base, (d) => d.rules[0].require.members.push(OWNER_A)) }],
+    ['count-zero', 'policy.rule.count', 'count 0, which would approve without a passkey.', { document: altered(base, (d) => (d.rules[0].require.count = 0)) }],
+    ['count-nine', 'policy.rule.count', `count ${POLICY_LIMITS.count + 1}, more than a policy may ask for.`, { document: altered(base, (d) => (d.rules[0].require.count = POLICY_LIMITS.count + 1)) }],
+    ['count-more-than-members', 'policy.rule.count', 'count 3 with 2 members: nobody could ever approve it.', { document: altered(base, (d) => (d.rules[0].require.count = 3)) }],
+    ['signature-sig-63-bytes', 'signature.sig', 'A 63-byte signature.', { document: altered(base, (d) => (d.signature.sig = Buffer.from(d.signature.sig, 'base64url').subarray(1).toString('base64url'))) }],
+    ['signature-kid-padded', 'signature.kid', 'Padding after the kid of the signature.', { document: altered(base, (d) => (d.signature.kid = `${d.signature.kid}=`)) }],
+    ['signed-by-another-key', 'signature.unknown', 'A policy signed by another team\'s key with its own kid (options.signingKid is the team\'s).', { document: signPolicy(unsigned(base), other.privateKey), options: { signingKid: team.kid } }],
+    ['ambiguous-tie', 'policy.rule.ambiguous', 'Two rules that match the same job with the same specificity: no rule wins.', {
+      document: altered(documents[1].document, (d) => (d.rules = [rule('ios-a', { platform: 'ios', type: 'build' }), rule('ios-b', { platform: 'ios', type: 'build', profile: '*' })])),
+    }],
+  ].map(([name, code, description, value]) => {
+    const result = validatePolicy('json' in value ? value.json : value.document, value.options ?? {});
+    if (result.valid || result.code !== code) throw new Error(`malformed policy ${name} gives ${result.valid ? 'valid' : result.code}, not ${code}`);
+    return { name, code, description, ...value };
+  });
+  const tampered = [
+    ['rule-changed', 'A profile changed without signing.', altered(base, (d) => (d.rules[0].profile = 'production'))],
+    ['member-added', 'A member added by the server, who could then approve.', altered(base, (d) => d.rules[0].require.members.push(NOBODY))],
+    ['count-lowered', 'The count lowered to one, so one approval is enough.', altered(documents[1].document, (d) => (d.rules[0].require.count = 1))],
+    ['rule-removed', 'A rule removed: its jobs would be denied or fall to a * rule.', altered(documents[1].document, (d) => d.rules.pop())],
+    ['not-after-extended', 'not_after moved further away, to keep an expired policy alive.', altered(base, (d) => (d.not_after = '2030-01-01T00:00:00Z'))],
+    ['signature-of-another-team', 'Signed by another key under the team\'s kid.', (() => {
+      const forged = signPolicy(unsigned(base), other.privateKey);
+      return { ...forged, signature: { kid: team.kid, sig: forged.signature.sig } };
+    })()],
+    ['signature-bit', 'One bit of the signature changed.', altered(base, (d) => {
+      const bytes = Buffer.from(d.signature.sig, 'base64url');
+      bytes[0] ^= 1;
+      d.signature.sig = bytes.toString('base64url');
+    })],
+    ['rules-reordered', 'The rules in another order, which the signature covers.', altered(documents[2].document, (d) => d.rules.reverse())],
+    ['version-raised', 'The version raised without signing, to look newer than the one a runner has.', altered(base, (d) => (d.version = 9))],
+  ].map(([name, description, document]) => {
+    if (!validatePolicy(document, { signingKid: team.kid }).valid) throw new Error(`tampered policy ${name} is not well formed`);
+    try {
+      verifyPolicy(document, team.publicKey);
+      throw new Error(`tampered policy ${name} verifies`);
+    } catch (error) {
+      if (error.code !== 'policy.signature') throw new Error(`tampered policy ${name} fails with ${error.code ?? error.message}`);
+    }
+    return { name, description, error: 'policy.signature', document };
+  });
+  const expired = [
+    {
+      name: 'expired',
+      description: 'A policy that was valid when it was signed and expired on 2026-10-01: the runner rejects it with policy.expired, the server only if it is already past when it is uploaded.',
+      now: '2026-10-28T00:00:00Z',
+      error: 'policy.expired',
+      document: signPolicy({ version: 1, not_after: '2026-10-01T00:00:00Z', rules: [rule('heredado')] }, team.privateKey),
+    },
+  ].map((vector) => {
+    verifyPolicy(vector.document, team.publicKey, { now: new Date('2026-09-01T00:00:00Z') });
+    try {
+      verifyPolicy(vector.document, team.publicKey, { now: new Date(vector.now) });
+      throw new Error(`expired policy ${vector.name} verifies`);
+    } catch (error) {
+      if (error.code !== vector.error) throw new Error(`expired policy ${vector.name} fails with ${error.code ?? error.message}`);
+    }
+    return vector;
+  });
+  const matching = [
+    ['exact-beats-wildcard', documents[2].document, { app: 'jscheduler', platform: 'ios', profile: 'production', type: 'build' }, 'ios-production'],
+    [ 'play-internal', documents[1].document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'internal' }, 'play-internal'],
+    ['play-production-is-not-internal', documents[1].document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'production' }, null, 'policy.unmatched'],
+    ['ios-submit-is-not-a-build', documents[1].document, { app: 'jscheduler', platform: 'ios', profile: 'production', type: 'submit', target: 'app_store_connect' }, null, 'policy.unmatched'],
+    ['another-profile', documents[1].document, { app: 'jscheduler', platform: 'ios', profile: 'preview', type: 'build' }, null, 'policy.unmatched'],
+    ['wildcard-only', documents[0].document, { app: 'acme', platform: 'android', profile: 'preview', type: 'build' }, 'heredado'],
+    ['four-rules-client', documents[2].document, { app: 'acme', platform: 'ios', profile: 'preview', type: 'build' }, 'cliente'],
+    // A TestFlight action is a submission to App Store Connect without a track, and a release a submission to Google Play with its track.
+    ['testflight-is-an-app-store-submission', testflightAndRelease.document, { app: 'jscheduler', platform: 'ios', profile: 'production', type: 'testflight' }, 'asc-submit'],
+    ['testflight-is-not-a-build', documents[1].document, { app: 'jscheduler', platform: 'ios', profile: 'production', type: 'testflight' }, null, 'policy.unmatched'],
+    ['release-is-a-play-submission-with-its-track', testflightAndRelease.document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'release', track: 'production' }, 'play-production-release'],
+    ['release-another-track-is-denied', testflightAndRelease.document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'release', track: 'beta' }, null, 'policy.unmatched'],
+    ['wildcard-covers-testflight', documents[0].document, { app: 'jscheduler', platform: 'ios', profile: 'production', type: 'testflight' }, 'heredado'],
+    ['wildcard-covers-release', documents[0].document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'release', track: 'production' }, 'heredado'],
+    // A form factor's track: `:` is part of the name, and the rule that names it is the one that decides.
+    ['wear-production-is-a-track', formFactor.document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'wear:production' }, 'play-wear-production'],
+    ['production-is-not-wear-production', formFactor.document, { app: 'jscheduler', platform: 'android', profile: 'production', type: 'submit', target: 'google_play', track: 'production' }, null, 'policy.unmatched'],
+  ].map(([name, policy, job, id, error = null]) => {
+    const result = simulate(policy, job, { now: new Date('2026-10-28T00:00:00Z') });
+    if (id === null ? result.allowed || result.code !== error : !result.allowed || result.rule.id !== id) throw new Error(`matching vector ${name} gives ${result.allowed ? result.rule.id : result.code}`);
+    return { name, job, rule: id, error, document: policy, specificity: id === null ? null : result.specificity };
+  });
+  const summaries = [
+    {
+      name: 'two-rules',
+      description: 'The two-rule document over one app and two profiles: the only owner with a passkey cannot reach the two approvals of ios-production, and the combinations no rule covers.',
+      document: documents[1].document,
+      options: { apps: ['jscheduler'], profiles: ['preview', 'production'], members: [OWNER_A], now: '2026-10-28T00:00:00Z' },
+    },
+  ].map((vector) => {
+    const result = summary(vector.document, { ...vector.options, now: new Date(vector.options.now) });
+    return { ...vector, summary: result, uncovered: result.uncovered.map((entry) => `${entry.app}/${entry.platform}/${entry.profile}/${entry.type}/${entry.target}/${entry.track}`), unsatisfiable: result.unsatisfiable.map((entry) => entry.id) };
+  });
+  return {
+    format: POLICY_FORMAT,
+    description: `The signed approval policy (${POLICY_FORMAT}, docs/technical/vault.md §2.5): documents are good ones signed with the team key of ias-vault-2/keys.json (signing.team; other-team makes the forgeries), each with the signedText the signature covers and the hash of that text. malformed must be rejected with code (validatePolicy, with options); tampered are well formed but do not verify (verifyPolicy: policy.signature); expired verifies before its date and gives policy.expired after it; matching gives the rule simulate picks for a job (or the code of its denial), and summaries what summary reports.`,
+    warning: 'Test vectors: the keys are public. Never use them for anything else.',
+    signing: { kid: team.kid, publicKey: team.publicKey },
+    members: { 'owner-a': OWNER_A, 'owner-b': OWNER_B, 'owner-c': OWNER_C, 'without-passkey': NOBODY },
+    documents,
+    malformed,
+    tampered,
+    expired,
+    matching,
+    summaries,
+  };
+}