@geekmidas/constructs 10.0.0-alpha.45 → 10.0.0-alpha.47

package/dist/encryption.cjs

@@ -0,0 +1,96 @@
+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.
+*/
+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.`));
+		if (scheme === _geekmidas_manifest.KMS_SCHEME) {
+			const { kmsCipher } = await Promise.resolve().then(() => require("./kms-B-Hm3d5r.cjs"));
+			return kmsCipher(this.id, url);
+		}
+		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.formatKeyring = require_cipher.formatKeyring;
+exports.generateKeyring = require_cipher.generateKeyring;
+exports.keyringCipher = require_cipher.keyringCipher;
+exports.parseKeyring = require_cipher.parseKeyring;
+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":["canonicalId","provideKey","serviceKey","keyringCipher","KMS_SCHEME","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\tkeyringCipher,\n\tLOCAL_SCHEME,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport type { Cipher } 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\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\tif (scheme === KMS_SCHEME) {\n\t\t\t// Loaded only here, so a project that never deploys to AWS never\n\t\t\t// needs `@aws-sdk/client-kms` installed.\n\t\t\tconst { kmsCipher } = await import('./encryption/kms');\n\t\t\treturn kmsCipher(this.id, url);\n\t\t}\n\n\t\tthrow new UnknownEncryptionScheme(this.id, scheme);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,IAAa,aAAb,MAEA;CACC;CACA;;;;;CAMA;;;;;CAMA;CAEA,YAAY,IAA0B;EACrC,MAAM,aAAA,GAAYA,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;EAGD,IAAI,WAAWC,oBAAAA,YAAY;GAG1B,MAAM,EAAE,cAAc,MAAA,QAAA,QAAA,CAAA,CAAA,WAAA,QAAM,oBAAA,CAAA;GAC5B,OAAO,UAAU,KAAK,IAAI,GAAG;EAC9B;EAEA,MAAM,IAAIC,eAAAA,wBAAwB,KAAK,IAAI,MAAM;CAClD;AACD"}

package/dist/encryption.d.cts

@@ -0,0 +1,117 @@
+import { n as Construct } from "./construct-interface-B1AfqRl4.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+//#region src/encryption/cipher.d.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`.
+ */
+/** What a handler is given: `services.pii.encrypt(…)` and the rest. */
+interface Cipher {
+  /** Plaintext in, a self-describing ciphertext string out. */
+  encrypt(plaintext: string): Promise<string>;
+  /** Opens any ciphertext this construct wrote, under whichever key wrote it. */
+  decrypt(ciphertext: string): Promise<string>;
+  /**
+   * A blind index: the same value always gives the same string, so an
+   * encrypted column can still be looked up by an indexed column beside it.
+   *
+   * Deterministic on purpose, which is also why its key never rotates — a
+   * rotated index key would make every stored index miss.
+   */
+  index(value: string): Promise<string>;
+  /**
+   * The same plaintext under the current key — what a sweep runs over a
+   * column before an old key is retired. Unchanged when it is already current.
+   */
+  reencrypt(ciphertext: string): Promise<string>;
+}
+export declare class EncryptionUrlInvalid extends Error {
+  readonly construct: string;
+  readonly reason: string;
+  constructor(construct: string, reason: string);
+}
+export declare class UnknownEncryptionScheme extends Error {
+  readonly construct: string;
+  readonly scheme: string;
+  constructor(construct: string, scheme: string);
+}
+export declare class CiphertextMalformed extends Error {
+  readonly construct: string;
+  constructor(construct: string);
+}
+export declare class EncryptionKeyRetired extends Error {
+  readonly construct: string;
+  readonly keyId: string;
+  constructor(construct: string, keyId: string);
+}
+export declare class CiphertextNotAuthentic extends Error {
+  readonly construct: string;
+  constructor(construct: string);
+}
+export declare class CurrentKeyCannotRetire extends Error {
+  readonly construct: string;
+  readonly keyId: string;
+  constructor(construct: string, keyId: string);
+}
+/** A local keyring: newest key first, and the index key that never rotates. */
+interface Keyring {
+  keys: {
+    id: string;
+    key: Buffer;
+  }[];
+  index: Buffer;
+}
+/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */
+export declare function parseKeyring(construct: string, url: string): Keyring;
+export declare function formatKeyring(keyring: Keyring): string;
+/** A keyring with one fresh key, `k1`, and a fresh index key. */
+export declare function generateKeyring(): string;
+/**
+ * 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}.
+ */
+export declare function rotateKeyring(construct: string, url: string): string;
+/** The keyring without `keyId`, which must not be the current key. */
+export declare function retireKey(construct: string, url: string, keyId: string): string;
+/** Says, once per key per process, that a value is still under an old key. */
+type StaleKeyReporter = (keyId: string, current: string) => void;
+/** The `aes256gcm://` cipher: a keyring held in process. */
+export declare function keyringCipher(construct: string, url: string, onStaleKey?: StaleKeyReporter): Cipher;
+//#endregion
+//#region src/encryption.d.ts
+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, Keyring };
+//# sourceMappingURL=encryption.d.cts.map

