@geekmidas/constructs 10.0.0-alpha.11 → 10.0.0-alpha.111

package/dist/email.cjs

@@ -1,9 +1,22 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_emailkit = require_chunk.__toESM(require("@geekmidas/emailkit"));
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_emailkit = require("@geekmidas/emailkit");
 //#region src/email.ts
+/**
+* `Email` — declared outbound mail.
+*
+* The same three-package meeting point as `ObjectStorage`: it implements the
+* construct contract, derives its env key through `@geekmidas/manifest`, and
+* hands back an `@geekmidas/emailkit` client. It names no provider — locally the
+* injected URL points at Mailpit, deployed it points at SES or whichever service
+* config selected.
+*
+* Where object storage needs a driver per provider, this needs none: mail is
+* delivered over SMTP whoever delivers it, so there is one client and one URL
+* shape, and the provider survives only as a host and a credential.
+*/
 var Email = class {
+	options;
 	id;
 	service;
 	/**
@@ -13,15 +26,15 @@ var Email = class {
 	keys;
 	constructor(id, options) {
 		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
 		this.keys = {
-			url: (0, __geekmidas_manifest.provideKey)(canonical, "url"),
-			from: (0, __geekmidas_manifest.provideKey)(canonical, "from")
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			from: (0, _geekmidas_manifest.provideKey)(canonical, "from")
 		};
 		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
-			register: (options$1) => this.connect(options$1)
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
+			register: (options) => this.connect(options)
 		};
 	}
 	declare() {
@@ -43,8 +56,8 @@ var Email = class {
 			url: get(this.keys.url).string(),
 			from: get(this.keys.from).string()
 		})).parse();
-		return (0, __geekmidas_emailkit.createEmailClient)({
-			smtp: (0, __geekmidas_emailkit.parseEmailUrl)(url),
+		return (0, _geekmidas_emailkit.createEmailClient)({
+			smtp: (0, _geekmidas_emailkit.parseEmailUrl)(url),
 			templates: this.options.templates,
 			defaults: {
 				from,
@@ -53,7 +66,7 @@ var Email = class {
 		});
 	}
 };
-
 //#endregion
 exports.Email = Email;
+
 //# sourceMappingURL=email.cjs.map

package/dist/email.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"email.cjs","names":["id: ConstructName<TName>","options: EmailOptions<TTemplates>","options"],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\n\t\t};\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 [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;;AAkDA,IAAa,QAAb,MAIA;CACC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;CAEjB,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,sCAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO;GACX,KAAK,qCAAW,WAAW,MAAM;GAIjC,MAAM,qCAAW,WAAW,OAAO;EACnC;AAGD,OAAK,UAAU;GACd,aAAa,qCAAW,UAAU;GAClC,UAAU,CAACC,cAAY,KAAK,QAAQA,UAAQ;EAC5C;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAK;EACzC,CACD;CACD;;;;;;;;CASD,MAAc,QAAQ,EACrB,WACwB,EAAoC;EAC5D,MAAM,EAAE,KAAK,MAAM,GAAG,UACpB,OAAO,CAAC,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,QAAQ;GAChC,MAAM,IAAI,KAAK,KAAK,KAAK,CAAC,QAAQ;EAClC,GAAE,CACF,OAAO;AAET,SAAO,4CAAkB;GACxB,MAAM,wCAAc,IAAI;GACxB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAS,IAAG,CAAE;GACjE;EACD,EAAC;CACF;AACD"}
+{"version":3,"file":"email.cjs","names":["canonicalId","provideKey","serviceKey","createEmailClient","parseEmailUrl"],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\n\t\t};\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 [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAkDA,IAAa,QAAb,MAIA;CAYmB;CAXlB;CACA;;;;;CAMA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,aAAA,GAAYA,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,MAAA,GAAKC,oBAAAA,WAAAA,CAAW,WAAW,KAAK;GAIhC,OAAA,GAAMA,oBAAAA,WAAAA,CAAW,WAAW,MAAM;EACnC;EAGA,KAAK,UAAU;GACd,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,SAAS;GACjC,WAAW,YAAY,KAAK,QAAQ,OAAO;EAC5C;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAI;EACzC,CACD;CACD;;;;;;;;CASA,MAAc,QAAQ,EACrB,aAC4D;EAC5D,MAAM,EAAE,KAAK,SAAS,UACpB,QAAQ,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,OAAO;GAC/B,MAAM,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,OAAO;EAClC,EAAE,CAAC,CACF,MAAM;EAER,QAAA,GAAOC,oBAAAA,kBAAAA,CAAkB;GACxB,OAAA,GAAMC,oBAAAA,cAAAA,CAAc,GAAG;GACvB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAQ,IAAI,CAAC;GACjE;EACD,CAAC;CACF;AACD"}

package/dist/email.d.cts

@@ -1,11 +1,9 @@
-import { Construct } from "./construct-interface-D9d4Gm4p.cjs";
+import { n as Construct } from "./construct-interface-B1AfqRl4.cjs";
 import { Service } from "@geekmidas/services";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
 import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
-
 //#region src/email.d.ts
-
-interface EmailOptions<TTemplates extends TemplateRecord> {
+export interface EmailOptions<TTemplates extends TemplateRecord> {
   /**
    * The React templates this app can send.
    *
@@ -24,7 +22,7 @@ interface EmailOptions<TTemplates extends TemplateRecord> {
    */
   replyTo?: string;
 }
-declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
+export declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
   private readonly options;
   readonly id: TName;
   readonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;
@@ -44,7 +42,5 @@ declare class Email<TName extends string = string, TTemplates extends TemplateRe
    */
   private connect;
 }
-//# sourceMappingURL=email.d.ts.map
 //#endregion
-export { Email, EmailOptions };
 //# sourceMappingURL=email.d.cts.map

package/dist/email.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.cts","names":[],"sources":["../src/email.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqD8B,UAvBb,YAuBa,CAAA,mBAvBmB,cAuBnB,CAAA,CAAA;EAAW;;;;;;;;EAYtB,SACsB,EA3B7B,UA2B6B;EAAU;;;AAb7B;;;;;;cAHT,wDAEO,iBAAiB,2BACxB,UAAU,OAAO,YAAY;;eAE5B;oBACK,QAAQ,aAAa,QAAQ,YAAY;;;;;;kBAStD,cAAc,iBACQ,aAAa;aAoB7B"}
+{"version":3,"file":"email.d.cts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;iBA8BiB,aAAa,mBAAmB;;;;;;;;;EAShD,WAAW;;;;;;;;EAQX;;qBAGY,MACZ,+BACA,mBAAmB,iBAAiB,2BACxB,UAAU,OAAO,YAAY;mBAavB;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,YAAY;;;;;mBAM1C;EAEjB,YACC,IAAI,cAAc,QACD,SAAS,aAAa;EAoBxC,WAAW;;;;;;;;UAiBG"}

package/dist/email.d.mts

@@ -1,11 +1,9 @@
-import { Construct } from "./construct-interface-g5GM5pwR.mjs";
+import { n as Construct } from "./construct-interface-ZvYQbivO.mjs";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
-import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
 import { Service } from "@geekmidas/services";
-
+import { EmailClient, TemplateRecord } from "@geekmidas/emailkit";
 //#region src/email.d.ts
