@geekmidas/constructs 10.0.0-alpha.46 → 10.0.0-alpha.48

package/dist/adaptors/testing.cjs

@@ -12,6 +12,7 @@ const require_Topic = require("../Topic-CkxOTrMv.cjs");
 const require_HonoEndpointAdaptor = require("../HonoEndpointAdaptor-CMi0MJsF.cjs");
 const require_processAudits = require("../processAudits-D_2W5x8k.cjs");
 let _geekmidas_manifest = require("@geekmidas/manifest");
+let node_crypto = require("node:crypto");
 let _geekmidas_errors = require("@geekmidas/errors");
 let _geekmidas_envkit = require("@geekmidas/envkit");
 let _geekmidas_services = require("@geekmidas/services");
@@ -19,7 +20,6 @@ let hono = require("hono");
 let _geekmidas_audit = require("@geekmidas/audit");
 let _geekmidas_testkit_context = require("@geekmidas/testkit/context");
 let msw = require("msw");
-let node_crypto = require("node:crypto");
 let _geekmidas_testkit_browser = require("@geekmidas/testkit/browser");
 let _geekmidas_testkit_faker = require("@geekmidas/testkit/faker");
 let _geekmidas_testkit_mailbox = require("@geekmidas/testkit/mailbox");

package/dist/adaptors/testing.mjs

@@ -10,6 +10,7 @@ import { t as Topic } from "../Topic-hPffOsot.mjs";
 import { t as HonoEndpoint } from "../HonoEndpointAdaptor-BIS0O3M9.mjs";
 import { n as executeWithAuditTransaction } from "../processAudits-BpRlPQMW.mjs";
 import { provideKey } from "@geekmidas/manifest";
+import { randomUUID } from "node:crypto";
 import { ForbiddenError } from "@geekmidas/errors";
 import { EnvironmentParser } from "@geekmidas/envkit";
 import { ServiceDiscovery, runWithRequestContext, serviceContext } from "@geekmidas/services";
@@ -17,7 +18,6 @@ import { Hono } from "hono";
 import { DefaultAuditor } from "@geekmidas/audit";
 import { TEST_CONTEXT_HEADER, currentTestContext, installContextFetch, runAsServer, runInTestContext, testContextOf } from "@geekmidas/testkit/context";
 import { http } from "msw";
-import { randomUUID } from "node:crypto";
 import { Browser } from "@geekmidas/testkit/browser";
 import { faker } from "@geekmidas/testkit/faker";
 import { createMailbox } from "@geekmidas/testkit/mailbox";

package/dist/cipher-C1lEFX63.mjs

