@geekmidas/constructs 10.0.0-alpha.12 → 10.0.0-alpha.121

package/dist/encryption/kms.cjs

@@ -0,0 +1,95 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cipher = require("../cipher-CVxfwLjk.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _aws_sdk_client_kms = require("@aws-sdk/client-kms");
+//#region src/encryption/kms.ts
+/**
+* The `kms://` cipher: envelope encryption under an AWS KMS key.
+*
+* Each `encrypt` asks KMS for a fresh data key, seals the plaintext with it
+* locally, and stores the data key *as KMS encrypted it* beside the data. The
+* plaintext data key is used once and dropped, and the master key never leaves
+* KMS — every decrypt is a KMS call IAM can refuse and CloudTrail records.
+*
+* Rotation is KMS's: it keeps every backing version of the key, and the
+* encrypted data key names the one that wrapped it, so nothing here tracks a
+* version and `reencrypt` has nothing to move. The ciphertext's key field is
+* `kms` for that reason.
+*
+* The blind index is a KMS HMAC key's `GenerateMac`: deterministic, and the
+* key is as unextractable as the encryption key.
+*
+* In its own entry, `@geekmidas/constructs/encryption/kms`, which only an
+* AWS build's generated entry imports — to register {@link kmsCipherDriver}
+* — so a project that never deploys to AWS never needs
+* `@aws-sdk/client-kms` installed, and its bundle never mentions it.
+*/
+/** The ciphertext's key field: the version lives inside KMS's own blob. */
+const KMS_KEY_ID = "kms";
+function kmsCipher(construct, url) {
+	const parsed = new URL(url);
+	const region = parsed.hostname;
+	const keyId = parsed.searchParams.get("key");
+	const indexKeyId = parsed.searchParams.get("index");
+	if (!region || !keyId || !indexKeyId) throw new require_cipher.EncryptionUrlInvalid(construct, "a kms:// URL names a region, a key and an index key");
+	const endpoint = parsed.searchParams.get("endpoint");
+	const kms = new _aws_sdk_client_kms.KMSClient({
+		region,
+		...endpoint ? { endpoint } : {}
+	});
+	const context = { construct };
+	const aad = require_cipher.associatedData(construct, KMS_KEY_ID);
+	return {
+		async encrypt(plaintext) {
+			const dataKey = await kms.send(new _aws_sdk_client_kms.GenerateDataKeyCommand({
+				KeyId: keyId,
+				KeySpec: "AES_256",
+				EncryptionContext: context
+			}));
+			const wrapped = Buffer.from(dataKey.CiphertextBlob);
+			const sealed = require_cipher.seal(Buffer.from(dataKey.Plaintext), Buffer.from(plaintext, "utf8"), aad);
+			const length = Buffer.alloc(2);
+			length.writeUInt16BE(wrapped.length);
+			return require_cipher.formatCiphertext(KMS_KEY_ID, Buffer.concat([
+				length,
+				wrapped,
+				sealed
+			]));
+		},
+		async decrypt(ciphertext) {
+			const { payload } = require_cipher.parseCiphertext(construct, ciphertext);
+			const length = payload.length >= 2 ? payload.readUInt16BE(0) : 0;
+			const wrapped = payload.subarray(2, 2 + length);
+			if (!length || wrapped.length !== length) throw new require_cipher.CiphertextNotAuthentic(construct);
+			const dataKey = await kms.send(new _aws_sdk_client_kms.DecryptCommand({
+				CiphertextBlob: wrapped,
+				EncryptionContext: context
+			}));
+			const plaintext = require_cipher.open(Buffer.from(dataKey.Plaintext), payload.subarray(2 + length), aad);
+			if (!plaintext) throw new require_cipher.CiphertextNotAuthentic(construct);
+			return plaintext.toString("utf8");
+		},
+		async index(value) {
+			const { Mac } = await kms.send(new _aws_sdk_client_kms.GenerateMacCommand({
+				KeyId: indexKeyId,
+				MacAlgorithm: "HMAC_SHA_256",
+				Message: Buffer.from(value, "utf8")
+			}));
+			return Buffer.from(Mac).toString("base64url");
+		},
+		async reencrypt(ciphertext) {
+			require_cipher.parseCiphertext(construct, ciphertext);
+			return ciphertext;
+		}
+	};
+}
+/** The `kms:` cipher, as an AWS build's entry registers it. */
+const kmsCipherDriver = {
+	scheme: _geekmidas_manifest.KMS_SCHEME,
+	open: kmsCipher
+};
+//#endregion
+exports.kmsCipher = kmsCipher;
+exports.kmsCipherDriver = kmsCipherDriver;
+
+//# sourceMappingURL=kms.cjs.map

package/dist/encryption/kms.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.cjs","names":["EncryptionUrlInvalid","KMSClient","associatedData","GenerateDataKeyCommand","seal","formatCiphertext","parseCiphertext","CiphertextNotAuthentic","DecryptCommand","open","GenerateMacCommand","KMS_SCHEME"],"sources":["../../src/encryption/kms.ts"],"sourcesContent":["/**\n * The `kms://` cipher: envelope encryption under an AWS KMS key.\n *\n * Each `encrypt` asks KMS for a fresh data key, seals the plaintext with it\n * locally, and stores the data key *as KMS encrypted it* beside the data. The\n * plaintext data key is used once and dropped, and the master key never leaves\n * KMS — every decrypt is a KMS call IAM can refuse and CloudTrail records.\n *\n * Rotation is KMS's: it keeps every backing version of the key, and the\n * encrypted data key names the one that wrapped it, so nothing here tracks a\n * version and `reencrypt` has nothing to move. The ciphertext's key field is\n * `kms` for that reason.\n *\n * The blind index is a KMS HMAC key's `GenerateMac`: deterministic, and the\n * key is as unextractable as the encryption key.\n *\n * In its own entry, `@geekmidas/constructs/encryption/kms`, which only an\n * AWS build's generated entry imports — to register {@link kmsCipherDriver}\n * — so a project that never deploys to AWS never needs\n * `@aws-sdk/client-kms` installed, and its bundle never mentions it.\n */\n\nimport {\n\tDecryptCommand,\n\tGenerateDataKeyCommand,\n\tGenerateMacCommand,\n\tKMSClient,\n} from '@aws-sdk/client-kms';\nimport { KMS_SCHEME } from '@geekmidas/manifest';\nimport {\n\tassociatedData,\n\ttype Cipher,\n\ttype CipherDriver,\n\tCiphertextNotAuthentic,\n\tEncryptionUrlInvalid,\n\tformatCiphertext,\n\topen,\n\tparseCiphertext,\n\tseal,\n} from './cipher';\n\n/** The ciphertext's key field: the version lives inside KMS's own blob. */\nconst KMS_KEY_ID = 'kms';\n\nexport function kmsCipher(construct: string, url: string): Cipher {\n\tconst parsed = new URL(url);\n\tconst region = parsed.hostname;\n\tconst keyId = parsed.searchParams.get('key');\n\tconst indexKeyId = parsed.searchParams.get('index');\n\tif (!region || !keyId || !indexKeyId) {\n\t\tthrow new EncryptionUrlInvalid(\n\t\t\tconstruct,\n\t\t\t'a kms:// URL names a region, a key and an index key',\n\t\t);\n\t}\n\n\tconst endpoint = parsed.searchParams.get('endpoint');\n\t// Credentials are not part of the address: the default chain — a Lambda's\n\t// role deployed, the environment against an emulator.\n\tconst kms = new KMSClient({ region, ...(endpoint ? { endpoint } : {}) });\n\t// What KMS checks on every decrypt, and what CloudTrail shows each call was\n\t// for — a data key minted for one construct will not open for another.\n\tconst context = { construct };\n\tconst aad = associatedData(construct, KMS_KEY_ID);\n\n\treturn {\n\t\tasync encrypt(plaintext) {\n\t\t\tconst dataKey = await kms.send(\n\t\t\t\tnew GenerateDataKeyCommand({\n\t\t\t\t\tKeyId: keyId,\n\t\t\t\t\tKeySpec: 'AES_256',\n\t\t\t\t\tEncryptionContext: context,\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst wrapped = Buffer.from(dataKey.CiphertextBlob!);\n\t\t\tconst sealed = seal(\n\t\t\t\tBuffer.from(dataKey.Plaintext!),\n\t\t\t\tBuffer.from(plaintext, 'utf8'),\n\t\t\t\taad,\n\t\t\t);\n\n\t\t\tconst length = Buffer.alloc(2);\n\t\t\tlength.writeUInt16BE(wrapped.length);\n\t\t\treturn formatCiphertext(\n\t\t\t\tKMS_KEY_ID,\n\t\t\t\tBuffer.concat([length, wrapped, sealed]),\n\t\t\t);\n\t\t},\n\n\t\tasync decrypt(ciphertext) {\n\t\t\tconst { payload } = parseCiphertext(construct, ciphertext);\n\t\t\tconst length = payload.length >= 2 ? payload.readUInt16BE(0) : 0;\n\t\t\tconst wrapped = payload.subarray(2, 2 + length);\n\t\t\tif (!length || wrapped.length !== length) {\n\t\t\t\tthrow new CiphertextNotAuthentic(construct);\n\t\t\t}\n\n\t\t\tconst dataKey = await kms.send(\n\t\t\t\tnew DecryptCommand({\n\t\t\t\t\tCiphertextBlob: wrapped,\n\t\t\t\t\tEncryptionContext: context,\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst plaintext = open(\n\t\t\t\tBuffer.from(dataKey.Plaintext!),\n\t\t\t\tpayload.subarray(2 + length),\n\t\t\t\taad,\n\t\t\t);\n\t\t\tif (!plaintext) throw new CiphertextNotAuthentic(construct);\n\n\t\t\treturn plaintext.toString('utf8');\n\t\t},\n\n\t\tasync index(value) {\n\t\t\tconst { Mac } = await kms.send(\n\t\t\t\tnew GenerateMacCommand({\n\t\t\t\t\tKeyId: indexKeyId,\n\t\t\t\t\tMacAlgorithm: 'HMAC_SHA_256',\n\t\t\t\t\tMessage: Buffer.from(value, 'utf8'),\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn Buffer.from(Mac!).toString('base64url');\n\t\t},\n\n\t\t// KMS keeps every version it rotated through, so a value is never under\n\t\t// a key that could be retired from under it.\n\t\tasync reencrypt(ciphertext) {\n\t\t\tparseCiphertext(construct, ciphertext);\n\t\t\treturn ciphertext;\n\t\t},\n\t};\n}\n\n/** The `kms:` cipher, as an AWS build's entry registers it. */\nexport const kmsCipherDriver: CipherDriver = {\n\tscheme: KMS_SCHEME,\n\topen: kmsCipher,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAM,aAAa;AAEnB,SAAgB,UAAU,WAAmB,KAAqB;CACjE,MAAM,SAAS,IAAI,IAAI,GAAG;CAC1B,MAAM,SAAS,OAAO;CACtB,MAAM,QAAQ,OAAO,aAAa,IAAI,KAAK;CAC3C,MAAM,aAAa,OAAO,aAAa,IAAI,OAAO;CAClD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,YACzB,MAAM,IAAIA,eAAAA,qBACT,WACA,qDACD;CAGD,MAAM,WAAW,OAAO,aAAa,IAAI,UAAU;CAGnD,MAAM,MAAM,IAAIC,oBAAAA,UAAU;EAAE;EAAQ,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;CAAG,CAAC;CAGvE,MAAM,UAAU,EAAE,UAAU;CAC5B,MAAM,MAAMC,eAAAA,eAAe,WAAW,UAAU;CAEhD,OAAO;EACN,MAAM,QAAQ,WAAW;GACxB,MAAM,UAAU,MAAM,IAAI,KACzB,IAAIC,oBAAAA,uBAAuB;IAC1B,OAAO;IACP,SAAS;IACT,mBAAmB;GACpB,CAAC,CACF;GACA,MAAM,UAAU,OAAO,KAAK,QAAQ,cAAe;GACnD,MAAM,SAASC,eAAAA,KACd,OAAO,KAAK,QAAQ,SAAU,GAC9B,OAAO,KAAK,WAAW,MAAM,GAC7B,GACD;GAEA,MAAM,SAAS,OAAO,MAAM,CAAC;GAC7B,OAAO,cAAc,QAAQ,MAAM;GACnC,OAAOC,eAAAA,iBACN,YACA,OAAO,OAAO;IAAC;IAAQ;IAAS;GAAM,CAAC,CACxC;EACD;EAEA,MAAM,QAAQ,YAAY;GACzB,MAAM,EAAE,YAAYC,eAAAA,gBAAgB,WAAW,UAAU;GACzD,MAAM,SAAS,QAAQ,UAAU,IAAI,QAAQ,aAAa,CAAC,IAAI;GAC/D,MAAM,UAAU,QAAQ,SAAS,GAAG,IAAI,MAAM;GAC9C,IAAI,CAAC,UAAU,QAAQ,WAAW,QACjC,MAAM,IAAIC,eAAAA,uBAAuB,SAAS;GAG3C,MAAM,UAAU,MAAM,IAAI,KACzB,IAAIC,oBAAAA,eAAe;IAClB,gBAAgB;IAChB,mBAAmB;GACpB,CAAC,CACF;GACA,MAAM,YAAYC,eAAAA,KACjB,OAAO,KAAK,QAAQ,SAAU,GAC9B,QAAQ,SAAS,IAAI,MAAM,GAC3B,GACD;GACA,IAAI,CAAC,WAAW,MAAM,IAAIF,eAAAA,uBAAuB,SAAS;GAE1D,OAAO,UAAU,SAAS,MAAM;EACjC;EAEA,MAAM,MAAM,OAAO;GAClB,MAAM,EAAE,QAAQ,MAAM,IAAI,KACzB,IAAIG,oBAAAA,mBAAmB;IACtB,OAAO;IACP,cAAc;IACd,SAAS,OAAO,KAAK,OAAO,MAAM;GACnC,CAAC,CACF;GACA,OAAO,OAAO,KAAK,GAAI,CAAC,CAAC,SAAS,WAAW;EAC9C;EAIA,MAAM,UAAU,YAAY;GAC3B,eAAA,gBAAgB,WAAW,UAAU;GACrC,OAAO;EACR;CACD;AACD;;AAGA,MAAa,kBAAgC;CAC5C,QAAQC,oBAAAA;CACR,MAAM;AACP"}

package/dist/encryption/kms.d.cts

@@ -0,0 +1,7 @@
+import { n as CipherDriver, t as Cipher } from "../cipher-DSDxPRIp.cjs";
+//#region src/encryption/kms.d.ts
+export declare function kmsCipher(construct: string, url: string): Cipher;
+/** The `kms:` cipher, as an AWS build's entry registers it. */
+export declare const kmsCipherDriver: CipherDriver;
+//#endregion
+//# sourceMappingURL=kms.d.cts.map

package/dist/encryption/kms.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.d.cts","names":[],"sources":["../../src/encryption/kms.ts"],"mappings":";;wBA4CgB,UAAU,mBAAmB,cAAc;;qBA0F9C,iBAAiB"}

package/dist/encryption/kms.d.mts

@@ -0,0 +1,7 @@
+import { n as CipherDriver, t as Cipher } from "../cipher-DSDxPRIp.mjs";
+//#region src/encryption/kms.d.ts
+export declare function kmsCipher(construct: string, url: string): Cipher;
+/** The `kms:` cipher, as an AWS build's entry registers it. */
+export declare const kmsCipherDriver: CipherDriver;
+//#endregion
+//# sourceMappingURL=kms.d.mts.map

package/dist/encryption/kms.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.d.mts","names":[],"sources":["../../src/encryption/kms.ts"],"mappings":";;wBA4CgB,UAAU,mBAAmB,cAAc;;qBA0F9C,iBAAiB"}

package/dist/encryption/kms.mjs

@@ -0,0 +1,93 @@
+import { a as EncryptionUrlInvalid, c as associatedData, l as formatCiphertext, m as parseCiphertext, n as CiphertextNotAuthentic, p as open, v as seal } from "../cipher-C1lEFX63.mjs";
+import { KMS_SCHEME } from "@geekmidas/manifest";
+import { DecryptCommand, GenerateDataKeyCommand, GenerateMacCommand, KMSClient } from "@aws-sdk/client-kms";
+//#region src/encryption/kms.ts
+/**
+* The `kms://` cipher: envelope encryption under an AWS KMS key.
+*
+* Each `encrypt` asks KMS for a fresh data key, seals the plaintext with it
+* locally, and stores the data key *as KMS encrypted it* beside the data. The
+* plaintext data key is used once and dropped, and the master key never leaves
+* KMS — every decrypt is a KMS call IAM can refuse and CloudTrail records.
+*
+* Rotation is KMS's: it keeps every backing version of the key, and the
+* encrypted data key names the one that wrapped it, so nothing here tracks a
+* version and `reencrypt` has nothing to move. The ciphertext's key field is
+* `kms` for that reason.
+*
+* The blind index is a KMS HMAC key's `GenerateMac`: deterministic, and the
+* key is as unextractable as the encryption key.
+*
+* In its own entry, `@geekmidas/constructs/encryption/kms`, which only an
+* AWS build's generated entry imports — to register {@link kmsCipherDriver}
+* — so a project that never deploys to AWS never needs
+* `@aws-sdk/client-kms` installed, and its bundle never mentions it.
+*/
+/** The ciphertext's key field: the version lives inside KMS's own blob. */
+const KMS_KEY_ID = "kms";
+function kmsCipher(construct, url) {
+	const parsed = new URL(url);
+	const region = parsed.hostname;
+	const keyId = parsed.searchParams.get("key");
+	const indexKeyId = parsed.searchParams.get("index");
+	if (!region || !keyId || !indexKeyId) throw new EncryptionUrlInvalid(construct, "a kms:// URL names a region, a key and an index key");
+	const endpoint = parsed.searchParams.get("endpoint");
+	const kms = new KMSClient({
+		region,
+		...endpoint ? { endpoint } : {}
+	});
+	const context = { construct };
+	const aad = associatedData(construct, KMS_KEY_ID);
+	return {
+		async encrypt(plaintext) {
+			const dataKey = await kms.send(new GenerateDataKeyCommand({
+				KeyId: keyId,
+				KeySpec: "AES_256",
+				EncryptionContext: context
+			}));
+			const wrapped = Buffer.from(dataKey.CiphertextBlob);
+			const sealed = seal(Buffer.from(dataKey.Plaintext), Buffer.from(plaintext, "utf8"), aad);
+			const length = Buffer.alloc(2);
+			length.writeUInt16BE(wrapped.length);
+			return formatCiphertext(KMS_KEY_ID, Buffer.concat([
+				length,
+				wrapped,
+				sealed
+			]));
+		},
+		async decrypt(ciphertext) {
+			const { payload } = parseCiphertext(construct, ciphertext);
+			const length = payload.length >= 2 ? payload.readUInt16BE(0) : 0;
+			const wrapped = payload.subarray(2, 2 + length);
+			if (!length || wrapped.length !== length) throw new CiphertextNotAuthentic(construct);
+			const dataKey = await kms.send(new DecryptCommand({
+				CiphertextBlob: wrapped,
+				EncryptionContext: context
+			}));
+			const plaintext = open(Buffer.from(dataKey.Plaintext), payload.subarray(2 + length), aad);
+			if (!plaintext) throw new CiphertextNotAuthentic(construct);
+			return plaintext.toString("utf8");
+		},
+		async index(value) {
+			const { Mac } = await kms.send(new GenerateMacCommand({
+				KeyId: indexKeyId,
+				MacAlgorithm: "HMAC_SHA_256",
+				Message: Buffer.from(value, "utf8")
+			}));
+			return Buffer.from(Mac).toString("base64url");
+		},
+		async reencrypt(ciphertext) {
+			parseCiphertext(construct, ciphertext);
+			return ciphertext;
+		}
+	};
+}
+/** The `kms:` cipher, as an AWS build's entry registers it. */
+const kmsCipherDriver = {
+	scheme: KMS_SCHEME,
+	open: kmsCipher
+};
+//#endregion
+export { kmsCipher, kmsCipherDriver };
+
+//# sourceMappingURL=kms.mjs.map

package/dist/encryption/kms.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms.mjs","names":[],"sources":["../../src/encryption/kms.ts"],"sourcesContent":["/**\n * The `kms://` cipher: envelope encryption under an AWS KMS key.\n *\n * Each `encrypt` asks KMS for a fresh data key, seals the plaintext with it\n * locally, and stores the data key *as KMS encrypted it* beside the data. The\n * plaintext data key is used once and dropped, and the master key never leaves\n * KMS — every decrypt is a KMS call IAM can refuse and CloudTrail records.\n *\n * Rotation is KMS's: it keeps every backing version of the key, and the\n * encrypted data key names the one that wrapped it, so nothing here tracks a\n * version and `reencrypt` has nothing to move. The ciphertext's key field is\n * `kms` for that reason.\n *\n * The blind index is a KMS HMAC key's `GenerateMac`: deterministic, and the\n * key is as unextractable as the encryption key.\n *\n * In its own entry, `@geekmidas/constructs/encryption/kms`, which only an\n * AWS build's generated entry imports — to register {@link kmsCipherDriver}\n * — so a project that never deploys to AWS never needs\n * `@aws-sdk/client-kms` installed, and its bundle never mentions it.\n */\n\nimport {\n\tDecryptCommand,\n\tGenerateDataKeyCommand,\n\tGenerateMacCommand,\n\tKMSClient,\n} from '@aws-sdk/client-kms';\nimport { KMS_SCHEME } from '@geekmidas/manifest';\nimport {\n\tassociatedData,\n\ttype Cipher,\n\ttype CipherDriver,\n\tCiphertextNotAuthentic,\n\tEncryptionUrlInvalid,\n\tformatCiphertext,\n\topen,\n\tparseCiphertext,\n\tseal,\n} from './cipher';\n\n/** The ciphertext's key field: the version lives inside KMS's own blob. */\nconst KMS_KEY_ID = 'kms';\n\nexport function kmsCipher(construct: string, url: string): Cipher {\n\tconst parsed = new URL(url);\n\tconst region = parsed.hostname;\n\tconst keyId = parsed.searchParams.get('key');\n\tconst indexKeyId = parsed.searchParams.get('index');\n\tif (!region || !keyId || !indexKeyId) {\n\t\tthrow new EncryptionUrlInvalid(\n\t\t\tconstruct,\n\t\t\t'a kms:// URL names a region, a key and an index key',\n\t\t);\n\t}\n\n\tconst endpoint = parsed.searchParams.get('endpoint');\n\t// Credentials are not part of the address: the default chain — a Lambda's\n\t// role deployed, the environment against an emulator.\n\tconst kms = new KMSClient({ region, ...(endpoint ? { endpoint } : {}) });\n\t// What KMS checks on every decrypt, and what CloudTrail shows each call was\n\t// for — a data key minted for one construct will not open for another.\n\tconst context = { construct };\n\tconst aad = associatedData(construct, KMS_KEY_ID);\n\n\treturn {\n\t\tasync encrypt(plaintext) {\n\t\t\tconst dataKey = await kms.send(\n\t\t\t\tnew GenerateDataKeyCommand({\n\t\t\t\t\tKeyId: keyId,\n\t\t\t\t\tKeySpec: 'AES_256',\n\t\t\t\t\tEncryptionContext: context,\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst wrapped = Buffer.from(dataKey.CiphertextBlob!);\n\t\t\tconst sealed = seal(\n\t\t\t\tBuffer.from(dataKey.Plaintext!),\n\t\t\t\tBuffer.from(plaintext, 'utf8'),\n\t\t\t\taad,\n\t\t\t);\n\n\t\t\tconst length = Buffer.alloc(2);\n\t\t\tlength.writeUInt16BE(wrapped.length);\n\t\t\treturn formatCiphertext(\n\t\t\t\tKMS_KEY_ID,\n\t\t\t\tBuffer.concat([length, wrapped, sealed]),\n\t\t\t);\n\t\t},\n\n\t\tasync decrypt(ciphertext) {\n\t\t\tconst { payload } = parseCiphertext(construct, ciphertext);\n\t\t\tconst length = payload.length >= 2 ? payload.readUInt16BE(0) : 0;\n\t\t\tconst wrapped = payload.subarray(2, 2 + length);\n\t\t\tif (!length || wrapped.length !== length) {\n\t\t\t\tthrow new CiphertextNotAuthentic(construct);\n\t\t\t}\n\n\t\t\tconst dataKey = await kms.send(\n\t\t\t\tnew DecryptCommand({\n\t\t\t\t\tCiphertextBlob: wrapped,\n\t\t\t\t\tEncryptionContext: context,\n\t\t\t\t}),\n\t\t\t);\n\t\t\tconst plaintext = open(\n\t\t\t\tBuffer.from(dataKey.Plaintext!),\n\t\t\t\tpayload.subarray(2 + length),\n\t\t\t\taad,\n\t\t\t);\n\t\t\tif (!plaintext) throw new CiphertextNotAuthentic(construct);\n\n\t\t\treturn plaintext.toString('utf8');\n\t\t},\n\n\t\tasync index(value) {\n\t\t\tconst { Mac } = await kms.send(\n\t\t\t\tnew GenerateMacCommand({\n\t\t\t\t\tKeyId: indexKeyId,\n\t\t\t\t\tMacAlgorithm: 'HMAC_SHA_256',\n\t\t\t\t\tMessage: Buffer.from(value, 'utf8'),\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn Buffer.from(Mac!).toString('base64url');\n\t\t},\n\n\t\t// KMS keeps every version it rotated through, so a value is never under\n\t\t// a key that could be retired from under it.\n\t\tasync reencrypt(ciphertext) {\n\t\t\tparseCiphertext(construct, ciphertext);\n\t\t\treturn ciphertext;\n\t\t},\n\t};\n}\n\n/** The `kms:` cipher, as an AWS build's entry registers it. */\nexport const kmsCipherDriver: CipherDriver = {\n\tscheme: KMS_SCHEME,\n\topen: kmsCipher,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAM,aAAa;AAEnB,SAAgB,UAAU,WAAmB,KAAqB;CACjE,MAAM,SAAS,IAAI,IAAI,GAAG;CAC1B,MAAM,SAAS,OAAO;CACtB,MAAM,QAAQ,OAAO,aAAa,IAAI,KAAK;CAC3C,MAAM,aAAa,OAAO,aAAa,IAAI,OAAO;CAClD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,YACzB,MAAM,IAAI,qBACT,WACA,qDACD;CAGD,MAAM,WAAW,OAAO,aAAa,IAAI,UAAU;CAGnD,MAAM,MAAM,IAAI,UAAU;EAAE;EAAQ,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;CAAG,CAAC;CAGvE,MAAM,UAAU,EAAE,UAAU;CAC5B,MAAM,MAAM,eAAe,WAAW,UAAU;CAEhD,OAAO;EACN,MAAM,QAAQ,WAAW;GACxB,MAAM,UAAU,MAAM,IAAI,KACzB,IAAI,uBAAuB;IAC1B,OAAO;IACP,SAAS;IACT,mBAAmB;GACpB,CAAC,CACF;GACA,MAAM,UAAU,OAAO,KAAK,QAAQ,cAAe;GACnD,MAAM,SAAS,KACd,OAAO,KAAK,QAAQ,SAAU,GAC9B,OAAO,KAAK,WAAW,MAAM,GAC7B,GACD;GAEA,MAAM,SAAS,OAAO,MAAM,CAAC;GAC7B,OAAO,cAAc,QAAQ,MAAM;GACnC,OAAO,iBACN,YACA,OAAO,OAAO;IAAC;IAAQ;IAAS;GAAM,CAAC,CACxC;EACD;EAEA,MAAM,QAAQ,YAAY;GACzB,MAAM,EAAE,YAAY,gBAAgB,WAAW,UAAU;GACzD,MAAM,SAAS,QAAQ,UAAU,IAAI,QAAQ,aAAa,CAAC,IAAI;GAC/D,MAAM,UAAU,QAAQ,SAAS,GAAG,IAAI,MAAM;GAC9C,IAAI,CAAC,UAAU,QAAQ,WAAW,QACjC,MAAM,IAAI,uBAAuB,SAAS;GAG3C,MAAM,UAAU,MAAM,IAAI,KACzB,IAAI,eAAe;IAClB,gBAAgB;IAChB,mBAAmB;GACpB,CAAC,CACF;GACA,MAAM,YAAY,KACjB,OAAO,KAAK,QAAQ,SAAU,GAC9B,QAAQ,SAAS,IAAI,MAAM,GAC3B,GACD;GACA,IAAI,CAAC,WAAW,MAAM,IAAI,uBAAuB,SAAS;GAE1D,OAAO,UAAU,SAAS,MAAM;EACjC;EAEA,MAAM,MAAM,OAAO;GAClB,MAAM,EAAE,QAAQ,MAAM,IAAI,KACzB,IAAI,mBAAmB;IACtB,OAAO;IACP,cAAc;IACd,SAAS,OAAO,KAAK,OAAO,MAAM;GACnC,CAAC,CACF;GACA,OAAO,OAAO,KAAK,GAAI,CAAC,CAAC,SAAS,WAAW;EAC9C;EAIA,MAAM,UAAU,YAAY;GAC3B,gBAAgB,WAAW,UAAU;GACrC,OAAO;EACR;CACD;AACD;;AAGA,MAAa,kBAAgC;CAC5C,QAAQ;CACR,MAAM;AACP"}

package/dist/encryption.cjs

@@ -0,0 +1,116 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cipher = require("./cipher-CVxfwLjk.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+//#region src/encryption.ts
+/**
+* `Encryption` — a key that encrypts what the application stores.
+*
+* ```ts
+* export const pii = new Encryption('Pii');
+*
+* // an endpoint that `.dependsOn([pii])`
+* const email = await services.pii.encrypt(body.email);
+* const emailIndex = await services.pii.index(body.email);
+* await db.insertInto('users').values({ email, emailIndex }).execute();
+*
+* // and to find them again, without decrypting a column
+* db.selectFrom('users').where('emailIndex', '=', await services.pii.index(q));
+* ```
+*
+* The app names no cipher and holds no key. The construct provides one URL,
+* `<ID>_URL`, and its scheme picks the backend the way a queue's connection
+* string picks its broker:
+*
+* - **AWS** — `kms://`: envelope encryption under a KMS key that rotates
+*   yearly, and a KMS HMAC key for the index. Only a function that depends on
+*   the construct is granted either key.
+* - **Server, local, tests** — `aes256gcm://`: a keyring the process holds.
+*   Derived locally, so `gkm dev` and `gkm test` need nothing set; generated
+*   into a server stage's secrets on its first deploy, and rotated there with
+*   `gkm encryption:rotate`.
+*
+* Every ciphertext names the key that wrote it, so a rotated key still opens
+* what it wrote. Retiring one is explicit — `reencrypt` the column, then
+* `gkm encryption:retire` — and a value still under an old key says so when it
+* is decrypted, once per key per process.
+*/
+const drivers = /* @__PURE__ */ new Map();
+/** Make a cipher available for its scheme. Idempotent. */
+function registerCipherDriver(driver) {
+	drivers.set(driver.scheme, driver);
+}
+/**
+* A key whose URL names a cipher this process registered no driver for —
+* `kms:` in an entry built for a target whose keys are local.
+*/
+var UnregisteredEncryptionScheme = class extends Error {
+	construct;
+	scheme;
+	constructor(construct, scheme) {
+		super(`${construct}'s key is a '${scheme}' URL, and this build registered no cipher for it. ` + (scheme === _geekmidas_manifest.KMS_SCHEME ? "A KMS key is an AWS target's: build for it (gkm build --provider aws), which registers the KMS cipher and needs @aws-sdk/client-kms installed." : "Register its driver with registerCipherDriver before the first request."));
+		this.construct = construct;
+		this.scheme = scheme;
+		this.name = "UnregisteredEncryptionScheme";
+	}
+};
+var Encryption = class {
+	id;
+	service;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the key the
+	* target publishes and the key the client reads cannot drift.
+	*/
+	key;
+	/**
+	* One cipher per process, held as the promise: a keyring is parsed once and
+	* a KMS client is built once, however many handlers register it at once.
+	*/
+	cipher;
+	constructor(id) {
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		this.key = (0, _geekmidas_manifest.provideKey)(canonical, "url");
+		this.service = {
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
+			register: (options) => this.connect(options)
+		};
+	}
+	declare() {
+		return [{
+			kind: "encryption",
+			id: this.id,
+			provides: [this.key]
+		}];
+	}
+	connect(options) {
+		this.cipher ??= this.open(options);
+		return this.cipher;
+	}
+	async open(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.key).string() })).parse();
+		const scheme = url.slice(0, url.indexOf(":") + 1);
+		if (scheme === "aes256gcm:") return require_cipher.keyringCipher(this.id, url, (stale, current) => console.warn(`${this.id} decrypted a value still under '${stale}' (current: '${current}'). reencrypt it, and retire '${stale}' once nothing is left under it.`));
+		const driver = drivers.get(scheme);
+		if (driver) return driver.open(this.id, url);
+		if (scheme === _geekmidas_manifest.KMS_SCHEME) throw new UnregisteredEncryptionScheme(this.id, scheme);
+		throw new require_cipher.UnknownEncryptionScheme(this.id, scheme);
+	}
+};
+//#endregion
+exports.CiphertextMalformed = require_cipher.CiphertextMalformed;
+exports.CiphertextNotAuthentic = require_cipher.CiphertextNotAuthentic;
+exports.CurrentKeyCannotRetire = require_cipher.CurrentKeyCannotRetire;
+exports.Encryption = Encryption;
+exports.EncryptionKeyRetired = require_cipher.EncryptionKeyRetired;
+exports.EncryptionUrlInvalid = require_cipher.EncryptionUrlInvalid;
+exports.UnknownEncryptionScheme = require_cipher.UnknownEncryptionScheme;
+exports.UnregisteredEncryptionScheme = UnregisteredEncryptionScheme;
+exports.formatKeyring = require_cipher.formatKeyring;
+exports.generateKeyring = require_cipher.generateKeyring;
+exports.keyringCipher = require_cipher.keyringCipher;
+exports.parseKeyring = require_cipher.parseKeyring;
+exports.registerCipherDriver = registerCipherDriver;
+exports.retireKey = require_cipher.retireKey;
+exports.rotateKeyring = require_cipher.rotateKeyring;
+
+//# sourceMappingURL=encryption.cjs.map

