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

package/shared/vault/index.mjs

@@ -0,0 +1,583 @@
+// The sealed vault of IAS (docs/technical/vault.md, PLAN-APPLICATION-SERVICES.md §2.5). Each secret is encrypted with a random
+// data key, and the data key is wrapped for every recipient (the team's recovery key and each authorised runner) with
+// an ephemeral X25519 key, HKDF-SHA256 and AES-256-GCM. In ias-vault-2 the team signs the whole envelope with its
+// Ed25519 key (decision D11), and the runner checks that signature against the team key it pinned, so a server that
+// seals an envelope of its own is caught. The server stores envelopes and checks their shape (validateEnvelope) but
+// holds no private key, so it can never open one nor sign one. ias-vault-1, unsigned, stays for the tests. Only
+// node:crypto.
+import { Buffer } from 'node:buffer';
+import { createCipheriv, createDecipheriv, createHash, createPrivateKey, createPublicKey, diffieHellman, hkdfSync, randomBytes, sign, verify } from 'node:crypto';
+
+export const FORMAT_1 = 'ias-vault-1';
+export const FORMAT_2 = 'ias-vault-2';
+/** The format the CLI seals with and the server takes. ias-vault-1 is only for the tests (decision D11). */
+export const FORMAT = FORMAT_2;
+export const FORMATS = Object.freeze([FORMAT_1, FORMAT_2]);
+/** The list of authorised runners, signed by the team (docs/technical/vault.md §9). */
+export const RUNNERS_FORMAT = 'ias-vault-2/runners';
+
+/** The limits of the format. The server enforces the same ones; changing them changes the format. */
+export const LIMITS = Object.freeze({
+  envelopeBytes: 512 * 1024,
+  plaintextBytes: 256 * 1024,
+  recipients: 64,
+  /** Runners in the signed list: with the recovery key, an envelope for all of them still fits in `recipients`. */
+  runners: 63,
+  version: 2147483647,
+});
+
+/** Who a recipient key belongs to. It is metadata of the key, not part of an envelope. */
+export const RECIPIENT_KINDS = Object.freeze(['recovery', 'runner']);
+
+export const KEY_BYTES = 32;
+export const IV_BYTES = 12;
+export const TAG_BYTES = 16;
+export const SIGNATURE_BYTES = 64;
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const BASE64URL = /^[A-Za-z0-9_-]*$/;
+
+/**
+ * What changes from one format to the other: the fields of the envelope, the pattern of credential.type (in
+ * ias-vault-2 it is the name of the management API, apple_distribution_certificate…) and whether the team signs it.
+ * Every string that goes into a derivation starts with the format, so an envelope of one never opens as the other.
+ */
+const SPECS = Object.freeze({
+  [FORMAT_1]: { fields: ['format', 'credential', 'data', 'recipients'], type: /^[a-z][a-z0-9-]{0,63}$/, typeRule: 'a-z 0-9 -', signed: false },
+  [FORMAT_2]: { fields: ['format', 'credential', 'data', 'recipients', 'signature'], type: /^[a-z][a-z0-9_]{0,63}$/, typeRule: 'a-z 0-9 _', signed: true },
+});
+
+/** DER prefixes of X25519 and Ed25519 keys (RFC 8410): the raw 32 bytes follow them. */
+const PKCS8_X25519 = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const SPKI_X25519 = Buffer.from('302a300506032b656e032100', 'hex');
+const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex');
+const SPKI_ED25519 = Buffer.from('302a300506032b6570032100', 'hex');
+
+/** A vault failure. `code` is stable (docs/technical/vault.md §7) and the message never holds key material or plaintext. */
+export class VaultError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'VaultError';
+    this.code = code;
+  }
+}
+
+export const encode = (bytes) => Buffer.from(bytes).toString('base64url');
+
+/** Decodes canonical unpadded base64url: anything else (padding, +/, stray bits) is null. */
+export function decode(text) {
+  if (typeof text !== 'string' || !BASE64URL.test(text) || text.length % 4 === 1) return null;
+  const bytes = Buffer.from(text, 'base64url');
+  return bytes.toString('base64url') === text ? bytes : null;
+}
+
+const sha256 = (data) => createHash('sha256').update(data).digest();
+
+/** The identifier of a key (a recipient's or the team's signing key): the SHA-256 of its raw 32-byte public key, in base64url. */
+export function keyId(publicKey) {
+  const raw = typeof publicKey === 'string' ? decode(publicKey) : Buffer.from(publicKey);
+  if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('key', 'a public key is 32 bytes in base64url');
+  return encode(sha256(raw));
+}
+
+const privateKeyObject = (raw) => createPrivateKey({ key: Buffer.concat([PKCS8_X25519, raw]), format: 'der', type: 'pkcs8' });
+const publicKeyObject = (raw) => createPublicKey({ key: Buffer.concat([SPKI_X25519, raw]), format: 'der', type: 'spki' });
+const rawPublicKey = (privateKey) => createPublicKey(privateKey).export({ format: 'der', type: 'spki' }).subarray(SPKI_X25519.length);
+
+/** `n` bytes from the random source; vectors inject theirs (docs/technical/vault.md §4 gives the order). */
+function take(random, n) {
+  const bytes = random(n);
+  if (!(bytes instanceof Uint8Array) || bytes.length !== n) throw new VaultError('random', `the random source must return ${n} bytes`);
+  return Buffer.from(bytes);
+}
+
+/** The rules of `format`, or a VaultError if the library does not know it. */
+function specOf(format) {
+  const spec = SPECS[format];
+  if (!spec) throw new VaultError('format', `the format is one of: ${FORMATS.join(', ')}`);
+  return spec;
+}
+
+/** The formats a caller accepts: a subset of FORMATS, the current one by default. */
+function acceptedFormats(formats = [FORMAT]) {
+  if (!Array.isArray(formats) || formats.length === 0 || formats.some((format) => !SPECS[format])) throw new VaultError('format', `formats is a list of: ${FORMATS.join(', ')}`);
+  return formats;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Keys.
+
+/**
+ * A new recipient key pair: the team's recovery key or a runner's. The private key never goes to the server: the
+ * recovery one lives in 1Password, a runner's in its keychain. The server gets publicRecipient(key).
+ */
+export function generateRecipient(kind, { random = randomBytes } = {}) {
+  if (!RECIPIENT_KINDS.includes(kind)) throw new VaultError('key', `a recipient is one of: ${RECIPIENT_KINDS.join(', ')}`);
+  return recipientFromPrivateKey(encode(take(random, KEY_BYTES)), kind);
+}
+
+/** The key pair of a private key (base64url of its 32 raw bytes), as generateRecipient returns it. */
+export function recipientFromPrivateKey(privateKey, kind) {
+  const raw = decode(privateKey);
+  if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('key', 'a private key is 32 bytes in base64url');
+  const publicKey = encode(rawPublicKey(privateKeyObject(raw)));
+  return { ...(kind === undefined ? {} : { kind }), kid: keyId(publicKey), publicKey, privateKey };
+}
+
+/** What the server stores of a recipient: everything but the private key. */
+export function publicRecipient({ kind, kid, publicKey }) {
+  if (kid !== keyId(publicKey)) throw new VaultError('key', 'the kid does not match the public key');
+  return { ...(kind === undefined ? {} : { kind }), kid, publicKey };
+}
+
+/**
+ * A new signing key of the team (Ed25519, RFC 8032): { kid, publicKey, privateKey }, the private key being the 32-byte
+ * seed in base64url. It lives in 1Password beside the recovery key; the server and the runners get publicSigningKey().
+ */
+export function generateSigningKey({ random = randomBytes } = {}) {
+  return signingKeyFromPrivateKey(encode(take(random, KEY_BYTES)));
+}
+
+/** The signing key pair of a private key (the base64url of its 32-byte Ed25519 seed). */
+export function signingKeyFromPrivateKey(privateKey) {
+  const raw = decode(privateKey);
+  if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('signing-key', 'a signing private key is a 32-byte Ed25519 seed in base64url');
+  const object = createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, raw]), format: 'der', type: 'pkcs8' });
+  const publicKey = encode(createPublicKey(object).export({ format: 'der', type: 'spki' }).subarray(SPKI_ED25519.length));
+  return { kid: keyId(publicKey), publicKey, privateKey };
+}
+
+/** What the server and the runners keep of the team's signing key: { kid, publicKey }, the kid checked. */
+export function publicSigningKey({ kid, publicKey }) {
+  if (kid !== keyId(publicKey)) throw new VaultError('signing-key', 'the kid does not match the signing public key');
+  return { kid, publicKey };
+}
+
+/** The team's private signing key, from its seed or its pair: { kid, object }. */
+function signerOf(key) {
+  const seed = typeof key === 'string' ? key : key?.privateKey;
+  if (typeof seed !== 'string') throw new VaultError('signing-key', `an ${FORMAT_2} envelope is signed with the team's signing key (its private key)`);
+  const pair = signingKeyFromPrivateKey(seed);
+  return { kid: pair.kid, publicKey: pair.publicKey, object: createPrivateKey({ key: Buffer.concat([PKCS8_ED25519, decode(seed)]), format: 'der', type: 'pkcs8' }) };
+}
+
+/** The team's public signing key, the one a runner pinned: a base64url public key or { publicKey }. */
+function verifierOf(key) {
+  const publicKey = typeof key === 'string' ? key : key?.publicKey;
+  const raw = typeof publicKey === 'string' ? decode(publicKey) : null;
+  if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('signing-key', `an ${FORMAT_2} envelope is checked against the team's signing public key (32 bytes in base64url)`);
+  if (typeof key === 'object' && key.kid !== undefined && key.kid !== keyId(raw)) throw new VaultError('signing-key', 'the kid does not match the signing public key');
+  let object = null;
+  try {
+    object = createPublicKey({ key: Buffer.concat([SPKI_ED25519, raw]), format: 'der', type: 'spki' });
+  } catch {
+    object = null; // bytes that are no point of the curve: nothing verifies against them
+  }
+  return { kid: keyId(raw), object };
+}
+
+const signText = (signer, text) => encode(sign(null, text, signer.object));
+
+function verifies(verifier, text, signature) {
+  if (verifier.object === null) return false;
+  try {
+    return verify(null, text, verifier.object, decode(signature));
+  } catch {
+    return false;
+  }
+}
+
+/** The recipients to wrap for, with their kid checked against the public key and no repeats. */
+function targets(recipients, { allowEmpty = false } = {}) {
+  if (!Array.isArray(recipients) || (!allowEmpty && recipients.length === 0)) throw new VaultError('recipients', 'an envelope needs at least one recipient');
+  const seen = new Set();
+  return recipients.map((recipient) => {
+    const raw = decode(recipient?.publicKey);
+    if (raw === null || raw.length !== KEY_BYTES) throw new VaultError('key', 'a recipient public key is 32 bytes in base64url');
+    const kid = keyId(raw);
+    if (recipient.kid !== undefined && recipient.kid !== kid) throw new VaultError('key', `the kid ${recipient.kid} does not match its public key`);
+    if (seen.has(kid)) throw new VaultError('recipient.duplicate', `${kid} is a recipient twice`);
+    seen.add(kid);
+    return { kid, raw };
+  });
+}
+
+/** The private key of the caller: a base64url string or a key pair from generateRecipient. */
+function ownKey(key) {
+  const pair = recipientFromPrivateKey(typeof key === 'string' ? key : key?.privateKey);
+  return { kid: pair.kid, raw: decode(pair.publicKey), object: privateKeyObject(decode(pair.privateKey)) };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// The pieces of docs/technical/vault.md §4 and §5.
+
+function credentialProblem(credential, spec) {
+  if (!isRecord(credential) || !sameKeys(credential, ['id', 'type', 'version'])) return ['credential', 'credential must be an object with exactly id, type and version'];
+  if (typeof credential.id !== 'string' || !ID.test(credential.id)) return ['credential.id', 'credential.id must be 1 to 128 characters of A-Z a-z 0-9 . _ - and start with a letter or digit'];
+  if (typeof credential.type !== 'string' || !spec.type.test(credential.type)) return ['credential.type', `credential.type must be 1 to 64 characters of ${spec.typeRule} and start with a letter`];
+  if (!Number.isInteger(credential.version) || credential.version < 1 || credential.version > LIMITS.version) return ['credential.version', `credential.version must be an integer from 1 to ${LIMITS.version}`];
+  return null;
+}
+
+/**
+ * The associated data that binds the data ciphertext to its credential (id, type and version) and, with `kid`, a
+ * wrap to its recipient as well. Neither can be moved to another credential, version, recipient or format.
+ */
+export function associatedData({ id, type, version }, kid, format = FORMAT) {
+  specOf(format);
+  return Buffer.from(kid === undefined ? `${format}\ndata\n${id}\n${type}\n${version}` : `${format}\nwrap\n${id}\n${type}\n${version}\n${kid}`, 'utf8');
+}
+
+/** The key that wraps the data key for one recipient: HKDF-SHA256 of the X25519 secret, salted with both public keys. */
+export function wrapKey(sharedSecret, ephemeralPublicKey, recipientPublicKey, format = FORMAT) {
+  specOf(format);
+  return Buffer.from(hkdfSync('sha256', sharedSecret, Buffer.concat([ephemeralPublicKey, recipientPublicKey]), Buffer.from(`${format}/x25519-hkdf-sha256-aes-256-gcm`, 'utf8'), KEY_BYTES));
+}
+
+/**
+ * What the team signs in an ias-vault-2 envelope (docs/technical/vault.md §5.1): every field of the envelope but the signature
+ * itself, one per line, with the kid of the signing key and the number of wraps. No field can hold a newline, so the
+ * text reads back one way only.
+ */
+export function signedText({ credential, data, recipients }, signingKid) {
+  const lines = [FORMAT_2, 'signature', signingKid, credential.id, credential.type, String(credential.version), data.iv, data.ct, String(recipients.length)];
+  for (const wrap of recipients) lines.push(wrap.kid, wrap.epk, wrap.iv, wrap.wk);
+  return Buffer.from(lines.join('\n'), 'utf8');
+}
+
+function encrypt(key, iv, aad, plaintext) {
+  const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+  cipher.setAAD(aad);
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+/** AES-256-GCM decryption of ciphertext‖tag; null when it does not authenticate. */
+function decrypt(key, iv, aad, sealed) {
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: TAG_BYTES });
+    decipher.setAAD(aad);
+    decipher.setAuthTag(sealed.subarray(sealed.length - TAG_BYTES));
+    return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - TAG_BYTES)), decipher.final()]);
+  } catch {
+    return null;
+  }
+}
+
+function wrapFor(dataKey, credential, { kid, raw }, random, format) {
+  const ephemeral = privateKeyObject(take(random, KEY_BYTES));
+  const epk = rawPublicKey(ephemeral);
+  const iv = take(random, IV_BYTES);
+  const shared = diffieHellman({ privateKey: ephemeral, publicKey: publicKeyObject(raw) });
+  return { kid, epk: encode(epk), iv: encode(iv), wk: encode(encrypt(wrapKey(shared, epk, raw, format), iv, associatedData(credential, kid, format), dataKey)) };
+}
+
+/** The envelope with the team's signature, when its format is signed; the fields in their order. */
+function signed(envelope, signer) {
+  const { format, credential, data, recipients } = envelope;
+  if (!specOf(format).signed) return { format, credential, data, recipients };
+  return { format, credential, data, recipients, signature: { kid: signer.kid, sig: signText(signer, signedText(envelope, signer.kid)) } };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Sealing, checking and opening.
+
+/**
+ * Seals `plaintext` (bytes or a UTF-8 string) for `recipients` ({ publicKey, kid? }) as a credential's version. In
+ * ias-vault-2, `signingKey` is the team's private signing key (seed or pair). The random source is called for the data
+ * key, the data IV and then, per recipient in order, the ephemeral private key and the wrap IV.
+ */
+export function seal(plaintext, { credential, recipients, signingKey, format = FORMAT, random = randomBytes }) {
+  const spec = specOf(format);
+  const signer = spec.signed ? signerOf(signingKey) : null;
+  const binding = isRecord(credential) ? { id: credential.id, type: credential.type, version: credential.version } : credential;
+  const problem = credentialProblem(binding, spec);
+  if (problem) throw new VaultError(...problem);
+  const bytes = typeof plaintext === 'string' ? Buffer.from(plaintext, 'utf8') : plaintext instanceof Uint8Array ? Buffer.from(plaintext) : null;
+  if (bytes === null || bytes.length === 0 || bytes.length > LIMITS.plaintextBytes) throw new VaultError('plaintext', `the plaintext must be 1 to ${LIMITS.plaintextBytes} bytes`);
+  const to = targets(recipients);
+  if (to.length > LIMITS.recipients) throw new VaultError('recipients', `an envelope has at most ${LIMITS.recipients} recipients`);
+  const dataKey = take(random, KEY_BYTES);
+  try {
+    const iv = take(random, IV_BYTES);
+    return signed(
+      {
+        format,
+        credential: binding,
+        data: { iv: encode(iv), ct: encode(encrypt(dataKey, iv, associatedData(binding, undefined, format), bytes)) },
+        recipients: to.map((recipient) => wrapFor(dataKey, binding, recipient, random, format)),
+      },
+      signer,
+    );
+  } finally {
+    dataKey.fill(0);
+  }
+}
+
+/** An envelope given as JSON text or as an object, checked; throws VaultError with the code of the first problem. */
+function parse(envelope, options) {
+  const result = validateEnvelope(envelope, options);
+  if (!result.valid) throw new VaultError(result.code, result.message);
+  return typeof envelope === 'string' ? JSON.parse(envelope) : structuredClone(envelope);
+}
+
+/** Throws signature-invalid unless the team's signature of `envelope` verifies with `verifier`. */
+function checkSignature(envelope, verifier) {
+  if (!verifies(verifier, signedText(envelope, envelope.signature.kid), envelope.signature.sig)) {
+    throw new VaultError('signature-invalid', `the signature does not verify with the team's signing key ${verifier.kid}: the envelope was altered, or made by someone without that key`);
+  }
+}
+
+/**
+ * Checks the team's signature of an ias-vault-2 envelope against `signedBy`, the team's public signing key the runner
+ * pinned, and returns the envelope parsed. Throws signature.unknown when it is signed with another key and
+ * signature-invalid when the signature does not verify.
+ */
+export function verifyEnvelope(envelope, signedBy) {
+  const verifier = verifierOf(signedBy);
+  const parsed = parse(envelope, { formats: [FORMAT_2], signingKid: verifier.kid });
+  checkSignature(parsed, verifier);
+  return parsed;
+}
+
+/** The data key of `envelope` for `own`, checked against the data ciphertext so that a wrong key is never handed on. */
+function dataKeyFor(envelope, own) {
+  const { format } = envelope;
+  const wrap = envelope.recipients.find((candidate) => candidate.kid === own.kid);
+  if (!wrap) throw new VaultError('not-a-recipient', `the key ${own.kid} is not a recipient of this envelope`);
+  let key = null;
+  try {
+    const epk = decode(wrap.epk);
+    const shared = diffieHellman({ privateKey: own.object, publicKey: publicKeyObject(epk) });
+    key = decrypt(wrapKey(shared, epk, own.raw, format), decode(wrap.iv), associatedData(envelope.credential, wrap.kid, format), decode(wrap.wk));
+  } catch {
+    key = null; // a low-order ephemeral key makes the X25519 derivation fail
+  }
+  if (key === null) throw new VaultError('unwrap-failed', `the wrap for ${own.kid} does not open: it was altered, moved from another envelope or made for another key`);
+  const plaintext = decrypt(key, decode(envelope.data.iv), associatedData(envelope.credential, undefined, format), decode(envelope.data.ct));
+  if (plaintext === null) {
+    key.fill(0);
+    throw new VaultError('decrypt-failed', 'the data does not open with its data key: the ciphertext or its credential was altered, or the wrap comes from another envelope');
+  }
+  return { key, plaintext };
+}
+
+/** The envelope parsed for an operation of the team: its signature checked against the key that will sign it again. */
+function parseSigned(envelope, { formats, signingKey }) {
+  const parsed = parse(envelope, { formats: acceptedFormats(formats) });
+  if (!specOf(parsed.format).signed) return { parsed, signer: null };
+  const signer = signerOf(signingKey);
+  const verifier = verifierOf(signer.publicKey);
+  if (parsed.signature.kid !== verifier.kid) throw new VaultError('signature.unknown', `the envelope is signed with ${parsed.signature.kid}, not with the team's key ${verifier.kid}`);
+  checkSignature(parsed, verifier);
+  return { parsed, signer };
+}
+
+/**
+ * Opens `envelope` with a recipient's private key and returns the plaintext as bytes. An ias-vault-2 envelope opens
+ * only after its signature verifies with `signedBy`, the team's public signing key. ias-vault-1 opens only when
+ * `formats` names it.
+ */
+export function open(envelope, privateKey, { signedBy, formats } = {}) {
+  const accepted = acceptedFormats(formats);
+  const verifier = accepted.some((format) => SPECS[format].signed) && signedBy !== undefined ? verifierOf(signedBy) : null;
+  const parsed = parse(envelope, { formats: accepted, ...(verifier ? { signingKid: verifier.kid } : {}) });
+  if (specOf(parsed.format).signed) {
+    if (!verifier) throw new VaultError('signing-key', `an ${FORMAT_2} envelope opens only after checking its signature: pass the team's signing public key (signedBy)`);
+    checkSignature(parsed, verifier);
+  }
+  const { key, plaintext } = dataKeyFor(parsed, ownKey(privateKey));
+  key.fill(0);
+  return plaintext;
+}
+
+/**
+ * Opens the data key with `privateKey` (the recovery key, for `ias vault grant`) and wraps it for the recipients that
+ * do not have it yet. Recipients already in the envelope keep their wrap, so granting twice changes nothing. In
+ * ias-vault-2 the signature is checked first and made again with `signingKey`.
+ */
+export function rewrap(envelope, privateKey, recipients, { signingKey, formats, random = randomBytes } = {}) {
+  const { parsed, signer } = parseSigned(envelope, { formats, signingKey });
+  const { key, plaintext } = dataKeyFor(parsed, ownKey(privateKey));
+  plaintext.fill(0);
+  try {
+    const present = new Set(parsed.recipients.map((wrap) => wrap.kid));
+    const added = targets(recipients, { allowEmpty: true }).filter(({ kid }) => !present.has(kid));
+    if (parsed.recipients.length + added.length > LIMITS.recipients) throw new VaultError('recipients', `an envelope has at most ${LIMITS.recipients} recipients`);
+    return signed({ ...parsed, recipients: [...parsed.recipients, ...added.map((recipient) => wrapFor(key, parsed.credential, recipient, random, parsed.format))] }, signer);
+  } finally {
+    key.fill(0);
+  }
+}
+
+/**
+ * The envelope without the wrap of `kid`, signed again in ias-vault-2. It does not undo what that recipient may already
+ * have read (docs/technical/vault.md §10). The last recipient cannot be removed: nobody could open the envelope again.
+ */
+export function removeRecipient(envelope, kid, { signingKey, formats } = {}) {
+  const { parsed, signer } = parseSigned(envelope, { formats, signingKey });
+  if (!parsed.recipients.some((wrap) => wrap.kid === kid)) throw new VaultError('not-a-recipient', `${kid} is not a recipient of this envelope`);
+  if (parsed.recipients.length === 1) throw new VaultError('last-recipient', `${kid} is the only recipient: nobody could open the envelope without it`);
+  return signed({ ...parsed, recipients: parsed.recipients.filter((wrap) => wrap.kid !== kid) }, signer);
+}
+
+/** The kids an envelope is wrapped for, in order. */
+export function recipientsOf(envelope, { formats } = {}) {
+  return parse(envelope, { formats: acceptedFormats(formats) }).recipients.map((wrap) => wrap.kid);
+}
+
+/**
+ * A SHA-256 of what the envelope protects (format, credential, data IV and ciphertext), in base64url. Granting or
+ * revoking recipients does not change it, nor does the signature, so a store build job can name the exact secrets it
+ * was approved with (§2.6).
+ */
+export function digest(envelope, { formats } = {}) {
+  const { format, credential, data } = parse(envelope, { formats: acceptedFormats(formats) });
+  return encode(sha256(Buffer.from(`${format}\ndigest\n${credential.id}\n${credential.type}\n${credential.version}\n${data.iv}\n${data.ct}`, 'utf8')));
+}
+
+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);
+};
+const listed = (names) => `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`;
+
+/** A canonical base64url field of `size` bytes (or `min` to `max`). */
+function bytesProblem(value, path, { size, min = size, max = size }) {
+  const bytes = decode(value);
+  if (bytes === null || bytes.length < min || bytes.length > max) {
+    return [path, `${path} must be ${min === max ? min : `${min} to ${max}`} bytes in unpadded base64url`];
+  }
+  return null;
+}
+
+/** The shape of a signature: { kid, sig }, a 32-byte kid and a 64-byte Ed25519 signature. */
+function signatureProblem(signature) {
+  if (!isRecord(signature) || !sameKeys(signature, ['kid', 'sig'])) return ['signature', 'signature must be an object with exactly kid and sig'];
+  return bytesProblem(signature.kid, 'signature.kid', { size: KEY_BYTES }) ?? bytesProblem(signature.sig, 'signature.sig', { size: SIGNATURE_BYTES });
+}
+
+function shapeProblem(envelope, { formats, requiredKids, signingKid }) {
+  if (!isRecord(envelope)) return ['envelope', 'the envelope must be a JSON object'];
+  if (!formats.includes(envelope.format)) return ['format', `the format must be ${formats.join(' or ')}`];
+  const spec = SPECS[envelope.format];
+  if (!sameKeys(envelope, spec.fields)) return ['envelope.fields', `an ${envelope.format} envelope must have exactly ${listed(spec.fields)}`];
+  const credential = credentialProblem(envelope.credential, spec);
+  if (credential) return credential;
+  const { data, recipients } = envelope;
+  if (!isRecord(data) || !sameKeys(data, ['iv', 'ct'])) return ['data', 'data must be an object with exactly iv and ct'];
+  const dataProblem = bytesProblem(data.iv, 'data.iv', { size: IV_BYTES }) ?? bytesProblem(data.ct, 'data.ct', { min: 1 + TAG_BYTES, max: LIMITS.plaintextBytes + TAG_BYTES });
+  if (dataProblem) return dataProblem;
+  if (!Array.isArray(recipients) || recipients.length === 0 || recipients.length > LIMITS.recipients) return ['recipients', `recipients must be a list of 1 to ${LIMITS.recipients} wraps`];
+  const seen = new Set();
+  for (const wrap of recipients) {
+    if (!isRecord(wrap) || !sameKeys(wrap, ['kid', 'epk', 'iv', 'wk'])) return ['recipient', 'each recipient must be an object with exactly kid, epk, iv and wk'];
+    const problem =
+      bytesProblem(wrap.kid, 'recipient.kid', { size: KEY_BYTES }) ??
+      bytesProblem(wrap.epk, 'recipient.epk', { size: KEY_BYTES }) ??
+      bytesProblem(wrap.iv, 'recipient.iv', { size: IV_BYTES }) ??
+      bytesProblem(wrap.wk, 'recipient.wk', { size: KEY_BYTES + TAG_BYTES });
+    if (problem) return problem;
+    if (seen.has(wrap.kid)) return ['recipient.duplicate', `${wrap.kid} is a recipient twice`];
+    seen.add(wrap.kid);
+  }
+  if (spec.signed) {
+    const problem = signatureProblem(envelope.signature);
+    if (problem) return problem;
+  }
+  const missing = requiredKids.find((kid) => !seen.has(kid));
+  if (missing !== undefined) return ['recipient.missing', `${missing} must be a recipient`];
+  if (spec.signed && signingKid !== undefined && envelope.signature.kid !== signingKid) return ['signature.unknown', `the envelope must be signed with the team's key ${signingKid}`];
+  return null;
+}
+
+/**
+ * Checks the shape of an envelope without opening it, which is all the server does: the fields, the format, the
+ * credential binding, the size of every value and, in ias-vault-2, the shape of the signature. `formats` are the
+ * formats taken (ias-vault-2 by default); `requiredKids` are kids that must be recipients (the server asks for the
+ * team's recovery key); `signingKid` is the kid the signature must have (the team's registered signing key). Returns
+ * { valid: true } or { valid: false, code, message } for the first problem. It does not verify the signature.
+ */
+export function validateEnvelope(envelope, { formats = [FORMAT], requiredKids = [], signingKid } = {}) {
+  const accepted = acceptedFormats(formats);
+  let value = envelope;
+  if (typeof envelope === 'string') {
+    if (Buffer.byteLength(envelope, 'utf8') > LIMITS.envelopeBytes) return { valid: false, code: 'too-large', message: `the envelope must not exceed ${LIMITS.envelopeBytes} bytes` };
+    try {
+      value = JSON.parse(envelope);
+    } catch {
+      return { valid: false, code: 'json', message: 'the envelope is not JSON' };
+    }
+  }
+  const problem = shapeProblem(value, { formats: accepted, requiredKids, signingKid });
+  return problem ? { valid: false, code: problem[0], message: problem[1] } : { valid: true };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// The list of authorised runners, signed by the team (docs/technical/vault.md §9).
+
+/** What the team signs in a runner list: its serial and each runner's kid and public key, in order. */
+export function runnerListText({ serial, runners }, signingKid) {
+  const lines = [FORMAT_2, 'runners', signingKid, String(serial), String(runners.length)];
+  for (const runner of runners) lines.push(runner.kid, runner.public_key);
+  return Buffer.from(lines.join('\n'), 'utf8');
+}
+
+/**
+ * The list of the runners the team authorised, signed with `signingKey`: { format, serial, runners, signature }.
+ * `runners` are { publicKey, kid? }; `serial` goes up by one with every change, so an older list can be told apart.
+ */
+export function signRunnerList({ serial, runners }, signingKey) {
+  const signer = signerOf(signingKey);
+  if (!Number.isInteger(serial) || serial < 1 || serial > LIMITS.version) throw new VaultError('runners.serial', `the serial is an integer from 1 to ${LIMITS.version}`);
+  const entries = targets(runners, { allowEmpty: true }).map(({ kid, raw }) => ({ kid, public_key: encode(raw) }));
+  if (entries.length > LIMITS.runners) throw new VaultError('runners.list', `the list has at most ${LIMITS.runners} runners`);
+  const list = { format: RUNNERS_FORMAT, serial, runners: entries };
+  return { ...list, signature: { kid: signer.kid, sig: signText(signer, runnerListText(list, signer.kid)) } };
+}
+
+/**
+ * Checks the shape of a runner list, as validateEnvelope does for an envelope: { valid: true } or { valid: false, code,
+ * message }. With `signingKid`, the signature must carry it. Each kid must be the SHA-256 of its public key.
+ */
+export function validateRunnerList(list, { signingKid } = {}) {
+  const fail = (code, message) => ({ valid: false, code, message });
+  if (!isRecord(list)) return fail('runners', 'the runner list must be a JSON object');
+  if (list.format !== RUNNERS_FORMAT) return fail('runners.format', `the format of the runner list must be ${RUNNERS_FORMAT}`);
+  if (!sameKeys(list, ['format', 'serial', 'runners', 'signature'])) return fail('runners.fields', 'the runner list must have exactly format, serial, runners and signature');
+  if (!Number.isInteger(list.serial) || list.serial < 1 || list.serial > LIMITS.version) return fail('runners.serial', `serial must be an integer from 1 to ${LIMITS.version}`);
+  if (!Array.isArray(list.runners) || list.runners.length > LIMITS.runners) return fail('runners.list', `runners must be a list of at most ${LIMITS.runners} runners`);
+  const seen = new Set();
+  for (const runner of list.runners) {
+    if (!isRecord(runner) || !sameKeys(runner, ['kid', 'public_key'])) return fail('runner', 'each runner must be an object with exactly kid and public_key');
+    const problem = bytesProblem(runner.kid, 'runner.kid', { size: KEY_BYTES }) ?? bytesProblem(runner.public_key, 'runner.public_key', { size: KEY_BYTES });
+    if (problem) return fail(...problem);
+    if (runner.kid !== keyId(runner.public_key)) return fail('runner.key', `${runner.kid} is not the kid of its public key`);
+    if (seen.has(runner.kid)) return fail('runner.duplicate', `${runner.kid} is in the list twice`);
+    seen.add(runner.kid);
+  }
+  const problem = signatureProblem(list.signature);
+  if (problem) return fail(...problem);
+  if (signingKid !== undefined && list.signature.kid !== signingKid) return fail('signature.unknown', `the runner list must be signed with the team's key ${signingKid}`);
+  return { valid: true };
+}
+
+/**
+ * The runner list checked against `signedBy`, the team's public signing key: its runners as recipients ({ kind:
+ * 'runner', kid, publicKey }) to seal for, and its serial. Throws on the first problem.
+ */
+export function verifyRunnerList(list, signedBy) {
+  const verifier = verifierOf(signedBy);
+  const value = typeof list === 'string' ? JSON.parse(list) : list;
+  const result = validateRunnerList(value, { signingKid: verifier.kid });
+  if (!result.valid) throw new VaultError(result.code, result.message);
+  if (!verifies(verifier, runnerListText(value, value.signature.kid), value.signature.sig)) {
+    throw new VaultError('signature-invalid', `the runner list does not verify with the team's signing key ${verifier.kid}: it was altered, or made by someone without that key`);
+  }
+  return { serial: value.serial, runners: value.runners.map((runner) => ({ kind: 'runner', kid: runner.kid, publicKey: runner.public_key })) };
+}
+
+export { PLAINTEXT_TYPES, PlaintextError, decodePlaintext, encodePlaintext, validatePlaintext } from './plaintext.mjs';
+// The passkeys that may approve a store job, signed by the team with the same key (docs/technical/vault.md §2.4). approvers.mjs
+// imports this module; it only defines functions at its top level, so the cycle is safe either way it is entered.
+export { APPROVERS_FORMAT, APPROVER_ALGORITHMS, APPROVER_LIMITS, approverAlgorithm, approverFingerprint, approversText, signApprovers, validateApprovers, verifyApprovers } from './approvers.mjs';