@geekmidas/constructs 10.0.0-alpha.1 → 10.0.0-alpha.100

package/dist/encryption.mjs

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

package/dist/encryption.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.mjs","names":[],"sources":["../src/encryption.ts"],"sourcesContent":["/**\n * `Encryption` — a key that encrypts what the application stores.\n *\n * ```ts\n * export const pii = new Encryption('Pii');\n *\n * // an endpoint that `.dependsOn([pii])`\n * const email = await services.pii.encrypt(body.email);\n * const emailIndex = await services.pii.index(body.email);\n * await db.insertInto('users').values({ email, emailIndex }).execute();\n *\n * // and to find them again, without decrypting a column\n * db.selectFrom('users').where('emailIndex', '=', await services.pii.index(q));\n * ```\n *\n * The app names no cipher and holds no key. The construct provides one URL,\n * `<ID>_URL`, and its scheme picks the backend the way a queue's connection\n * string picks its broker:\n *\n * - **AWS** — `kms://`: envelope encryption under a KMS key that rotates\n *   yearly, and a KMS HMAC key for the index. Only a function that depends on\n *   the construct is granted either key.\n * - **Server, local, tests** — `aes256gcm://`: a keyring the process holds.\n *   Derived locally, so `gkm dev` and `gkm test` need nothing set; generated\n *   into a server stage's secrets on its first deploy, and rotated there with\n *   `gkm encryption:rotate`.\n *\n * Every ciphertext names the key that wrote it, so a rotated key still opens\n * what it wrote. Retiring one is explicit — `reencrypt` the column, then\n * `gkm encryption:retire` — and a value still under an old key says so when it\n * is decrypted, once per key per process.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tKMS_SCHEME,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { Construct } from './construct-interface';\nimport {\n\ttype Cipher,\n\tkeyringCipher,\n\tLOCAL_SCHEME,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport type { Cipher } from './encryption/cipher';\nexport {\n\tCiphertextMalformed,\n\tCiphertextNotAuthentic,\n\tCurrentKeyCannotRetire,\n\tEncryptionKeyRetired,\n\tEncryptionUrlInvalid,\n\tformatKeyring,\n\tgenerateKeyring,\n\ttype Keyring,\n\tkeyringCipher,\n\tparseKeyring,\n\tretireKey,\n\trotateKeyring,\n\tUnknownEncryptionScheme,\n} from './encryption/cipher';\n\nexport class Encryption<TName extends string = string>\n\timplements Construct<TName, Cipher>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Cipher>;\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the key the\n\t * target publishes and the key the client reads cannot drift.\n\t */\n\tprivate readonly key: string;\n\n\t/**\n\t * One cipher per process, held as the promise: a keyring is parsed once and\n\t * a KMS client is built once, however many handlers register it at once.\n\t */\n\tprivate cipher?: Promise<Cipher>;\n\n\tconstructor(id: ConstructName<TName>) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.key = provideKey(canonical, 'url');\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (options) => this.connect(options),\n\t\t};\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [{ kind: 'encryption', id: this.id, provides: [this.key] }];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tthis.cipher ??= this.open(options);\n\t\treturn this.cipher;\n\t}\n\n\tprivate async open(options: ServiceRegisterOptions): Promise<Cipher> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.key).string() }))\n\t\t\t.parse();\n\t\tconst scheme = url.slice(0, url.indexOf(':') + 1);\n\n\t\tif (scheme === LOCAL_SCHEME) {\n\t\t\treturn keyringCipher(this.id, url, (stale, current) =>\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`${this.id} decrypted a value still under '${stale}' (current: '${current}'). reencrypt it, and retire '${stale}' once nothing is left under it.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tif (scheme === KMS_SCHEME) {\n\t\t\t// Loaded only here, so a project that never deploys to AWS never\n\t\t\t// needs `@aws-sdk/client-kms` installed.\n\t\t\tconst { kmsCipher } = await import('./encryption/kms');\n\t\t\treturn kmsCipher(this.id, url);\n\t\t}\n\n\t\tthrow new UnknownEncryptionScheme(this.id, scheme);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,IAAa,aAAb,MAEA;CACC;CACA;;;;;CAMA;;;;;CAMA;CAEA,YAAY,IAA0B;EACrC,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,MAAM,WAAW,WAAW,KAAK;EAGtC,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,YAAY,KAAK,QAAQ,OAAO;EAC5C;CACD;CAEA,UAAyB;EACxB,OAAO,CAAC;GAAE,MAAM;GAAc,IAAI,KAAK;GAAI,UAAU,CAAC,KAAK,GAAG;EAAE,CAAC;CAClE;CAEA,QAAgB,SAAkD;EACjE,KAAK,WAAW,KAAK,KAAK,OAAO;EACjC,OAAO,KAAK;CACb;CAEA,MAAc,KAAK,SAAkD;EACpE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAClD,MAAM;EACR,MAAM,SAAS,IAAI,MAAM,GAAG,IAAI,QAAQ,GAAG,IAAI,CAAC;EAEhD,IAAI,WAAA,cACH,OAAO,cAAc,KAAK,IAAI,MAAM,OAAO,YAC1C,QAAQ,KACP,GAAG,KAAK,GAAG,kCAAkC,MAAM,eAAe,QAAQ,gCAAgC,MAAM,iCACjH,CACD;EAGD,IAAI,WAAW,YAAY;GAG1B,MAAM,EAAE,cAAc,MAAM,OAAO;GACnC,OAAO,UAAU,KAAK,IAAI,GAAG;EAC9B;EAEA,MAAM,IAAI,wBAAwB,KAAK,IAAI,MAAM;CAClD;AACD"}

package/dist/endpoints/index.cjs

@@ -1,17 +1,14 @@
-require('../construct-interface-BfjcOD_E.cjs');
-require('../Construct-roId57cU.cjs');
-require('../functions-DukjG8ov.cjs');
-const require_EndpointFactory = require('../EndpointFactory-DYoGLaIT.cjs');
-require('../clone-Dy0cR2SZ.cjs');
-const require_Endpoint = require('../Endpoint-BBkV6l0k.cjs');
-const require_surfaceEnv = require('../surfaceEnv-BFXEms2f.cjs');
-const require_publisher = require('../publisher-CqGsXB2X.cjs');
-const require_lazyAccessors = require('../lazyAccessors-DrJj8NpA.cjs');
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_EndpointFactory = require("../EndpointFactory-DJ7gXLpR.cjs");
+const require_functions = require("../functions-CfzJG9hK.cjs");
+const require_Endpoint = require("../Endpoint-BoUg8ocM.cjs");
+const require_surfaceEnv = require("../surfaceEnv-CNimK76p.cjs");
+const require_lazyAccessors = require("../lazyAccessors-hJKGv8Ay.cjs");
 exports.BUILT_IN_SECURITY_SCHEMES = require_EndpointFactory.BUILT_IN_SECURITY_SCHEMES;
 exports.Endpoint = require_Endpoint.Endpoint;
 exports.EndpointBuilder = require_EndpointFactory.EndpointBuilder;
 exports.EndpointFactory = require_EndpointFactory.EndpointFactory;
+exports.NoAuthenticator = require_Endpoint.NoAuthenticator;
 exports.RLS_BYPASS = require_EndpointFactory.RLS_BYPASS;
 exports.ResponseBuilder = require_Endpoint.ResponseBuilder;
 exports.createApiGatewayCookies = require_lazyAccessors.createApiGatewayCookies;
@@ -25,4 +22,4 @@ exports.defaultEnvParser = require_surfaceEnv.defaultEnvParser;
 exports.envParserFor = require_surfaceEnv.envParserFor;
 exports.getSecurityScheme = require_EndpointFactory.getSecurityScheme;
 exports.isBuiltInSecurityScheme = require_EndpointFactory.isBuiltInSecurityScheme;
-exports.publishConstructEvents = require_publisher.publishConstructEvents;
+exports.publishConstructEvents = require_functions.publishConstructEvents;

package/dist/endpoints/index.d.cts

@@ -1,7 +1,51 @@
-import "../Construct-WhCXIOPV.cjs";
-import "../index-BTvozlUD.cjs";
-import "../construct-interface-D2nNkHUN.cjs";
-import "../types-BlAkSuGI.cjs";
-import { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointContext, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../Endpoint-BQ9O0P1w.cjs";
-import { EndpointBuilder, EndpointFactory, createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, publishConstructEvents } from "../index-D5zqAJ2e.cjs";
-export { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointBuilder, EndpointContext, EndpointFactory, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { s as publishConstructEvents } from "../Construct-BQALFCh2.cjs";
+import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-aCvBMPoH.cjs";
+import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-I7s1co3Y.cjs";
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Context } from "hono";
+//#region src/endpoints/lazyAccessors.d.ts
+/**
+ * Create a lazy header accessor for Hono.
+ * Uses `c.req.header(name)` for single lookups (native, case-insensitive).
+ * Only calls `c.req.header()` to get all headers when needed.
+ */
+export declare function createHonoHeaders(c: Context): HeaderFn;
+/**
+ * Create a lazy cookie accessor for Hono.
+ * Uses `getCookie(c, name)` for single lookups (native).
+ * Only parses the cookie header when all cookies are requested.
+ */
+export declare function createHonoCookies(c: Context): CookieFn;
+/**
+ * Create a lazy header accessor for API Gateway events.
+ * Handles case-insensitive lookups.
+ */
+export declare function createApiGatewayHeaders(headers: Record<string, string | undefined> | null | undefined): HeaderFn;
+/**
+ * Create a lazy cookie accessor for API Gateway events.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export declare function createApiGatewayCookies(cookies: string[] | undefined, cookieHeader: string | undefined): CookieFn;
+/**
+ * Create a no-op header accessor (for minimal endpoints that don't use headers).
+ */
+export declare function createNoopHeaders(): HeaderFn;
+/**
+ * Create a no-op cookie accessor (for minimal endpoints that don't use cookies).
+ */
+export declare function createNoopCookies(): CookieFn;
+//#endregion
+//#region src/endpoints/surfaceEnv.d.ts
+/**
+ * The default parser, built once.
+ *
+ * Once because `Credentials` resolves through `globalThis` and decryption is
+ * not free, and because two parsers over the same environment are two caches of
+ * the same answer.
+ */
+export declare function defaultEnvParser(): EnvironmentParser<{}>;
+/** The parser for an endpoint, from its surface or the default. */
+export declare function envParserFor(surface: EndpointSurface | undefined): EnvironmentParser<{}>;
+//#endregion
+export { type ActorExtractor, type Authorizer, BUILT_IN_SECURITY_SCHEMES, type BuiltInSecuritySchemeId, type ConvertRouteParams, Endpoint, EndpointBuilder, type EndpointContext, EndpointFactory, type EndpointHandler, type EndpointOutput, type EndpointSchemas, type MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+//# sourceMappingURL=index.d.cts.map

package/dist/endpoints/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/endpoints/lazyAccessors.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;wBAgBgB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.d.mts

@@ -1,7 +1,51 @@
-import "../Construct-B-xc0SE9.mjs";
-import "../index-L7pz0R0T.mjs";
-import "../construct-interface-BqwRNYA2.mjs";
-import "../types-aKksMEWL.mjs";
-import { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointContext, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../Endpoint-BKR5QH6O.mjs";
-import { EndpointBuilder, EndpointFactory, createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, publishConstructEvents } from "../index-Cvz551AO.mjs";
-export { ActorExtractor, Authorizer, BUILT_IN_SECURITY_SCHEMES, BuiltInSecuritySchemeId, Endpoint, EndpointBuilder, EndpointContext, EndpointFactory, EndpointHandler, EndpointOutput, EndpointSchemas, MappedAudit, OAuthFlow, OAuthFlows, RLS_BYPASS, ResponseBuilder, RlsBypass, RlsConfig, RlsContext, RlsContextExtractor, SecurityScheme, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { s as publishConstructEvents } from "../Construct-QXnl3VqT.mjs";
+import { A as getSecurityScheme, C as Authorizer, D as OAuthFlows, E as OAuthFlow, O as SecurityScheme, S as MappedAudit, T as BuiltInSecuritySchemeId, _ as RlsBypass, a as EndpointContext, b as RlsContextExtractor, c as EndpointSchemas, d as ResponseBuilder, g as RLS_BYPASS, h as SessionAuth, i as Endpoint, j as isBuiltInSecurityScheme, k as createAuthorizer, l as EndpointSurface, m as NoAuthenticator, n as ConvertRouteParams, o as EndpointHandler, r as CookieFn, s as EndpointOutput, u as HeaderFn, v as RlsConfig, w as BUILT_IN_SECURITY_SCHEMES, x as ActorExtractor, y as RlsContext } from "../Endpoint-Du-NwPX2.mjs";
+import { n as EndpointBuilder, t as EndpointFactory } from "../EndpointFactory-DMYdJCOj.mjs";
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Context } from "hono";
+//#region src/endpoints/lazyAccessors.d.ts
+/**
+ * Create a lazy header accessor for Hono.
+ * Uses `c.req.header(name)` for single lookups (native, case-insensitive).
+ * Only calls `c.req.header()` to get all headers when needed.
+ */
+export declare function createHonoHeaders(c: Context): HeaderFn;
+/**
+ * Create a lazy cookie accessor for Hono.
+ * Uses `getCookie(c, name)` for single lookups (native).
+ * Only parses the cookie header when all cookies are requested.
+ */
+export declare function createHonoCookies(c: Context): CookieFn;
+/**
+ * Create a lazy header accessor for API Gateway events.
+ * Handles case-insensitive lookups.
+ */
+export declare function createApiGatewayHeaders(headers: Record<string, string | undefined> | null | undefined): HeaderFn;
+/**
+ * Create a lazy cookie accessor for API Gateway events.
+ * Decodes URL-encoded values to match browser behavior.
+ */
+export declare function createApiGatewayCookies(cookies: string[] | undefined, cookieHeader: string | undefined): CookieFn;
+/**
+ * Create a no-op header accessor (for minimal endpoints that don't use headers).
+ */
+export declare function createNoopHeaders(): HeaderFn;
+/**
+ * Create a no-op cookie accessor (for minimal endpoints that don't use cookies).
+ */
+export declare function createNoopCookies(): CookieFn;
+//#endregion
+//#region src/endpoints/surfaceEnv.d.ts
+/**
+ * The default parser, built once.
+ *
+ * Once because `Credentials` resolves through `globalThis` and decryption is
+ * not free, and because two parsers over the same environment are two caches of
+ * the same answer.
+ */
+export declare function defaultEnvParser(): EnvironmentParser<{}>;
+/** The parser for an endpoint, from its surface or the default. */
+export declare function envParserFor(surface: EndpointSurface | undefined): EnvironmentParser<{}>;
+//#endregion
+export { type ActorExtractor, type Authorizer, BUILT_IN_SECURITY_SCHEMES, type BuiltInSecuritySchemeId, type ConvertRouteParams, Endpoint, EndpointBuilder, type EndpointContext, EndpointFactory, type EndpointHandler, type EndpointOutput, type EndpointSchemas, type MappedAudit, NoAuthenticator, type OAuthFlow, type OAuthFlows, RLS_BYPASS, ResponseBuilder, type RlsBypass, type RlsConfig, type RlsContext, type RlsContextExtractor, type SecurityScheme, type SessionAuth, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+//# sourceMappingURL=index.d.mts.map

package/dist/endpoints/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/endpoints/lazyAccessors.ts","../../src/endpoints/surfaceEnv.ts"],"mappings":";;;;;;;;;;;wBAgBgB,kBAAkB,GAAG,UAAU;;;;;;wBAqB/B,kBAAkB,GAAG,UAAU;;;;;wBAgC/B,wBACf,SAAS,wDACP;;;;;wBAoCa,wBACf,+BACA,mCACE;;;;wBAmHa,qBAAqB;;;;wBAUrB,qBAAqB;;;;;;;;;;wBC1MrB,oBAAoB;;wBASpB,aACf,SAAS,8BACP"}

package/dist/endpoints/index.mjs

@@ -1,11 +1,6 @@
-import "../Construct-CdhThxDI.mjs";
-import "../construct-interface-Z4CpS8tK.mjs";
-import "../functions-Cpff1uZH.mjs";
-import { BUILT_IN_SECURITY_SCHEMES, EndpointBuilder, EndpointFactory, RLS_BYPASS, createAuthorizer, getSecurityScheme, isBuiltInSecurityScheme } from "../EndpointFactory-BejSTzbB.mjs";
-import "../clone-DblgEZZa.mjs";
-import { Endpoint, ResponseBuilder } from "../Endpoint-BTj58Gob.mjs";
-import { defaultEnvParser, envParserFor } from "../surfaceEnv-C3Ktahea.mjs";
-import { publishConstructEvents } from "../publisher-CGEo8UKD.mjs";
-import { createApiGatewayCookies, createApiGatewayHeaders, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders } from "../lazyAccessors-DM6HcXQk.mjs";
-
-export { BUILT_IN_SECURITY_SCHEMES, Endpoint, EndpointBuilder, EndpointFactory, RLS_BYPASS, ResponseBuilder, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };
+import { a as createAuthorizer, i as BUILT_IN_SECURITY_SCHEMES, n as EndpointBuilder, o as getSecurityScheme, r as RLS_BYPASS, s as isBuiltInSecurityScheme, t as EndpointFactory } from "../EndpointFactory-BDtsrEvJ.mjs";
+import { i as publishConstructEvents } from "../functions-BFizikJU.mjs";
+import { n as ResponseBuilder, r as NoAuthenticator, t as Endpoint } from "../Endpoint-BG4UJ9oA.mjs";
+import { n as envParserFor, t as defaultEnvParser } from "../surfaceEnv-wMT5QzgZ.mjs";
+import { a as createHonoHeaders, i as createHonoCookies, n as createApiGatewayHeaders, o as createNoopCookies, s as createNoopHeaders, t as createApiGatewayCookies } from "../lazyAccessors-CFanua0O.mjs";
+export { BUILT_IN_SECURITY_SCHEMES, Endpoint, EndpointBuilder, EndpointFactory, NoAuthenticator, RLS_BYPASS, ResponseBuilder, createApiGatewayCookies, createApiGatewayHeaders, createAuthorizer, createHonoCookies, createHonoHeaders, createNoopCookies, createNoopHeaders, defaultEnvParser, envParserFor, getSecurityScheme, isBuiltInSecurityScheme, publishConstructEvents };

package/dist/external-api-MJ8id87V.d.mts

@@ -0,0 +1,105 @@
+import { t as StandardSchemaV1 } from "./index-CeEtxDmK.mjs";
+import { r as Consumable } from "./construct-interface-DluK3_da.mjs";
+import { n as DeployedStage, r as LocalStage } from "./stages-BSCF19o2.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+/**
+ * Where an external API answers: one URL for every stage, or one per stage
+ * name with `default` for any stage not listed.
+ *
+ * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,
+ * so a key that names no stage — `prodution` — is a type error rather than a
+ * URL nothing reads. Without the file any key goes, as before.
+ */
+type ExternalApiUrl = string | (string extends LocalStage | DeployedStage ? Readonly<Record<string, string>> : { readonly [S in LocalStage | DeployedStage]?: string; } & {
+  readonly default?: string;
+});
+interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {
+  /**
+   * Where it answers deployed: one URL for every stage, or one per stage
+   * name, with `default` for any stage not listed.
+   */
+  url: ExternalApiUrl;
+  /** What the stage's `<ID>_CREDENTIALS` must look like. */
+  credentials: TSchema;
+  /** What a handler is handed, built from where it answers and the credentials. */
+  client: (connection: {
+    url: string;
+    credentials: Value<TSchema>;
+  }) => TClient | Promise<TClient>;
+}
+declare class ExternalApi<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1, TClient = unknown> implements Consumable<TName, TClient> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, TClient>;
+  /** Read by both `declare()` and `connect()`, so the two cannot drift. */
+  private readonly keys;
+  /** The promise, so concurrent registrations share one client. */
+  private connected?;
+  constructor(id: ConstructName<TName>, options: ExternalApiOptions<TSchema, TClient>);
+  /**
+   * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+   * is validated against where it is read. Public so a tool setting the value
+   * (`gkm secrets:add`) can check it, and describe its fields, before it is
+   * stored rather than at the first request.
+   */
+  get credentialsSchema(): TSchema;
+  declare(): Declaration[];
+  private connect;
+}
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * Marks a fake. A registered symbol, so a fake built by a second copy of this
+ * package — a linked workspace, two versions in a lockfile — is still one.
+ */
+declare const FAKE: unique symbol;
+/** What an external API's credentials look like going in, for a fake to supply. */
+type CredentialsOf<TApi> = TApi extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what the fake accepts, and what a local or test stage is
+ * handed as `<ID>_CREDENTIALS` in place of the stage's own.
+ */
+type Fake = {
+  readonly [FAKE]: true;
+  readonly credentials: unknown;
+} & ({
+  readonly kind: 'app';
+  /** Served by gkm: in-process in a test, on its own port in `gkm dev`. */
+  readonly handler: FetchHandler;
+} | {
+  readonly kind: 'image';
+  /** The provider's own local server, run as a container. */
+  readonly image: string;
+  /** The port it listens on inside the container. */
+  readonly port: number;
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the API's type to have the credentials checked against its schema —
+ * `fake.app<typeof polar>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of the API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server the provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+declare function isFake(value: unknown): value is Fake;
+//#endregion
+export { FetchHandler as a, Fake as i, ExternalApiOptions as n, fake as o, ExternalApiUrl as r, isFake as s, ExternalApi as t };
+//# sourceMappingURL=external-api-MJ8id87V.d.mts.map

package/dist/external-api-MJ8id87V.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-MJ8id87V.d.mts","names":[],"sources":["../src/external-api.ts"],"mappings":";;;;;;;KAqDK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;;;;;;;;;KAUlB,0CAEO,aAAa,gBAC3B,SAAS,sCACG,KAAK,aAAa;WACrB;;UAGG,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,KAAK;;EAEL,aAAa;;EAEb,SAAS;IACR;IACA,aAAa,MAAM;QACd,UAAU,QAAQ;;cAGZ,YACZ,+BACA,gBAAgB,mBAAmB,kBACnC,8BACY,WAAW,OAAO;mBAeZ;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;mBAG9B;;UAGT;EAER,YACC,IAAI,cAAc,QACD,SAAS,mBAAmB,SAAS;;;;;;;MA0BnD,qBAAqB;EAIzB,WAAW;UAaG;;;UA6BE;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;cAOvC;;KAGD,cAAc,QAClB,aAAa,0BAA0B,oBACpC,iBAAiB,WAAW;;;;;;;KASpB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;iBAYY,OAAO,iBAAiB,SAAS"}

package/dist/external-api-O107yzZJ.d.cts

@@ -0,0 +1,105 @@
+import { t as StandardSchemaV1 } from "./index-CeEtxDmK.cjs";
+import { r as Consumable } from "./construct-interface-B1AfqRl4.cjs";
+import { n as DeployedStage, r as LocalStage } from "./stages-BSCF19o2.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+//#region src/external-api.d.ts
+/** What a credentials schema yields. */
+type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
+/**
+ * Where an external API answers: one URL for every stage, or one per stage
+ * name with `default` for any stage not listed.
+ *
+ * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,
+ * so a key that names no stage — `prodution` — is a type error rather than a
+ * URL nothing reads. Without the file any key goes, as before.
+ */
+type ExternalApiUrl = string | (string extends LocalStage | DeployedStage ? Readonly<Record<string, string>> : { readonly [S in LocalStage | DeployedStage]?: string; } & {
+  readonly default?: string;
+});
+interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {
+  /**
+   * Where it answers deployed: one URL for every stage, or one per stage
+   * name, with `default` for any stage not listed.
+   */
+  url: ExternalApiUrl;
+  /** What the stage's `<ID>_CREDENTIALS` must look like. */
+  credentials: TSchema;
+  /** What a handler is handed, built from where it answers and the credentials. */
+  client: (connection: {
+    url: string;
+    credentials: Value<TSchema>;
+  }) => TClient | Promise<TClient>;
+}
+declare class ExternalApi<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1, TClient = unknown> implements Consumable<TName, TClient> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, TClient>;
+  /** Read by both `declare()` and `connect()`, so the two cannot drift. */
+  private readonly keys;
+  /** The promise, so concurrent registrations share one client. */
+  private connected?;
+  constructor(id: ConstructName<TName>, options: ExternalApiOptions<TSchema, TClient>);
+  /**
+   * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+   * is validated against where it is read. Public so a tool setting the value
+   * (`gkm secrets:add`) can check it, and describe its fields, before it is
+   * stored rather than at the first request.
+   */
+  get credentialsSchema(): TSchema;
+  declare(): Declaration[];
+  private connect;
+}
+/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */
+interface FetchHandler {
+  fetch(request: Request): Response | Promise<Response>;
+}
+/**
+ * Marks a fake. A registered symbol, so a fake built by a second copy of this
+ * package — a linked workspace, two versions in a lockfile — is still one.
+ */
+declare const FAKE: unique symbol;
+/** What an external API's credentials look like going in, for a fake to supply. */
+type CredentialsOf<TApi> = TApi extends ExternalApi<string, infer TSchema, unknown> ? StandardSchemaV1.InferInput<TSchema> : unknown;
+/**
+ * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.
+ *
+ * `credentials` are what the fake accepts, and what a local or test stage is
+ * handed as `<ID>_CREDENTIALS` in place of the stage's own.
+ */
+type Fake = {
+  readonly [FAKE]: true;
+  readonly credentials: unknown;
+} & ({
+  readonly kind: 'app';
+  /** Served by gkm: in-process in a test, on its own port in `gkm dev`. */
+  readonly handler: FetchHandler;
+} | {
+  readonly kind: 'image';
+  /** The provider's own local server, run as a container. */
+  readonly image: string;
+  /** The port it listens on inside the container. */
+  readonly port: number;
+});
+/**
+ * Build the fake `test/fakes/<id>.ts` default-exports.
+ *
+ * Pass the API's type to have the credentials checked against its schema —
+ * `fake.app<typeof polar>(…)`.
+ */
+declare const fake: {
+  /** A working implementation of the API, kept beside the tests that use it. */
+  app<TApi = unknown>(handler: FetchHandler, options: {
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+  /** A local server the provider publishes — `stripe/stripe-mock`. */
+  image<TApi = unknown>(image: string, options: {
+    port: number;
+    credentials: CredentialsOf<TApi>;
+  }): Fake;
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+declare function isFake(value: unknown): value is Fake;
+//#endregion
+export { FetchHandler as a, Fake as i, ExternalApiOptions as n, fake as o, ExternalApiUrl as r, isFake as s, ExternalApi as t };
+//# sourceMappingURL=external-api-O107yzZJ.d.cts.map

package/dist/external-api-O107yzZJ.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api-O107yzZJ.d.cts","names":[],"sources":["../src/external-api.ts"],"mappings":";;;;;;;KAqDK,MAAM,gBAAgB,oBAC1B,iBAAiB,YAAY;;;;;;;;;KAUlB,0CAEO,aAAa,gBAC3B,SAAS,sCACG,KAAK,aAAa;WACrB;;UAGG,mBAAmB,gBAAgB,kBAAkB;;;;;EAKrE,KAAK;;EAEL,aAAa;;EAEb,SAAS;IACR;IACA,aAAa,MAAM;QACd,UAAU,QAAQ;;cAGZ,YACZ,+BACA,gBAAgB,mBAAmB,kBACnC,8BACY,WAAW,OAAO;mBAeZ;WAXT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ;;mBAG9B;;UAGT;EAER,YACC,IAAI,cAAc,QACD,SAAS,mBAAmB,SAAS;;;;;;;MA0BnD,qBAAqB;EAIzB,WAAW;UAaG;;;UA6BE;EAChB,MAAM,SAAS,UAAU,WAAW,QAAQ;;;;;;cAOvC;;KAGD,cAAc,QAClB,aAAa,0BAA0B,oBACpC,iBAAiB,WAAW;;;;;;;KASpB;YACD;WACD;;WAGE;;WAEA,SAAS;;WAGT;;WAEA;;WAEA;;;;;;;;cAUC;;EAEZ,IAAI,gBAAc,SACR,cAAY;IACV,aAAa,cAAc;MACpC;;EAUH,MAAM,gBAAc,eACN;IACF;IAAc,aAAa,cAAc;MAClD;;;iBAYY,OAAO,iBAAiB,SAAS"}

package/dist/external-api.cjs

@@ -0,0 +1,142 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_credential = require("./credential.cjs");
+const require_tracing = require("./tracing-DPMidF_r.cjs");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+//#region src/external-api.ts
+/**
+* `ExternalApi` — an HTTP API somebody else runs.
+*
+* Polar, Stripe, a payment gateway: nothing to provision, but an address that
+* changes by stage and credentials the provider issued for each one. Without a
+* construct every integration writes that switching by hand — an optional
+* `POLAR_URL`, a fake started somewhere, a client built in a service — and the
+* target cannot see any of it.
+*
+* ```ts
+* // constructs/polar.ts
+* export const polar = new ExternalApi('Polar', {
+*   url: 'https://www.polaraccesslink.com',
+*   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),
+*   client: ({ url, credentials }) => new PolarClient(url, credentials),
+* });
+*
+* // test/fakes/polar.ts
+* export default fake.app(new Hono().post('/v3/oauth2/token', …), {
+*   credentials: { clientId: 'fake', clientSecret: 'fake' },
+* });
+*
+* // in a handler — the real API deployed, the fake locally and in tests
+* .dependsOn([polar])
+* .handle(({ services }) => services.polar.exchangeCode(code))
+* ```
+*
+* Deployed, the URL is `url` — one for every stage, or one per stage name with
+* a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one
+* JSON value read the way a `Credential`'s is. Locally and in tests both come
+* from the fake.
+*
+* **The construct never names its fake.** It is found by convention, at
+* `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —
+* so a fake, and the recorded responses it answers from, cannot end up in a
+* deployed bundle however the bundler follows imports.
+*/
+var ExternalApi = class {
+	options;
+	id;
+	service;
+	/** Read by both `declare()` and `connect()`, so the two cannot drift. */
+	keys;
+	/** The promise, so concurrent registrations share one client. */
+	connected;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		this.keys = {
+			url: (0, _geekmidas_manifest.provideKey)(canonical, "url"),
+			credentials: (0, _geekmidas_manifest.provideKey)(canonical, "credentials")
+		};
+		this.service = {
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
+			register: (registerOptions) => {
+				this.connected ??= this.connect(registerOptions);
+				return this.connected;
+			}
+		};
+	}
+	/**
+	* What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+	* is validated against where it is read. Public so a tool setting the value
+	* (`gkm secrets:add`) can check it, and describe its fields, before it is
+	* stored rather than at the first request.
+	*/
+	get credentialsSchema() {
+		return this.options.credentials;
+	}
+	declare() {
+		return [{
+			kind: "external-api",
+			id: this.id,
+			url: this.options.url,
+			provides: [this.keys.url, this.keys.credentials]
+		}];
+	}
+	async connect(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.keys.url).string() })).parse();
+		const credentials = await require_credential.readCredentials(this.id, this.keys.credentials, this.options.credentials, options.envParser);
+		const client = await this.options.client({
+			url,
+			credentials
+		});
+		return require_tracing.traceClient(this.id, client, { "server.address": hostOf(url) });
+	}
+};
+function hostOf(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+/**
+* Marks a fake. A registered symbol, so a fake built by a second copy of this
+* package — a linked workspace, two versions in a lockfile — is still one.
+*/
+const FAKE = Symbol.for("@geekmidas/constructs/fake");
+/**
+* Build the fake `test/fakes/<id>.ts` default-exports.
+*
+* Pass the API's type to have the credentials checked against its schema —
+* `fake.app<typeof polar>(…)`.
+*/
+const fake = {
+	/** A working implementation of the API, kept beside the tests that use it. */
+	app(handler, options) {
+		return {
+			[FAKE]: true,
+			kind: "app",
+			handler,
+			credentials: options.credentials
+		};
+	},
+	/** A local server the provider publishes — `stripe/stripe-mock`. */
+	image(image, options) {
+		return {
+			[FAKE]: true,
+			kind: "image",
+			image,
+			port: options.port,
+			credentials: options.credentials
+		};
+	}
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+function isFake(value) {
+	return typeof value === "object" && value !== null && value[FAKE] === true;
+}
+//#endregion
+exports.ExternalApi = ExternalApi;
+exports.fake = fake;
+exports.isFake = isFake;
+
+//# sourceMappingURL=external-api.cjs.map