package/dist/encryption.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.cjs","names":["KMS_SCHEME","canonicalId","provideKey","serviceKey","keyringCipher","UnknownEncryptionScheme"],"sources":["../src/encryption.ts"],"sourcesContent":["/**\n * `Encryption` — a key that encrypts what the application stores.\n *\n * ```ts\n * export const pii = new Encryption('Pii');\n *\n * // an endpoint that `.dependsOn([pii])`\n * const email = await services.pii.encrypt(body.email);\n * const emailIndex = await services.pii.index(body.email);\n * await db.insertInto('users').values({ email, emailIndex }).execute();\n *\n * // and to find them again, without decrypting a column\n * db.selectFrom('users').where('emailIndex', '=', await services.pii.index(q));\n * ```\n *\n * The app names no cipher and holds no key. The construct provides one URL,\n * `<ID>_URL`, and its scheme picks the backend the way a queue's connection\n * string picks its broker:\n *\n * - **AWS** — `kms://`: envelope encryption under a KMS key that rotates\n *   yearly, and a KMS HMAC key for the index. Only a function that depends on\n *   the construct is granted either key.\n * - **Server, local, tests** — `aes256gcm://`: a keyring the process holds.\n *   Derived locally, so `gkm dev` and `gkm test` need nothing set; generated\n *   into a server stage's secrets on its first deploy, and rotated there with\n *   `gkm encryption:rotate`.\n *\n * Every ciphertext names the key that wrote it, so a rotated key still opens\n * what it wrote. Retiring one is explicit — `reencrypt` the column, then\n * `gkm encryption:retire` — and a value still under an old key says so when it\n * is decrypted, once per key per process.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tKMS_SCHEME,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\nimport {\n\ttype Cipher,\n\ttype CipherDriver,\n\tkeyringCipher,\n\tLOCAL_SCHEME,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport type { Cipher, CipherDriver } from './encryption/cipher';\nexport {\n\tCiphertextMalformed,\n\tCiphertextNotAuthentic,\n\tCurrentKeyCannotRetire,\n\tEncryptionKeyRetired,\n\tEncryptionUrlInvalid,\n\tformatKeyring,\n\tgenerateKeyring,\n\ttype Keyring,\n\tkeyringCipher,\n\tparseKeyring,\n\tretireKey,\n\trotateKeyring,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nconst drivers = new Map<string, CipherDriver>();\n\n/** Make a cipher available for its scheme. Idempotent. */\nexport function registerCipherDriver(driver: CipherDriver): void {\n\tdrivers.set(driver.scheme, driver);\n}\n\n/**\n * A key whose URL names a cipher this process registered no driver for —\n * `kms:` in an entry built for a target whose keys are local.\n */\nexport class UnregisteredEncryptionScheme 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 key is a '${scheme}' URL, and this build registered no cipher for it. ` +\n\t\t\t\t(scheme === KMS_SCHEME\n\t\t\t\t\t? \"A KMS key is an AWS target's: build for it (gkm build --provider aws), which registers the KMS cipher and needs @aws-sdk/client-kms installed.\"\n\t\t\t\t\t: 'Register its driver with registerCipherDriver before the first request.'),\n\t\t);\n\t\tthis.name = 'UnregisteredEncryptionScheme';\n\t}\n}\n\nexport class Encryption<TName extends string = string>\n\timplements Construct<TName, Cipher>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Cipher>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly key: string;\n\n\t/**\n\t * One cipher per process, held as the promise: a keyring is parsed once and\n\t * a KMS client is built once, however many handlers register it at once.\n\t */\n\tprivate cipher?: Promise<Cipher>;\n\n\tconstructor(id: ConstructName<TName>) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.key = provideKey(canonical, 'url');\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (options) => this.connect(options),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [{ kind: 'encryption', id: this.id, provides: [this.key] }];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tthis.cipher ??= this.open(options);\n\t\treturn this.cipher;\n\t}\n\n\tprivate async open(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.key).string() }))\n\t\t\t.parse();\n\t\tconst scheme = url.slice(0, url.indexOf(':') + 1);\n\n\t\tif (scheme === LOCAL_SCHEME) {\n\t\t\treturn keyringCipher(this.id, url, (stale, current) =>\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`${this.id} decrypted a value still under '${stale}' (current: '${current}'). reencrypt it, and retire '${stale}' once nothing is left under it.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\t// Registered by the entry a build generates, only for a target whose\n\t\t// keys live there — so no other process imports that cipher's SDK.\n\t\tconst driver = drivers.get(scheme);\n\t\tif (driver) return driver.open(this.id, url);\n\t\tif (scheme === KMS_SCHEME) {\n\t\t\tthrow new UnregisteredEncryptionScheme(this.id, scheme);\n\t\t}\n\n\t\tthrow new UnknownEncryptionScheme(this.id, scheme);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,MAAM,0BAAU,IAAI,IAA0B;;AAG9C,SAAgB,qBAAqB,QAA4B;CAChE,QAAQ,IAAI,OAAO,QAAQ,MAAM;AAClC;;;;;AAMA,IAAa,+BAAb,cAAkD,MAAM;CAE7C;CACA;CAFV,YACC,WACA,QACC;EACD,MACC,GAAG,UAAU,eAAe,OAAO,wDACjC,WAAWA,oBAAAA,aACT,mJACA,0EACL;EARS,KAAA,YAAA;EACA,KAAA,SAAA;EAQT,KAAK,OAAO;CACb;AACD;AAEA,IAAa,aAAb,MAEA;CACC;CACA;;;;;CAMA;;;;;CAMA;CAEA,YAAY,IAA0B;EACrC,MAAM,aAAA,GAAYC,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAA,GAAMC,oBAAAA,WAAAA,CAAW,WAAW,KAAK;EAGtC,KAAK,UAAU;GACd,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,SAAS;GACjC,WAAW,YAAY,KAAK,QAAQ,OAAO;EAC5C;CACD;CAEA,UAAyB;EACxB,OAAO,CAAC;GAAE,MAAM;GAAc,IAAI,KAAK;GAAI,UAAU,CAAC,KAAK,GAAG;EAAE,CAAC;CAClE;CAEA,QAAgB,SAAkD;EACjE,KAAK,WAAW,KAAK,KAAK,OAAO;EACjC,OAAO,KAAK;CACb;CAEA,MAAc,KAAK,SAAkD;EACpE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAClD,MAAM;EACR,MAAM,SAAS,IAAI,MAAM,GAAG,IAAI,QAAQ,GAAG,IAAI,CAAC;EAEhD,IAAI,WAAA,cACH,OAAOC,eAAAA,cAAc,KAAK,IAAI,MAAM,OAAO,YAC1C,QAAQ,KACP,GAAG,KAAK,GAAG,kCAAkC,MAAM,eAAe,QAAQ,gCAAgC,MAAM,iCACjH,CACD;EAKD,MAAM,SAAS,QAAQ,IAAI,MAAM;EACjC,IAAI,QAAQ,OAAO,OAAO,KAAK,KAAK,IAAI,GAAG;EAC3C,IAAI,WAAWJ,oBAAAA,YACd,MAAM,IAAI,6BAA6B,KAAK,IAAI,MAAM;EAGvD,MAAM,IAAIK,eAAAA,wBAAwB,KAAK,IAAI,MAAM;CAClD;AACD"}