package/dist/encryption.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.cts","names":[],"sources":["../src/encryption/cipher.ts","../src/encryption.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;UAyBiB;;EAEhB,QAAQ,oBAAoB;;EAE5B,QAAQ,qBAAqB;;;;;;;;EAQ7B,MAAM,gBAAgB;;;;;EAKtB,UAAU,qBAAqB;;qBAanB,6BAA6B;WAE/B;WACA;EAFV,YACU,mBACA;;qBASE,gCAAgC;WAElC;WACA;EAFV,YACU,mBACA;;qBASE,4BAA4B;WACnB;EAArB,YAAqB;;qBAQT,6BAA6B;WAE/B;WACA;EAFV,YACU,mBACA;;qBASE,+BAA+B;WACtB;EAArB,YAAqB;;qBAQT,+BAA+B;WAEjC;WACA;EAFV,YACU,mBACA;;;UAuEM;EAChB;IAAQ;IAAY,KAAK;;EACzB,OAAO;;;wBAIQ,aAAa,mBAAmB,cAAc;wBAqC9C,cAAc,SAAS;;wBAQvB;;;;;;;wBAaA,cAAc,mBAAmB;;wBAYjC,UACf,mBACA,aACA;;KAiBW,oBAAoB,eAAe;;wBAG/B,cACf,mBACA,aACA,aAAY,mBACV;;;qBC3NU,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,117 @@
+import { n as Construct } from "./construct-interface-DluK3_da.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+//#region src/encryption/cipher.d.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`.
+ */
+/** What a handler is given: `services.pii.encrypt(…)` and the rest. */
+interface Cipher {
+  /** Plaintext in, a self-describing ciphertext string out. */
+  encrypt(plaintext: string): Promise<string>;
+  /** Opens any ciphertext this construct wrote, under whichever key wrote it. */
+  decrypt(ciphertext: string): Promise<string>;
+  /**
+   * A blind index: the same value always gives the same string, so an
+   * encrypted column can still be looked up by an indexed column beside it.
+   *
+   * Deterministic on purpose, which is also why its key never rotates — a
+   * rotated index key would make every stored index miss.
+   */
+  index(value: string): Promise<string>;
+  /**
+   * The same plaintext under the current key — what a sweep runs over a
+   * column before an old key is retired. Unchanged when it is already current.
+   */
+  reencrypt(ciphertext: string): Promise<string>;
+}
+export declare class EncryptionUrlInvalid extends Error {
+  readonly construct: string;
+  readonly reason: string;
+  constructor(construct: string, reason: string);
+}
+export declare class UnknownEncryptionScheme extends Error {
+  readonly construct: string;
+  readonly scheme: string;
+  constructor(construct: string, scheme: string);
+}
+export declare class CiphertextMalformed extends Error {
+  readonly construct: string;
+  constructor(construct: string);
+}
+export declare class EncryptionKeyRetired extends Error {
+  readonly construct: string;
+  readonly keyId: string;
+  constructor(construct: string, keyId: string);
+}
+export declare class CiphertextNotAuthentic extends Error {
+  readonly construct: string;
+  constructor(construct: string);
+}
+export declare class CurrentKeyCannotRetire extends Error {
+  readonly construct: string;
+  readonly keyId: string;
+  constructor(construct: string, keyId: string);
+}
+/** A local keyring: newest key first, and the index key that never rotates. */
+interface Keyring {
+  keys: {
+    id: string;
+    key: Buffer;
+  }[];
+  index: Buffer;
+}
+/** Parse `aes256gcm://local?keys=k2.<key>,k1.<key>&index=<key>`. */
+export declare function parseKeyring(construct: string, url: string): Keyring;
+export declare function formatKeyring(keyring: Keyring): string;
+/** A keyring with one fresh key, `k1`, and a fresh index key. */
+export declare function generateKeyring(): string;
+/**
+ * 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}.
+ */
+export declare function rotateKeyring(construct: string, url: string): string;
+/** The keyring without `keyId`, which must not be the current key. */
+export declare function retireKey(construct: string, url: string, keyId: string): string;
+/** Says, once per key per process, that a value is still under an old key. */
+type StaleKeyReporter = (keyId: string, current: string) => void;
+/** The `aes256gcm://` cipher: a keyring held in process. */
+export declare function keyringCipher(construct: string, url: string, onStaleKey?: StaleKeyReporter): Cipher;
+//#endregion
+//#region src/encryption.d.ts
+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, Keyring };
+//# sourceMappingURL=encryption.d.mts.map

