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

package/shared/credentials/index.mjs

@@ -0,0 +1,354 @@
+// What is not secret in the signing credentials of an app (docs/technical/vault.md §3, PLAN-APPLICATION-SERVICES.md §2.5 point
+// 3): the metadata the CLI stores beside each sealed envelope, so that the panel shows the inventory and warns before
+// anything expires without ever seeing a secret. Ported from jscheduler-app's scripts/store-signing.mjs and
+// store-credentials.mjs, which read the same material from 1Password.
+// Nothing here returns or prints a password or a key, and no password is ever a command argument (visible to `ps`):
+// openssl and keytool get them through the environment. Fingerprints, serial numbers, names and dates are not secret.
+import { Buffer } from 'node:buffer';
+import { spawnSync } from 'node:child_process';
+import { X509Certificate, createHash, createPrivateKey, createPublicKey } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import process from 'node:process';
+import { signedContent } from './cms.mjs';
+import { parsePlist } from './plist.mjs';
+
+/**
+ * The kinds of credential the vault holds: the names of the management API (docs/technical/manage-api.md §8.1 and §9), which in
+ * ias-vault-2 are also credential.type in an envelope (docs/technical/vault.md §3.3).
+ */
+export const CREDENTIAL_TYPES = Object.freeze([
+  'apple_distribution_certificate',
+  'apple_provisioning_profile',
+  'android_upload_keystore',
+  'apns_key',
+  'asc_api_key',
+  'google_service_account',
+  'environment_variable',
+]);
+
+/** The provisioning profile types, as Xcode and EAS name them. */
+export const PROFILE_TYPES = Object.freeze(['app-store', 'ad-hoc', 'development', 'enterprise']);
+
+const APPLE_ID = /^[A-Z0-9]{10}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PEM_CERTIFICATE = /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g;
+
+/** A credential that cannot be read. The message names the file or the tool, never a secret. */
+export class CredentialError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CredentialError';
+  }
+}
+
+const sha1 = (der) => createHash('sha1').update(der).digest('hex').toUpperCase();
+const colonHex = (bytes) => bytes.toString('hex').toUpperCase().match(/../g).join(':');
+const isoDate = (value) => new Date(value).toISOString();
+
+/** The bytes of `source`: a path, or the bytes themselves. */
+function bytesOf(source, what) {
+  if (source instanceof Uint8Array) return Buffer.from(source);
+  try {
+    return readFileSync(source);
+  } catch {
+    throw new CredentialError(`no ${what} at ${source}`);
+  }
+}
+
+/** The attributes of an X.509 name, as Node prints it ("CN=…\nOU=…"). */
+function nameAttributes(name) {
+  const attributes = {};
+  for (const line of name.split('\n')) {
+    const separator = line.indexOf('=');
+    if (separator > 0) attributes[line.slice(0, separator)] ??= line.slice(separator + 1);
+  }
+  return attributes;
+}
+
+/** Subject, serial, dates and fingerprints of an X.509 certificate, none of them secret. */
+export function describeCertificate(certificate) {
+  return {
+    subject: certificate.subject.replace(/\n/g, ', '),
+    commonName: nameAttributes(certificate.subject).CN ?? null,
+    serial: certificate.serialNumber,
+    validFrom: isoDate(certificate.validFrom),
+    expires: isoDate(certificate.validTo),
+    sha1: sha1(certificate.raw),
+    sha256: certificate.fingerprint256,
+  };
+}
+
+/** What an Apple signing certificate is for, from its common name. */
+function appleCertificateKind(commonName) {
+  if (/^(Apple|iPhone) Distribution:/.test(commonName ?? '')) return 'distribution';
+  if (/^(Apple Development|iPhone Developer):/.test(commonName ?? '')) return 'development';
+  return null;
+}
+
+/** Replaces every secret in tool output, in case a tool ever echoes one. */
+function scrub(text, secrets) {
+  let clean = String(text ?? '');
+  for (const secret of secrets) if (secret) clean = clean.split(secret).join('[secret]');
+  return clean;
+}
+
+/**
+ * Runs a tool with the secrets in its environment (never in its arguments) and returns its exit status and its
+ * output with the secrets scrubbed out.
+ */
+function runTool(command, args, secrets, label) {
+  const result = spawnSync(command, args, { encoding: 'utf8', env: { ...process.env, ...secrets }, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 });
+  if (result.error) throw new CredentialError(result.error.code === 'ENOENT' ? `${label}: ${command} is not installed` : `${label}: ${result.error.message}`);
+  const values = Object.values(secrets);
+  return { status: result.status, stdout: scrub(result.stdout, values), stderr: scrub(result.stderr, values) };
+}
+
+/** The first line of tool output that explains a failure. */
+function reason(output, pattern) {
+  const lines = output.split('\n').map((line) => line.trim()).filter(Boolean);
+  return lines.find((line) => pattern.test(line)) ?? lines[0] ?? 'no output';
+}
+
+/**
+ * The distribution (or development) certificate of a .p12 and its password: subject, Apple team, serial, SHA-1 (the
+ * identity codesign uses) and expiry. The p12 must hold exactly one identity: one certificate with its key. The key
+ * is never decrypted. Throws if the password is wrong.
+ */
+export function inspectP12(source, password, { openssl = 'openssl' } = {}) {
+  const path = typeof source === 'string' ? source : null;
+  if (path === null) throw new CredentialError('inspectP12 reads a .p12 from a path');
+  bytesOf(path, '.p12');
+  const secrets = { IAS_P12_PASSWORD: String(password ?? '') };
+  const args = ['pkcs12', '-in', path, '-passin', 'env:IAS_P12_PASSWORD', '-nokeys', '-clcerts', '-info'];
+  let result = runTool(openssl, args, secrets, 'openssl pkcs12');
+  // OpenSSL 3 and later only read the RC2 of older .p12 files (Keychain Access, EAS) with -legacy; LibreSSL always does.
+  if (result.status !== 0 && !/mac verify|invalid password/i.test(result.stderr)) {
+    const legacy = runTool(openssl, [...args, '-legacy'], secrets, 'openssl pkcs12 -legacy');
+    if (legacy.status === 0) result = legacy;
+  }
+  if (result.status !== 0) {
+    const wrongPassword = /mac verify|invalid password/i.test(result.stderr);
+    throw new CredentialError(wrongPassword ? `${basename(path)}: wrong password` : `${basename(path)} is not a .p12 that openssl can read: ${reason(result.stderr, /error|unsupported|unable/i)}`);
+  }
+  const certificates = [...result.stdout.matchAll(PEM_CERTIFICATE)].map(([block]) => new X509Certificate(block));
+  const keys = (result.stderr.match(/^(Shrouded Keybag|Key bag)/gim) ?? []).length;
+  if (certificates.length !== 1 || keys !== 1) {
+    throw new CredentialError(`${basename(path)} has ${certificates.length} certificates with a key and ${keys} keys; it should have one identity (one certificate and its key)`);
+  }
+  const [certificate] = certificates;
+  const description = describeCertificate(certificate);
+  return { ...description, team: nameAttributes(certificate.subject).OU ?? null, kind: appleCertificateKind(description.commonName) };
+}
+
+/** The type of a profile, by the rules Xcode and EAS use. */
+function profileType(plist) {
+  if (plist.ProvisionsAllDevices === true) return 'enterprise';
+  if (Array.isArray(plist.ProvisionedDevices)) return plist.Entitlements?.['get-task-allow'] === true ? 'development' : 'ad-hoc';
+  return 'app-store';
+}
+
+/** Entitlements as JSON: data values (rare) become base64. */
+function plainEntitlements(entitlements) {
+  return JSON.parse(JSON.stringify(entitlements ?? {}, (key, value) => (value?.type === 'Buffer' && Array.isArray(value.data) ? Buffer.from(value.data).toString('base64') : value)));
+}
+
+/**
+ * A provisioning profile (it is signed, not secret): UUID, name, type, team, bundle id, entitlements, how many
+ * devices it lists, the SHA-1 of the certificates it accepts, and its dates. Read without `security` or `plutil`, so
+ * it works off macOS too; Apple's signature is not checked here.
+ */
+export function inspectProfile(source) {
+  const bytes = bytesOf(source, 'provisioning profile');
+  let plist;
+  try {
+    plist = parsePlist(signedContent(bytes).toString('utf8'));
+  } catch (error) {
+    throw new CredentialError(`${typeof source === 'string' ? basename(source) : 'the profile'} is not a provisioning profile: ${error.message}`);
+  }
+  const team = plist.TeamIdentifier?.[0] ?? null;
+  const applicationIdentifier = plist.Entitlements?.['application-identifier'] ?? null;
+  const prefix = team ? `${team}.` : null;
+  return {
+    uuid: plist.UUID ?? null,
+    name: plist.Name ?? null,
+    type: profileType(plist),
+    team,
+    teamName: plist.TeamName ?? null,
+    appIdName: plist.AppIDName ?? null,
+    applicationIdentifier,
+    bundleId: applicationIdentifier && prefix && applicationIdentifier.startsWith(prefix) ? applicationIdentifier.slice(prefix.length) : null,
+    platforms: plist.Platform ?? [],
+    entitlements: plainEntitlements(plist.Entitlements),
+    devices: Array.isArray(plist.ProvisionedDevices) ? plist.ProvisionedDevices.length : 0,
+    certificates: (plist.DeveloperCertificates ?? []).filter(Buffer.isBuffer).map(sha1),
+    created: plist.CreationDate ?? null,
+    expires: plist.ExpirationDate ?? null,
+  };
+}
+
+/**
+ * An Android keystore (.jks or PKCS12) with its passwords and alias, by keytool: the certificate of the alias, with
+ * its SHA-1 and SHA-256 (what Play Console and assetlinks.json show) and its expiry. The key password is checked by
+ * using the key: keytool -certreq signs a request with it and nothing is written.
+ */
+export function inspectKeystore(source, { storePassword, alias, keyPassword }, { keytool = 'keytool' } = {}) {
+  const path = typeof source === 'string' ? source : null;
+  if (path === null) throw new CredentialError('inspectKeystore reads a keystore from a path');
+  if (!alias) throw new CredentialError('the keystore alias is missing');
+  bytesOf(path, 'keystore');
+  const secrets = { IAS_STOREPASS: String(storePassword ?? ''), IAS_KEYPASS: String(keyPassword ?? storePassword ?? '') };
+  // English messages, whatever the locale of the JVM.
+  const common = ['-J-Duser.language=en', '-keystore', path, '-storepass:env', 'IAS_STOREPASS', '-alias', alias];
+  const exported = runTool(keytool, ['-exportcert', '-rfc', ...common], secrets, 'keytool -exportcert');
+  if (exported.status !== 0) throw new CredentialError(`${basename(path)}: ${reason(`${exported.stdout}\n${exported.stderr}`, /keytool error/i)} (wrong keystore password or alias?)`);
+  const request = runTool(keytool, ['-certreq', ...common, '-keypass:env', 'IAS_KEYPASS'], secrets, 'keytool -certreq');
+  if (request.status !== 0) throw new CredentialError(`${basename(path)}: ${reason(`${request.stdout}\n${request.stderr}`, /keytool error/i)} (wrong key password, or the alias has no key?)`);
+  const [pem] = exported.stdout.match(PEM_CERTIFICATE) ?? [];
+  if (!pem) throw new CredentialError(`${basename(path)}: keytool gave no certificate for ${alias}`);
+  return { alias, ...describeCertificate(new X509Certificate(pem)) };
+}
+
+/** The SHA-256 of a public key in SubjectPublicKeyInfo DER: identifies a key without revealing it. */
+const publicKeySha256 = (privateKey) => colonHex(createHash('sha256').update(createPublicKey(privateKey).export({ format: 'der', type: 'spki' })).digest());
+
+/**
+ * A .p8 key of APNs or of the App Store Connect API (an ES256 key that never expires), by the key id and the team
+ * given; the key id may come from the file name (AuthKey_<id>.p8). Returns the ids and the SHA-256 of the public key.
+ */
+export function inspectP8(source, { keyId, teamId, issuerId } = {}) {
+  const fromName = typeof source === 'string' ? /^AuthKey_([A-Z0-9]{10})\.p8$/.exec(basename(source))?.[1] : undefined;
+  const id = keyId ?? fromName;
+  if (!id || !APPLE_ID.test(id)) throw new CredentialError('the key id of a .p8 is 10 characters of A-Z and 0-9 (AuthKey_<id>.p8)');
+  if (fromName && keyId && fromName !== keyId) throw new CredentialError(`the file is the key ${fromName}, not ${keyId}`);
+  if (!teamId || !APPLE_ID.test(teamId)) throw new CredentialError('the Apple team of a .p8 is 10 characters of A-Z and 0-9');
+  if (issuerId !== undefined && !UUID.test(issuerId)) throw new CredentialError('the issuer id of an App Store Connect key is a UUID');
+  let key;
+  try {
+    key = createPrivateKey({ key: bytesOf(source, '.p8'), format: 'pem' });
+  } catch (error) {
+    if (error instanceof CredentialError) throw error;
+    throw new CredentialError(`${typeof source === 'string' ? basename(source) : 'the .p8'} is not a PEM private key`);
+  }
+  if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1') throw new CredentialError('a .p8 of Apple is an EC P-256 key (ES256)');
+  return { keyId: id, teamId, ...(issuerId === undefined ? {} : { issuerId }), algorithm: 'ES256', publicKeySha256: publicKeySha256(key), expires: null };
+}
+
+/** A Google service account key (JSON): its email, project and key id, and the SHA-256 of its public key. */
+export function inspectServiceAccount(source) {
+  let json;
+  try {
+    json = typeof source === 'object' && !(source instanceof Uint8Array) ? source : JSON.parse(bytesOf(source, 'service account').toString('utf8'));
+  } catch (error) {
+    if (error instanceof CredentialError) throw error;
+    throw new CredentialError('the service account is not JSON');
+  }
+  if (json?.type !== 'service_account') throw new CredentialError('not a Google service account key (type is not service_account)');
+  if (typeof json.client_email !== 'string' || typeof json.project_id !== 'string') throw new CredentialError('the service account has no client_email or project_id');
+  let key;
+  try {
+    key = createPrivateKey({ key: json.private_key, format: 'pem' });
+  } catch {
+    throw new CredentialError('the service account has no readable private_key');
+  }
+  return { clientEmail: json.client_email, projectId: json.project_id, privateKeyId: json.private_key_id ?? null, publicKeySha256: publicKeySha256(key), expires: null };
+}
+
+const expired = (date, now) => !(Date.parse(date) > now);
+
+/**
+ * The problems of an iOS certificate and profile for an app, from their metadata: they are the checks of
+ * store-signing.mjs inspectIos. `teamId` and `bundleId` are checked when given; `type` is the profile the build
+ * needs ('app-store' for the stores).
+ */
+export function checkIos({ certificate, profile }, { teamId, bundleId, type = 'app-store', now = Date.now() } = {}) {
+  const problems = [];
+  if (teamId && profile.team !== teamId) problems.push(`the profile is for team ${profile.team}, not ${teamId}`);
+  if (teamId && bundleId && profile.applicationIdentifier !== `${teamId}.${bundleId}`) problems.push(`the profile is for ${profile.applicationIdentifier}, not ${teamId}.${bundleId}`);
+  if (profile.type !== type) problems.push(`the profile is ${profile.type}, not ${type}`);
+  if (type === 'app-store' && profile.entitlements['get-task-allow'] !== false) problems.push('the profile allows debugging (get-task-allow): not an App Store profile');
+  if (expired(profile.expires, now)) problems.push(`the profile expired on ${profile.expires}`);
+  if (!profile.certificates.includes(certificate.sha1)) problems.push('the profile does not include this certificate');
+  if (teamId && certificate.team !== teamId) problems.push(`the certificate is for team ${certificate.team}, not ${teamId}`);
+  const kind = type === 'development' ? 'development' : 'distribution';
+  if (certificate.kind !== kind) problems.push(`a ${type} profile needs a ${kind} certificate, and this one is ${certificate.kind ?? 'neither'} (${certificate.commonName})`);
+  if (expired(certificate.expires, now)) problems.push(`the certificate expired on ${certificate.expires}`);
+  return problems;
+}
+
+/** The problems of an Android upload key: expired, or not one of the SHA-256 the app expects (Play, assetlinks.json). */
+export function checkAndroid(keystore, { sha256 = [], now = Date.now() } = {}) {
+  const problems = [];
+  if (expired(keystore.expires, now)) problems.push(`the upload key certificate expired on ${keystore.expires}`);
+  if (sha256.length > 0 && !sha256.includes(keystore.sha256)) problems.push(`the upload key SHA-256 ${keystore.sha256} is not one of the expected ones`);
+  return problems;
+}
+
+/** The iOS material of an app ({ p12, password, profile }): the metadata of both and their problems for `expected`. */
+export function inspectIos({ p12, password, profile }, expected = {}, tools = {}) {
+  const certificate = inspectP12(p12, password, tools);
+  const profileData = inspectProfile(profile);
+  return { certificate, profile: profileData, problems: checkIos({ certificate, profile: profileData }, expected) };
+}
+
+/** The Android material of an app ({ keystore, storePassword, alias, keyPassword }): its metadata and problems. */
+export function inspectAndroid({ keystore, storePassword, alias, keyPassword }, expected = {}, tools = {}) {
+  const metadata = inspectKeystore(keystore, { storePassword, alias, keyPassword }, tools);
+  return { keystore: metadata, problems: checkAndroid(metadata, expected) };
+}
+
+/**
+ * The metadata of what an EAS credentials.json in `dir` holds (eas credentials › Download credentials from EAS), as
+ * inspectIos and inspectAndroid give it. The passwords in the file are used and never returned.
+ */
+export function inspectEasCredentials(dir, expected = {}, tools = {}) {
+  let json;
+  try {
+    json = JSON.parse(readFileSync(resolve(dir, 'credentials.json'), 'utf8'));
+  } catch {
+    throw new CredentialError(`no readable credentials.json in ${dir}`);
+  }
+  const result = {};
+  let ios = json.ios;
+  if (ios && !ios.distributionCertificate) {
+    const targets = Object.keys(ios);
+    if (targets.length !== 1) throw new CredentialError(`credentials.json has iOS credentials for ${targets.length} targets; only one is supported`);
+    ios = ios[targets[0]];
+  }
+  if (ios) {
+    result.ios = inspectIos({ p12: resolve(dir, ios.distributionCertificate.path), password: ios.distributionCertificate.password, profile: resolve(dir, ios.provisioningProfilePath) }, expected.ios, tools);
+  }
+  const keystore = json.android?.keystore;
+  if (keystore) {
+    result.android = inspectAndroid({ keystore: resolve(dir, keystore.keystorePath), storePassword: keystore.keystorePassword, alias: keystore.keyAlias, keyPassword: keystore.keyPassword }, expected.android, tools);
+  }
+  if (Object.keys(result).length === 0) throw new CredentialError('credentials.json has neither iOS nor Android credentials');
+  return result;
+}
+
+/**
+ * The metadata of a credential of `type`, exactly as the server stores it beside the envelope (docs/technical/vault.md §3.4):
+ * what the inspect function of the type returns. `input` holds the files and fields of the plaintext (docs/technical/vault.md
+ * §3.5) as paths or bytes: { p12, password }, { mobileprovision }, { keystore, storePassword, alias, keyPassword },
+ * { p8, keyId, teamId, issuerId? } or { json }. A secret variable has none: null.
+ */
+export function metadataOf(type, input, tools = {}) {
+  switch (type) {
+    case 'apple_distribution_certificate':
+      return inspectP12(input.p12, input.password, tools);
+    case 'apple_provisioning_profile':
+      return inspectProfile(input.mobileprovision);
+    case 'android_upload_keystore':
+      return inspectKeystore(input.keystore, { storePassword: input.storePassword, alias: input.alias, keyPassword: input.keyPassword }, tools);
+    case 'apns_key':
+      return inspectP8(input.p8, { keyId: input.keyId, teamId: input.teamId });
+    case 'asc_api_key':
+      return inspectP8(input.p8, { keyId: input.keyId, teamId: input.teamId, issuerId: input.issuerId });
+    case 'google_service_account':
+      return inspectServiceAccount(input.json);
+    case 'environment_variable':
+      return null;
+    default:
+      throw new CredentialError(`there is no credential type ${type}: it is one of ${CREDENTIAL_TYPES.join(', ')}`);
+  }
+}