package/dist/encryption.d.cts

@@ -0,0 +1,37 @@
+import { n as Construct } from "./construct-interface-B1AfqRl4.cjs";
+import { a as CurrentKeyCannotRetire, c as Keyring, d as generateKeyring, f as keyringCipher, h as rotateKeyring, i as CiphertextNotAuthentic, l as UnknownEncryptionScheme, m as retireKey, n as CipherDriver, o as EncryptionKeyRetired, p as parseKeyring, r as CiphertextMalformed, s as EncryptionUrlInvalid, t as Cipher, u as formatKeyring } from "./cipher-DSDxPRIp.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+//#region src/encryption.d.ts
+/** Make a cipher available for its scheme. Idempotent. */
+export declare function registerCipherDriver(driver: CipherDriver): void;
+/**
+ * A key whose URL names a cipher this process registered no driver for —
+ * `kms:` in an entry built for a target whose keys are local.
+ */
+export declare class UnregisteredEncryptionScheme extends Error {
+  readonly construct: string;
+  readonly scheme: string;
+  constructor(construct: string, scheme: string);
+}
+export declare class Encryption<TName extends string = string> implements Construct<TName, Cipher> {
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Cipher>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * target publishes and the key the client reads cannot drift.
+   */
+  private readonly key;
+  /**
+   * One cipher per process, held as the promise: a keyring is parsed once and
+   * a KMS client is built once, however many handlers register it at once.
+   */
+  private cipher?;
+  constructor(id: ConstructName<TName>);
+  declare(): Declaration[];
+  private connect;
+  private open;
+}
+//#endregion
+export { type Cipher, type CipherDriver, CiphertextMalformed, CiphertextNotAuthentic, CurrentKeyCannotRetire, EncryptionKeyRetired, EncryptionUrlInvalid, type Keyring, UnknownEncryptionScheme, formatKeyring, generateKeyring, keyringCipher, parseKeyring, retireKey, rotateKeyring };
+//# sourceMappingURL=encryption.d.cts.map

