@geekmidas/constructs 10.0.0-alpha.116 → 10.0.0-alpha.118

package/dist/encryption.cjs

@@ -34,6 +34,25 @@ let _geekmidas_manifest = require("@geekmidas/manifest");
 * `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;
@@ -71,10 +90,9 @@ var Encryption = class {
 		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);
-		}
+		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);
 	}
 };
@@ -86,10 +104,12 @@ 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;
 

package/dist/encryption.cjs.map

@@ -1 +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"}
+{"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

@@ -1,99 +1,19 @@
 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/cipher.d.ts
+//#region src/encryption.d.ts
+/** Make a cipher available for its scheme. Idempotent. */
+export declare function registerCipherDriver(driver: CipherDriver): void;
 /**
- * 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`.
+ * 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.
  */
-/** 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 {
+export declare class UnregisteredEncryptionScheme 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>;
@@ -113,5 +33,5 @@ export declare class Encryption<TName extends string = string> implements Constr
   private open;
 }
 //#endregion
-export type { Cipher, Keyring };
+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

@@ -1 +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"}
+{"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

@@ -1,99 +1,19 @@
 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/cipher.d.ts
+//#region src/encryption.d.ts
+/** Make a cipher available for its scheme. Idempotent. */
+export declare function registerCipherDriver(driver: CipherDriver): void;
 /**
- * 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`.
+ * 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.
  */
-/** 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 {
+export declare class UnregisteredEncryptionScheme 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>;
@@ -113,5 +33,5 @@ export declare class Encryption<TName extends string = string> implements Constr
   private open;
 }
 //#endregion
-export type { Cipher, Keyring };
+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

@@ -1 +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"}
+{"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

@@ -33,6 +33,25 @@ import { KMS_SCHEME, canonicalId, provideKey, serviceKey } from "@geekmidas/mani
 * `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;
@@ -70,14 +89,13 @@ var Encryption = class {
 		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);
-		}
+		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, formatKeyring, generateKeyring, keyringCipher, parseKeyring, retireKey, rotateKeyring };
+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

@@ -1 +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"}
+{"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/{kysely-D0bpzgPs.d.cts → kysely-BHYV-WC-.d.cts}

@@ -21,7 +21,7 @@ declare function closeDatabasePools(): Promise<void>;
  * straight through, so anything Kysely adds later arrives without being
  * tracked here.
  */
-interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
+interface KyselyDatabaseBaseOptions extends Omit<KyselyConfig, 'dialect'> {
   /**
    * The schema, pinned on both roles' `search_path`.
    *
@@ -39,16 +39,15 @@ interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
    */
   roles?: boolean;
   /**
-   * The Postgres major version to provision.
+   * Extensions to create in this database, as the cluster master, before the
+   * first migration — for the ones the owner role a migration runs as may not
+   * create (PostGIS is not a trusted extension). They are created in
+   * `public`, which joins this database's roles' `search_path`, so their
+   * types resolve unqualified.
    *
-   * Declared here so one statement reaches both targets. It was previously
-   * set in two unrelated places — a container tag locally, nothing at all on
-   * AWS (so Aurora chose) — which is how local came to run 18 while deployed
-   * ran 17.7 with nothing recording the difference.
-   *
-   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   * Only attempted: the image has to ship them.
    */
-  version?: PostgresVersion;
+  extensions?: readonly string[];
   /**
    * End each query run inside a request with a comment naming what ran it —
    * `/*operation='POST /orders',request_id='…'*\/` — so `pg_stat_activity`
@@ -58,6 +57,48 @@ interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
    */
   queryTags?: boolean;
 }