package/shared/credentials/plist.mjs

@@ -0,0 +1,93 @@
+// A reader of XML property lists, enough for provisioning profiles: dict, array, string, integer, real, true, false,
+// date and data. Dates come back as ISO strings and data as Buffers.
+import { Buffer } from 'node:buffer';
+
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+const TAG = /\s*<(\/?)([A-Za-z]+)(?:\s[^>]*?)?\s*(\/?)>/y;
+
+const unescape = (text) =>
+  text.replace(/&(#x[0-9A-Fa-f]+|#[0-9]+|[a-z]+);/g, (entity, name) => {
+    if (name.startsWith('#x')) return String.fromCodePoint(Number.parseInt(name.slice(2), 16));
+    if (name.startsWith('#')) return String.fromCodePoint(Number.parseInt(name.slice(1), 10));
+    return ENTITIES[name] ?? entity;
+  });
+
+/** Parses an XML property list into plain values. Throws on anything else. */
+export function parsePlist(xml) {
+  const text = String(xml)
+    .replace(/<\?xml[\s\S]*?\?>/g, '')
+    .replace(/<!DOCTYPE[^>]*>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '');
+  let position = 0;
+  const fail = (what) => {
+    throw new Error(`not an XML property list (${what})`);
+  };
+  const tag = () => {
+    TAG.lastIndex = position;
+    const match = TAG.exec(text);
+    if (!match) fail(`expected a tag at ${position}`);
+    position = TAG.lastIndex;
+    return { close: match[1] === '/', name: match[2], empty: match[3] === '/' };
+  };
+  const content = (open) => {
+    if (open.empty) return '';
+    const end = text.indexOf(`</${open.name}>`, position);
+    if (end < 0) fail(`unclosed <${open.name}>`);
+    const raw = text.slice(position, end);
+    if (raw.includes('<')) fail(`markup inside <${open.name}>`);
+    position = end + open.name.length + 3;
+    return unescape(raw);
+  };
+  const value = (open, depth) => {
+    if (open.close || depth > 64) fail(`unexpected </${open.name}>`);
+    switch (open.name) {
+      case 'dict': {
+        const dict = {};
+        if (open.empty) return dict;
+        for (;;) {
+          const next = tag();
+          if (next.close && next.name === 'dict') return dict;
+          if (next.name !== 'key' || next.close) fail(`<${next.name}> where a <key> goes`);
+          // defineProperty, so that a key named __proto__ stays a key.
+          Object.defineProperty(dict, content(next), { value: value(tag(), depth + 1), enumerable: true, writable: true, configurable: true });
+        }
+      }
+      case 'array': {
+        const array = [];
+        if (open.empty) return array;
+        for (;;) {
+          const next = tag();
+          if (next.close && next.name === 'array') return array;
+          array.push(value(next, depth + 1));
+        }
+      }
+      case 'string':
+        return content(open);
+      case 'integer':
+      case 'real': {
+        const number = Number(content(open).trim());
+        if (!Number.isFinite(number)) fail(`a bad <${open.name}>`);
+        return number;
+      }
+      case 'true':
+      case 'false':
+        if (!open.empty) fail(`<${open.name}> with content`);
+        return open.name === 'true';
+      case 'date': {
+        const date = new Date(content(open).trim());
+        if (Number.isNaN(date.getTime())) fail('a bad <date>');
+        return date.toISOString();
+      }
+      case 'data':
+        return Buffer.from(content(open).replace(/\s+/g, ''), 'base64');
+      default:
+        return fail(`<${open.name}>`);
+    }
+  };
+  const root = tag();
+  if (root.name !== 'plist' || root.close || root.empty) fail('no <plist>');
+  const result = value(tag(), 0);
+  const end = tag();
+  if (!end.close || end.name !== 'plist' || text.slice(position).trim() !== '') fail('content after the value');
+  return result;
+}