package/dist/encryption.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.cts","names":[],"sources":["../src/encryption.ts"],"mappings":";;;;;;wBAuEgB,qBAAqB,QAAQ;;;;;qBAQhC,qCAAqC;WAEvC;WACA;EAFV,YACU,mBACA;;qBAYE,WAAW,0CACZ,UAAU,OAAO;WAEnB,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;;;;mBAM9B;;;;;UAMT;EAER,YAAY,IAAI,cAAc;EAa9B,WAAW;UAIH;UAKM"}

package/dist/encryption.d.mts

@@ -0,0 +1,37 @@
+import { n as Construct } from "./construct-interface-ZvYQbivO.mjs";
+import { a as CurrentKeyCannotRetire, c as Keyring, d as generateKeyring, f as keyringCipher, h as rotateKeyring, i as CiphertextNotAuthentic, l as UnknownEncryptionScheme, m as retireKey, n as CipherDriver, o as EncryptionKeyRetired, p as parseKeyring, r as CiphertextMalformed, s as EncryptionUrlInvalid, t as Cipher, u as formatKeyring } from "./cipher-DSDxPRIp.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+//#region src/encryption.d.ts
+/** Make a cipher available for its scheme. Idempotent. */
+export declare function registerCipherDriver(driver: CipherDriver): void;
+/**
+ * A key whose URL names a cipher this process registered no driver for —
+ * `kms:` in an entry built for a target whose keys are local.
+ */
+export declare class UnregisteredEncryptionScheme extends Error {
+  readonly construct: string;
+  readonly scheme: string;
+  constructor(construct: string, scheme: string);
+}
+export declare class Encryption<TName extends string = string> implements Construct<TName, Cipher> {
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Cipher>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * target publishes and the key the client reads cannot drift.
+   */
+  private readonly key;
+  /**
+   * One cipher per process, held as the promise: a keyring is parsed once and
+   * a KMS client is built once, however many handlers register it at once.
+   */
+  private cipher?;
+  constructor(id: ConstructName<TName>);
+  declare(): Declaration[];
+  private connect;
+  private open;
+}
+//#endregion
+export { type Cipher, type CipherDriver, CiphertextMalformed, CiphertextNotAuthentic, CurrentKeyCannotRetire, EncryptionKeyRetired, EncryptionUrlInvalid, type Keyring, UnknownEncryptionScheme, formatKeyring, generateKeyring, keyringCipher, parseKeyring, retireKey, rotateKeyring };
+//# sourceMappingURL=encryption.d.mts.map