@@ -0,0 +1,225 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+//#region src/encryption/cipher.ts
+/**
+* The cipher behind an `Encryption` construct, and the format it writes.
+*
+* Every ciphertext names the key that wrote it — `gkm1.<keyId>.<payload>` — so
+* `decrypt` never has to guess, a rotated key still opens what it wrote, and
+* retiring a key is a decision made against data rather than a hope. The
+* format version leads, so the day it has to change, both can be read.
+*
+* Two backends, picked by the scheme of the construct's URL, the way a queue's
+* connection string picks its broker:
+*
+* - `aes256gcm://` — a keyring this process holds: AES-256-GCM with the newest
+*   key, HMAC-SHA256 for the blind index. Local, test and server stages.
+* - `kms://` — envelope encryption under an AWS KMS key, and a KMS HMAC key for
+*   the index. The key material never leaves KMS. See `./kms`.
+*/
+/** The format every ciphertext leads with. */
+const CIPHERTEXT_VERSION = "gkm1";
+/** AES-256-GCM's nonce and tag, in bytes. */
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const LOCAL_SCHEME = "aes256gcm:";
+var EncryptionUrlInvalid = class extends Error {
+	construct;
+	reason;
+	constructor(construct, reason) {
+		super(`${construct}'s encryption URL is not usable: ${reason}. gkm composes it — derived locally, generated into a server stage's secrets on its first deploy, provisioned on AWS — so it should not be set by hand.`);
+		this.construct = construct;
+		this.reason = reason;
+		this.name = "EncryptionUrlInvalid";
+	}
+};
+var UnknownEncryptionScheme = class extends Error {
+	construct;
+	scheme;
+	constructor(construct, scheme) {
+		super(`${construct}'s encryption URL uses '${scheme}', which no cipher handles. Expected 'aes256gcm:' (a local keyring) or 'kms:' (AWS KMS).`);
+		this.construct = construct;
+		this.scheme = scheme;
+		this.name = "UnknownEncryptionScheme";
+	}
+};
+var CiphertextMalformed = class extends Error {
+	construct;
+	constructor(construct) {
+		super(`${construct} was asked to decrypt something it did not write: a ciphertext starts '${CIPHERTEXT_VERSION}.<key>.'. Check the column holds what \`encrypt\` returned, untrimmed.`);
+		this.construct = construct;
+		this.name = "CiphertextMalformed";
+	}
+};
+var EncryptionKeyRetired = class extends Error {
+	construct;
+	keyId;
+	constructor(construct, keyId) {
+		super(`${construct} has no key '${keyId}' any more, so a value it wrote cannot be read. It was retired before every value was re-encrypted; restore it from the stage's secrets history, run the sweep, then retire it again.`);
+		this.construct = construct;
+		this.keyId = keyId;
+		this.name = "EncryptionKeyRetired";
+	}
+};
+var CiphertextNotAuthentic = class extends Error {
+	construct;
+	constructor(construct) {
+		super(`${construct} could not authenticate a ciphertext: it was altered, or written by a different Encryption construct. Ciphertexts are bound to the construct that wrote them.`);
+		this.construct = construct;
+		this.name = "CiphertextNotAuthentic";
+	}
+};
+var CurrentKeyCannotRetire = class extends Error {
+	construct;
+	keyId;
+	constructor(construct, keyId) {
+		super(`'${keyId}' is ${construct}'s current key — everything new is written with it. Rotate first, sweep, then retire '${keyId}'.`);
+		this.construct = construct;
+		this.keyId = keyId;
+		this.name = "CurrentKeyCannotRetire";
+	}
+};
+/** A ciphertext's three parts. */
+function parseCiphertext(construct, ciphertext) {
+	const [version, keyId, payload, ...rest] = ciphertext.split(".");
+	if (version !== "gkm1" || !keyId || !payload || rest.length) throw new CiphertextMalformed(construct);
+	return {
+		keyId,
+		payload: Buffer.from(payload, "base64url")
+	};
+}
+function formatCiphertext(keyId, payload) {
+	return `${CIPHERTEXT_VERSION}.${keyId}.${payload.toString("base64url")}`;
+}
+/**
+* What the cipher authenticates alongside the data: the construct and the key.
+*
+* Binding the construct means a value copied from one `Encryption` into
+* another's column fails instead of decrypting under the wrong policy.
+*/
+function associatedData(construct, keyId) {
+	return Buffer.from(`${CIPHERTEXT_VERSION}:${construct}:${keyId}`);
+}
+/** `iv | tag | ciphertext`, under one AES-256-GCM key. */
+function seal(key, plaintext, aad) {
+	const iv = randomBytes(IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", key, iv);
+	cipher.setAAD(aad);
+	const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+	return Buffer.concat([
+		iv,
+		cipher.getAuthTag(),
+		body
+	]);
+}
+/** The inverse of {@link seal}; `undefined` when it does not authenticate. */
+function open(key, sealed, aad) {
+	if (sealed.length < 28) return void 0;
+	const decipher = createDecipheriv("aes-256-gcm", key, sealed.subarray(0, IV_BYTES));
+	decipher.setAAD(aad);
+	decipher.setAuthTag(sealed.subarray(IV_BYTES, 28));
+	try {
+		return Buffer.concat([decipher.update(sealed.subarray(28)), decipher.final()]);
+	} catch {
+		return;
+	}
+}
+/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */
+function parseKeyring(construct, url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new EncryptionUrlInvalid(construct, "it is not a URL");
+	}
+	const keys = (parsed.searchParams.get("keys") ?? "").split(",").filter(Boolean).map((entry) => {
+		const [id, encoded] = entry.split(".");
+		const key = Buffer.from(encoded ?? "", "base64url");
+		if (!id || key.length !== KEY_BYTES) throw new EncryptionUrlInvalid(construct, `'${id ?? entry}' is not a 256-bit key`);
+		return {
+			id,
+			key
+		};
+	});
+	if (keys.length === 0) throw new EncryptionUrlInvalid(construct, "it holds no keys");
+	const index = Buffer.from(parsed.searchParams.get("index") ?? "", "base64url");
+	if (index.length !== KEY_BYTES) throw new EncryptionUrlInvalid(construct, "its index key is missing");
+	return {
+		keys,
+		index
+	};
+}
+function formatKeyring(keyring) {
+	const keys = keyring.keys.map(({ id, key }) => `${id}.${key.toString("base64url")}`).join(",");
+	return `${LOCAL_SCHEME}//local?keys=${keys}&index=${keyring.index.toString("base64url")}`;
+}
+/** A keyring with one fresh key, `k1`, and a fresh index key. */
+function generateKeyring() {
+	return formatKeyring({
+		keys: [{
+			id: "k1",
+			key: randomBytes(KEY_BYTES)
+		}],
+		index: randomBytes(KEY_BYTES)
+	});
+}
+/**
+* The keyring with a new current key in front, and every older one kept.
+*
+* Nothing is dropped: what the old keys wrote still has to open until a sweep
+* has re-encrypted it — see {@link retireKey}.
+*/
+function rotateKeyring(construct, url) {
+	const keyring = parseKeyring(construct, url);
+	const next = Math.max(...keyring.keys.map(({ id }) => Number(id.slice(1)) || 0)) + 1;
+	return formatKeyring({
+		...keyring,
+		keys: [{
+			id: `k${next}`,
+			key: randomBytes(KEY_BYTES)
+		}, ...keyring.keys]
+	});
+}
+/** The keyring without `keyId`, which must not be the current key. */
+function retireKey(construct, url, keyId) {
+	const keyring = parseKeyring(construct, url);
+	if (keyring.keys[0]?.id === keyId) throw new CurrentKeyCannotRetire(construct, keyId);
+	if (!keyring.keys.some(({ id }) => id === keyId)) throw new EncryptionKeyRetired(construct, keyId);
+	return formatKeyring({
+		...keyring,
+		keys: keyring.keys.filter(({ id }) => id !== keyId)
+	});
+}
+/** The `aes256gcm://` cipher: a keyring held in process. */
+function keyringCipher(construct, url, onStaleKey = () => {}) {
+	const keyring = parseKeyring(construct, url);
+	const current = keyring.keys[0];
+	const byId = new Map(keyring.keys.map(({ id, key }) => [id, key]));
+	const reported = /* @__PURE__ */ new Set();
+	const decrypt = async (ciphertext) => {
+		const { keyId, payload } = parseCiphertext(construct, ciphertext);
+		const key = byId.get(keyId);
+		if (!key) throw new EncryptionKeyRetired(construct, keyId);
+		const plaintext = open(key, payload, associatedData(construct, keyId));
+		if (!plaintext) throw new CiphertextNotAuthentic(construct);
+		if (keyId !== current.id && !reported.has(keyId)) {
+			reported.add(keyId);
+			onStaleKey(keyId, current.id);
+		}
+		return plaintext.toString("utf8");
+	};
+	const encrypt = async (plaintext) => formatCiphertext(current.id, seal(current.key, Buffer.from(plaintext, "utf8"), associatedData(construct, current.id)));
+	return {
+		encrypt,
+		decrypt,
+		index: async (value) => createHmac("sha256", keyring.index).update(value, "utf8").digest("base64url"),
+		reencrypt: async (ciphertext) => {
+			const { keyId } = parseCiphertext(construct, ciphertext);
+			if (keyId === current.id) return ciphertext;
+			return encrypt(await decrypt(ciphertext));
+		}
+	};
+}
+//#endregion
+export { rotateKeyring as _, EncryptionUrlInvalid as a, associatedData as c, generateKeyring as d, keyringCipher as f, retireKey as g, parseKeyring as h, EncryptionKeyRetired as i, formatCiphertext as l, parseCiphertext as m, CiphertextNotAuthentic as n, LOCAL_SCHEME as o, open as p, CurrentKeyCannotRetire as r, UnknownEncryptionScheme as s, CiphertextMalformed as t, formatKeyring as u, seal as v };
+
+//# sourceMappingURL=cipher-C1lEFX63.mjs.map