package/shared/vault/approvers-vectors.mjs

@@ -0,0 +1,188 @@
+// The test vectors of ias-approvers-1 (docs/technical/vault.md §2.4 and §8): test-vectors/ias-vault-2/approvers.json, signed with
+// the team's test key of keys.json. vectors.mjs writes them with the rest; the tests fail if the file differs. The
+// passkeys are public keys only, made from labels (P-256 and P-384) or fixed here (RSA), and the first document holds
+// exactly the approvers of tests/Fixtures/runner-v1/approval-vectors.json, so the runner can check a whole approval:
+// the document with the team key, then the assertion of that file with the passkey the document names.
+import { Buffer } from 'node:buffer';
+import { createECDH, createHash, createPublicKey } from 'node:crypto';
+import { encode } from './index.mjs';
+import { APPROVERS_FORMAT, APPROVER_LIMITS, approverAlgorithm, approverFingerprint, approversText, signApprovers, validateApprovers, verifyApprovers } from './approvers.mjs';
+
+/** A P-256 or P-384 public key (SPKI, DER, base64url) whose private scalar is the SHA-256 or SHA-384 of `label`. */
+function curveKey(label, curve = 'prime256v1') {
+  const [hash, crv, size] = curve === 'prime256v1' ? ['sha256', 'P-256', 32] : ['sha384', 'P-384', 48];
+  const ecdh = createECDH(curve);
+  ecdh.setPrivateKey(createHash(hash).update(`${APPROVERS_FORMAT} test vector\n${label}`, 'utf8').digest());
+  const point = ecdh.getPublicKey();
+  const jwk = { kty: 'EC', crv, x: encode(point.subarray(1, 1 + size)), y: encode(point.subarray(1 + size)) };
+  return encode(createPublicKey({ key: jwk, format: 'jwk' }).export({ format: 'der', type: 'spki' }));
+}
+
+/** A credential id of 16 bytes made from `label`, as a browser would give one. */
+const credentialId = (label) => encode(createHash('sha256').update(`${APPROVERS_FORMAT} test vector\ncredential ${label}`, 'utf8').digest().subarray(0, 16));
+
+// RSA public keys made once with node:crypto (their private keys were thrown away): one of 2048 bits, which an approver
+// may use (RS256), and one of 1024, which it may not.
+const RSA_2048 = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyOiOy7rHLrSxmUE-Gn_HR8t8wn0f5_dpJbSe7z3UdwFGm0LnBmdPc2IoNhtM4pWHYET0LY1wVqsX389TeTESdb1rB46uaQwsj85iWqvr6_AYqJDh22nLJ_Z_5JgiMZBBx5QSalEf3_xHSwKK_UljzniwE2Hwku1hRjOpKqorjKKV9frdpFhFqfF2VplbRoQh2HHxbNKHA-8p-XOzbPfRs2Pdkdg70sfCbxjc5aBdtWLkB1Y7kJLPdnsf0rUgG00s2xzk7nCKS3H2xGo4j0RgvdOGoEdM8ue_yhy_arSevmBJNOkJmLV4K8pPuIpbGdomHqX2-XUu2D3Dn1mqUJpklwIDAQAB';
+const RSA_1024 = 'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5qBnOaxo_40x9jG9eOUD9VK4ElyA5t6oZKtJpzgPNuoG-VR62mEOj2owqbk1k1uTeSaYJ3ffrOmu2WYFZ1hLX4HeGqBIkIsxpyuiGsJG9ChPj4ENLLDFIemEKNscvZIPNTo8UT_u9qlOIEpQ9WNzRfKfzuEjov6i39UcSTRR1cwIDAQAB';
+
+/**
+ * The approver of tests/Fixtures/runner-v1/approval-vectors.json (its test passkey P-256 and owner), written out here
+ * so this package does not read the repository; the tests check that both stay the same.
+ */
+export const RUNNER_V1_APPROVERS = Object.freeze({
+  version: 1,
+  rp_id: 'ias.imagina.build',
+  origins: ['https://ias.imagina.build', 'https://sync.domibi.com'],
+  approvers: [
+    {
+      credential_id: 'Gqerejj6atYqw9aLMbf5nw',
+      public_key: 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEI5jFKVlRvVohfg3qfjblCcGXBFdlmJ6UMBm2QcPXfTBKFu_jrRIV6k7_583rgV8p2LLeg7aQR6xRAck7_pycUA',
+      alg: -7,
+      member: '01930000-0000-7000-8000-00000000a001',
+      name: 'Owner de prueba',
+    },
+  ],
+});
+
+/** The test passkeys: { credential_id, public_key, alg, fingerprint }; alg is null for the ones no approver may use. */
+function passkeys() {
+  const keys = {
+    'runner-v1-owner': { credential_id: RUNNER_V1_APPROVERS.approvers[0].credential_id, public_key: RUNNER_V1_APPROVERS.approvers[0].public_key },
+    'owner-phone': { credential_id: credentialId('owner-phone'), public_key: curveKey('owner-phone') },
+    'second-owner-rsa': { credential_id: credentialId('second-owner-rsa'), public_key: RSA_2048 },
+    'local-owner': { credential_id: credentialId('local-owner'), public_key: curveKey('local-owner') },
+    outsider: { credential_id: credentialId('outsider'), public_key: curveKey('outsider') },
+    'p-384': { credential_id: credentialId('p-384'), public_key: curveKey('p-384', 'secp384r1') },
+    'rsa-1024': { credential_id: credentialId('rsa-1024'), public_key: RSA_1024 },
+  };
+  return Object.fromEntries(Object.entries(keys).map(([name, key]) => [name, { ...key, alg: approverAlgorithm(key.public_key), fingerprint: approverFingerprint(key.public_key) }]));
+}
+
+/** Copies `document` and lets `change` alter the copy. */
+const altered = (document, change) => {
+  const copy = structuredClone(document);
+  change(copy);
+  return copy;
+};
+
+/** The vectors of approvers.json, made with the team's signing key and another team's (`signing` of keys.json). */
+export function approverVectors(signing) {
+  const team = signing.team;
+  const keys = passkeys();
+  const approver = (key, member, name) => ({ credential_id: keys[key].credential_id, public_key: keys[key].public_key, alg: keys[key].alg, member, name });
+  const owner = '01930000-0000-7000-8000-00000000a001';
+  const secondOwner = '01930000-0000-7000-8000-00000000a002';
+  const steps = [
+    ['approval-vectors', 'The list of tests/Fixtures/runner-v1/approval-vectors.json, signed by the team: the valid assertion of that file passes §3.3 with it, and each invalid one fails at its step.', RUNNER_V1_APPROVERS],
+    ['two-owners', 'A later version: the first owner with a second passkey, and a second owner whose passkey is RSA (RS256); only the new origin.', {
+      version: 2,
+      rp_id: 'ias.imagina.build',
+      origins: ['https://ias.imagina.build'],
+      approvers: [{ ...RUNNER_V1_APPROVERS.approvers[0] }, approver('owner-phone', owner, 'Owner de prueba'), approver('second-owner-rsa', secondOwner, 'Segunda owner, con ñ y tilde: Úrsula')],
+    }],
+    ['local', 'The panel of a development machine: an rp_id under .test, and http://localhost with a port.', {
+      version: 1,
+      rp_id: 'application-services.test',
+      origins: ['https://application-services.test', 'http://localhost:8000'],
+      approvers: [approver('local-owner', owner, 'Owner local')],
+    }],
+  ];
+  const documents = steps.map(([name, description, input]) => {
+    const document = signApprovers(input, team.privateKey);
+    verifyApprovers(document, team.publicKey);
+    return { name, description, signedText: approversText(document, team.kid).toString('utf8'), fingerprints: Object.fromEntries(document.approvers.map((entry) => [entry.credential_id, approverFingerprint(entry.public_key)])), document };
+  });
+  const base = documents[1].document;
+  const malformed = [
+    ['array', 'approvers', 'A list instead of an object.', { document: [base] }],
+    ['not-json', 'approvers', 'Text that is not JSON.', { json: '{"format":"ias-approvers-1",' }],
+    ['other-format', 'approvers.format', 'Another format.', { document: altered(base, (d) => (d.format = 'ias-approvers-2')) }],
+    ['missing-signature', 'approvers.fields', 'No signature.', { document: altered(base, (d) => delete d.signature) }],
+    ['extra-field', 'approvers.fields', 'A field besides format, version, rp_id, origins, approvers and signature.', { document: altered(base, (d) => (d.issued_at = '2026-10-21T10:00:00+00:00')) }],
+    ['version-zero', 'approvers.version', 'Version 0.', { document: altered(base, (d) => (d.version = 0)) }],
+    ['version-string', 'approvers.version', 'The version as a string.', { document: altered(base, (d) => (d.version = '2')) }],
+    ['version-decimal', 'approvers.version', 'A version with decimals.', { document: altered(base, (d) => (d.version = 2.5)) }],
+    ['rp-id-uppercase', 'approvers.rp_id', 'An rp_id in capitals.', { document: altered(base, (d) => (d.rp_id = 'IAS.imagina.build')) }],
+    ['rp-id-url', 'approvers.rp_id', 'An rp_id with its scheme: it is a domain, not an origin.', { document: altered(base, (d) => (d.rp_id = 'https://ias.imagina.build')) }],
+    ['rp-id-ip', 'approvers.rp_id', 'An IP address, which WebAuthn never takes as rp_id.', { document: altered(base, (d) => (d.rp_id = '127.0.0.1')) }],
+    ['origins-empty', 'approvers.origins', 'No origins.', { document: altered(base, (d) => (d.origins = [])) }],
+    ['origins-string', 'approvers.origins', 'One origin as a string, not a list.', { document: altered(base, (d) => (d.origins = 'https://ias.imagina.build')) }],
+    ['origins-too-many', 'approvers.origins', `More than ${APPROVER_LIMITS.origins} origins.`, { document: altered(base, (d) => (d.origins = Array.from({ length: APPROVER_LIMITS.origins + 1 }, (_, index) => `https://panel-${index}.imagina.build`))) }],
+    ['origin-with-path', 'approvers.origin', 'An origin with a trailing slash.', { document: altered(base, (d) => (d.origins = ['https://ias.imagina.build/'])) }],
+    ['origin-http', 'approvers.origin', 'http for a host that is not localhost.', { document: altered(base, (d) => (d.origins = ['http://ias.imagina.build'])) }],
+    ['origin-default-port', 'approvers.origin', 'The default port, which a browser leaves out of clientDataJSON.', { document: altered(base, (d) => (d.origins = ['https://ias.imagina.build:443'])) }],
+    ['origin-uppercase', 'approvers.origin', 'A host in capitals.', { document: altered(base, (d) => (d.origins = ['https://IAS.imagina.build'])) }],
+    ['origin-duplicate', 'approvers.origin', 'The same origin twice.', { document: altered(base, (d) => d.origins.push(d.origins[0])) }],
+    ['approvers-empty', 'approvers.list', 'Nobody can approve: a list must have at least one passkey.', { document: altered(base, (d) => (d.approvers = [])) }],
+    ['approvers-object', 'approvers.list', 'The approvers as an object keyed by credential id.', { document: altered(base, (d) => (d.approvers = Object.fromEntries(d.approvers.map((entry) => [entry.credential_id, entry])))) }],
+    ['approver-email', 'approver', 'An approver with the member\'s email: the list carries only the five fields.', { document: altered(base, (d) => (d.approvers[0].email = 'owner@example.com')) }],
+    ['approver-without-alg', 'approver', 'An approver without alg.', { document: altered(base, (d) => delete d.approvers[1].alg) }],
+    ['credential-id-padded', 'approver.credential_id', 'Padding after a credential id.', { document: altered(base, (d) => (d.approvers[0].credential_id = `${d.approvers[0].credential_id}==`)) }],
+    ['credential-id-empty', 'approver.credential_id', 'An empty credential id.', { document: altered(base, (d) => (d.approvers[0].credential_id = '')) }],
+    ['public-key-pem', 'approver.public_key', 'The public key as PEM text.', { document: altered(base, (d) => (d.approvers[0].public_key = createPublicKey({ key: Buffer.from(d.approvers[0].public_key, 'base64url'), format: 'der', type: 'spki' }).export({ format: 'pem', type: 'spki' }))) }],
+    ['public-key-raw-point', 'approver.public_key', 'The raw P-256 point (0x04, x, y) instead of a SubjectPublicKeyInfo.', { document: altered(base, (d) => (d.approvers[0].public_key = encode(Buffer.from(d.approvers[0].public_key, 'base64url').subarray(-65)))) }],
+    ['alg-eddsa', 'approver.alg', 'alg -8 (EdDSA), which the runner does not check.', { document: altered(base, (d) => (d.approvers[0].alg = -8)) }],
+    ['alg-string', 'approver.alg', 'alg as a string.', { document: altered(base, (d) => (d.approvers[0].alg = '-7')) }],
+    ['alg-of-other-key', 'approver.key', 'alg -257 (RS256) for a P-256 key.', { document: altered(base, (d) => (d.approvers[0].alg = -257)) }],
+    ['key-p-384', 'approver.key', 'A P-384 key under alg -7, which is P-256 only.', { document: altered(base, (d) => Object.assign(d.approvers[1], { credential_id: keys['p-384'].credential_id, public_key: keys['p-384'].public_key })) }],
+    ['key-rsa-1024', 'approver.key', 'An RSA key of 1024 bits under alg -257.', { document: altered(base, (d) => Object.assign(d.approvers[2], { credential_id: keys['rsa-1024'].credential_id, public_key: keys['rsa-1024'].public_key })) }],
+    ['member-empty', 'approver.member', 'An approver without a member.', { document: altered(base, (d) => (d.approvers[0].member = '')) }],
+    ['name-newline', 'approver.name', 'A line break in a name, which would make the signed text read two ways.', { document: altered(base, (d) => (d.approvers[0].name = 'Owner de prueba\n-7')) }],
+    ['name-empty', 'approver.name', 'An empty name.', { document: altered(base, (d) => (d.approvers[0].name = '')) }],
+    ['name-too-long', 'approver.name', `A name of ${APPROVER_LIMITS.name + 1} characters.`, { document: altered(base, (d) => (d.approvers[0].name = 'ñ'.repeat(APPROVER_LIMITS.name + 1))) }],
+    ['approver-duplicate', 'approver.duplicate', 'The same passkey twice.', { document: altered(base, (d) => d.approvers.push(structuredClone(d.approvers[0]))) }],
+    ['signature-sig-63-bytes', 'signature.sig', 'A 63-byte signature.', { document: altered(base, (d) => (d.signature.sig = encode(Buffer.from(d.signature.sig, 'base64url').subarray(1)))) }],
+    ['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', 'The list signed by another team\'s key with its own kid (options.signingKid is the team\'s).', { document: signApprovers(base, signing['other-team'].privateKey), options: { signingKid: team.kid } }],
+  ].map(([name, code, description, value]) => {
+    const result = validateApprovers('json' in value ? value.json : value.document, value.options ?? {});
+    if (result.valid || result.code !== code) throw new Error(`malformed approvers document ${name} gives ${result.valid ? 'valid' : result.code}, not ${code}`);
+    return { name, code, description, ...value };
+  });
+  const tampered = [
+    ['approver-added-by-the-server', 'The server adds a passkey of its own: it could then approve any store job.', altered(base, (d) => d.approvers.push({ credential_id: keys.outsider.credential_id, public_key: keys.outsider.public_key, alg: keys.outsider.alg, member: '01930000-0000-7000-8000-00000000a009', name: 'Owner de prueba' }))],
+    ['public-key-replaced', 'The first approver keeps its credential id and name, with the key of another passkey.', altered(base, (d) => (d.approvers[0].public_key = keys.outsider.public_key))],
+    ['approver-removed', 'An approver removed without signing.', altered(base, (d) => d.approvers.pop())],
+    ['origin-added', 'An origin of someone else added, where a passkey could be asked to sign.', altered(base, (d) => d.origins.push('https://ias.imagina.build.evil.example'))],
+    ['rp-id-changed', 'Another rp_id.', altered(base, (d) => (d.rp_id = 'imagina.build'))],
+    ['version-raised', 'The version raised without signing, to look newer than the one a runner has.', altered(base, (d) => (d.version = 9))],
+    ['name-changed', 'The name of an approver changed.', altered(base, (d) => (d.approvers[2].name = 'Otra persona'))],
+    ['approvers-reordered', 'The approvers in another order.', altered(base, (d) => d.approvers.reverse())],
+    ['forged-under-the-team-kid', 'A list with the outsider\'s passkey signed by another key under the team\'s kid.', (() => {
+      const forged = signApprovers({ ...base, version: 3, approvers: [...base.approvers, { credential_id: keys.outsider.credential_id, public_key: keys.outsider.public_key, alg: keys.outsider.alg, member: owner, name: 'Owner de prueba' }] }, signing['other-team'].privateKey);
+      return { ...forged, signature: { kid: team.kid, sig: forged.signature.sig } };
+    })()],
+  ].map(([name, description, document]) => {
+    if (!validateApprovers(document, { signingKid: team.kid }).valid) throw new Error(`tampered approvers document ${name} is not well formed`);
+    try {
+      verifyApprovers(document, team.publicKey);
+      throw new Error(`tampered approvers document ${name} verifies`);
+    } catch (error) {
+      if (error.code !== 'signature-invalid') throw new Error(`tampered approvers document ${name} fails with ${error.code ?? error.message}`);
+    }
+    return { name, description, error: 'signature-invalid', document };
+  });
+  const older = [
+    ['older-than-seen', 'Version 1 when the runner has already seen version 2: a server that serves an older list, still signed, to bring back a removed passkey.', documents[0].document, 2],
+  ].map(([name, description, document, minimumVersion]) => {
+    try {
+      verifyApprovers(document, team.publicKey, { minimumVersion });
+      throw new Error(`older approvers document ${name} verifies`);
+    } catch (error) {
+      if (error.code !== 'version-backwards') throw new Error(`older approvers document ${name} fails with ${error.code ?? error.message}`);
+    }
+    return { name, description, options: { minimumVersion }, error: 'version-backwards', document };
+  });
+  return {
+    format: APPROVERS_FORMAT,
+    description: `The passkeys that may approve a store job (${APPROVERS_FORMAT}, docs/technical/vault.md §2.4 and docs/technical/runner-api.md §1), signed with the team key of keys.json (signing.team; other-team makes the forgeries). passkeys are public keys only: alg is the COSE algorithm an approver uses with it, or null if none may. documents are good ones, each with the signedText the signature covers and the fingerprint of each passkey; the first holds the approvers of tests/Fixtures/runner-v1/approval-vectors.json. malformed must be rejected with code (validateApprovers, with options); tampered are well formed but do not verify; older verify but are older than options.minimumVersion.`,
+    warning: 'Test vectors: the keys are public. Never use them for anything else.',
+    signing: { kid: team.kid, publicKey: team.publicKey },
+    passkeys: keys,
+    documents,
+    malformed,
+    tampered,
+    older,
+  };
+}