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

package/dist/credential-DfSAOOdY.mjs

@@ -0,0 +1,222 @@
+import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+import { parseSchema } from "@geekmidas/schema/parser";
+//#region src/fake.ts
+/**
+* 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 construct's type to have the value checked against its schema —
+* `fake.app<typeof polar>(…)`, `fake.credential<typeof stripe>(…)`.
+*/
+const fake = {
+	/** A working implementation of an external API, kept beside the tests that use it. */
+	app(handler, options) {
+		return {
+			[FAKE]: true,
+			kind: "app",
+			handler,
+			credentials: options.credentials
+		};
+	},
+	/** A local server an external API's provider publishes — `stripe/stripe-mock`. */
+	image(image, options) {
+		return {
+			[FAKE]: true,
+			kind: "image",
+			image,
+			port: options.port,
+			credentials: options.credentials
+		};
+	},
+	/**
+	* A `Credential`'s value on the test stage and under `gkm dev --fake`, as
+	* its schema takes it — a string, or the object a JSON credential holds.
+	* It is validated where it is read, like the real one.
+	*/
+	credential(credentials) {
+		return {
+			[FAKE]: true,
+			kind: "credential",
+			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
+//#region src/credential.ts
+/**
+* `Credential` — a third-party credential with a shape.
+*
+* The answer to the design's first open question, "where does `Secret` sit?".
+* It sits beside a secret rather than replacing it, because the two differ by
+* *lifecycle* and that is the only difference worth two kinds for: a secret is
+* generated and rotated by the platform and is one opaque string, while a
+* credential is issued by someone else, arrives with several fields, and is
+* worth validating on the way in.
+*
+* ```ts
+* export const stripe = new Credential('Stripe', {
+*   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),
+* });
+*
+* // in a handler — no await, already parsed and validated
+* services.stripe.secretKey
+* ```
+*
+* **Nothing about it is async at the call site**, which is the part that looks
+* like it should be hard and is not. `Service.register()` may return a promise
+* and `ServiceDiscovery` awaits every one before a handler runs, so fetching a
+* value and validating it — including when a StandardSchema's `~standard.validate`
+* returns a promise of its own — both happen inside that existing seam.
+*
+* **One key holding JSON, not one key per field.** That is the shape a secret
+* manager stores, and it is the only shape that works with an arbitrary
+* StandardSchema: the spec has no introspection API, so enumerating a schema's
+* fields means reaching into one library's internals (`.shape`) and being wrong
+* for every other.
+*
+* **A test stage is handed a fake.** Nobody issues a credential to a test
+* stage set up fresh — CI's auto-setup stores no third party's values — so a
+* credential a test reaches has a fake at `test/fakes/<id>.ts`, the folder an
+* `ExternalApi`'s fake lives in:
+*
+* ```ts
+* // test/fakes/stripe.ts
+* import { fake } from '@geekmidas/constructs/credential';
+* import type { stripe } from '../../constructs/stripe';
+*
+* export default fake.credential<typeof stripe>({
+*   secretKey: 'sk_test_fake',
+*   webhookSecret: 'whsec_fake',
+* });
+* ```
+*
+* gkm reads it for `gkm test` and `gkm dev --fake` only, and the construct
+* never names it, so it is in no deployed bundle and a deploy still refuses a
+* stage without the real value.
+*/
+var Credential = class {
+	options;
+	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.
+	*/
+	keys;
+	/**
+	* The resolved value, held as the *promise* rather than the value.
+	*
+	* Caching the promise is what makes two concurrent registrations share one
+	* resolution: caching the value would let both start before either finished,
+	* which is a duplicated fetch every cold start rather than never.
+	*/
+	resolved;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.keys = { credentials: provideKey(canonical, "credentials") };
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (registerOptions) => this.connect(registerOptions)
+		};
+	}
+	/**
+	* 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.schema;
+	}
+	declare() {
+		return [{
+			kind: "credential",
+			id: this.id,
+			provides: [this.keys.credentials]
+		}];
+	}
+	connect(options) {
+		if (this.options.refresh) return this.resolve(options);
+		this.resolved ??= this.resolve(options);
+		return this.resolved;
+	}
+	resolve(options) {
+		return readCredentials(this.id, this.keys.credentials, this.options.schema, options.envParser);
+	}
+};
+/**
+* A credentials key, read and validated against its schema.
+*
+* Shared with every construct that holds a third party's credentials — an
+* `ExternalApi` reads its own the same way — so the shape a stage stores and
+* the error a bad value raises are the same everywhere.
+*
+* @throws {MalformedCredential} when the value is not what the schema says.
+*/
+async function readCredentials(id, key, schema, envParser) {
+	const { raw } = envParser.create((get) => ({ raw: get(key).string() })).parse();
+	try {
+		return await parseSchema(schema, decodeCredentials(raw));
+	} catch (issues) {
+		throw new MalformedCredential(id, key, issues);
+	}
+}
+/**
+* The raw environment value as the thing the schema should see.
+*
+* JSON when it is JSON, and the string itself when it is not — a credential
+* with a single opaque field is ordinary, and requiring `"…"` around it would
+* be ceremony that every operator setting one by hand would get wrong once.
+*
+* Exported so a tool checking a value before it is stored reads it exactly as
+* the process that uses it will.
+*/
+function decodeCredentials(raw) {
+	const value = raw.startsWith(JSON_SCHEME) ? raw.slice(JSON_SCHEME.length) : raw;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}
+/**
+* The explicit form, for the case a credential legitimately *is* a JSON string
+* and must not be parsed into an object. Rare, and cheaper to support than to
+* explain.
+*/
+const JSON_SCHEME = "json:";
+/** A credential was set, and is not what its schema says it should be. */
+var MalformedCredential = class extends Error {
+	id;
+	key;
+	issues;
+	constructor(id, key, issues) {
+		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
+		this.id = id;
+		this.key = key;
+		this.issues = issues;
+		this.name = "MalformedCredential";
+	}
+};
+/** StandardSchema issues as one line. */
+function describe(issues) {
+	if (!Array.isArray(issues)) return String(issues);
+	return issues.map((issue) => {
+		const path = issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+//#endregion
+export { fake as a, readCredentials as i, MalformedCredential as n, isFake as o, decodeCredentials as r, Credential as t };
+
+//# sourceMappingURL=credential-DfSAOOdY.mjs.map

package/dist/credential-DfSAOOdY.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-DfSAOOdY.mjs","names":[],"sources":["../src/fake.ts","../src/credential.ts"],"sourcesContent":["/**\n * Fakes: what a test stage — and `gkm dev --fake` — is handed in place of a\n * third party.\n *\n * An `ExternalApi`'s fake answers its requests and says which credentials it\n * accepts; a `Credential`'s fake is the value the test stage is handed in\n * place of the one a third party issued. Both live at `test/fakes/<id>.ts`,\n * found by convention and default-exported:\n *\n * ```ts\n * // test/fakes/polar.ts\n * export default fake.app<typeof polar>(new Hono()…, {\n *   credentials: { clientId: 'fake', clientSecret: 'fake' },\n * });\n *\n * // test/fakes/reviewer-password.ts\n * export default fake.credential<typeof reviewerPassword>(\n *   'a-reviewer-password-for-tests',\n * );\n * ```\n *\n * **The construct never names its fake**, so a fake cannot end up in a\n * deployed bundle however the bundler follows imports. gkm reads the folder\n * for `gkm test` (and the suite it starts) and for `gkm dev --fake`, and for\n * nothing that acts on a deployed stage: a deploy still refuses a stage that\n * lacks the real value.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Credential } from './credential';\nimport type { ExternalApi } from './external-api';\n\n/**\n * Marks a fake. A registered symbol, so a fake built by a second copy of this\n * package — a linked workspace, two versions in a lockfile — is still one.\n */\nconst FAKE = Symbol.for('@geekmidas/constructs/fake');\n\n/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */\nexport interface FetchHandler {\n\tfetch(request: Request): Response | Promise<Response>;\n}\n\n/**\n * What a construct's credentials look like going in, for a fake to supply —\n * an external API's `credentials` schema, or a credential's `schema`.\n */\ntype CredentialsOf<TConstruct> =\n\tTConstruct extends ExternalApi<string, infer TSchema, unknown>\n\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t: TConstruct extends Credential<string, infer TSchema>\n\t\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t\t: unknown;\n\n/**\n * A third party's stand-in, as `test/fakes/<id>.ts` default-exports it.\n *\n * `credentials` are what a local or test stage is handed as `<ID>_CREDENTIALS`\n * in place of the stage's own: what an external API's fake accepts, or a\n * credential's test value.\n */\nexport type Fake = {\n\treadonly [FAKE]: true;\n\treadonly credentials: unknown;\n} & (\n\t| {\n\t\t\treadonly kind: 'app';\n\t\t\t/** Served by gkm: in-process in a test, on its own port in `gkm dev`. */\n\t\t\treadonly handler: FetchHandler;\n\t  }\n\t| {\n\t\t\treadonly kind: 'image';\n\t\t\t/** The provider's own local server, run as a container. */\n\t\t\treadonly image: string;\n\t\t\t/** The port it listens on inside the container. */\n\t\t\treadonly port: number;\n\t  }\n\t| {\n\t\t\t/** A `Credential`'s test value — nothing to serve. */\n\t\t\treadonly kind: 'credential';\n\t  }\n);\n\n/**\n * Build the fake `test/fakes/<id>.ts` default-exports.\n *\n * Pass the construct's type to have the value checked against its schema —\n * `fake.app<typeof polar>(…)`, `fake.credential<typeof stripe>(…)`.\n */\nexport const fake = {\n\t/** A working implementation of an external API, kept beside the tests that use it. */\n\tapp<TApi = unknown>(\n\t\thandler: FetchHandler,\n\t\toptions: { credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'app',\n\t\t\thandler,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/** A local server an external API's provider publishes — `stripe/stripe-mock`. */\n\timage<TApi = unknown>(\n\t\timage: string,\n\t\toptions: { port: number; credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'image',\n\t\t\timage,\n\t\t\tport: options.port,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/**\n\t * A `Credential`'s value on the test stage and under `gkm dev --fake`, as\n\t * its schema takes it — a string, or the object a JSON credential holds.\n\t * It is validated where it is read, like the real one.\n\t */\n\tcredential<TCredential = unknown>(\n\t\tcredentials: CredentialsOf<TCredential>,\n\t): Fake {\n\t\treturn { [FAKE]: true, kind: 'credential', credentials };\n\t},\n};\n\n/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */\nexport function isFake(value: unknown): value is Fake {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\t(value as { [FAKE]?: unknown })[FAKE] === true\n\t);\n}\n","/**\n * `Credential` — a third-party credential with a shape.\n *\n * The answer to the design's first open question, \"where does `Secret` sit?\".\n * It sits beside a secret rather than replacing it, because the two differ by\n * *lifecycle* and that is the only difference worth two kinds for: a secret is\n * generated and rotated by the platform and is one opaque string, while a\n * credential is issued by someone else, arrives with several fields, and is\n * worth validating on the way in.\n *\n * ```ts\n * export const stripe = new Credential('Stripe', {\n *   schema: z.object({ secretKey: z.string(), webhookSecret: z.string() }),\n * });\n *\n * // in a handler — no await, already parsed and validated\n * services.stripe.secretKey\n * ```\n *\n * **Nothing about it is async at the call site**, which is the part that looks\n * like it should be hard and is not. `Service.register()` may return a promise\n * and `ServiceDiscovery` awaits every one before a handler runs, so fetching a\n * value and validating it — including when a StandardSchema's `~standard.validate`\n * returns a promise of its own — both happen inside that existing seam.\n *\n * **One key holding JSON, not one key per field.** That is the shape a secret\n * manager stores, and it is the only shape that works with an arbitrary\n * StandardSchema: the spec has no introspection API, so enumerating a schema's\n * fields means reaching into one library's internals (`.shape`) and being wrong\n * for every other.\n *\n * **A test stage is handed a fake.** Nobody issues a credential to a test\n * stage set up fresh — CI's auto-setup stores no third party's values — so a\n * credential a test reaches has a fake at `test/fakes/<id>.ts`, the folder an\n * `ExternalApi`'s fake lives in:\n *\n * ```ts\n * // test/fakes/stripe.ts\n * import { fake } from '@geekmidas/constructs/credential';\n * import type { stripe } from '../../constructs/stripe';\n *\n * export default fake.credential<typeof stripe>({\n *   secretKey: 'sk_test_fake',\n *   webhookSecret: 'whsec_fake',\n * });\n * ```\n *\n * gkm reads it for `gkm test` and `gkm dev --fake` only, and the construct\n * never names it, so it is in no deployed bundle and a deploy still refuses a\n * stage without the real value.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport { parseSchema } from '@geekmidas/schema/parser';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\n\n/** What a credential's schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\nexport interface CredentialOptions<TSchema extends StandardSchemaV1> {\n\t/**\n\t * What the credential must look like.\n\t *\n\t * Validated at registration, so a malformed or half-set credential fails\n\t * when the process starts rather than on the first request that needs the\n\t * one field somebody forgot.\n\t */\n\tschema: TSchema;\n\t/**\n\t * Re-resolve on every registration instead of once per process.\n\t *\n\t * Off by default: a credential is resolved once and reused, because the\n\t * alternative is a fetch on every request. The cost of that default is that\n\t * a rotated credential needs a restart, which is the right trade for a value\n\t * that changes a few times a year — and this is the escape hatch for when it\n\t * is not.\n\t */\n\trefresh?: boolean;\n}\n\nexport class Credential<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n> implements Consumable<TName, Value<TSchema>>\n{\n\t// `Consumable` rather than `Construct`, and not by preference: `Construct`\n\t// types its service as `[TClient] extends [never] ? never : Service<…>` so\n\t// that a `Cron` cannot be depended on, and TypeScript cannot evaluate that\n\t// conditional while `TClient` is still a type parameter. Every construct\n\t// with a concrete client satisfies `Construct`; the first one whose client\n\t// is generic cannot. `Consumable` is the face `.dependsOn()` requires and\n\t// carries no conditional, so it is the honest annotation here.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, Value<TSchema>>;\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 keys: { credentials: string };\n\n\t/**\n\t * The resolved value, held as the *promise* rather than the value.\n\t *\n\t * Caching the promise is what makes two concurrent registrations share one\n\t * resolution: caching the value would let both start before either finished,\n\t * which is a duplicated fetch every cold start rather than never.\n\t */\n\tprivate resolved?: Promise<Value<TSchema>>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: CredentialOptions<TSchema>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = { credentials: provideKey(canonical, 'credentials') };\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: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value\n\t * is validated against where it is read. Public so a tool setting the value\n\t * (`gkm secrets:add`) can check it, and describe its fields, before it is\n\t * stored rather than at the first request.\n\t */\n\tget credentialsSchema(): TSchema {\n\t\treturn this.options.schema;\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'credential',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate connect(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\tif (this.options.refresh) return this.resolve(options);\n\n\t\tthis.resolved ??= this.resolve(options);\n\n\t\treturn this.resolved;\n\t}\n\n\tprivate resolve(options: ServiceRegisterOptions): Promise<Value<TSchema>> {\n\t\treturn readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.schema,\n\t\t\toptions.envParser,\n\t\t);\n\t}\n}\n\n/**\n * A credentials key, read and validated against its schema.\n *\n * Shared with every construct that holds a third party's credentials — an\n * `ExternalApi` reads its own the same way — so the shape a stage stores and\n * the error a bad value raises are the same everywhere.\n *\n * @throws {MalformedCredential} when the value is not what the schema says.\n */\nexport async function readCredentials<TSchema extends StandardSchemaV1>(\n\tid: string,\n\tkey: string,\n\tschema: TSchema,\n\tenvParser: ServiceRegisterOptions['envParser'],\n): Promise<Value<TSchema>> {\n\tconst { raw } = envParser\n\t\t.create((get) => ({ raw: get(key).string() }))\n\t\t.parse();\n\n\ttry {\n\t\treturn await parseSchema(schema, decodeCredentials(raw));\n\t} catch (issues) {\n\t\tthrow new MalformedCredential(id, key, issues);\n\t}\n}\n\n/**\n * The raw environment value as the thing the schema should see.\n *\n * JSON when it is JSON, and the string itself when it is not — a credential\n * with a single opaque field is ordinary, and requiring `\"…\"` around it would\n * be ceremony that every operator setting one by hand would get wrong once.\n *\n * Exported so a tool checking a value before it is stored reads it exactly as\n * the process that uses it will.\n */\nexport function decodeCredentials(raw: string): unknown {\n\tconst value = raw.startsWith(JSON_SCHEME)\n\t\t? raw.slice(JSON_SCHEME.length)\n\t\t: raw;\n\n\ttry {\n\t\treturn JSON.parse(value);\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/**\n * The explicit form, for the case a credential legitimately *is* a JSON string\n * and must not be parsed into an object. Rare, and cheaper to support than to\n * explain.\n */\nconst JSON_SCHEME = 'json:';\n\n/** A credential was set, and is not what its schema says it should be. */\nexport class MalformedCredential extends Error {\n\tconstructor(\n\t\treadonly id: string,\n\t\treadonly key: string,\n\t\treadonly issues: unknown,\n\t) {\n\t\tsuper(\n\t\t\t`${key} is not a valid ${id} credential. ` +\n\t\t\t\t`It is validated where it is read, so this is the value that is set ` +\n\t\t\t\t`rather than the code that uses it: ${describe(issues)}`,\n\t\t);\n\t\tthis.name = 'MalformedCredential';\n\t}\n}\n\n/** StandardSchema issues as one line. */\nfunction describe(issues: unknown): string {\n\tif (!Array.isArray(issues)) return String(issues);\n\n\treturn issues\n\t\t.map((issue: StandardSchemaV1.Issue) => {\n\t\t\tconst path = issue.path\n\t\t\t\t?.map((segment) =>\n\t\t\t\t\ttypeof segment === 'object' ? String(segment.key) : String(segment),\n\t\t\t\t)\n\t\t\t\t.join('.');\n\n\t\t\treturn path ? `${path}: ${issue.message}` : issue.message;\n\t\t})\n\t\t.join('; ');\n}\n\nexport { type Fake, fake, isFake } from './fake';\n"],"mappings":";;;;;;;AAoCA,MAAM,OAAO,OAAO,IAAI,4BAA4B;;;;;;;AAqDpD,MAAa,OAAO;;CAEnB,IACC,SACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,aAAa,QAAQ;EACtB;CACD;;CAGA,MACC,OACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,MAAM,QAAQ;GACd,aAAa,QAAQ;EACtB;CACD;;;;;;CAOA,WACC,aACO;EACP,OAAO;IAAG,OAAO;GAAM,MAAM;GAAc;EAAY;CACxD;AACD;;AAGA,SAAgB,OAAO,OAA+B;CACrD,OACC,OAAO,UAAU,YACjB,UAAU,QACT,MAA+B,UAAU;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/CA,IAAa,aAAb,MAIA;CA4BmB;CApBlB;CACA;;;;;CAMA;;;;;;;;CASA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO,EAAE,aAAa,WAAW,WAAW,aAAa,EAAE;EAGhE,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,oBAAoB,KAAK,QAAQ,eAAe;EAC5D;CACD;;;;;;;CAQA,IAAI,oBAA6B;EAChC,OAAO,KAAK,QAAQ;CACrB;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GACT,UAAU,CAAC,KAAK,KAAK,WAAW;EACjC,CACD;CACD;CAEA,QAAgB,SAA0D;EACzE,IAAI,KAAK,QAAQ,SAAS,OAAO,KAAK,QAAQ,OAAO;EAErD,KAAK,aAAa,KAAK,QAAQ,OAAO;EAEtC,OAAO,KAAK;CACb;CAEA,QAAgB,SAA0D;EACzE,OAAO,gBACN,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,QACb,QAAQ,SACT;CACD;AACD;;;;;;;;;;AAWA,eAAsB,gBACrB,IACA,KACA,QACA,WAC0B;CAC1B,MAAM,EAAE,QAAQ,UACd,QAAQ,SAAS,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAC7C,MAAM;CAER,IAAI;EACH,OAAO,MAAM,YAAY,QAAQ,kBAAkB,GAAG,CAAC;CACxD,SAAS,QAAQ;EAChB,MAAM,IAAI,oBAAoB,IAAI,KAAK,MAAM;CAC9C;AACD;;;;;;;;;;;AAYA,SAAgB,kBAAkB,KAAsB;CACvD,MAAM,QAAQ,IAAI,WAAW,WAAW,IACrC,IAAI,MAAM,YAAY,MAAM,IAC5B;CAEH,IAAI;EACH,OAAO,KAAK,MAAM,KAAK;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;AAOA,MAAM,cAAc;;AAGpB,IAAa,sBAAb,cAAyC,MAAM;CAEpC;CACA;CACA;CAHV,YACC,IACA,KACA,QACC;EACD,MACC,GAAG,IAAI,kBAAkB,GAAG,qHAEW,SAAS,MAAM,GACvD;EARS,KAAA,KAAA;EACA,KAAA,MAAA;EACA,KAAA,SAAA;EAOT,KAAK,OAAO;CACb;AACD;;AAGA,SAAS,SAAS,QAAyB;CAC1C,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,OAAO,OAAO,MAAM;CAEhD,OAAO,OACL,KAAK,UAAkC;EACvC,MAAM,OAAO,MAAM,MAChB,KAAK,YACN,OAAO,YAAY,WAAW,OAAO,QAAQ,GAAG,IAAI,OAAO,OAAO,CACnE,CAAC,CACA,KAAK,GAAG;EAEV,OAAO,OAAO,GAAG,KAAK,IAAI,MAAM,YAAY,MAAM;CACnD,CAAC,CAAC,CACD,KAAK,IAAI;AACZ"}

package/dist/credential.cjs

@@ -1,96 +1,8 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_schema_parser = require_chunk.__toESM(require("@geekmidas/schema/parser"));
-
-//#region src/credential.ts
-var Credential = 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.
-	*/
-	keys;
-	/**
-	* The resolved value, held as the *promise* rather than the value.
-	*
-	* Caching the promise is what makes two concurrent registrations share one
-	* resolution: caching the value would let both start before either finished,
-	* which is a duplicated fetch every cold start rather than never.
-	*/
-	resolved;
-	constructor(id, options) {
-		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
-		this.id = canonical;
-		this.keys = { credential: (0, __geekmidas_manifest.provideKey)(canonical, "credential") };
-		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
-			register: (registerOptions) => this.connect(registerOptions)
-		};
-	}
-	declare() {
-		return [{
-			kind: "credential",
-			id: this.id,
-			provides: [this.keys.credential]
-		}];
-	}
-	connect(options) {
-		if (this.options.refresh) return this.resolve(options);
-		this.resolved ??= this.resolve(options);
-		return this.resolved;
-	}
-	async resolve(options) {
-		const { raw } = options.envParser.create((get) => ({ raw: get(this.keys.credential).string() })).parse();
-		try {
-			return await (0, __geekmidas_schema_parser.parseSchema)(this.options.schema, decode(raw));
-		} catch (issues) {
-			throw new MalformedCredential(this.id, this.keys.credential, issues);
-		}
-	}
-};
-/**
-* The raw environment value as the thing the schema should see.
-*
-* JSON when it is JSON, and the string itself when it is not — a credential
-* with a single opaque field is ordinary, and requiring `"…"` around it would
-* be ceremony that every operator setting one by hand would get wrong once.
-*/
-function decode(raw) {
-	const value = raw.startsWith(JSON_SCHEME) ? raw.slice(JSON_SCHEME.length) : raw;
-	try {
-		return JSON.parse(value);
-	} catch {
-		return value;
-	}
-}
-/**
-* The explicit form, for the case a credential legitimately *is* a JSON string
-* and must not be parsed into an object. Rare, and cheaper to support than to
-* explain.
-*/
-const JSON_SCHEME = "json:";
-/** A credential was set, and is not what its schema says it should be. */
-var MalformedCredential = class extends Error {
-	constructor(id, key, issues) {
-		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
-		this.id = id;
-		this.key = key;
-		this.issues = issues;
-		this.name = "MalformedCredential";
-	}
-};
-/** StandardSchema issues as one line. */
-function describe(issues) {
-	if (!Array.isArray(issues)) return String(issues);
-	return issues.map((issue) => {
-		const path = issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".");
-		return path ? `${path}: ${issue.message}` : issue.message;
-	}).join("; ");
-}
-
-//#endregion
-exports.Credential = Credential;
-exports.MalformedCredential = MalformedCredential;
-//# sourceMappingURL=credential.cjs.map
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_credential = require("./credential-DYymbp_7.cjs");
+exports.Credential = require_credential.Credential;
+exports.MalformedCredential = require_credential.MalformedCredential;
+exports.decodeCredentials = require_credential.decodeCredentials;
+exports.fake = require_credential.fake;
+exports.isFake = require_credential.isFake;
+exports.readCredentials = require_credential.readCredentials;

package/dist/credential.d.cts

@@ -1,61 +1,2 @@
-import { Consumable } from "./construct-interface-D9d4Gm4p.cjs";
-import { Service } from "@geekmidas/services";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-import { ConstructName, Declaration } from "@geekmidas/manifest";
-
-//#region src/credential.d.ts
-
-/** What a credential's schema yields. */
-type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
-interface CredentialOptions<TSchema extends StandardSchemaV1> {
-  /**
-   * What the credential must look like.
-   *
-   * Validated at registration, so a malformed or half-set credential fails
-   * when the process starts rather than on the first request that needs the
-   * one field somebody forgot.
-   */
-  schema: TSchema;
-  /**
-   * Re-resolve on every registration instead of once per process.
-   *
-   * Off by default: a credential is resolved once and reused, because the
-   * alternative is a fetch on every request. The cost of that default is that
-   * a rotated credential needs a restart, which is the right trade for a value
-   * that changes a few times a year — and this is the escape hatch for when it
-   * is not.
-   */
-  refresh?: boolean;
-}
-declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
-  private readonly options;
-  readonly id: TName;
-  readonly service: Service<Uncapitalize<TName>, Value<TSchema>>;
-  /**
-   * 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 keys;
-  /**
-   * The resolved value, held as the *promise* rather than the value.
-   *
-   * Caching the promise is what makes two concurrent registrations share one
-   * resolution: caching the value would let both start before either finished,
-   * which is a duplicated fetch every cold start rather than never.
-   */
-  private resolved?;
-  constructor(id: ConstructName<TName>, options: CredentialOptions<TSchema>);
-  declare(): Declaration[];
-  private connect;
-  private resolve;
-}
-/** A credential was set, and is not what its schema says it should be. */
-declare class MalformedCredential extends Error {
-  readonly id: string;
-  readonly key: string;
-  readonly issues: unknown;
-  constructor(id: string, key: string, issues: unknown);
-}
-//#endregion
-export { Credential, CredentialOptions, MalformedCredential };
-//# sourceMappingURL=credential.d.cts.map
+import { c as Credential, d as decodeCredentials, f as readCredentials, i as isFake, l as CredentialOptions, r as fake, t as Fake, u as MalformedCredential } from "./fake-Dvion_Fh.cjs";
+export { Credential, CredentialOptions, type Fake, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };

package/dist/credential.d.mts

@@ -1,61 +1,2 @@
-import { Consumable } from "./construct-interface-g5GM5pwR.mjs";
-import { ConstructName, Declaration } from "@geekmidas/manifest";
-import { Service } from "@geekmidas/services";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-
-//#region src/credential.d.ts
-
-/** What a credential's schema yields. */
-type Value<TSchema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<TSchema>;
-interface CredentialOptions<TSchema extends StandardSchemaV1> {
-  /**
-   * What the credential must look like.
-   *
-   * Validated at registration, so a malformed or half-set credential fails
-   * when the process starts rather than on the first request that needs the
-   * one field somebody forgot.
-   */
-  schema: TSchema;
-  /**
-   * Re-resolve on every registration instead of once per process.
-   *
-   * Off by default: a credential is resolved once and reused, because the
-   * alternative is a fetch on every request. The cost of that default is that
-   * a rotated credential needs a restart, which is the right trade for a value
-   * that changes a few times a year — and this is the escape hatch for when it
-   * is not.
-   */
-  refresh?: boolean;
-}
-declare class Credential<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> implements Consumable<TName, Value<TSchema>> {
-  private readonly options;
-  readonly id: TName;
-  readonly service: Service<Uncapitalize<TName>, Value<TSchema>>;
-  /**
-   * 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 keys;
-  /**
-   * The resolved value, held as the *promise* rather than the value.
-   *
-   * Caching the promise is what makes two concurrent registrations share one
-   * resolution: caching the value would let both start before either finished,
-   * which is a duplicated fetch every cold start rather than never.
-   */
-  private resolved?;
-  constructor(id: ConstructName<TName>, options: CredentialOptions<TSchema>);
-  declare(): Declaration[];
-  private connect;
-  private resolve;
-}
-/** A credential was set, and is not what its schema says it should be. */
-declare class MalformedCredential extends Error {
-  readonly id: string;
-  readonly key: string;
-  readonly issues: unknown;
-  constructor(id: string, key: string, issues: unknown);
-}
-//#endregion
-export { Credential, CredentialOptions, MalformedCredential };
-//# sourceMappingURL=credential.d.mts.map
+import { c as Credential, d as decodeCredentials, f as readCredentials, i as isFake, l as CredentialOptions, r as fake, t as Fake, u as MalformedCredential } from "./fake-DqKo8INJ.mjs";
+export { Credential, CredentialOptions, type Fake, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };

package/dist/credential.mjs

@@ -1,94 +1,2 @@
-import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
-import { parseSchema } from "@geekmidas/schema/parser";
-
-//#region src/credential.ts
-var Credential = 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.
-	*/
-	keys;
-	/**
-	* The resolved value, held as the *promise* rather than the value.
-	*
-	* Caching the promise is what makes two concurrent registrations share one
-	* resolution: caching the value would let both start before either finished,
-	* which is a duplicated fetch every cold start rather than never.
-	*/
-	resolved;
-	constructor(id, options) {
-		this.options = options;
-		const canonical = canonicalId(id);
-		this.id = canonical;
-		this.keys = { credential: provideKey(canonical, "credential") };
-		this.service = {
-			serviceName: serviceKey(canonical),
-			register: (registerOptions) => this.connect(registerOptions)
-		};
-	}
-	declare() {
-		return [{
-			kind: "credential",
-			id: this.id,
-			provides: [this.keys.credential]
-		}];
-	}
-	connect(options) {
-		if (this.options.refresh) return this.resolve(options);
-		this.resolved ??= this.resolve(options);
-		return this.resolved;
-	}
-	async resolve(options) {
-		const { raw } = options.envParser.create((get) => ({ raw: get(this.keys.credential).string() })).parse();
-		try {
-			return await parseSchema(this.options.schema, decode(raw));
-		} catch (issues) {
-			throw new MalformedCredential(this.id, this.keys.credential, issues);
-		}
-	}
-};
-/**
-* The raw environment value as the thing the schema should see.
-*
-* JSON when it is JSON, and the string itself when it is not — a credential
-* with a single opaque field is ordinary, and requiring `"…"` around it would
-* be ceremony that every operator setting one by hand would get wrong once.
-*/
-function decode(raw) {
-	const value = raw.startsWith(JSON_SCHEME) ? raw.slice(JSON_SCHEME.length) : raw;
-	try {
-		return JSON.parse(value);
-	} catch {
-		return value;
-	}
-}
-/**
-* The explicit form, for the case a credential legitimately *is* a JSON string
-* and must not be parsed into an object. Rare, and cheaper to support than to
-* explain.
-*/
-const JSON_SCHEME = "json:";
-/** A credential was set, and is not what its schema says it should be. */
-var MalformedCredential = class extends Error {
-	constructor(id, key, issues) {
-		super(`${key} is not a valid ${id} credential. It is validated where it is read, so this is the value that is set rather than the code that uses it: ${describe(issues)}`);
-		this.id = id;
-		this.key = key;
-		this.issues = issues;
-		this.name = "MalformedCredential";
-	}
-};
-/** StandardSchema issues as one line. */
-function describe(issues) {
-	if (!Array.isArray(issues)) return String(issues);
-	return issues.map((issue) => {
-		const path = issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".");
-		return path ? `${path}: ${issue.message}` : issue.message;
-	}).join("; ");
-}
-
-//#endregion
-export { Credential, MalformedCredential };
-//# sourceMappingURL=credential.mjs.map
+import { a as fake, i as readCredentials, n as MalformedCredential, o as isFake, r as decodeCredentials, t as Credential } from "./credential-DfSAOOdY.mjs";
+export { Credential, MalformedCredential, decodeCredentials, fake, isFake, readCredentials };