package/dist/cipher-C1lEFX63.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-C1lEFX63.mjs","names":[],"sources":["../src/encryption/cipher.ts"],"sourcesContent":["/**\n * The cipher behind an `Encryption` construct, and the format it writes.\n *\n * Every ciphertext names the key that wrote it — `gkm1.<keyId>.<payload>` — so\n * `decrypt` never has to guess, a rotated key still opens what it wrote, and\n * retiring a key is a decision made against data rather than a hope. The\n * format version leads, so the day it has to change, both can be read.\n *\n * Two backends, picked by the scheme of the construct's URL, the way a queue's\n * connection string picks its broker:\n *\n * - `aes256gcm://` — a keyring this process holds: AES-256-GCM with the newest\n *   key, HMAC-SHA256 for the blind index. Local, test and server stages.\n * - `kms://` — envelope encryption under an AWS KMS key, and a KMS HMAC key for\n *   the index. The key material never leaves KMS. See `./kms`.\n */\n\nimport {\n\tcreateCipheriv,\n\tcreateDecipheriv,\n\tcreateHmac,\n\trandomBytes,\n} from 'node:crypto';\n\n/** What a handler is given: `services.pii.encrypt(…)` and the rest. */\nexport interface Cipher {\n\t/** Plaintext in, a self-describing ciphertext string out. */\n\tencrypt(plaintext: string): Promise<string>;\n\t/** Opens any ciphertext this construct wrote, under whichever key wrote it. */\n\tdecrypt(ciphertext: string): Promise<string>;\n\t/**\n\t * A blind index: the same value always gives the same string, so an\n\t * encrypted column can still be looked up by an indexed column beside it.\n\t *\n\t * Deterministic on purpose, which is also why its key never rotates — a\n\t * rotated index key would make every stored index miss.\n\t */\n\tindex(value: string): Promise<string>;\n\t/**\n\t * The same plaintext under the current key — what a sweep runs over a\n\t * column before an old key is retired. Unchanged when it is already current.\n\t */\n\treencrypt(ciphertext: string): Promise<string>;\n}\n\n/** The format every ciphertext leads with. */\nexport const CIPHERTEXT_VERSION = 'gkm1';\n\n/** AES-256-GCM's nonce and tag, in bytes. */\nconst IV_BYTES = 12;\nconst TAG_BYTES = 16;\nconst KEY_BYTES = 32;\n\nexport const LOCAL_SCHEME = 'aes256gcm:';\n\nexport class EncryptionUrlInvalid extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly reason: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct}'s encryption URL is not usable: ${reason}. gkm composes it — derived locally, generated into a server stage's secrets on its first deploy, provisioned on AWS — so it should not be set by hand.`,\n\t\t);\n\t\tthis.name = 'EncryptionUrlInvalid';\n\t}\n}\n\nexport class UnknownEncryptionScheme extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly scheme: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct}'s encryption URL uses '${scheme}', which no cipher handles. Expected 'aes256gcm:' (a local keyring) or 'kms:' (AWS KMS).`,\n\t\t);\n\t\tthis.name = 'UnknownEncryptionScheme';\n\t}\n}\n\nexport class CiphertextMalformed extends Error {\n\tconstructor(readonly construct: string) {\n\t\tsuper(\n\t\t\t`${construct} was asked to decrypt something it did not write: a ciphertext starts '${CIPHERTEXT_VERSION}.<key>.'. Check the column holds what \\`encrypt\\` returned, untrimmed.`,\n\t\t);\n\t\tthis.name = 'CiphertextMalformed';\n\t}\n}\n\nexport class EncryptionKeyRetired extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly keyId: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct} has no key '${keyId}' any more, so a value it wrote cannot be read. It was retired before every value was re-encrypted; restore it from the stage's secrets history, run the sweep, then retire it again.`,\n\t\t);\n\t\tthis.name = 'EncryptionKeyRetired';\n\t}\n}\n\nexport class CiphertextNotAuthentic extends Error {\n\tconstructor(readonly construct: string) {\n\t\tsuper(\n\t\t\t`${construct} could not authenticate a ciphertext: it was altered, or written by a different Encryption construct. Ciphertexts are bound to the construct that wrote them.`,\n\t\t);\n\t\tthis.name = 'CiphertextNotAuthentic';\n\t}\n}\n\nexport class CurrentKeyCannotRetire extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly keyId: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${keyId}' is ${construct}'s current key — everything new is written with it. Rotate first, sweep, then retire '${keyId}'.`,\n\t\t);\n\t\tthis.name = 'CurrentKeyCannotRetire';\n\t}\n}\n\n/** A ciphertext's three parts. */\nexport function parseCiphertext(\n\tconstruct: string,\n\tciphertext: string,\n): { keyId: string; payload: Buffer } {\n\tconst [version, keyId, payload, ...rest] = ciphertext.split('.');\n\tif (version !== CIPHERTEXT_VERSION || !keyId || !payload || rest.length) {\n\t\tthrow new CiphertextMalformed(construct);\n\t}\n\treturn { keyId, payload: Buffer.from(payload, 'base64url') };\n}\n\nexport function formatCiphertext(keyId: string, payload: Buffer): string {\n\treturn `${CIPHERTEXT_VERSION}.${keyId}.${payload.toString('base64url')}`;\n}\n\n/**\n * What the cipher authenticates alongside the data: the construct and the key.\n *\n * Binding the construct means a value copied from one `Encryption` into\n * another's column fails instead of decrypting under the wrong policy.\n */\nexport function associatedData(construct: string, keyId: string): Buffer {\n\treturn Buffer.from(`${CIPHERTEXT_VERSION}:${construct}:${keyId}`);\n}\n\n/** `iv | tag | ciphertext`, under one AES-256-GCM key. */\nexport function seal(key: Buffer, plaintext: Buffer, aad: Buffer): Buffer {\n\tconst iv = randomBytes(IV_BYTES);\n\tconst cipher = createCipheriv('aes-256-gcm', key, iv);\n\tcipher.setAAD(aad);\n\tconst body = Buffer.concat([cipher.update(plaintext), cipher.final()]);\n\treturn Buffer.concat([iv, cipher.getAuthTag(), body]);\n}\n\n/** The inverse of {@link seal}; `undefined` when it does not authenticate. */\nexport function open(\n\tkey: Buffer,\n\tsealed: Buffer,\n\taad: Buffer,\n): Buffer | undefined {\n\tif (sealed.length < IV_BYTES + TAG_BYTES) return undefined;\n\n\tconst decipher = createDecipheriv(\n\t\t'aes-256-gcm',\n\t\tkey,\n\t\tsealed.subarray(0, IV_BYTES),\n\t);\n\tdecipher.setAAD(aad);\n\tdecipher.setAuthTag(sealed.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));\n\n\ttry {\n\t\treturn Buffer.concat([\n\t\t\tdecipher.update(sealed.subarray(IV_BYTES + TAG_BYTES)),\n\t\t\tdecipher.final(),\n\t\t]);\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** A local keyring: newest key first, and the index key that never rotates. */\nexport interface Keyring {\n\tkeys: { id: string; key: Buffer }[];\n\tindex: Buffer;\n}\n\n/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */\nexport function parseKeyring(construct: string, url: string): Keyring {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(url);\n\t} catch {\n\t\tthrow new EncryptionUrlInvalid(construct, 'it is not a URL');\n\t}\n\n\tconst keys = (parsed.searchParams.get('keys') ?? '')\n\t\t.split(',')\n\t\t.filter(Boolean)\n\t\t.map((entry) => {\n\t\t\tconst [id, encoded] = entry.split('.');\n\t\t\tconst key = Buffer.from(encoded ?? '', 'base64url');\n\t\t\tif (!id || key.length !== KEY_BYTES) {\n\t\t\t\tthrow new EncryptionUrlInvalid(\n\t\t\t\t\tconstruct,\n\t\t\t\t\t`'${id ?? entry}' is not a 256-bit key`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn { id, key };\n\t\t});\n\tif (keys.length === 0) {\n\t\tthrow new EncryptionUrlInvalid(construct, 'it holds no keys');\n\t}\n\n\tconst index = Buffer.from(\n\t\tparsed.searchParams.get('index') ?? '',\n\t\t'base64url',\n\t);\n\tif (index.length !== KEY_BYTES) {\n\t\tthrow new EncryptionUrlInvalid(construct, 'its index key is missing');\n\t}\n\n\treturn { keys, index };\n}\n\nexport function formatKeyring(keyring: Keyring): string {\n\tconst keys = keyring.keys\n\t\t.map(({ id, key }) => `${id}.${key.toString('base64url')}`)\n\t\t.join(',');\n\treturn `${LOCAL_SCHEME}//local?keys=${keys}&index=${keyring.index.toString('base64url')}`;\n}\n\n/** A keyring with one fresh key, `k1`, and a fresh index key. */\nexport function generateKeyring(): string {\n\treturn formatKeyring({\n\t\tkeys: [{ id: 'k1', key: randomBytes(KEY_BYTES) }],\n\t\tindex: randomBytes(KEY_BYTES),\n\t});\n}\n\n/**\n * The keyring with a new current key in front, and every older one kept.\n *\n * Nothing is dropped: what the old keys wrote still has to open until a sweep\n * has re-encrypted it — see {@link retireKey}.\n */\nexport function rotateKeyring(construct: string, url: string): string {\n\tconst keyring = parseKeyring(construct, url);\n\tconst next =\n\t\tMath.max(...keyring.keys.map(({ id }) => Number(id.slice(1)) || 0)) + 1;\n\n\treturn formatKeyring({\n\t\t...keyring,\n\t\tkeys: [{ id: `k${next}`, key: randomBytes(KEY_BYTES) }, ...keyring.keys],\n\t});\n}\n\n/** The keyring without `keyId`, which must not be the current key. */\nexport function retireKey(\n\tconstruct: string,\n\turl: string,\n\tkeyId: string,\n): string {\n\tconst keyring = parseKeyring(construct, url);\n\tif (keyring.keys[0]?.id === keyId) {\n\t\tthrow new CurrentKeyCannotRetire(construct, keyId);\n\t}\n\tif (!keyring.keys.some(({ id }) => id === keyId)) {\n\t\tthrow new EncryptionKeyRetired(construct, keyId);\n\t}\n\n\treturn formatKeyring({\n\t\t...keyring,\n\t\tkeys: keyring.keys.filter(({ id }) => id !== keyId),\n\t});\n}\n\n/** Says, once per key per process, that a value is still under an old key. */\nexport type StaleKeyReporter = (keyId: string, current: string) => void;\n\n/** The `aes256gcm://` cipher: a keyring held in process. */\nexport function keyringCipher(\n\tconstruct: string,\n\turl: string,\n\tonStaleKey: StaleKeyReporter = () => {},\n): Cipher {\n\tconst keyring = parseKeyring(construct, url);\n\tconst current = keyring.keys[0]!;\n\tconst byId = new Map(keyring.keys.map(({ id, key }) => [id, key]));\n\tconst reported = new Set<string>();\n\n\tconst decrypt = async (ciphertext: string) => {\n\t\tconst { keyId, payload } = parseCiphertext(construct, ciphertext);\n\t\tconst key = byId.get(keyId);\n\t\tif (!key) throw new EncryptionKeyRetired(construct, keyId);\n\n\t\tconst plaintext = open(key, payload, associatedData(construct, keyId));\n\t\tif (!plaintext) throw new CiphertextNotAuthentic(construct);\n\n\t\tif (keyId !== current.id && !reported.has(keyId)) {\n\t\t\treported.add(keyId);\n\t\t\tonStaleKey(keyId, current.id);\n\t\t}\n\n\t\treturn plaintext.toString('utf8');\n\t};\n\n\tconst encrypt = async (plaintext: string) =>\n\t\tformatCiphertext(\n\t\t\tcurrent.id,\n\t\t\tseal(\n\t\t\t\tcurrent.key,\n\t\t\t\tBuffer.from(plaintext, 'utf8'),\n\t\t\t\tassociatedData(construct, current.id),\n\t\t\t),\n\t\t);\n\n\treturn {\n\t\tencrypt,\n\t\tdecrypt,\n\t\tindex: async (value) =>\n\t\t\tcreateHmac('sha256', keyring.index)\n\t\t\t\t.update(value, 'utf8')\n\t\t\t\t.digest('base64url'),\n\t\treencrypt: async (ciphertext) => {\n\t\t\tconst { keyId } = parseCiphertext(construct, ciphertext);\n\t\t\tif (keyId === current.id) return ciphertext;\n\t\t\treturn encrypt(await decrypt(ciphertext));\n\t\t},\n\t};\n}\n"],"mappings":"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"}

package/dist/cipher-CVxfwLjk.cjs

@@ -0,0 +1,332 @@
+let node_crypto = require("node:crypto");
+//#region src/encryption/cipher.ts
+/**
+* The cipher behind an `Encryption` construct, and the format it writes.
+*
+* Every ciphertext names the key that wrote it — `gkm1.<keyId>.<payload>` — so
+* `decrypt` never has to guess, a rotated key still opens what it wrote, and
+* retiring a key is a decision made against data rather than a hope. The
+* format version leads, so the day it has to change, both can be read.
+*
+* Two backends, picked by the scheme of the construct's URL, the way a queue's
+* connection string picks its broker:
+*
+* - `aes256gcm://` — a keyring this process holds: AES-256-GCM with the newest
+*   key, HMAC-SHA256 for the blind index. Local, test and server stages.
+* - `kms://` — envelope encryption under an AWS KMS key, and a KMS HMAC key for
+*   the index. The key material never leaves KMS. See `./kms`.
+*/
+/** The format every ciphertext leads with. */
+const CIPHERTEXT_VERSION = "gkm1";
+/** AES-256-GCM's nonce and tag, in bytes. */
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+const LOCAL_SCHEME = "aes256gcm:";
+var EncryptionUrlInvalid = class extends Error {
+	construct;
+	reason;
+	constructor(construct, reason) {
+		super(`${construct}'s encryption URL is not usable: ${reason}. gkm composes it — derived locally, generated into a server stage's secrets on its first deploy, provisioned on AWS — so it should not be set by hand.`);
+		this.construct = construct;
+		this.reason = reason;
+		this.name = "EncryptionUrlInvalid";
+	}
+};
+var UnknownEncryptionScheme = class extends Error {
+	construct;
+	scheme;
+	constructor(construct, scheme) {
+		super(`${construct}'s encryption URL uses '${scheme}', which no cipher handles. Expected 'aes256gcm:' (a local keyring) or 'kms:' (AWS KMS).`);
+		this.construct = construct;
+		this.scheme = scheme;
+		this.name = "UnknownEncryptionScheme";
+	}
+};
+var CiphertextMalformed = class extends Error {
+	construct;
+	constructor(construct) {
+		super(`${construct} was asked to decrypt something it did not write: a ciphertext starts '${CIPHERTEXT_VERSION}.<key>.'. Check the column holds what \`encrypt\` returned, untrimmed.`);
+		this.construct = construct;
+		this.name = "CiphertextMalformed";
+	}
+};
+var EncryptionKeyRetired = class extends Error {
+	construct;
+	keyId;
+	constructor(construct, keyId) {
+		super(`${construct} has no key '${keyId}' any more, so a value it wrote cannot be read. It was retired before every value was re-encrypted; restore it from the stage's secrets history, run the sweep, then retire it again.`);
+		this.construct = construct;
+		this.keyId = keyId;
+		this.name = "EncryptionKeyRetired";
+	}
+};
+var CiphertextNotAuthentic = class extends Error {
+	construct;
+	constructor(construct) {
+		super(`${construct} could not authenticate a ciphertext: it was altered, or written by a different Encryption construct. Ciphertexts are bound to the construct that wrote them.`);
+		this.construct = construct;
+		this.name = "CiphertextNotAuthentic";
+	}
+};
+var CurrentKeyCannotRetire = class extends Error {
+	construct;
+	keyId;
+	constructor(construct, keyId) {
+		super(`'${keyId}' is ${construct}'s current key — everything new is written with it. Rotate first, sweep, then retire '${keyId}'.`);
+		this.construct = construct;
+		this.keyId = keyId;
+		this.name = "CurrentKeyCannotRetire";
+	}
+};
+/** A ciphertext's three parts. */
+function parseCiphertext(construct, ciphertext) {
+	const [version, keyId, payload, ...rest] = ciphertext.split(".");
+	if (version !== "gkm1" || !keyId || !payload || rest.length) throw new CiphertextMalformed(construct);
+	return {
+		keyId,
+		payload: Buffer.from(payload, "base64url")
+	};
+}
+function formatCiphertext(keyId, payload) {
+	return `${CIPHERTEXT_VERSION}.${keyId}.${payload.toString("base64url")}`;
+}
+/**
+* What the cipher authenticates alongside the data: the construct and the key.
+*
+* Binding the construct means a value copied from one `Encryption` into
+* another's column fails instead of decrypting under the wrong policy.
+*/
+function associatedData(construct, keyId) {
+	return Buffer.from(`${CIPHERTEXT_VERSION}:${construct}:${keyId}`);
+}
+/** `iv | tag | ciphertext`, under one AES-256-GCM key. */
+function seal(key, plaintext, aad) {
+	const iv = (0, node_crypto.randomBytes)(IV_BYTES);
+	const cipher = (0, node_crypto.createCipheriv)("aes-256-gcm", key, iv);
+	cipher.setAAD(aad);
+	const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+	return Buffer.concat([
+		iv,
+		cipher.getAuthTag(),
+		body
+	]);
+}
+/** The inverse of {@link seal}; `undefined` when it does not authenticate. */
+function open(key, sealed, aad) {
+	if (sealed.length < 28) return void 0;
+	const decipher = (0, node_crypto.createDecipheriv)("aes-256-gcm", key, sealed.subarray(0, IV_BYTES));
+	decipher.setAAD(aad);
+	decipher.setAuthTag(sealed.subarray(IV_BYTES, 28));
+	try {
+		return Buffer.concat([decipher.update(sealed.subarray(28)), decipher.final()]);
+	} catch {
+		return;
+	}
+}
+/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */
+function parseKeyring(construct, url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new EncryptionUrlInvalid(construct, "it is not a URL");
+	}
+	const keys = (parsed.searchParams.get("keys") ?? "").split(",").filter(Boolean).map((entry) => {
+		const [id, encoded] = entry.split(".");
+		const key = Buffer.from(encoded ?? "", "base64url");
+		if (!id || key.length !== KEY_BYTES) throw new EncryptionUrlInvalid(construct, `'${id ?? entry}' is not a 256-bit key`);
+		return {
+			id,
+			key
+		};
+	});
+	if (keys.length === 0) throw new EncryptionUrlInvalid(construct, "it holds no keys");
+	const index = Buffer.from(parsed.searchParams.get("index") ?? "", "base64url");
+	if (index.length !== KEY_BYTES) throw new EncryptionUrlInvalid(construct, "its index key is missing");
+	return {
+		keys,
+		index
+	};
+}
+function formatKeyring(keyring) {
+	const keys = keyring.keys.map(({ id, key }) => `${id}.${key.toString("base64url")}`).join(",");
+	return `${LOCAL_SCHEME}//local?keys=${keys}&index=${keyring.index.toString("base64url")}`;
+}
+/** A keyring with one fresh key, `k1`, and a fresh index key. */
+function generateKeyring() {
+	return formatKeyring({
+		keys: [{
+			id: "k1",
+			key: (0, node_crypto.randomBytes)(KEY_BYTES)
+		}],
+		index: (0, node_crypto.randomBytes)(KEY_BYTES)
+	});
+}
+/**
+* The keyring with a new current key in front, and every older one kept.
+*
+* Nothing is dropped: what the old keys wrote still has to open until a sweep
+* has re-encrypted it — see {@link retireKey}.
+*/
+function rotateKeyring(construct, url) {
+	const keyring = parseKeyring(construct, url);
+	const next = Math.max(...keyring.keys.map(({ id }) => Number(id.slice(1)) || 0)) + 1;
+	return formatKeyring({
+		...keyring,
+		keys: [{
+			id: `k${next}`,
+			key: (0, node_crypto.randomBytes)(KEY_BYTES)
+		}, ...keyring.keys]
+	});
+}
+/** The keyring without `keyId`, which must not be the current key. */
+function retireKey(construct, url, keyId) {
+	const keyring = parseKeyring(construct, url);
+	if (keyring.keys[0]?.id === keyId) throw new CurrentKeyCannotRetire(construct, keyId);
+	if (!keyring.keys.some(({ id }) => id === keyId)) throw new EncryptionKeyRetired(construct, keyId);
+	return formatKeyring({
+		...keyring,
+		keys: keyring.keys.filter(({ id }) => id !== keyId)
+	});
+}
+/** The `aes256gcm://` cipher: a keyring held in process. */
+function keyringCipher(construct, url, onStaleKey = () => {}) {
+	const keyring = parseKeyring(construct, url);
+	const current = keyring.keys[0];
+	const byId = new Map(keyring.keys.map(({ id, key }) => [id, key]));
+	const reported = /* @__PURE__ */ new Set();
+	const decrypt = async (ciphertext) => {
+		const { keyId, payload } = parseCiphertext(construct, ciphertext);
+		const key = byId.get(keyId);
+		if (!key) throw new EncryptionKeyRetired(construct, keyId);
+		const plaintext = open(key, payload, associatedData(construct, keyId));
+		if (!plaintext) throw new CiphertextNotAuthentic(construct);
+		if (keyId !== current.id && !reported.has(keyId)) {
+			reported.add(keyId);
+			onStaleKey(keyId, current.id);
+		}
+		return plaintext.toString("utf8");
+	};
+	const encrypt = async (plaintext) => formatCiphertext(current.id, seal(current.key, Buffer.from(plaintext, "utf8"), associatedData(construct, current.id)));
+	return {
+		encrypt,
+		decrypt,
+		index: async (value) => (0, node_crypto.createHmac)("sha256", keyring.index).update(value, "utf8").digest("base64url"),
+		reencrypt: async (ciphertext) => {
+			const { keyId } = parseCiphertext(construct, ciphertext);
+			if (keyId === current.id) return ciphertext;
+			return encrypt(await decrypt(ciphertext));
+		}
+	};
+}
+//#endregion
+Object.defineProperty(exports, "CiphertextMalformed", {
+	enumerable: true,
+	get: function() {
+		return CiphertextMalformed;
+	}
+});
+Object.defineProperty(exports, "CiphertextNotAuthentic", {
+	enumerable: true,
+	get: function() {
+		return CiphertextNotAuthentic;
+	}
+});
+Object.defineProperty(exports, "CurrentKeyCannotRetire", {
+	enumerable: true,
+	get: function() {
+		return CurrentKeyCannotRetire;
+	}
+});
+Object.defineProperty(exports, "EncryptionKeyRetired", {
+	enumerable: true,
+	get: function() {
+		return EncryptionKeyRetired;
+	}
+});
+Object.defineProperty(exports, "EncryptionUrlInvalid", {
+	enumerable: true,
+	get: function() {
+		return EncryptionUrlInvalid;
+	}
+});
+Object.defineProperty(exports, "LOCAL_SCHEME", {
+	enumerable: true,
+	get: function() {
+		return LOCAL_SCHEME;
+	}
+});
+Object.defineProperty(exports, "UnknownEncryptionScheme", {
+	enumerable: true,
+	get: function() {
+		return UnknownEncryptionScheme;
+	}
+});
+Object.defineProperty(exports, "associatedData", {
+	enumerable: true,
+	get: function() {
+		return associatedData;
+	}
+});
+Object.defineProperty(exports, "formatCiphertext", {
+	enumerable: true,
+	get: function() {
+		return formatCiphertext;
+	}
+});
+Object.defineProperty(exports, "formatKeyring", {
+	enumerable: true,
+	get: function() {
+		return formatKeyring;
+	}
+});
+Object.defineProperty(exports, "generateKeyring", {
+	enumerable: true,
+	get: function() {
+		return generateKeyring;
+	}
+});
+Object.defineProperty(exports, "keyringCipher", {
+	enumerable: true,
+	get: function() {
+		return keyringCipher;
+	}
+});
+Object.defineProperty(exports, "open", {
+	enumerable: true,
+	get: function() {
+		return open;
+	}
+});
+Object.defineProperty(exports, "parseCiphertext", {
+	enumerable: true,
+	get: function() {
+		return parseCiphertext;
+	}
+});
+Object.defineProperty(exports, "parseKeyring", {
+	enumerable: true,
+	get: function() {
+		return parseKeyring;
+	}
+});
+Object.defineProperty(exports, "retireKey", {
+	enumerable: true,
+	get: function() {
+		return retireKey;
+	}
+});
+Object.defineProperty(exports, "rotateKeyring", {
+	enumerable: true,
+	get: function() {
+		return rotateKeyring;
+	}
+});
+Object.defineProperty(exports, "seal", {
+	enumerable: true,
+	get: function() {
+		return seal;
+	}
+});
+
+//# sourceMappingURL=cipher-CVxfwLjk.cjs.map

package/dist/cipher-CVxfwLjk.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher-CVxfwLjk.cjs","names":["randomBytes","createCipheriv","createDecipheriv","createHmac"],"sources":["../src/encryption/cipher.ts"],"sourcesContent":["/**\n * The cipher behind an `Encryption` construct, and the format it writes.\n *\n * Every ciphertext names the key that wrote it — `gkm1.<keyId>.<payload>` — so\n * `decrypt` never has to guess, a rotated key still opens what it wrote, and\n * retiring a key is a decision made against data rather than a hope. The\n * format version leads, so the day it has to change, both can be read.\n *\n * Two backends, picked by the scheme of the construct's URL, the way a queue's\n * connection string picks its broker:\n *\n * - `aes256gcm://` — a keyring this process holds: AES-256-GCM with the newest\n *   key, HMAC-SHA256 for the blind index. Local, test and server stages.\n * - `kms://` — envelope encryption under an AWS KMS key, and a KMS HMAC key for\n *   the index. The key material never leaves KMS. See `./kms`.\n */\n\nimport {\n\tcreateCipheriv,\n\tcreateDecipheriv,\n\tcreateHmac,\n\trandomBytes,\n} from 'node:crypto';\n\n/** What a handler is given: `services.pii.encrypt(…)` and the rest. */\nexport interface Cipher {\n\t/** Plaintext in, a self-describing ciphertext string out. */\n\tencrypt(plaintext: string): Promise<string>;\n\t/** Opens any ciphertext this construct wrote, under whichever key wrote it. */\n\tdecrypt(ciphertext: string): Promise<string>;\n\t/**\n\t * A blind index: the same value always gives the same string, so an\n\t * encrypted column can still be looked up by an indexed column beside it.\n\t *\n\t * Deterministic on purpose, which is also why its key never rotates — a\n\t * rotated index key would make every stored index miss.\n\t */\n\tindex(value: string): Promise<string>;\n\t/**\n\t * The same plaintext under the current key — what a sweep runs over a\n\t * column before an old key is retired. Unchanged when it is already current.\n\t */\n\treencrypt(ciphertext: string): Promise<string>;\n}\n\n/** The format every ciphertext leads with. */\nexport const CIPHERTEXT_VERSION = 'gkm1';\n\n/** AES-256-GCM's nonce and tag, in bytes. */\nconst IV_BYTES = 12;\nconst TAG_BYTES = 16;\nconst KEY_BYTES = 32;\n\nexport const LOCAL_SCHEME = 'aes256gcm:';\n\nexport class EncryptionUrlInvalid extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly reason: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct}'s encryption URL is not usable: ${reason}. gkm composes it — derived locally, generated into a server stage's secrets on its first deploy, provisioned on AWS — so it should not be set by hand.`,\n\t\t);\n\t\tthis.name = 'EncryptionUrlInvalid';\n\t}\n}\n\nexport class UnknownEncryptionScheme extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly scheme: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct}'s encryption URL uses '${scheme}', which no cipher handles. Expected 'aes256gcm:' (a local keyring) or 'kms:' (AWS KMS).`,\n\t\t);\n\t\tthis.name = 'UnknownEncryptionScheme';\n\t}\n}\n\nexport class CiphertextMalformed extends Error {\n\tconstructor(readonly construct: string) {\n\t\tsuper(\n\t\t\t`${construct} was asked to decrypt something it did not write: a ciphertext starts '${CIPHERTEXT_VERSION}.<key>.'. Check the column holds what \\`encrypt\\` returned, untrimmed.`,\n\t\t);\n\t\tthis.name = 'CiphertextMalformed';\n\t}\n}\n\nexport class EncryptionKeyRetired extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly keyId: string,\n\t) {\n\t\tsuper(\n\t\t\t`${construct} has no key '${keyId}' any more, so a value it wrote cannot be read. It was retired before every value was re-encrypted; restore it from the stage's secrets history, run the sweep, then retire it again.`,\n\t\t);\n\t\tthis.name = 'EncryptionKeyRetired';\n\t}\n}\n\nexport class CiphertextNotAuthentic extends Error {\n\tconstructor(readonly construct: string) {\n\t\tsuper(\n\t\t\t`${construct} could not authenticate a ciphertext: it was altered, or written by a different Encryption construct. Ciphertexts are bound to the construct that wrote them.`,\n\t\t);\n\t\tthis.name = 'CiphertextNotAuthentic';\n\t}\n}\n\nexport class CurrentKeyCannotRetire extends Error {\n\tconstructor(\n\t\treadonly construct: string,\n\t\treadonly keyId: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${keyId}' is ${construct}'s current key — everything new is written with it. Rotate first, sweep, then retire '${keyId}'.`,\n\t\t);\n\t\tthis.name = 'CurrentKeyCannotRetire';\n\t}\n}\n\n/** A ciphertext's three parts. */\nexport function parseCiphertext(\n\tconstruct: string,\n\tciphertext: string,\n): { keyId: string; payload: Buffer } {\n\tconst [version, keyId, payload, ...rest] = ciphertext.split('.');\n\tif (version !== CIPHERTEXT_VERSION || !keyId || !payload || rest.length) {\n\t\tthrow new CiphertextMalformed(construct);\n\t}\n\treturn { keyId, payload: Buffer.from(payload, 'base64url') };\n}\n\nexport function formatCiphertext(keyId: string, payload: Buffer): string {\n\treturn `${CIPHERTEXT_VERSION}.${keyId}.${payload.toString('base64url')}`;\n}\n\n/**\n * What the cipher authenticates alongside the data: the construct and the key.\n *\n * Binding the construct means a value copied from one `Encryption` into\n * another's column fails instead of decrypting under the wrong policy.\n */\nexport function associatedData(construct: string, keyId: string): Buffer {\n\treturn Buffer.from(`${CIPHERTEXT_VERSION}:${construct}:${keyId}`);\n}\n\n/** `iv | tag | ciphertext`, under one AES-256-GCM key. */\nexport function seal(key: Buffer, plaintext: Buffer, aad: Buffer): Buffer {\n\tconst iv = randomBytes(IV_BYTES);\n\tconst cipher = createCipheriv('aes-256-gcm', key, iv);\n\tcipher.setAAD(aad);\n\tconst body = Buffer.concat([cipher.update(plaintext), cipher.final()]);\n\treturn Buffer.concat([iv, cipher.getAuthTag(), body]);\n}\n\n/** The inverse of {@link seal}; `undefined` when it does not authenticate. */\nexport function open(\n\tkey: Buffer,\n\tsealed: Buffer,\n\taad: Buffer,\n): Buffer | undefined {\n\tif (sealed.length < IV_BYTES + TAG_BYTES) return undefined;\n\n\tconst decipher = createDecipheriv(\n\t\t'aes-256-gcm',\n\t\tkey,\n\t\tsealed.subarray(0, IV_BYTES),\n\t);\n\tdecipher.setAAD(aad);\n\tdecipher.setAuthTag(sealed.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));\n\n\ttry {\n\t\treturn Buffer.concat([\n\t\t\tdecipher.update(sealed.subarray(IV_BYTES + TAG_BYTES)),\n\t\t\tdecipher.final(),\n\t\t]);\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** A local keyring: newest key first, and the index key that never rotates. */\nexport interface Keyring {\n\tkeys: { id: string; key: Buffer }[];\n\tindex: Buffer;\n}\n\n/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */\nexport function parseKeyring(construct: string, url: string): Keyring {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(url);\n\t} catch {\n\t\tthrow new EncryptionUrlInvalid(construct, 'it is not a URL');\n\t}\n\n\tconst keys = (parsed.searchParams.get('keys') ?? '')\n\t\t.split(',')\n\t\t.filter(Boolean)\n\t\t.map((entry) => {\n\t\t\tconst [id, encoded] = entry.split('.');\n\t\t\tconst key = Buffer.from(encoded ?? '', 'base64url');\n\t\t\tif (!id || key.length !== KEY_BYTES) {\n\t\t\t\tthrow new EncryptionUrlInvalid(\n\t\t\t\t\tconstruct,\n\t\t\t\t\t`'${id ?? entry}' is not a 256-bit key`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn { id, key };\n\t\t});\n\tif (keys.length === 0) {\n\t\tthrow new EncryptionUrlInvalid(construct, 'it holds no keys');\n\t}\n\n\tconst index = Buffer.from(\n\t\tparsed.searchParams.get('index') ?? '',\n\t\t'base64url',\n\t);\n\tif (index.length !== KEY_BYTES) {\n\t\tthrow new EncryptionUrlInvalid(construct, 'its index key is missing');\n\t}\n\n\treturn { keys, index };\n}\n\nexport function formatKeyring(keyring: Keyring): string {\n\tconst keys = keyring.keys\n\t\t.map(({ id, key }) => `${id}.${key.toString('base64url')}`)\n\t\t.join(',');\n\treturn `${LOCAL_SCHEME}//local?keys=${keys}&index=${keyring.index.toString('base64url')}`;\n}\n\n/** A keyring with one fresh key, `k1`, and a fresh index key. */\nexport function generateKeyring(): string {\n\treturn formatKeyring({\n\t\tkeys: [{ id: 'k1', key: randomBytes(KEY_BYTES) }],\n\t\tindex: randomBytes(KEY_BYTES),\n\t});\n}\n\n/**\n * The keyring with a new current key in front, and every older one kept.\n *\n * Nothing is dropped: what the old keys wrote still has to open until a sweep\n * has re-encrypted it — see {@link retireKey}.\n */\nexport function rotateKeyring(construct: string, url: string): string {\n\tconst keyring = parseKeyring(construct, url);\n\tconst next =\n\t\tMath.max(...keyring.keys.map(({ id }) => Number(id.slice(1)) || 0)) + 1;\n\n\treturn formatKeyring({\n\t\t...keyring,\n\t\tkeys: [{ id: `k${next}`, key: randomBytes(KEY_BYTES) }, ...keyring.keys],\n\t});\n}\n\n/** The keyring without `keyId`, which must not be the current key. */\nexport function retireKey(\n\tconstruct: string,\n\turl: string,\n\tkeyId: string,\n): string {\n\tconst keyring = parseKeyring(construct, url);\n\tif (keyring.keys[0]?.id === keyId) {\n\t\tthrow new CurrentKeyCannotRetire(construct, keyId);\n\t}\n\tif (!keyring.keys.some(({ id }) => id === keyId)) {\n\t\tthrow new EncryptionKeyRetired(construct, keyId);\n\t}\n\n\treturn formatKeyring({\n\t\t...keyring,\n\t\tkeys: keyring.keys.filter(({ id }) => id !== keyId),\n\t});\n}\n\n/** Says, once per key per process, that a value is still under an old key. */\nexport type StaleKeyReporter = (keyId: string, current: string) => void;\n\n/** The `aes256gcm://` cipher: a keyring held in process. */\nexport function keyringCipher(\n\tconstruct: string,\n\turl: string,\n\tonStaleKey: StaleKeyReporter = () => {},\n): Cipher {\n\tconst keyring = parseKeyring(construct, url);\n\tconst current = keyring.keys[0]!;\n\tconst byId = new Map(keyring.keys.map(({ id, key }) => [id, key]));\n\tconst reported = new Set<string>();\n\n\tconst decrypt = async (ciphertext: string) => {\n\t\tconst { keyId, payload } = parseCiphertext(construct, ciphertext);\n\t\tconst key = byId.get(keyId);\n\t\tif (!key) throw new EncryptionKeyRetired(construct, keyId);\n\n\t\tconst plaintext = open(key, payload, associatedData(construct, keyId));\n\t\tif (!plaintext) throw new CiphertextNotAuthentic(construct);\n\n\t\tif (keyId !== current.id && !reported.has(keyId)) {\n\t\t\treported.add(keyId);\n\t\t\tonStaleKey(keyId, current.id);\n\t\t}\n\n\t\treturn plaintext.toString('utf8');\n\t};\n\n\tconst encrypt = async (plaintext: string) =>\n\t\tformatCiphertext(\n\t\t\tcurrent.id,\n\t\t\tseal(\n\t\t\t\tcurrent.key,\n\t\t\t\tBuffer.from(plaintext, 'utf8'),\n\t\t\t\tassociatedData(construct, current.id),\n\t\t\t),\n\t\t);\n\n\treturn {\n\t\tencrypt,\n\t\tdecrypt,\n\t\tindex: async (value) =>\n\t\t\tcreateHmac('sha256', keyring.index)\n\t\t\t\t.update(value, 'utf8')\n\t\t\t\t.digest('base64url'),\n\t\treencrypt: async (ciphertext) => {\n\t\t\tconst { keyId } = parseCiphertext(construct, ciphertext);\n\t\t\tif (keyId === current.id) return ciphertext;\n\t\t\treturn encrypt(await decrypt(ciphertext));\n\t\t},\n\t};\n}\n"],"mappings":"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"}