+/**
+ * Which Postgres the database runs: a major on the stock image, or an image
+ * the project names. One or the other, never both — an image's tag already
+ * says its major, and a second statement of it is one that can disagree.
+ */
+type PostgresRuntime = {
+  /**
+   * The Postgres major version to provision, on the stock image.
+   *
+   * Declared here so one statement reaches every target. It was
+   * previously set in two unrelated places — a container tag locally,
+   * nothing at all on AWS (so Aurora chose) — which is how local came to
+   * run 18 while deployed ran 17.7 with nothing recording the difference.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+  image?: never;
+} | {
+  /**
+   * The container image to run, wherever a target runs one (local,
+   * Dokploy), in place of `postgres:<version>`.
+   *
+   * Yours to choose and used as written: its tag is the major, and it
+   * should ship every extension in `extensions`. AWS runs RDS, ignores
+   * it, and provisions {@link DEFAULT_POSTGRES_VERSION}.
+   *
+   * ```ts
+   * new KyselyDatabase<GeoDB>('Geo', {
+   *   image: 'postgis/postgis:18-3.6-alpine',
+   *   extensions: ['postgis'],
+   * });
+   * ```
+   */
+  image: string;
+  version?: never;
+};
+/**
+ * Everything Kysely takes, plus what this construct declares — including
+ * which Postgres it runs, as a version or an image.
+ */
+type KyselyDatabaseOptions = KyselyDatabaseBaseOptions & PostgresRuntime;
 /** What makes a construct derived rather than a database in its own right. */
 interface DerivedFrom {
   kind: 'database-reader' | 'database-schema';
@@ -82,7 +123,7 @@ declare class KyselyDatabase<DB = unknown, TName extends string = string> implem
   private readonly config;
   private readonly schemaName;
   private readonly roles;
-  private readonly version;
+  private readonly runtime;
   private readonly derivedFrom?;
   constructor(id: ConstructName<TName>, options?: KyselyDatabaseOptions, derivedFrom?: DerivedFrom);
   declare(): Declaration[];
@@ -171,5 +212,5 @@ declare class KyselyDatabase<DB = unknown, TName extends string = string> implem
  */
 type ReadOnlyDatabase<DB, TName extends string> = Omit<KyselyDatabase<DB, TName>, 'reader' | 'cache' | 'schema'>;
 //#endregion
-export { closeDatabasePools as i, KyselyDatabaseOptions as n, ReadOnlyDatabase as r, KyselyDatabase as t };
-//# sourceMappingURL=kysely-D0bpzgPs.d.cts.map
+export { closeDatabasePools as a, ReadOnlyDatabase as i, KyselyDatabaseOptions as n, PostgresRuntime as r, KyselyDatabase as t };
+//# sourceMappingURL=kysely-BHYV-WC-.d.cts.map

package/dist/kysely-BHYV-WC-.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-BHYV-WC-.d.cts","names":[],"sources":["../src/database/pool.ts","../src/database/kysely.ts"],"mappings":";;;;;;;;;;;iBAwGsB,sBAAsB;;;;;;;;;;;;UChElC,kCAAkC,KAAK;;;;;;;;EAQhD;;;;;;;;EAQA;;;;;;;;;;EAUA;;;;;;;;EAQA;;;;;;;KAQW;;;;;;;;;;;EAYT,UAAU;EACV;;;;;;;;;;;;;;;;;EAkBA;EACA;;;;;;KAOS,wBAAwB,4BAA4B;;UAGtD;EACT;EACA;EACA;;;;;;;;;cAUY,eAAe,cAAc,0CAC9B,UAAU,OAAO,OAAO;mBAiBjB;WAfT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,OAAO;;;;;mBAMrC;mBACA;mBACA;mBACA;mBACA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,uBAC1B,cAAc;EA2Bf,WAAW;;;;;;;;;;;;;EAyDX,UAAU,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;EAyBlC,MAAM,2BAA2B,cAChC,KAAI,cAAc,SAClB;IAAW;MACT,MAAM;;;;;;;;;EAeT,OAAO,UAAU,wBAChB,IAAI,cAAc,UAClB,UAAS,wBACP,eAAe,UAAU;;;;;;;;;;;;;MAoBxB,SAAS,WAAW,aAAa,eAAe,OAAO;;;;;;;;;MAgBvD,gBAAgB,KAAK;UAiBX;;;;;;;;;;;;;;;;;;;KAuCH,iBAAiB,IAAI,wBAAwB,KACxD,eAAe,IAAI"}

package/dist/{kysely-DKwnl0nf.d.mts → kysely-CAW3QSqp.d.mts}

@@ -21,7 +21,7 @@ declare function closeDatabasePools(): Promise<void>;
  * straight through, so anything Kysely adds later arrives without being
  * tracked here.
  */
-interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
+interface KyselyDatabaseBaseOptions extends Omit<KyselyConfig, 'dialect'> {
   /**
    * The schema, pinned on both roles' `search_path`.
    *
@@ -39,16 +39,15 @@ interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
    */
   roles?: boolean;
   /**
-   * The Postgres major version to provision.
+   * Extensions to create in this database, as the cluster master, before the
+   * first migration — for the ones the owner role a migration runs as may not
+   * create (PostGIS is not a trusted extension). They are created in
+   * `public`, which joins this database's roles' `search_path`, so their
+   * types resolve unqualified.
    *
-   * Declared here so one statement reaches both targets. It was previously
-   * set in two unrelated places — a container tag locally, nothing at all on
-   * AWS (so Aurora chose) — which is how local came to run 18 while deployed
-   * ran 17.7 with nothing recording the difference.
-   *
-   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   * Only attempted: the image has to ship them.
    */
-  version?: PostgresVersion;
+  extensions?: readonly string[];
   /**
    * End each query run inside a request with a comment naming what ran it —
    * `/*operation='POST /orders',request_id='…'*\/` — so `pg_stat_activity`
@@ -58,6 +57,48 @@ interface KyselyDatabaseOptions extends Omit<KyselyConfig, 'dialect'> {
    */
   queryTags?: boolean;
 }
+/**
+ * Which Postgres the database runs: a major on the stock image, or an image
+ * the project names. One or the other, never both — an image's tag already
+ * says its major, and a second statement of it is one that can disagree.
+ */
+type PostgresRuntime = {
+  /**
+   * The Postgres major version to provision, on the stock image.
+   *
+   * Declared here so one statement reaches every target. It was
+   * previously set in two unrelated places — a container tag locally,
+   * nothing at all on AWS (so Aurora chose) — which is how local came to
+   * run 18 while deployed ran 17.7 with nothing recording the difference.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+  image?: never;
+} | {
+  /**
+   * The container image to run, wherever a target runs one (local,
+   * Dokploy), in place of `postgres:<version>`.
+   *
+   * Yours to choose and used as written: its tag is the major, and it
+   * should ship every extension in `extensions`. AWS runs RDS, ignores
+   * it, and provisions {@link DEFAULT_POSTGRES_VERSION}.
+   *
+   * ```ts
+   * new KyselyDatabase<GeoDB>('Geo', {
+   *   image: 'postgis/postgis:18-3.6-alpine',
+   *   extensions: ['postgis'],
+   * });
+   * ```
+   */
+  image: string;
+  version?: never;
+};
+/**
+ * Everything Kysely takes, plus what this construct declares — including
+ * which Postgres it runs, as a version or an image.
+ */
+type KyselyDatabaseOptions = KyselyDatabaseBaseOptions & PostgresRuntime;
 /** What makes a construct derived rather than a database in its own right. */
 interface DerivedFrom {
   kind: 'database-reader' | 'database-schema';
@@ -82,7 +123,7 @@ declare class KyselyDatabase<DB = unknown, TName extends string = string> implem
   private readonly config;
   private readonly schemaName;
   private readonly roles;
-  private readonly version;
+  private readonly runtime;
   private readonly derivedFrom?;
   constructor(id: ConstructName<TName>, options?: KyselyDatabaseOptions, derivedFrom?: DerivedFrom);
   declare(): Declaration[];
@@ -171,5 +212,5 @@ declare class KyselyDatabase<DB = unknown, TName extends string = string> implem
  */
 type ReadOnlyDatabase<DB, TName extends string> = Omit<KyselyDatabase<DB, TName>, 'reader' | 'cache' | 'schema'>;
 //#endregion
-export { closeDatabasePools as i, KyselyDatabaseOptions as n, ReadOnlyDatabase as r, KyselyDatabase as t };
-//# sourceMappingURL=kysely-DKwnl0nf.d.mts.map
+export { closeDatabasePools as a, ReadOnlyDatabase as i, KyselyDatabaseOptions as n, PostgresRuntime as r, KyselyDatabase as t };
+//# sourceMappingURL=kysely-CAW3QSqp.d.mts.map

package/dist/kysely-CAW3QSqp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-CAW3QSqp.d.mts","names":[],"sources":["../src/database/pool.ts","../src/database/kysely.ts"],"mappings":";;;;;;;;;;;iBAwGsB,sBAAsB;;;;;;;;;;;;UChElC,kCAAkC,KAAK;;;;;;;;EAQhD;;;;;;;;EAQA;;;;;;;;;;EAUA;;;;;;;;EAQA;;;;;;;KAQW;;;;;;;;;;;EAYT,UAAU;EACV;;;;;;;;;;;;;;;;;EAkBA;EACA;;;;;;KAOS,wBAAwB,4BAA4B;;UAGtD;EACT;EACA;EACA;;;;;;;;;cAUY,eAAe,cAAc,0CAC9B,UAAU,OAAO,OAAO;mBAiBjB;WAfT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,OAAO;;;;;mBAMrC;mBACA;mBACA;mBACA;mBACA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,uBAC1B,cAAc;EA2Bf,WAAW;;;;;;;;;;;;;EAyDX,UAAU,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;EAyBlC,MAAM,2BAA2B,cAChC,KAAI,cAAc,SAClB;IAAW;MACT,MAAM;;;;;;;;;EAeT,OAAO,UAAU,wBAChB,IAAI,cAAc,UAClB,UAAS,wBACP,eAAe,UAAU;;;;;;;;;;;;;MAoBxB,SAAS,WAAW,aAAa,eAAe,OAAO;;;;;;;;;MAgBvD,gBAAgB,KAAK;UAiBX;;;;;;;;;;;;;;;;;;;KAuCH,iBAAiB,IAAI,wBAAwB,KACxD,eAAe,IAAI"}