package/dist/encryption.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.mts","names":[],"sources":["../src/encryption.ts"],"mappings":";;;;;;wBAuEgB,qBAAqB,QAAQ;;;;;qBAQhC,qCAAqC;WAEvC;WACA;EAFV,YACU,mBACA;;qBAYE,WAAW,0CACZ,UAAU,OAAO;WAEnB,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;;;;mBAM9B;;;;;UAMT;EAER,YAAY,IAAI,cAAc;EAa9B,WAAW;UAIH;UAKM"}

package/dist/encryption.mjs

@@ -0,0 +1,101 @@
+import { _ as rotateKeyring, a as EncryptionUrlInvalid, d as generateKeyring, f as keyringCipher, g as retireKey, h as parseKeyring, i as EncryptionKeyRetired, n as CiphertextNotAuthentic, r as CurrentKeyCannotRetire, s as UnknownEncryptionScheme, t as CiphertextMalformed, u as formatKeyring } from "./cipher-C1lEFX63.mjs";
+import { KMS_SCHEME, canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+//#region src/encryption.ts
+/**
+* `Encryption` — a key that encrypts what the application stores.
+*
+* ```ts
+* export const pii = new Encryption('Pii');
+*
+* // an endpoint that `.dependsOn([pii])`
+* const email = await services.pii.encrypt(body.email);
+* const emailIndex = await services.pii.index(body.email);
+* await db.insertInto('users').values({ email, emailIndex }).execute();
+*
+* // and to find them again, without decrypting a column
+* db.selectFrom('users').where('emailIndex', '=', await services.pii.index(q));
+* ```
+*
+* The app names no cipher and holds no key. The construct provides one URL,
+* `<ID>_URL`, and its scheme picks the backend the way a queue's connection
+* string picks its broker:
+*
+* - **AWS** — `kms://`: envelope encryption under a KMS key that rotates
+*   yearly, and a KMS HMAC key for the index. Only a function that depends on
+*   the construct is granted either key.
+* - **Server, local, tests** — `aes256gcm://`: a keyring the process holds.
+*   Derived locally, so `gkm dev` and `gkm test` need nothing set; generated
+*   into a server stage's secrets on its first deploy, and rotated there with
+*   `gkm encryption:rotate`.
+*
+* Every ciphertext names the key that wrote it, so a rotated key still opens
+* what it wrote. Retiring one is explicit — `reencrypt` the column, then
+* `gkm encryption:retire` — and a value still under an old key says so when it
+* is decrypted, once per key per process.
+*/
+const drivers = /* @__PURE__ */ new Map();
+/** Make a cipher available for its scheme. Idempotent. */
+function registerCipherDriver(driver) {
+	drivers.set(driver.scheme, driver);
+}
+/**
+* A key whose URL names a cipher this process registered no driver for —
+* `kms:` in an entry built for a target whose keys are local.
+*/
+var UnregisteredEncryptionScheme = class extends Error {
+	construct;
+	scheme;
+	constructor(construct, scheme) {
+		super(`${construct}'s key is a '${scheme}' URL, and this build registered no cipher for it. ` + (scheme === KMS_SCHEME ? "A KMS key is an AWS target's: build for it (gkm build --provider aws), which registers the KMS cipher and needs @aws-sdk/client-kms installed." : "Register its driver with registerCipherDriver before the first request."));
+		this.construct = construct;
+		this.scheme = scheme;
+		this.name = "UnregisteredEncryptionScheme";
+	}
+};
+var Encryption = class {
+	id;
+	service;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the key the
+	* target publishes and the key the client reads cannot drift.
+	*/
+	key;
+	/**
+	* One cipher per process, held as the promise: a keyring is parsed once and
+	* a KMS client is built once, however many handlers register it at once.
+	*/
+	cipher;
+	constructor(id) {
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.key = provideKey(canonical, "url");
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (options) => this.connect(options)
+		};
+	}
+	declare() {
+		return [{
+			kind: "encryption",
+			id: this.id,
+			provides: [this.key]
+		}];
+	}
+	connect(options) {
+		this.cipher ??= this.open(options);
+		return this.cipher;
+	}
+	async open(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.key).string() })).parse();
+		const scheme = url.slice(0, url.indexOf(":") + 1);
+		if (scheme === "aes256gcm:") return keyringCipher(this.id, url, (stale, current) => console.warn(`${this.id} decrypted a value still under '${stale}' (current: '${current}'). reencrypt it, and retire '${stale}' once nothing is left under it.`));
+		const driver = drivers.get(scheme);
+		if (driver) return driver.open(this.id, url);
+		if (scheme === KMS_SCHEME) throw new UnregisteredEncryptionScheme(this.id, scheme);
+		throw new UnknownEncryptionScheme(this.id, scheme);
+	}
+};
+//#endregion
+export { CiphertextMalformed, CiphertextNotAuthentic, CurrentKeyCannotRetire, Encryption, EncryptionKeyRetired, EncryptionUrlInvalid, UnknownEncryptionScheme, UnregisteredEncryptionScheme, formatKeyring, generateKeyring, keyringCipher, parseKeyring, registerCipherDriver, retireKey, rotateKeyring };
+
+//# sourceMappingURL=encryption.mjs.map

