@geekmidas/constructs 10.0.0-alpha.6 → 10.0.0-alpha.60

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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"}

package/dist/{clone-DblgEZZa.mjs → clone-EKNovYHu.mjs}

@@ -33,7 +33,7 @@ function cloneWith(instance, delta) {
 	const next = Object.create(Object.getPrototypeOf(instance));
 	return Object.assign(next, instance, delta);
 }
-
 //#endregion
-export { cloneWith };
-//# sourceMappingURL=clone-DblgEZZa.mjs.map
+export { cloneWith as t };
+
+//# sourceMappingURL=clone-EKNovYHu.mjs.map

package/dist/clone-EKNovYHu.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-EKNovYHu.mjs","names":[],"sources":["../src/clone.ts"],"sourcesContent":["/**\n * Cloning a builder, without enumerating its fields.\n *\n * The builders were mutable singletons that reset themselves by listing every\n * field at the end of `.handle()`. Two things followed from that, and both were\n * real:\n *\n * A configured base could not be reused. `const fn = f.logger(log)` handed back\n * `f` itself, and the first `.handle()` reset `_logger` to the default — so the\n * second handler built from that base silently logged somewhere else. Every\n * field in the reset block behaved the same way, which made\n * `f.logger(l).timeout(60_000)` a base that worked exactly once.\n *\n * And a field left out of the reset list leaked into the next handler instead.\n * `_constructs` was left out, so a function was granted a bucket a *previous*\n * function had declared — an over-grant in the field a deploy reads to size an\n * IAM policy.\n *\n * Both are the same defect: a hand-maintained list of fields that has to be\n * edited every time a field is added, and is silent when it isn't. So this\n * copies whatever the instance actually has, and the list stops existing. The\n * prototype is carried over, so `instanceof` and every method still resolve,\n * and the constructor is deliberately not re-run — this copies state rather\n * than initialising it.\n *\n * Fields must be replaced rather than mutated in place: a clone and its parent\n * share whatever array a field points at, so `_events.push(…)` would be seen by\n * both. Every builder assigns a fresh array instead, which is what makes\n * sharing the reference safe.\n */\nexport function cloneWith<T extends object>(\n\tinstance: T,\n\tdelta: Record<string, unknown>,\n): T {\n\tconst next = Object.create(Object.getPrototypeOf(instance)) as T;\n\n\treturn Object.assign(next, instance, delta);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,UACf,UACA,OACI;CACJ,MAAM,OAAO,OAAO,OAAO,OAAO,eAAe,QAAQ,CAAC;CAE1D,OAAO,OAAO,OAAO,MAAM,UAAU,KAAK;AAC3C"}

package/dist/{clone-Dy0cR2SZ.cjs → clone-UGJpvQnL.cjs}

@@ -1,4 +1,3 @@
-
 //#region src/clone.ts
 /**
 * Cloning a builder, without enumerating its fields.
@@ -34,12 +33,12 @@ function cloneWith(instance, delta) {
 	const next = Object.create(Object.getPrototypeOf(instance));
 	return Object.assign(next, instance, delta);
 }
-
 //#endregion
-Object.defineProperty(exports, 'cloneWith', {
-  enumerable: true,
-  get: function () {
-    return cloneWith;
-  }
+Object.defineProperty(exports, "cloneWith", {
+	enumerable: true,
+	get: function() {
+		return cloneWith;
+	}
 });
-//# sourceMappingURL=clone-Dy0cR2SZ.cjs.map
+
+//# sourceMappingURL=clone-UGJpvQnL.cjs.map

package/dist/clone-UGJpvQnL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-UGJpvQnL.cjs","names":[],"sources":["../src/clone.ts"],"sourcesContent":["/**\n * Cloning a builder, without enumerating its fields.\n *\n * The builders were mutable singletons that reset themselves by listing every\n * field at the end of `.handle()`. Two things followed from that, and both were\n * real:\n *\n * A configured base could not be reused. `const fn = f.logger(log)` handed back\n * `f` itself, and the first `.handle()` reset `_logger` to the default — so the\n * second handler built from that base silently logged somewhere else. Every\n * field in the reset block behaved the same way, which made\n * `f.logger(l).timeout(60_000)` a base that worked exactly once.\n *\n * And a field left out of the reset list leaked into the next handler instead.\n * `_constructs` was left out, so a function was granted a bucket a *previous*\n * function had declared — an over-grant in the field a deploy reads to size an\n * IAM policy.\n *\n * Both are the same defect: a hand-maintained list of fields that has to be\n * edited every time a field is added, and is silent when it isn't. So this\n * copies whatever the instance actually has, and the list stops existing. The\n * prototype is carried over, so `instanceof` and every method still resolve,\n * and the constructor is deliberately not re-run — this copies state rather\n * than initialising it.\n *\n * Fields must be replaced rather than mutated in place: a clone and its parent\n * share whatever array a field points at, so `_events.push(…)` would be seen by\n * both. Every builder assigns a fresh array instead, which is what makes\n * sharing the reference safe.\n */\nexport function cloneWith<T extends object>(\n\tinstance: T,\n\tdelta: Record<string, unknown>,\n): T {\n\tconst next = Object.create(Object.getPrototypeOf(instance)) as T;\n\n\treturn Object.assign(next, instance, delta);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,UACf,UACA,OACI;CACJ,MAAM,OAAO,OAAO,OAAO,OAAO,eAAe,QAAQ,CAAC;CAE1D,OAAO,OAAO,OAAO,MAAM,UAAU,KAAK;AAC3C"}

package/dist/{construct-interface-D9d4Gm4p.d.cts → construct-interface-B1AfqRl4.d.cts}

@@ -1,8 +1,7 @@
+import { EnvironmentParser } from "@geekmidas/envkit";
 import { Service } from "@geekmidas/services";
 import { Declaration, Dependency } from "@geekmidas/manifest";
-
 //#region src/construct-interface.d.ts
-
 /**
  * @typeParam TName - the construct's canonical id, PascalCase. Keeping it a
  * literal is what lets the service key be `Uncapitalize<TName>` — a TypeScript
@@ -27,8 +26,8 @@ interface Construct<TName extends string = string, TClient = never> {
    * The consumable face — the address this construct owns, as a client.
    *
    * A field assigned once rather than a getter. `Construct.getEnvironment`
-   * caches by service *object*, and `Topic.publisher` returns a fresh literal
-   * on every access, so that cache never hits for topics or queues today.
+   * and `ServiceDiscovery` cache by service *object*, so a getter returning a
+   * fresh literal on every access would never hit either cache.
    */
   readonly service: [TClient] extends [never] ? never : Service<Uncapitalize<TName>, TClient>;
 }
@@ -45,6 +44,17 @@ interface Declarable<TName extends string = string> {
   readonly id: TName;
   declare(): Declaration[];
 }
+/**
+ * A construct that authenticates requests — what `RestApi.auth()` takes.
+ *
+ * `verify` is the one thing every provider shares: given a request's headers,
+ * whose request is it — the session, or `null` when there is none. Whether the
+ * provider is a server mounted beside the API, deployed elsewhere, or an issuer
+ * somebody else runs is its own business; a surface only ever asks this.
+ */
+interface Authenticator<TSession = unknown> extends Declarable {
+  verify(headers: Headers, envParser: EnvironmentParser<{}>): Promise<TSession | null>;
+}
 /**
  * The edge that points at a construct.
  *
@@ -85,7 +95,7 @@ interface Consumable<TName extends string = string, TClient = unknown> {
  * both keys — the same machinery `.services()` already uses, which is why
  * `dependsOn` needs no type plumbing of its own.
  */
-type ServicesOf<T extends readonly Consumable[]> = { [K in keyof T]: T[K]['service'] };
+type ServicesOf<T extends readonly Consumable[]> = { [K in keyof T]: T[K]['service']; };
 /**
  * The services of a list of constructs, at runtime.
  *
@@ -104,6 +114,28 @@ declare function servicesOf<const T extends readonly Consumable[]>(constructs: T
  * calls accumulate the way `.services()` already does.
  */
 declare function idsOf(constructs: readonly Consumable[], existing?: readonly string[]): string[];
+/**
+ * The edges after `.database(source)` names a builder's database.
+ *
+ * A database replaces the one before it — a worker's default, overridden by a
+ * runnable that names its own — so the edge the previous one added goes with
+ * it. Left behind, a Lambda built from a queue that moved to another database
+ * would still be granted the worker's.
+ *
+ * Only an edge `.database()` added is removed, which is why it is returned as
+ * `_databaseEdge` for the next call to read — and not even that one when
+ * `.dependsOn()` has since named the same construct, since the handler still
+ * reaches it through `services`.
+ */
+declare function databaseEdges(current: {
+  constructs: readonly string[];
+  edge: string | undefined;
+  service: Service | undefined;
+  services: readonly Service[];
+}, source: unknown): {
+  _constructs: string[];
+  _databaseEdge: string | undefined;
+};
 /** Something that is not a construct was passed to `.dependsOn()`. */
 declare class NotAConstruct extends Error {
   readonly value: unknown;
@@ -120,12 +152,11 @@ declare function isConsumable(value: unknown): value is Consumable;
 /**
  * The service behind either face.
  *
- * `.database()` and the publisher slots take a construct now; they took a
- * `Service` before and still do, because a hand-written one is exactly what
- * `Construct.fromService` exists to lift and not everything has been lifted.
+ * `.database()` and the auditor slot take a construct now; they took a
+ * `Service` before and still do, because not every hand-written service has a
+ * construct to stand for it.
  */
 declare function serviceOf<TName extends string, TClient>(source: Consumable<TName, TClient> | Service<TName, TClient>): Service<TName, TClient>;
-//# sourceMappingURL=construct-interface.d.ts.map
 //#endregion
-export { Construct, Consumable, Declarable, Infer, NameOf, NotAConstruct, ServicesOf, edgeTo, idsOf, isConsumable, serviceOf, servicesOf };
-//# sourceMappingURL=construct-interface-D9d4Gm4p.d.cts.map
+export { Infer as a, ServicesOf as c, idsOf as d, isConsumable as f, Declarable as i, databaseEdges as l, servicesOf as m, Construct as n, NameOf as o, serviceOf as p, Consumable as r, NotAConstruct as s, Authenticator as t, edgeTo as u };
+//# sourceMappingURL=construct-interface-B1AfqRl4.d.cts.map

package/dist/construct-interface-B1AfqRl4.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-interface-B1AfqRl4.d.cts","names":[],"sources":["../src/construct-interface.ts"],"mappings":";;;;;;;;;;;;;UA8BiB,UAAU,+BAA+B;;WAEhD,IAAI;;;;;;;;EASb,WAAW;;;;;;;;WASF,UAAU,mCAEhB,QAAQ,aAAa,QAAQ;;;;;;;;;;;UAYhB,WAAW;WAClB,IAAI;EACb,WAAW;;;;;;;;;;UAWK,cAAc,4BAA4B;EAC1D,OACC,SAAS,SACT,WAAW,wBACT,QAAQ;;;;;;;;;;;;;;iBAeI,OAAO,WAAW,aAAa;;KAWnC,MAAM,KACjB,UAAU,wBAAwB,WAAW;;KAGlC,OAAO,KAClB,UAAU,gBAAgB,kBAAkB;;;;;;;;;;;UAY5B,WAAW,+BAA+B;WACjD,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;EAC/C,WAAW;;;;;;;;;;KAWA,WAAW,mBAAmB,mBACxC,WAAW,IAAI,EAAE;;;;;;;;iBAUH,iBAAiB,mBAAmB,cACnD,YAAY,IACV,WAAW;;;;;;;;;;iBAiBE,MACf,qBAAqB,cACrB;;;;;;;;;;;;;;iBAkBe,cACf;EACC;EACA;EACA,SAAS;EACT,mBAAmB;GAEpB;EACI;EAAuB;;;cAgBf,sBAAsB;WACb;EAArB,YAAqB;;;;;;;;;iBAqBN,aAAa,iBAAiB,SAAS;;;;;;;;iBAmBvC,UAAU,sBAAsB,SAC/C,QAAQ,WAAW,OAAO,WAAW,QAAQ,OAAO,WAClD,QAAQ,OAAO"}

package/dist/{construct-interface-g5GM5pwR.d.mts → construct-interface-DluK3_da.d.mts}

@@ -1,8 +1,7 @@
 import { Declaration, Dependency } from "@geekmidas/manifest";
+import { EnvironmentParser } from "@geekmidas/envkit";
 import { Service } from "@geekmidas/services";
-
 //#region src/construct-interface.d.ts
-
 /**
  * @typeParam TName - the construct's canonical id, PascalCase. Keeping it a
  * literal is what lets the service key be `Uncapitalize<TName>` — a TypeScript
@@ -27,8 +26,8 @@ interface Construct<TName extends string = string, TClient = never> {
    * The consumable face — the address this construct owns, as a client.
    *
    * A field assigned once rather than a getter. `Construct.getEnvironment`
-   * caches by service *object*, and `Topic.publisher` returns a fresh literal
-   * on every access, so that cache never hits for topics or queues today.
+   * and `ServiceDiscovery` cache by service *object*, so a getter returning a
+   * fresh literal on every access would never hit either cache.
    */
   readonly service: [TClient] extends [never] ? never : Service<Uncapitalize<TName>, TClient>;
 }
@@ -45,6 +44,17 @@ interface Declarable<TName extends string = string> {
   readonly id: TName;
   declare(): Declaration[];
 }
+/**
+ * A construct that authenticates requests — what `RestApi.auth()` takes.
+ *
+ * `verify` is the one thing every provider shares: given a request's headers,
+ * whose request is it — the session, or `null` when there is none. Whether the
+ * provider is a server mounted beside the API, deployed elsewhere, or an issuer
+ * somebody else runs is its own business; a surface only ever asks this.
+ */
+interface Authenticator<TSession = unknown> extends Declarable {
+  verify(headers: Headers, envParser: EnvironmentParser<{}>): Promise<TSession | null>;
+}
 /**
  * The edge that points at a construct.
  *
@@ -85,7 +95,7 @@ interface Consumable<TName extends string = string, TClient = unknown> {
  * both keys — the same machinery `.services()` already uses, which is why
  * `dependsOn` needs no type plumbing of its own.
  */
-type ServicesOf<T extends readonly Consumable[]> = { [K in keyof T]: T[K]['service'] };
+type ServicesOf<T extends readonly Consumable[]> = { [K in keyof T]: T[K]['service']; };
 /**
  * The services of a list of constructs, at runtime.
  *
@@ -104,6 +114,28 @@ declare function servicesOf<const T extends readonly Consumable[]>(constructs: T
  * calls accumulate the way `.services()` already does.
  */
 declare function idsOf(constructs: readonly Consumable[], existing?: readonly string[]): string[];
+/**
+ * The edges after `.database(source)` names a builder's database.
+ *
+ * A database replaces the one before it — a worker's default, overridden by a
+ * runnable that names its own — so the edge the previous one added goes with
+ * it. Left behind, a Lambda built from a queue that moved to another database
+ * would still be granted the worker's.
+ *
+ * Only an edge `.database()` added is removed, which is why it is returned as
+ * `_databaseEdge` for the next call to read — and not even that one when
+ * `.dependsOn()` has since named the same construct, since the handler still
+ * reaches it through `services`.
+ */
+declare function databaseEdges(current: {
+  constructs: readonly string[];
+  edge: string | undefined;
+  service: Service | undefined;
+  services: readonly Service[];
+}, source: unknown): {
+  _constructs: string[];
+  _databaseEdge: string | undefined;
+};
 /** Something that is not a construct was passed to `.dependsOn()`. */
 declare class NotAConstruct extends Error {
   readonly value: unknown;
@@ -120,12 +152,11 @@ declare function isConsumable(value: unknown): value is Consumable;
 /**
  * The service behind either face.
  *
- * `.database()` and the publisher slots take a construct now; they took a
- * `Service` before and still do, because a hand-written one is exactly what
- * `Construct.fromService` exists to lift and not everything has been lifted.
+ * `.database()` and the auditor slot take a construct now; they took a
+ * `Service` before and still do, because not every hand-written service has a
+ * construct to stand for it.
  */
 declare function serviceOf<TName extends string, TClient>(source: Consumable<TName, TClient> | Service<TName, TClient>): Service<TName, TClient>;
-//# sourceMappingURL=construct-interface.d.ts.map
 //#endregion
-export { Construct, Consumable, Declarable, Infer, NameOf, NotAConstruct, ServicesOf, edgeTo, idsOf, isConsumable, serviceOf, servicesOf };
-//# sourceMappingURL=construct-interface-g5GM5pwR.d.mts.map
+export { Infer as a, ServicesOf as c, idsOf as d, isConsumable as f, Declarable as i, databaseEdges as l, servicesOf as m, Construct as n, NameOf as o, serviceOf as p, Consumable as r, NotAConstruct as s, Authenticator as t, edgeTo as u };
+//# sourceMappingURL=construct-interface-DluK3_da.d.mts.map

package/dist/construct-interface-DluK3_da.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-interface-DluK3_da.d.mts","names":[],"sources":["../src/construct-interface.ts"],"mappings":";;;;;;;;;;;;;UA8BiB,UAAU,+BAA+B;;WAEhD,IAAI;;;;;;;;EASb,WAAW;;;;;;;;WASF,UAAU,mCAEhB,QAAQ,aAAa,QAAQ;;;;;;;;;;;UAYhB,WAAW;WAClB,IAAI;EACb,WAAW;;;;;;;;;;UAWK,cAAc,4BAA4B;EAC1D,OACC,SAAS,SACT,WAAW,wBACT,QAAQ;;;;;;;;;;;;;;iBAeI,OAAO,WAAW,aAAa;;KAWnC,MAAM,KACjB,UAAU,wBAAwB,WAAW;;KAGlC,OAAO,KAClB,UAAU,gBAAgB,kBAAkB;;;;;;;;;;;UAY5B,WAAW,+BAA+B;WACjD,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;EAC/C,WAAW;;;;;;;;;;KAWA,WAAW,mBAAmB,mBACxC,WAAW,IAAI,EAAE;;;;;;;;iBAUH,iBAAiB,mBAAmB,cACnD,YAAY,IACV,WAAW;;;;;;;;;;iBAiBE,MACf,qBAAqB,cACrB;;;;;;;;;;;;;;iBAkBe,cACf;EACC;EACA;EACA,SAAS;EACT,mBAAmB;GAEpB;EACI;EAAuB;;;cAgBf,sBAAsB;WACb;EAArB,YAAqB;;;;;;;;;iBAqBN,aAAa,iBAAiB,SAAS;;;;;;;;iBAmBvC,UAAU,sBAAsB,SAC/C,QAAQ,WAAW,OAAO,WAAW,QAAQ,OAAO,WAClD,QAAQ,OAAO"}