-
-interface EmailOptions<TTemplates extends TemplateRecord> {
+export interface EmailOptions<TTemplates extends TemplateRecord> {
   /**
    * The React templates this app can send.
    *
@@ -24,7 +22,7 @@ interface EmailOptions<TTemplates extends TemplateRecord> {
    */
   replyTo?: string;
 }
-declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
+export declare class Email<TName extends string = string, TTemplates extends TemplateRecord = TemplateRecord> implements Construct<TName, EmailClient<TTemplates>> {
   private readonly options;
   readonly id: TName;
   readonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;
@@ -44,7 +42,5 @@ declare class Email<TName extends string = string, TTemplates extends TemplateRe
    */
   private connect;
 }
-//# sourceMappingURL=email.d.ts.map
 //#endregion
-export { Email, EmailOptions };
 //# sourceMappingURL=email.d.mts.map

package/dist/email.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.mts","names":[],"sources":["../src/email.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqD8B,UAvBb,YAuBa,CAAA,mBAvBmB,cAuBnB,CAAA,CAAA;EAAW;;;;;;;;EAYtB,SACsB,EA3B7B,UA2B6B;EAAU;;;AAb7B;;;;;;cAHT,wDAEO,iBAAiB,2BACxB,UAAU,OAAO,YAAY;;eAE5B;oBACK,QAAQ,aAAa,QAAQ,YAAY;;;;;;kBAStD,cAAc,iBACQ,aAAa;aAoB7B"}
+{"version":3,"file":"email.d.mts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;iBA8BiB,aAAa,mBAAmB;;;;;;;;;EAShD,WAAW;;;;;;;;EAQX;;qBAGY,MACZ,+BACA,mBAAmB,iBAAiB,2BACxB,UAAU,OAAO,YAAY;mBAavB;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,YAAY;;;;;mBAM1C;EAEjB,YACC,IAAI,cAAc,QACD,SAAS,aAAa;EAoBxC,WAAW;;;;;;;;UAiBG"}

package/dist/email.mjs

@@ -1,8 +1,21 @@
 import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
 import { createEmailClient, parseEmailUrl } from "@geekmidas/emailkit";
-
 //#region src/email.ts
+/**
+* `Email` — declared outbound mail.
+*
+* The same three-package meeting point as `ObjectStorage`: it implements the
+* construct contract, derives its env key through `@geekmidas/manifest`, and
+* hands back an `@geekmidas/emailkit` client. It names no provider — locally the
+* injected URL points at Mailpit, deployed it points at SES or whichever service
+* config selected.
+*
+* Where object storage needs a driver per provider, this needs none: mail is
+* delivered over SMTP whoever delivers it, so there is one client and one URL
+* shape, and the provider survives only as a host and a credential.
+*/
 var Email = class {
+	options;
 	id;
 	service;
 	/**
@@ -20,7 +33,7 @@ var Email = class {
 		};
 		this.service = {
 			serviceName: serviceKey(canonical),
-			register: (options$1) => this.connect(options$1)
+			register: (options) => this.connect(options)
 		};
 	}
 	declare() {
@@ -52,7 +65,7 @@ var Email = class {
 		});
 	}
 };
-
 //#endregion
 export { Email };
+
 //# sourceMappingURL=email.mjs.map

package/dist/email.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"email.mjs","names":["id: ConstructName<TName>","options: EmailOptions<TTemplates>","options"],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\n\t\t};\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 [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;AAkDA,IAAa,QAAb,MAIA;CACC,AAAS;CACT,AAAS;;;;;CAMT,AAAiB;CAEjB,YACCA,IACiBC,SAChB;EADgB;EAEjB,MAAM,YAAY,YAAY,GAAa;AAE3C,OAAK,KAAK;AACV,OAAK,OAAO;GACX,KAAK,WAAW,WAAW,MAAM;GAIjC,MAAM,WAAW,WAAW,OAAO;EACnC;AAGD,OAAK,UAAU;GACd,aAAa,WAAW,UAAU;GAClC,UAAU,CAACC,cAAY,KAAK,QAAQA,UAAQ;EAC5C;CACD;CAED,UAAyB;AACxB,SAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAK;EACzC,CACD;CACD;;;;;;;;CASD,MAAc,QAAQ,EACrB,WACwB,EAAoC;EAC5D,MAAM,EAAE,KAAK,MAAM,GAAG,UACpB,OAAO,CAAC,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,IAAI,CAAC,QAAQ;GAChC,MAAM,IAAI,KAAK,KAAK,KAAK,CAAC,QAAQ;EAClC,GAAE,CACF,OAAO;AAET,SAAO,kBAAkB;GACxB,MAAM,cAAc,IAAI;GACxB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAS,IAAG,CAAE;GACjE;EACD,EAAC;CACF;AACD"}
+{"version":3,"file":"email.mjs","names":[],"sources":["../src/email.ts"],"sourcesContent":["/**\n * `Email` — declared outbound mail.\n *\n * The same three-package meeting point as `ObjectStorage`: it implements the\n * construct contract, derives its env key through `@geekmidas/manifest`, and\n * hands back an `@geekmidas/emailkit` client. It names no provider — locally the\n * injected URL points at Mailpit, deployed it points at SES or whichever service\n * config selected.\n *\n * Where object storage needs a driver per provider, this needs none: mail is\n * delivered over SMTP whoever delivers it, so there is one client and one URL\n * shape, and the provider survives only as a host and a credential.\n */\n\nimport {\n\tcreateEmailClient,\n\ttype EmailClient,\n\tparseEmailUrl,\n\ttype TemplateRecord,\n} from '@geekmidas/emailkit';\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\n\nexport interface EmailOptions<TTemplates extends TemplateRecord> {\n\t/**\n\t * The React templates this app can send.\n\t *\n\t * Structural — they are code, they ship with the handler, and which ones\n\t * exist cannot differ between stages. They are also what types\n\t * `sendTemplate`, so passing them here is what makes the client's call sites\n\t * checkable.\n\t */\n\ttemplates: TTemplates;\n\t/**\n\t * A reply-to address for every send.\n\t *\n\t * `from` is deliberately absent: it belongs to the verified sending domain,\n\t * which is `myapp.test` locally and the real domain deployed, so it arrives\n\t * as stage config rather than being written here.\n\t */\n\treplyTo?: string;\n}\n\nexport class Email<\n\tTName extends string = string,\n\tTTemplates extends TemplateRecord = TemplateRecord,\n> implements Construct<TName, EmailClient<TTemplates>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, EmailClient<TTemplates>>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * build publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly keys: { url: string; from: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: EmailOptions<TTemplates>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\t// The sending identity travels with the URL rather than being a second\n\t\t\t// construct option, for the same reason the URL does: it is the one\n\t\t\t// thing about mail that differs per stage.\n\t\t\tfrom: provideKey(canonical, 'from'),\n\t\t};\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 [\n\t\t\t{\n\t\t\t\tkind: 'email',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.url, this.keys.from],\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds the client from the URL the adapter supplied.\n\t *\n\t * No provider branch and no driver lookup — `parseEmailUrl` turns any of\n\t * Mailpit, SES, or Resend into the same transport config, which is the whole\n\t * reason the scheme is always `smtp://`.\n\t */\n\tprivate async connect({\n\t\tenvParser,\n\t}: ServiceRegisterOptions): Promise<EmailClient<TTemplates>> {\n\t\tconst { url, from } = envParser\n\t\t\t.create((get) => ({\n\t\t\t\turl: get(this.keys.url).string(),\n\t\t\t\tfrom: get(this.keys.from).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\treturn createEmailClient({\n\t\t\tsmtp: parseEmailUrl(url),\n\t\t\ttemplates: this.options.templates,\n\t\t\tdefaults: {\n\t\t\t\tfrom,\n\t\t\t\t...(this.options.replyTo ? { replyTo: this.options.replyTo } : {}),\n\t\t\t},\n\t\t});\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkDA,IAAa,QAAb,MAIA;CAYmB;CAXlB;CACA;;;;;CAMA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,KAAK,WAAW,WAAW,KAAK;GAIhC,MAAM,WAAW,WAAW,MAAM;EACnC;EAGA,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,YAAY,KAAK,QAAQ,OAAO;EAC5C;CACD;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,IAAI;EACzC,CACD;CACD;;;;;;;;CASA,MAAc,QAAQ,EACrB,aAC4D;EAC5D,MAAM,EAAE,KAAK,SAAS,UACpB,QAAQ,SAAS;GACjB,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,OAAO;GAC/B,MAAM,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,OAAO;EAClC,EAAE,CAAC,CACF,MAAM;EAER,OAAO,kBAAkB;GACxB,MAAM,cAAc,GAAG;GACvB,WAAW,KAAK,QAAQ;GACxB,UAAU;IACT;IACA,GAAI,KAAK,QAAQ,UAAU,EAAE,SAAS,KAAK,QAAQ,QAAQ,IAAI,CAAC;GACjE;EACD,CAAC;CACF;AACD"}

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