package/dist/encryption.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.mjs","names":[],"sources":["../src/encryption.ts"],"sourcesContent":["/**\n * `Encryption` — a key that encrypts what the application stores.\n *\n * ```ts\n * export const pii = new Encryption('Pii');\n *\n * // an endpoint that `.dependsOn([pii])`\n * const email = await services.pii.encrypt(body.email);\n * const emailIndex = await services.pii.index(body.email);\n * await db.insertInto('users').values({ email, emailIndex }).execute();\n *\n * // and to find them again, without decrypting a column\n * db.selectFrom('users').where('emailIndex', '=', await services.pii.index(q));\n * ```\n *\n * The app names no cipher and holds no key. The construct provides one URL,\n * `<ID>_URL`, and its scheme picks the backend the way a queue's connection\n * string picks its broker:\n *\n * - **AWS** — `kms://`: envelope encryption under a KMS key that rotates\n *   yearly, and a KMS HMAC key for the index. Only a function that depends on\n *   the construct is granted either key.\n * - **Server, local, tests** — `aes256gcm://`: a keyring the process holds.\n *   Derived locally, so `gkm dev` and `gkm test` need nothing set; generated\n *   into a server stage's secrets on its first deploy, and rotated there with\n *   `gkm encryption:rotate`.\n *\n * Every ciphertext names the key that wrote it, so a rotated key still opens\n * what it wrote. Retiring one is explicit — `reencrypt` the column, then\n * `gkm encryption:retire` — and a value still under an old key says so when it\n * is decrypted, once per key per process.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tKMS_SCHEME,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\nimport {\n\ttype Cipher,\n\ttype CipherDriver,\n\tkeyringCipher,\n\tLOCAL_SCHEME,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport type { Cipher, CipherDriver } from './encryption/cipher';\nexport {\n\tCiphertextMalformed,\n\tCiphertextNotAuthentic,\n\tCurrentKeyCannotRetire,\n\tEncryptionKeyRetired,\n\tEncryptionUrlInvalid,\n\tformatKeyring,\n\tgenerateKeyring,\n\ttype Keyring,\n\tkeyringCipher,\n\tparseKeyring,\n\tretireKey,\n\trotateKeyring,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nconst drivers = new Map<string, CipherDriver>();\n\n/** Make a cipher available for its scheme. Idempotent. */\nexport function registerCipherDriver(driver: CipherDriver): void {\n\tdrivers.set(driver.scheme, driver);\n}\n\n/**\n * A key whose URL names a cipher this process registered no driver for —\n * `kms:` in an entry built for a target whose keys are local.\n */\nexport class UnregisteredEncryptionScheme 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 key is a '${scheme}' URL, and this build registered no cipher for it. ` +\n\t\t\t\t(scheme === KMS_SCHEME\n\t\t\t\t\t? \"A KMS key is an AWS target's: build for it (gkm build --provider aws), which registers the KMS cipher and needs @aws-sdk/client-kms installed.\"\n\t\t\t\t\t: 'Register its driver with registerCipherDriver before the first request.'),\n\t\t);\n\t\tthis.name = 'UnregisteredEncryptionScheme';\n\t}\n}\n\nexport class Encryption<TName extends string = string>\n\timplements Construct<TName, Cipher>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Cipher>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly key: string;\n\n\t/**\n\t * One cipher per process, held as the promise: a keyring is parsed once and\n\t * a KMS client is built once, however many handlers register it at once.\n\t */\n\tprivate cipher?: Promise<Cipher>;\n\n\tconstructor(id: ConstructName<TName>) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.key = provideKey(canonical, 'url');\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (options) => this.connect(options),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [{ kind: 'encryption', id: this.id, provides: [this.key] }];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tthis.cipher ??= this.open(options);\n\t\treturn this.cipher;\n\t}\n\n\tprivate async open(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.key).string() }))\n\t\t\t.parse();\n\t\tconst scheme = url.slice(0, url.indexOf(':') + 1);\n\n\t\tif (scheme === LOCAL_SCHEME) {\n\t\t\treturn keyringCipher(this.id, url, (stale, current) =>\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`${this.id} decrypted a value still under '${stale}' (current: '${current}'). reencrypt it, and retire '${stale}' once nothing is left under it.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\t// Registered by the entry a build generates, only for a target whose\n\t\t// keys live there — so no other process imports that cipher's SDK.\n\t\tconst driver = drivers.get(scheme);\n\t\tif (driver) return driver.open(this.id, url);\n\t\tif (scheme === KMS_SCHEME) {\n\t\t\tthrow new UnregisteredEncryptionScheme(this.id, scheme);\n\t\t}\n\n\t\tthrow new UnknownEncryptionScheme(this.id, scheme);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEA,MAAM,0BAAU,IAAI,IAA0B;;AAG9C,SAAgB,qBAAqB,QAA4B;CAChE,QAAQ,IAAI,OAAO,QAAQ,MAAM;AAClC;;;;;AAMA,IAAa,+BAAb,cAAkD,MAAM;CAE7C;CACA;CAFV,YACC,WACA,QACC;EACD,MACC,GAAG,UAAU,eAAe,OAAO,wDACjC,WAAW,aACT,mJACA,0EACL;EARS,KAAA,YAAA;EACA,KAAA,SAAA;EAQT,KAAK,OAAO;CACb;AACD;AAEA,IAAa,aAAb,MAEA;CACC;CACA;;;;;CAMA;;;;;CAMA;CAEA,YAAY,IAA0B;EACrC,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,MAAM,WAAW,WAAW,KAAK;EAGtC,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,YAAY,KAAK,QAAQ,OAAO;EAC5C;CACD;CAEA,UAAyB;EACxB,OAAO,CAAC;GAAE,MAAM;GAAc,IAAI,KAAK;GAAI,UAAU,CAAC,KAAK,GAAG;EAAE,CAAC;CAClE;CAEA,QAAgB,SAAkD;EACjE,KAAK,WAAW,KAAK,KAAK,OAAO;EACjC,OAAO,KAAK;CACb;CAEA,MAAc,KAAK,SAAkD;EACpE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAClD,MAAM;EACR,MAAM,SAAS,IAAI,MAAM,GAAG,IAAI,QAAQ,GAAG,IAAI,CAAC;EAEhD,IAAI,WAAA,cACH,OAAO,cAAc,KAAK,IAAI,MAAM,OAAO,YAC1C,QAAQ,KACP,GAAG,KAAK,GAAG,kCAAkC,MAAM,eAAe,QAAQ,gCAAgC,MAAM,iCACjH,CACD;EAKD,MAAM,SAAS,QAAQ,IAAI,MAAM;EACjC,IAAI,QAAQ,OAAO,OAAO,KAAK,KAAK,IAAI,GAAG;EAC3C,IAAI,WAAW,YACd,MAAM,IAAI,6BAA6B,KAAK,IAAI,MAAM;EAGvD,MAAM,IAAI,wBAAwB,KAAK,IAAI,MAAM;CAClD;AACD"}