package/dist/encryption.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.mts","names":[],"sources":["../src/encryption/cipher.ts","../src/encryption.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;UAyBiB;;EAEhB,QAAQ,oBAAoB;;EAE5B,QAAQ,qBAAqB;;;;;;;;EAQ7B,MAAM,gBAAgB;;;;;EAKtB,UAAU,qBAAqB;;qBAanB,6BAA6B;WAE/B;WACA;EAFV,YACU,mBACA;;qBASE,gCAAgC;WAElC;WACA;EAFV,YACU,mBACA;;qBASE,4BAA4B;WACnB;EAArB,YAAqB;;qBAQT,6BAA6B;WAE/B;WACA;EAFV,YACU,mBACA;;qBASE,+BAA+B;WACtB;EAArB,YAAqB;;qBAQT,+BAA+B;WAEjC;WACA;EAFV,YACU,mBACA;;;UAuEM;EAChB;IAAQ;IAAY,KAAK;;EACzB,OAAO;;;wBAIQ,aAAa,mBAAmB,cAAc;wBAqC9C,cAAc,SAAS;;wBAQvB;;;;;;;wBAaA,cAAc,mBAAmB;;wBAYjC,UACf,mBACA,aACA;;KAiBW,oBAAoB,eAAe;;wBAG/B,cACf,mBACA,aACA,aAAY,mBACV;;;qBC3NU,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,83 @@
+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.
+*/
+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.`));
+		if (scheme === KMS_SCHEME) {
+			const { kmsCipher } = await import("./kms-BdUlMJEZ.mjs");
+			return kmsCipher(this.id, url);
+		}
+		throw new UnknownEncryptionScheme(this.id, scheme);
+	}
+};
+//#endregion
+export { CiphertextMalformed, CiphertextNotAuthentic, CurrentKeyCannotRetire, Encryption, EncryptionKeyRetired, EncryptionUrlInvalid, UnknownEncryptionScheme, formatKeyring, generateKeyring, keyringCipher, parseKeyring, 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\tkeyringCipher,\n\tLOCAL_SCHEME,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport type { Cipher } 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\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\tif (scheme === KMS_SCHEME) {\n\t\t\t// Loaded only here, so a project that never deploys to AWS never\n\t\t\t// needs `@aws-sdk/client-kms` installed.\n\t\t\tconst { kmsCipher } = await import('./encryption/kms');\n\t\t\treturn kmsCipher(this.id, url);\n\t\t}\n\n\t\tthrow new UnknownEncryptionScheme(this.id, scheme);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,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;EAGD,IAAI,WAAW,YAAY;GAG1B,MAAM,EAAE,cAAc,MAAM,OAAO;GACnC,OAAO,UAAU,KAAK,IAAI,GAAG;EAC9B;EAEA,MAAM,IAAI,wBAAwB,KAAK,IAAI,MAAM;CAClD;AACD"}

package/dist/kms-B-Hm3d5r.cjs

@@ -0,0 +1,85 @@
+const require_cipher = require("./cipher-CVxfwLjk.cjs");
+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 module, loaded only when a URL says `kms://`, so a project that
+* never deploys to AWS never needs `@aws-sdk/client-kms` installed.
+*/
+/** 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;
+		}
+	};
+}
+//#endregion
+exports.kmsCipher = kmsCipher;
+
+//# sourceMappingURL=kms-B-Hm3d5r.cjs.map

package/dist/kms-B-Hm3d5r.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-B-Hm3d5r.cjs","names":["EncryptionUrlInvalid","KMSClient","associatedData","GenerateDataKeyCommand","seal","formatCiphertext","parseCiphertext","CiphertextNotAuthentic","DecryptCommand","open","GenerateMacCommand"],"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 module, loaded only when a URL says `kms://`, so a project that\n * never deploys to AWS never needs `@aws-sdk/client-kms` installed.\n */\n\nimport {\n\tDecryptCommand,\n\tGenerateDataKeyCommand,\n\tGenerateMacCommand,\n\tKMSClient,\n} from '@aws-sdk/client-kms';\nimport {\n\tassociatedData,\n\ttype Cipher,\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsCA,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"}

package/dist/kms-BdUlMJEZ.mjs

@@ -0,0 +1,85 @@
+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 { 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 module, loaded only when a URL says `kms://`, so a project that
+* never deploys to AWS never needs `@aws-sdk/client-kms` installed.
+*/
+/** 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;
+		}
+	};
+}
+//#endregion
+export { kmsCipher };
+
+//# sourceMappingURL=kms-BdUlMJEZ.mjs.map

package/dist/kms-BdUlMJEZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-BdUlMJEZ.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 module, loaded only when a URL says `kms://`, so a project that\n * never deploys to AWS never needs `@aws-sdk/client-kms` installed.\n */\n\nimport {\n\tDecryptCommand,\n\tGenerateDataKeyCommand,\n\tGenerateMacCommand,\n\tKMSClient,\n} from '@aws-sdk/client-kms';\nimport {\n\tassociatedData,\n\ttype Cipher,\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsCA,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"}