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

package/shared/vault/approvers.mjs

@@ -0,0 +1,234 @@
+// The list of the passkeys that may approve a store job (ias-approvers-1, docs/technical/runner-api.md §1 and docs/technical/vault.md
+// §2.4), signed by the team with the same Ed25519 key as the envelopes and the runner list. A runner cannot ask the
+// server which passkeys belong to an owner (a compromised server would add its own), so it checks the approval of a
+// job against this document, after verifying it with the team key it pinned. ias vault approvers signs it; the server
+// stores it and hands it out with each store job, and checks only its shape. 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 APPROVERS_FORMAT = 'ias-approvers-1';
+
+/** The COSE algorithms a passkey of an approver may use (docs/technical/runner-api.md §3.3, step 6). */
+export const APPROVER_ALGORITHMS = Object.freeze({ ES256: -7, RS256: -257 });
+
+/** The limits of the document. The server enforces the same ones; changing them changes the format. */
+export const APPROVER_LIMITS = Object.freeze({
+  approvers: 64,
+  origins: 8,
+  credentialIdBytes: 1023,
+  publicKeyBytes: 2048,
+  name: 100,
+  rsaBits: 2048,
+  hostname: 253,
+});
+
+const FIELDS = ['format', 'version', 'rp_id', 'origins', 'approvers', 'signature'];
+const APPROVER_FIELDS = ['credential_id', 'public_key', 'alg', 'member', 'name'];
+const MEMBER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
+const HOSTNAME = new RegExp(`^${LABEL}(?:\\.${LABEL})*$`);
+const ORIGIN = new RegExp(`^(https)://(${LABEL}(?:\\.${LABEL})*)(?::([1-9][0-9]{0,4}))?$|^(http)://(localhost)(?::([1-9][0-9]{0,4}))?$`);
+const DEFAULT_PORTS = { https: 443, http: 80 };
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+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 lowercase DNS name that is not an IP address (its last label is not only digits): what WebAuthn takes as rp_id. */
+const isHostname = (value) => typeof value === 'string' && value.length <= APPROVER_LIMITS.hostname && HOSTNAME.test(value) && !/^[0-9]+$/.test(value.split('.').at(-1));
+
+/**
+ * Whether `value` is an origin exactly as a browser writes it in clientDataJSON: https://<host>[:port], or
+ * http://localhost[:port] to try it locally; lowercase, no path, no default port.
+ */
+function isOrigin(value) {
+  const match = typeof value === 'string' ? ORIGIN.exec(value) : null;
+  if (!match) return false;
+  const [scheme, host, port] = match[1] ? [match[1], match[2], match[3]] : [match[4], match[5], match[6]];
+  if (!isHostname(host)) return false;
+  return port === undefined || (Number(port) <= 65535 && Number(port) !== DEFAULT_PORTS[scheme]);
+}
+
+/**
+ * The COSE algorithm of a passkey's public key (SubjectPublicKeyInfo, DER, in base64url): -7 for a P-256 key and -257
+ * for RSA of 2048 bits or more, or null if it is anything else, or not in the canonical DER that node:crypto (and
+ * OpenSSL in PHP) writes again from it.
+ */
+export function approverAlgorithm(publicKey) {
+  const der = decode(publicKey);
+  if (der === null || der.length === 0 || der.length > APPROVER_LIMITS.publicKeyBytes) return null;
+  let key;
+  try {
+    key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    return null;
+  }
+  if (!key.export({ format: 'der', type: 'spki' }).equals(der)) return null;
+  if (key.asymmetricKeyType === 'ec' && key.asymmetricKeyDetails?.namedCurve === 'prime256v1') return APPROVER_ALGORITHMS.ES256;
+  if (key.asymmetricKeyType === 'rsa' && key.asymmetricKeyDetails?.modulusLength >= APPROVER_LIMITS.rsaBits) return APPROVER_ALGORITHMS.RS256;
+  return null;
+}
+
+/**
+ * The fingerprint of a passkey that `ias vault approvers` shows for a person to compare: the SHA-256 of its public key
+ * (the DER bytes), in base64url, as the kid of a vault key.
+ */
+export function approverFingerprint(publicKey) {
+  const der = decode(publicKey);
+  if (der === null || der.length === 0) throw new VaultError('approver.public_key', 'a public key is a SubjectPublicKeyInfo in base64url');
+  return encode(createHash('sha256').update(der).digest());
+}
+
+/** The first problem of one approver, as [code, message], or null. */
+function approverProblem(approver) {
+  if (!isRecord(approver) || !sameKeys(approver, APPROVER_FIELDS)) return ['approver', `each approver must be an object with exactly ${APPROVER_FIELDS.join(', ')}`];
+  const credentialId = decode(approver.credential_id);
+  if (credentialId === null || credentialId.length === 0 || credentialId.length > APPROVER_LIMITS.credentialIdBytes) return ['approver.credential_id', `credential_id must be 1 to ${APPROVER_LIMITS.credentialIdBytes} bytes in unpadded base64url`];
+  const der = decode(approver.public_key);
+  let parsed = null;
+  try {
+    parsed = der === null || der.length === 0 || der.length > APPROVER_LIMITS.publicKeyBytes ? null : createPublicKey({ key: der, format: 'der', type: 'spki' });
+  } catch {
+    parsed = null;
+  }
+  if (parsed === null || !parsed.export({ format: 'der', type: 'spki' }).equals(der)) return ['approver.public_key', `public_key must be a SubjectPublicKeyInfo in canonical DER, of at most ${APPROVER_LIMITS.publicKeyBytes} bytes, in unpadded base64url`];
+  if (!Object.values(APPROVER_ALGORITHMS).includes(approver.alg)) return ['approver.alg', `alg must be ${APPROVER_ALGORITHMS.ES256} (ES256) or ${APPROVER_ALGORITHMS.RS256} (RS256)`];
+  if (approverAlgorithm(approver.public_key) !== approver.alg) return ['approver.key', `the public key is not one of alg ${approver.alg}: ${approver.alg === APPROVER_ALGORITHMS.ES256 ? 'a P-256 key' : `an RSA key of ${APPROVER_LIMITS.rsaBits} bits or more`}`];
+  if (typeof approver.member !== 'string' || !MEMBER.test(approver.member)) return ['approver.member', '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'];
+  const { name } = approver;
+  if (typeof name !== 'string' || !name.isWellFormed() || CONTROL.test(name) || [...name].length === 0 || [...name].length > APPROVER_LIMITS.name) return ['approver.name', `name must be 1 to ${APPROVER_LIMITS.name} characters without control characters (no line breaks)`];
+  return null;
+}
+
+/** The first problem of a document, as [code, message], or null. */
+function documentProblem(document, { signingKid }) {
+  if (!isRecord(document)) return ['approvers', 'the approvers document must be a JSON object'];
+  if (document.format !== APPROVERS_FORMAT) return ['approvers.format', `the format must be ${APPROVERS_FORMAT}`];
+  if (!sameKeys(document, FIELDS)) return ['approvers.fields', `the approvers document must have exactly ${FIELDS.join(', ')}`];
+  if (!Number.isInteger(document.version) || document.version < 1 || document.version > LIMITS.version) return ['approvers.version', `version must be an integer from 1 to ${LIMITS.version}`];
+  if (!isHostname(document.rp_id)) return ['approvers.rp_id', 'rp_id must be a lowercase domain name, such as ias.imagina.build'];
+  if (!Array.isArray(document.origins) || document.origins.length === 0 || document.origins.length > APPROVER_LIMITS.origins) return ['approvers.origins', `origins must be a list of 1 to ${APPROVER_LIMITS.origins} origins`];
+  const origins = new Set();
+  for (const origin of document.origins) {
+    if (!isOrigin(origin)) return ['approvers.origin', `${JSON.stringify(origin)} is not an origin as a browser writes it: https://<host>[:port], lowercase, without a path or the default port`];
+    if (origins.has(origin)) return ['approvers.origin', `${origin} is in origins twice`];
+    origins.add(origin);
+  }
+  if (!Array.isArray(document.approvers) || document.approvers.length === 0 || document.approvers.length > APPROVER_LIMITS.approvers) return ['approvers.list', `approvers must be a list of 1 to ${APPROVER_LIMITS.approvers} passkeys`];
+  const seen = new Set();
+  for (const approver of document.approvers) {
+    const problem = approverProblem(approver);
+    if (problem) return problem;
+    if (seen.has(approver.credential_id)) return ['approver.duplicate', `the passkey ${approver.credential_id} is in the list twice`];
+    seen.add(approver.credential_id);
+  }
+  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 approvers document must be signed with the team's key ${signingKid}`];
+  return null;
+}
+
+/**
+ * What the team signs in an approvers document (docs/technical/vault.md §5.3): its version, rp_id, origins and each approver, one
+ * value per line, in order. No value can hold a line break, so the text reads back one way only.
+ */
+export function approversText({ version, rp_id: rpId, origins, approvers }, signingKid) {
+  const lines = [APPROVERS_FORMAT, 'approvers', signingKid, String(version), rpId, String(origins.length), ...origins, String(approvers.length)];
+  for (const approver of approvers) lines.push(approver.credential_id, approver.public_key, String(approver.alg), approver.member, approver.name);
+  return Buffer.from(lines.join('\n'), 'utf8');
+}
+
+/**
+ * Checks the shape of an approvers document (an object or its JSON), as validateRunnerList does for the runner list:
+ * { valid: true } or { valid: false, code, message } for the first problem. With `signingKid`, the signature must carry
+ * it. It does not verify the signature; the server checks no more than this.
+ */
+export function validateApprovers(document, { signingKid } = {}) {
+  let value = document;
+  if (typeof document === 'string') {
+    try {
+      value = JSON.parse(document);
+    } catch {
+      return { valid: false, code: 'approvers', message: 'the approvers document is not JSON' };
+    }
+  }
+  const problem = documentProblem(value, { signingKid });
+  return problem ? { valid: false, code: problem[0], message: problem[1] } : { valid: true };
+}
+
+/** 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 approvers document 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 runner pinned (base64url or { publicKey, kid? }): { kid, object }, object null if no key. */
+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 approvers document 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 approvers document of `version`, signed with `signingKey` (the team's seed or pair): { format, version, rp_id,
+ * origins, approvers, signature }. Each approver is { credential_id, public_key, alg, member, name }; the order is kept
+ * and covered by the signature. Throws a VaultError with the code of validateApprovers for the first problem.
+ */
+export function signApprovers({ version, rp_id: rpId, origins, approvers }, signingKey) {
+  const signer = signerOf(signingKey);
+  const unsigned = {
+    format: APPROVERS_FORMAT,
+    version,
+    rp_id: rpId,
+    origins: Array.isArray(origins) ? [...origins] : origins,
+    approvers: Array.isArray(approvers) ? approvers.map((approver) => (isRecord(approver) ? Object.fromEntries(APPROVER_FIELDS.filter((field) => field in approver).map((field) => [field, approver[field]])) : approver)) : approvers,
+  };
+  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, approversText(unsigned, signer.kid), signer.object)) } };
+}
+
+/**
+ * The approvers document checked against `signedBy`, the team's public signing key the runner pinned: its shape, that
+ * it is signed with that key, that the signature verifies and, with `minimumVersion` (the highest version the runner
+ * has seen), that it is not older. Returns the document parsed; throws a VaultError otherwise (signature.unknown,
+ * signature-invalid, version-backwards, or a code of validateApprovers).
+ */
+export function verifyApprovers(document, signedBy, { minimumVersion } = {}) {
+  const verifier = verifierOf(signedBy);
+  let value = document;
+  if (typeof document === 'string') {
+    try {
+      value = JSON.parse(document);
+    } catch {
+      throw new VaultError('approvers', 'the approvers document 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, approversText(value, value.signature.kid), verifier.object, decode(value.signature.sig));
+  } catch {
+    verified = false;
+  }
+  if (!verified) throw new VaultError('signature-invalid', `the approvers document does not verify with the team's signing key ${verifier.kid}: it was altered, or made by someone without that key`);
+  if (minimumVersion !== undefined && value.version < minimumVersion) throw new VaultError('version-backwards', `the approvers document is version ${value.version}, older than version ${minimumVersion}, which this machine has already seen`);
+  return structuredClone(value);
+}