package/dist/endpoints/index.cjs

@@ -1,27 +1,38 @@
-require('../construct-interface-BfjcOD_E.cjs');
-require('../Construct-CyS3RpTL.cjs');
-require('../functions-i_la-N5r.cjs');
-const require_EndpointFactory = require('../EndpointFactory-CdWB7wPw.cjs');
-require('../clone-Dy0cR2SZ.cjs');
-const require_Endpoint = require('../Endpoint-DcWXE-SZ.cjs');
-const require_surfaceEnv = require('../surfaceEnv-BFXEms2f.cjs');
-const require_lazyAccessors = require('../lazyAccessors-e3j2oE2m.cjs');
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_EndpointFactory = require("../EndpointFactory-CSrAyazj.cjs");
+const require_functions = require("../functions-D7O5SGVc.cjs");
+const require_Endpoint = require("../Endpoint-yhR2T2Wt.cjs");
+const require_surfaceEnv = require("../surfaceEnv-CNimK76p.cjs");
+const require_readRequestBody = require("../readRequestBody-Dej_L3c4.cjs");
 exports.BUILT_IN_SECURITY_SCHEMES = require_EndpointFactory.BUILT_IN_SECURITY_SCHEMES;
 exports.Endpoint = require_Endpoint.Endpoint;
 exports.EndpointBuilder = require_EndpointFactory.EndpointBuilder;
 exports.EndpointFactory = require_EndpointFactory.EndpointFactory;
+exports.MalformedRequestBody = require_readRequestBody.MalformedRequestBody;
+exports.NoAuthenticator = require_Endpoint.NoAuthenticator;
 exports.RLS_BYPASS = require_EndpointFactory.RLS_BYPASS;
+exports.RedirectStatus = require_Endpoint.RedirectStatus;
 exports.ResponseBuilder = require_Endpoint.ResponseBuilder;
-exports.createApiGatewayCookies = require_lazyAccessors.createApiGatewayCookies;
-exports.createApiGatewayHeaders = require_lazyAccessors.createApiGatewayHeaders;
+exports.SUPPORTED_BODY_TYPES = require_readRequestBody.SUPPORTED_BODY_TYPES;
+exports.SuccessStatus = require_Endpoint.SuccessStatus;
+exports.UPLOAD_POST_SCHEMA = require_EndpointFactory.UPLOAD_POST_SCHEMA;
+exports.UnsupportedRequestContentType = require_readRequestBody.UnsupportedRequestContentType;
+exports.UploadAcceptInvalid = require_EndpointFactory.UploadAcceptInvalid;
+exports.UploadContentTypeRefused = require_EndpointFactory.UploadContentTypeRefused;
+exports.UploadContentTypeUnresolved = require_EndpointFactory.UploadContentTypeUnresolved;
+exports.UploadEndpointBuilder = require_EndpointFactory.UploadEndpointBuilder;
+exports.UploadExpiryInvalid = require_EndpointFactory.UploadExpiryInvalid;
+exports.UploadMaxSizeInvalid = require_EndpointFactory.UploadMaxSizeInvalid;
+exports.createApiGatewayCookies = require_readRequestBody.createApiGatewayCookies;
+exports.createApiGatewayHeaders = require_readRequestBody.createApiGatewayHeaders;
 exports.createAuthorizer = require_EndpointFactory.createAuthorizer;
-exports.createHonoCookies = require_lazyAccessors.createHonoCookies;
-exports.createHonoHeaders = require_lazyAccessors.createHonoHeaders;
-exports.createNoopCookies = require_lazyAccessors.createNoopCookies;
-exports.createNoopHeaders = require_lazyAccessors.createNoopHeaders;
+exports.createHonoCookies = require_readRequestBody.createHonoCookies;
+exports.createHonoHeaders = require_readRequestBody.createHonoHeaders;
+exports.createNoopCookies = require_readRequestBody.createNoopCookies;
+exports.createNoopHeaders = require_readRequestBody.createNoopHeaders;
 exports.defaultEnvParser = require_surfaceEnv.defaultEnvParser;
 exports.envParserFor = require_surfaceEnv.envParserFor;
 exports.getSecurityScheme = require_EndpointFactory.getSecurityScheme;
 exports.isBuiltInSecurityScheme = require_EndpointFactory.isBuiltInSecurityScheme;
-exports.publishConstructEvents = require_lazyAccessors.publishConstructEvents;
+exports.publishConstructEvents = require_functions.publishConstructEvents;
+exports.readRequestBody = require_readRequestBody.readRequestBody;