@lssm/integration.runtime 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217072406

package/dist/health.js

@@ -1 +1,69 @@
-var e=class{telemetry;nowFn;constructor(e={}){this.telemetry=e.telemetry,this.nowFn=e.now??(()=>new Date)}async check(e,n){let r=this.nowFn();try{await n(e);let t=this.nowFn(),i={status:`connected`,checkedAt:t,latencyMs:t.getTime()-r.getTime()};return this.emitTelemetry(e,i,`success`),i}catch(n){let i=this.nowFn(),a=n instanceof Error?n.message:`Unknown error`,o=t(n),s={status:`error`,checkedAt:i,latencyMs:i.getTime()-r.getTime(),errorMessage:a,errorCode:o};return this.emitTelemetry(e,s,`error`,o,a),s}}emitTelemetry(e,t,n,r,i){this.telemetry&&this.telemetry.record({tenantId:e.tenantId,appId:e.appId,environment:e.environment,slotId:e.slotId,integrationKey:e.spec.meta.key,integrationVersion:e.spec.meta.version,connectionId:e.connection.meta.id,status:n,durationMs:t.latencyMs,errorCode:r,errorMessage:i,occurredAt:t.checkedAt??this.nowFn(),metadata:{...e.trace?{blueprint:`${e.trace.blueprintName}.v${e.trace.blueprintVersion}`,configVersion:e.trace.configVersion}:{},status:t.status}})}};function t(e){if(!e||typeof e!=`object`)return;let t=e;if(t.code!=null)return String(t.code)}export{e as IntegrationHealthService};
+//#region src/health.ts
+var IntegrationHealthService = class {
+	telemetry;
+	nowFn;
+	constructor(options = {}) {
+		this.telemetry = options.telemetry;
+		this.nowFn = options.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	async check(context, executor) {
+		const start = this.nowFn();
+		try {
+			await executor(context);
+			const end = this.nowFn();
+			const result = {
+				status: "connected",
+				checkedAt: end,
+				latencyMs: end.getTime() - start.getTime()
+			};
+			this.emitTelemetry(context, result, "success");
+			return result;
+		} catch (error) {
+			const end = this.nowFn();
+			const message = error instanceof Error ? error.message : "Unknown error";
+			const code = extractErrorCode(error);
+			const result = {
+				status: "error",
+				checkedAt: end,
+				latencyMs: end.getTime() - start.getTime(),
+				errorMessage: message,
+				errorCode: code
+			};
+			this.emitTelemetry(context, result, "error", code, message);
+			return result;
+		}
+	}
+	emitTelemetry(context, result, status, errorCode, errorMessage) {
+		if (!this.telemetry) return;
+		this.telemetry.record({
+			tenantId: context.tenantId,
+			appId: context.appId,
+			environment: context.environment,
+			slotId: context.slotId,
+			integrationKey: context.spec.meta.key,
+			integrationVersion: context.spec.meta.version,
+			connectionId: context.connection.meta.id,
+			status,
+			durationMs: result.latencyMs,
+			errorCode,
+			errorMessage,
+			occurredAt: result.checkedAt ?? this.nowFn(),
+			metadata: {
+				...context.trace ? {
+					blueprint: `${context.trace.blueprintName}.v${context.trace.blueprintVersion}`,
+					configVersion: context.trace.configVersion
+				} : {},
+				status: result.status
+			}
+		});
+	}
+};
+function extractErrorCode(error) {
+	if (!error || typeof error !== "object") return void 0;
+	const candidate = error;
+	if (candidate.code == null) return void 0;
+	return String(candidate.code);
+}
+
+//#endregion
+export { IntegrationHealthService };

package/dist/index.js

@@ -1 +1,9 @@
-import{IntegrationHealthService as e}from"./health.js";import{IntegrationCallGuard as t,connectionStatusLabel as n,ensureConnectionReady as r}from"./runtime.js";import{SecretProviderError as i,normalizeSecretPayload as a,parseSecretUri as o}from"./secrets/provider.js";import{GcpSecretManagerProvider as s}from"./secrets/gcp-secret-manager.js";import{EnvSecretProvider as c}from"./secrets/env-secret-provider.js";import{SecretProviderManager as l}from"./secrets/manager.js";import"./secrets/index.js";export{c as EnvSecretProvider,s as GcpSecretManagerProvider,t as IntegrationCallGuard,e as IntegrationHealthService,i as SecretProviderError,l as SecretProviderManager,n as connectionStatusLabel,r as ensureConnectionReady,a as normalizeSecretPayload,o as parseSecretUri};
+import { IntegrationHealthService } from "./health.js";
+import { IntegrationCallGuard, connectionStatusLabel, ensureConnectionReady } from "./runtime.js";
+import { SecretProviderError, normalizeSecretPayload, parseSecretUri } from "./secrets/provider.js";
+import { GcpSecretManagerProvider } from "./secrets/gcp-secret-manager.js";
+import { EnvSecretProvider } from "./secrets/env-secret-provider.js";
+import { SecretProviderManager } from "./secrets/manager.js";
+import "./secrets/index.js";
+
+export { EnvSecretProvider, GcpSecretManagerProvider, IntegrationCallGuard, IntegrationHealthService, SecretProviderError, SecretProviderManager, connectionStatusLabel, ensureConnectionReady, normalizeSecretPayload, parseSecretUri };

package/dist/runtime.js

@@ -1 +1,186 @@
-import{performance as e}from"node:perf_hooks";var t=class{telemetry;maxAttempts;backoffMs;shouldRetry;sleep;now;constructor(e,t={}){this.secretProvider=e,this.telemetry=t.telemetry,this.maxAttempts=Math.max(1,t.maxAttempts??3),this.backoffMs=t.backoffMs??250,this.shouldRetry=t.shouldRetry??(e=>typeof e==`object`&&!!e&&`retryable`in e&&!!e.retryable),this.sleep=t.sleep??(e=>e<=0?Promise.resolve():new Promise(t=>setTimeout(t,e))),this.now=t.now??(()=>new Date)}async executeWithGuards(t,n,r,i,a){let o=this.findIntegration(t,i);if(!o)return this.failure({tenantId:i.tenantId,appId:i.appId,environment:i.environment,blueprintName:i.blueprintName,blueprintVersion:i.blueprintVersion,configVersion:i.configVersion,slotId:t,operation:n},void 0,{code:`SLOT_NOT_BOUND`,message:`Integration slot "${t}" is not bound for tenant "${i.tenantId}".`,retryable:!1},0);let s=o.connection.status;if(s===`disconnected`||s===`error`)return this.failure(this.makeContext(t,n,i),o,{code:`CONNECTION_NOT_READY`,message:`Integration connection "${o.connection.meta.label}" is in status "${s}".`,retryable:!1},0);let c=await this.fetchSecrets(o.connection),l=0,u=e.now();for(;l<this.maxAttempts;){l+=1;try{let r=await a(o.connection,c),s=e.now()-u;return this.emitTelemetry(this.makeContext(t,n,i),o,`success`,s),{success:!0,data:r,metadata:{latencyMs:s,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:l}}}catch(r){let a=e.now()-u;this.emitTelemetry(this.makeContext(t,n,i),o,`error`,a,this.errorCodeFor(r),r instanceof Error?r.message:String(r));let s=this.shouldRetry(r,l);if(!s||l>=this.maxAttempts)return{success:!1,error:{code:this.errorCodeFor(r),message:r instanceof Error?r.message:String(r),retryable:s,cause:r},metadata:{latencyMs:a,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:l}};await this.sleep(this.backoffMs)}}return{success:!1,error:{code:`UNKNOWN_ERROR`,message:`Integration call failed after retries.`,retryable:!1},metadata:{latencyMs:e.now()-u,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:this.maxAttempts}}}findIntegration(e,t){return t.integrations.find(t=>t.slot.slotId===e)}async fetchSecrets(e){if(!this.secretProvider.canHandle(e.secretRef))throw Error(`Secret provider "${this.secretProvider.id}" cannot handle reference "${e.secretRef}".`);let t=await this.secretProvider.getSecret(e.secretRef);return this.parseSecret(t)}parseSecret(e){let t=new TextDecoder().decode(e.data);try{let e=JSON.parse(t);if(e&&typeof e==`object`&&!Array.isArray(e)){let t=Object.entries(e).filter(([,e])=>typeof e==`string`||typeof e==`number`||typeof e==`boolean`);return Object.fromEntries(t.map(([e,t])=>[e,String(t)]))}}catch{}return{secret:t}}emitTelemetry(e,t,n,r,i,a){!this.telemetry||!t||this.telemetry.record({tenantId:e.tenantId,appId:e.appId,environment:e.environment,slotId:e.slotId,integrationKey:t.connection.meta.integrationKey,integrationVersion:t.connection.meta.integrationVersion,connectionId:t.connection.meta.id,status:n,durationMs:r,errorCode:i,errorMessage:a,occurredAt:this.now(),metadata:{blueprint:`${e.blueprintName}.v${e.blueprintVersion}`,configVersion:e.configVersion,operation:e.operation}})}failure(e,t,n,r){return t&&this.emitTelemetry(e,t,`error`,0,n.code,n.message),{success:!1,error:n,metadata:{latencyMs:0,connectionId:t?.connection.meta.id??`unknown`,ownershipMode:t?.connection.ownershipMode??`managed`,attempts:r}}}makeContext(e,t,n){return{tenantId:n.tenantId,appId:n.appId,environment:n.environment,blueprintName:n.blueprintName,blueprintVersion:n.blueprintVersion,configVersion:n.configVersion,slotId:e,operation:t}}errorCodeFor(e){return typeof e==`object`&&e&&`code`in e&&typeof e.code==`string`?e.code:`PROVIDER_ERROR`}};function n(e){let t=e.connection.status;if(t===`disconnected`||t===`error`)throw Error(`Integration connection "${e.connection.meta.label}" is in status "${t}".`)}function r(e){switch(e){case`connected`:return`connected`;case`disconnected`:return`disconnected`;case`error`:return`error`;case`unknown`:default:return`unknown`}}export{t as IntegrationCallGuard,r as connectionStatusLabel,n as ensureConnectionReady};
+import { performance } from "node:perf_hooks";
+
+//#region src/runtime.ts
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF_MS = 250;
+var IntegrationCallGuard = class {
+	telemetry;
+	maxAttempts;
+	backoffMs;
+	shouldRetry;
+	sleep;
+	now;
+	constructor(secretProvider, options = {}) {
+		this.secretProvider = secretProvider;
+		this.telemetry = options.telemetry;
+		this.maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+		this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+		this.shouldRetry = options.shouldRetry ?? ((error) => typeof error === "object" && error !== null && "retryable" in error && Boolean(error.retryable));
+		this.sleep = options.sleep ?? ((ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)));
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	async executeWithGuards(slotId, operation, _input, resolvedConfig, executor) {
+		const integration = this.findIntegration(slotId, resolvedConfig);
+		if (!integration) return this.failure({
+			tenantId: resolvedConfig.tenantId,
+			appId: resolvedConfig.appId,
+			environment: resolvedConfig.environment,
+			blueprintName: resolvedConfig.blueprintName,
+			blueprintVersion: resolvedConfig.blueprintVersion,
+			configVersion: resolvedConfig.configVersion,
+			slotId,
+			operation
+		}, void 0, {
+			code: "SLOT_NOT_BOUND",
+			message: `Integration slot "${slotId}" is not bound for tenant "${resolvedConfig.tenantId}".`,
+			retryable: false
+		}, 0);
+		const status = integration.connection.status;
+		if (status === "disconnected" || status === "error") return this.failure(this.makeContext(slotId, operation, resolvedConfig), integration, {
+			code: "CONNECTION_NOT_READY",
+			message: `Integration connection "${integration.connection.meta.label}" is in status "${status}".`,
+			retryable: false
+		}, 0);
+		const secrets = await this.fetchSecrets(integration.connection);
+		let attempt = 0;
+		const started = performance.now();
+		while (attempt < this.maxAttempts) {
+			attempt += 1;
+			try {
+				const data = await executor(integration.connection, secrets);
+				const duration = performance.now() - started;
+				this.emitTelemetry(this.makeContext(slotId, operation, resolvedConfig), integration, "success", duration);
+				return {
+					success: true,
+					data,
+					metadata: {
+						latencyMs: duration,
+						connectionId: integration.connection.meta.id,
+						ownershipMode: integration.connection.ownershipMode,
+						attempts: attempt
+					}
+				};
+			} catch (error) {
+				const duration = performance.now() - started;
+				this.emitTelemetry(this.makeContext(slotId, operation, resolvedConfig), integration, "error", duration, this.errorCodeFor(error), error instanceof Error ? error.message : String(error));
+				const retryable = this.shouldRetry(error, attempt);
+				if (!retryable || attempt >= this.maxAttempts) return {
+					success: false,
+					error: {
+						code: this.errorCodeFor(error),
+						message: error instanceof Error ? error.message : String(error),
+						retryable,
+						cause: error
+					},
+					metadata: {
+						latencyMs: duration,
+						connectionId: integration.connection.meta.id,
+						ownershipMode: integration.connection.ownershipMode,
+						attempts: attempt
+					}
+				};
+				await this.sleep(this.backoffMs);
+			}
+		}
+		return {
+			success: false,
+			error: {
+				code: "UNKNOWN_ERROR",
+				message: "Integration call failed after retries.",
+				retryable: false
+			},
+			metadata: {
+				latencyMs: performance.now() - started,
+				connectionId: integration.connection.meta.id,
+				ownershipMode: integration.connection.ownershipMode,
+				attempts: this.maxAttempts
+			}
+		};
+	}
+	findIntegration(slotId, config) {
+		return config.integrations.find((integration) => integration.slot.slotId === slotId);
+	}
+	async fetchSecrets(connection) {
+		if (!this.secretProvider.canHandle(connection.secretRef)) throw new Error(`Secret provider "${this.secretProvider.id}" cannot handle reference "${connection.secretRef}".`);
+		const secret = await this.secretProvider.getSecret(connection.secretRef);
+		return this.parseSecret(secret);
+	}
+	parseSecret(secret) {
+		const text = new TextDecoder().decode(secret.data);
+		try {
+			const parsed = JSON.parse(text);
+			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+				const entries = Object.entries(parsed).filter(([, value]) => typeof value === "string" || typeof value === "number" || typeof value === "boolean");
+				return Object.fromEntries(entries.map(([key, value]) => [key, String(value)]));
+			}
+		} catch {}
+		return { secret: text };
+	}
+	emitTelemetry(context, integration, status, durationMs, errorCode, errorMessage) {
+		if (!this.telemetry || !integration) return;
+		this.telemetry.record({
+			tenantId: context.tenantId,
+			appId: context.appId,
+			environment: context.environment,
+			slotId: context.slotId,
+			integrationKey: integration.connection.meta.integrationKey,
+			integrationVersion: integration.connection.meta.integrationVersion,
+			connectionId: integration.connection.meta.id,
+			status,
+			durationMs,
+			errorCode,
+			errorMessage,
+			occurredAt: this.now(),
+			metadata: {
+				blueprint: `${context.blueprintName}.v${context.blueprintVersion}`,
+				configVersion: context.configVersion,
+				operation: context.operation
+			}
+		});
+	}
+	failure(context, integration, error, attempts) {
+		if (integration) this.emitTelemetry(context, integration, "error", 0, error.code, error.message);
+		return {
+			success: false,
+			error,
+			metadata: {
+				latencyMs: 0,
+				connectionId: integration?.connection.meta.id ?? "unknown",
+				ownershipMode: integration?.connection.ownershipMode ?? "managed",
+				attempts
+			}
+		};
+	}
+	makeContext(slotId, operation, config) {
+		return {
+			tenantId: config.tenantId,
+			appId: config.appId,
+			environment: config.environment,
+			blueprintName: config.blueprintName,
+			blueprintVersion: config.blueprintVersion,
+			configVersion: config.configVersion,
+			slotId,
+			operation
+		};
+	}
+	errorCodeFor(error) {
+		if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") return error.code;
+		return "PROVIDER_ERROR";
+	}
+};
+function ensureConnectionReady(integration) {
+	const status = integration.connection.status;
+	if (status === "disconnected" || status === "error") throw new Error(`Integration connection "${integration.connection.meta.label}" is in status "${status}".`);
+}
+function connectionStatusLabel(status) {
+	switch (status) {
+		case "connected": return "connected";
+		case "disconnected": return "disconnected";
+		case "error": return "error";
+		case "unknown":
+		default: return "unknown";
+	}
+}
+
+//#endregion
+export { IntegrationCallGuard, connectionStatusLabel, ensureConnectionReady };

package/dist/secrets/env-secret-provider.js

@@ -1 +1,81 @@
-import{SecretProviderError as e,parseSecretUri as t}from"./provider.js";var n=class{id=`env`;aliases;constructor(e={}){this.aliases=e.aliases??{}}canHandle(e){let t=this.resolveEnvKey(e);return t!==void 0&&process.env[t]!==void 0}async getSecret(t){let n=this.resolveEnvKey(t);if(!n)throw new e({message:`Unable to resolve environment variable for reference "${t}".`,provider:this.id,reference:t,code:`INVALID`});let r=process.env[n];if(r===void 0)throw new e({message:`Environment variable "${n}" not found for reference "${t}".`,provider:this.id,reference:t,code:`NOT_FOUND`});return{data:Buffer.from(r,`utf-8`),version:`current`,metadata:{source:`env`,envKey:n},retrievedAt:new Date}}async setSecret(e,t){throw this.forbiddenError(`setSecret`,e)}async rotateSecret(e,t){throw this.forbiddenError(`rotateSecret`,e)}async deleteSecret(e){throw this.forbiddenError(`deleteSecret`,e)}resolveEnvKey(e){if(e){if(this.aliases[e])return this.aliases[e];if(!e.includes(`://`))return e;try{let n=t(e);return n.provider===`env`?n.path:n.extras?.env?n.extras.env:this.deriveEnvKey(n.path)}catch{return e}}}deriveEnvKey(e){if(e)return e.split(/[\/:\-\.]/).filter(Boolean).map(e=>e.replace(/[^a-zA-Z0-9]/g,`_`).replace(/_{2,}/g,`_`).toUpperCase()).join(`_`)}forbiddenError(t,n){return new e({message:`EnvSecretProvider is read-only. "${t}" is not allowed for ${n}.`,provider:this.id,reference:n,code:`FORBIDDEN`})}};export{n as EnvSecretProvider};
+import { SecretProviderError, parseSecretUri } from "./provider.js";
+
+//#region src/secrets/env-secret-provider.ts
+/**
+* Environment-variable backed secret provider. Read-only by design.
+* Allows overriding other secret providers by deriving environment variable
+* names from secret references (or by using explicit aliases).
+*/
+var EnvSecretProvider = class {
+	id = "env";
+	aliases;
+	constructor(options = {}) {
+		this.aliases = options.aliases ?? {};
+	}
+	canHandle(reference) {
+		const envKey = this.resolveEnvKey(reference);
+		return envKey !== void 0 && process.env[envKey] !== void 0;
+	}
+	async getSecret(reference) {
+		const envKey = this.resolveEnvKey(reference);
+		if (!envKey) throw new SecretProviderError({
+			message: `Unable to resolve environment variable for reference "${reference}".`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const value = process.env[envKey];
+		if (value === void 0) throw new SecretProviderError({
+			message: `Environment variable "${envKey}" not found for reference "${reference}".`,
+			provider: this.id,
+			reference,
+			code: "NOT_FOUND"
+		});
+		return {
+			data: Buffer.from(value, "utf-8"),
+			version: "current",
+			metadata: {
+				source: "env",
+				envKey
+			},
+			retrievedAt: /* @__PURE__ */ new Date()
+		};
+	}
+	async setSecret(reference, _payload) {
+		throw this.forbiddenError("setSecret", reference);
+	}
+	async rotateSecret(reference, _payload) {
+		throw this.forbiddenError("rotateSecret", reference);
+	}
+	async deleteSecret(reference) {
+		throw this.forbiddenError("deleteSecret", reference);
+	}
+	resolveEnvKey(reference) {
+		if (!reference) return;
+		if (this.aliases[reference]) return this.aliases[reference];
+		if (!reference.includes("://")) return reference;
+		try {
+			const parsed = parseSecretUri(reference);
+			if (parsed.provider === "env") return parsed.path;
+			if (parsed.extras?.env) return parsed.extras.env;
+			return this.deriveEnvKey(parsed.path);
+		} catch {
+			return reference;
+		}
+	}
+	deriveEnvKey(path) {
+		if (!path) return void 0;
+		return path.split(/[\/:\-\.]/).filter(Boolean).map((segment) => segment.replace(/[^a-zA-Z0-9]/g, "_").replace(/_{2,}/g, "_").toUpperCase()).join("_");
+	}
+	forbiddenError(operation, reference) {
+		return new SecretProviderError({
+			message: `EnvSecretProvider is read-only. "${operation}" is not allowed for ${reference}.`,
+			provider: this.id,
+			reference,
+			code: "FORBIDDEN"
+		});
+	}
+};
+
+//#endregion
+export { EnvSecretProvider };

package/dist/secrets/gcp-secret-manager.js

@@ -1 +1,229 @@
-import{SecretProviderError as e,normalizeSecretPayload as t,parseSecretUri as n}from"./provider.js";import{SecretManagerServiceClient as r,protos as i}from"@google-cloud/secret-manager";const a={automatic:{}};var o=class{id=`gcp-secret-manager`;client;explicitProjectId;replication;constructor(e={}){this.client=e.client??new r(e.clientOptions??{}),this.explicitProjectId=e.projectId,this.replication=e.defaultReplication??a}canHandle(e){try{return n(e).provider===`gcp`}catch{return!1}}async getSecret(t,n,r){let i=this.parseReference(t),a=this.buildVersionName(i,n?.version);try{let[n]=await this.client.accessSecretVersion({name:a},r??{}),i=n.payload;if(!i?.data)throw new e({message:`Secret payload empty for ${a}`,provider:this.id,reference:t,code:`UNKNOWN`});let o=s(n.name??a);return{data:i.data,version:o,metadata:i.dataCrc32c?{crc32c:i.dataCrc32c.toString()}:void 0,retrievedAt:new Date}}catch(e){throw c({error:e,provider:this.id,reference:t,operation:`access`})}}async setSecret(n,r){let i=this.parseReference(n),{secretName:a}=this.buildNames(i),o=t(r);await this.ensureSecretExists(i,r);try{let t=await this.client.addSecretVersion({parent:a,payload:{data:o}});if(!t)throw new e({message:`No version returned when adding secret version for ${a}`,provider:this.id,reference:n,code:`UNKNOWN`});let[r]=t,i=r?.name??`${a}/versions/latest`;return{reference:`gcp://${i}`,version:s(i)??`latest`}}catch(e){throw c({error:e,provider:this.id,reference:n,operation:`addSecretVersion`})}}async rotateSecret(e,t){return this.setSecret(e,t)}async deleteSecret(e){let t=this.parseReference(e),{secretName:n}=this.buildNames(t);try{await this.client.deleteSecret({name:n})}catch(t){throw c({error:t,provider:this.id,reference:e,operation:`delete`})}}parseReference(t){let r=n(t);if(r.provider!==`gcp`)throw new e({message:`Unsupported secret provider: ${r.provider}`,provider:this.id,reference:t,code:`INVALID`});let i=r.path.split(`/`).filter(Boolean);if(i.length<4||i[0]!==`projects`)throw new e({message:`Expected secret reference format gcp://projects/{project}/secrets/{secret}[(/versions/{version})] but received "${r.path}"`,provider:this.id,reference:t,code:`INVALID`});let a=i[1]??this.explicitProjectId;if(!a)throw new e({message:`Unable to resolve project or secret from reference "${r.path}"`,provider:this.id,reference:t,code:`INVALID`});let o=i.indexOf(`secrets`);if(o===-1||o+1>=i.length)throw new e({message:`Unable to resolve project or secret from reference "${r.path}"`,provider:this.id,reference:t,code:`INVALID`});let s=a,c=i[o+1];if(!c)throw new e({message:`Unable to resolve secret ID from reference "${r.path}"`,provider:this.id,reference:t,code:`INVALID`});let l=c,u=i.indexOf(`versions`);return{projectId:s,secretId:l,version:r.extras?.version??(u!==-1&&u+1<i.length?i[u+1]:void 0)}}buildNames(t){let n=t.projectId??this.explicitProjectId;if(!n)throw new e({message:`Project ID must be provided either in reference or provider configuration`,provider:this.id,reference:`gcp://projects//secrets/${t.secretId}`,code:`INVALID`});let r=`projects/${n}`;return{projectParent:r,secretName:`${r}/secrets/${t.secretId}`}}buildVersionName(e,t){let{secretName:n}=this.buildNames(e);return`${n}/versions/${t??e.version??`latest`}`}async ensureSecretExists(e,t){let{secretName:n,projectParent:r}=this.buildNames(e);try{await this.client.getSecret({name:n})}catch(i){let a=c({error:i,provider:this.id,reference:`gcp://${n}`,operation:`getSecret`,suppressThrow:!0});if(!a||a.code!==`NOT_FOUND`)throw a||i;try{await this.client.createSecret({parent:r,secretId:e.secretId,secret:{replication:this.replication,labels:t.labels}})}catch(e){throw c({error:e,provider:this.id,reference:`gcp://${n}`,operation:`createSecret`})}}}};function s(e){let t=e.split(`/`).filter(Boolean),n=t.indexOf(`versions`);if(!(n===-1||n+1>=t.length))return t[n+1]}function c(t){let{error:n,provider:r,reference:i,operation:a,suppressThrow:o}=t;if(n instanceof e)return n;let s=l(n),c=new e({message:n instanceof Error?n.message:`Unknown error during ${a}`,provider:r,reference:i,code:s,cause:n});if(o)return c;throw c}function l(e){if(typeof e!=`object`||!e)return`UNKNOWN`;let t=e.code;return t===5||t===`NOT_FOUND`?`NOT_FOUND`:t===6||t===`ALREADY_EXISTS`?`INVALID`:t===7||t===`PERMISSION_DENIED`||t===403?`FORBIDDEN`:t===3||t===`INVALID_ARGUMENT`?`INVALID`:`UNKNOWN`}export{o as GcpSecretManagerProvider};
+import { SecretProviderError, normalizeSecretPayload, parseSecretUri } from "./provider.js";
+import { SecretManagerServiceClient, protos } from "@google-cloud/secret-manager";
+
+//#region src/secrets/gcp-secret-manager.ts
+const DEFAULT_REPLICATION = { automatic: {} };
+var GcpSecretManagerProvider = class {
+	id = "gcp-secret-manager";
+	client;
+	explicitProjectId;
+	replication;
+	constructor(options = {}) {
+		this.client = options.client ?? new SecretManagerServiceClient(options.clientOptions ?? {});
+		this.explicitProjectId = options.projectId;
+		this.replication = options.defaultReplication ?? DEFAULT_REPLICATION;
+	}
+	canHandle(reference) {
+		try {
+			return parseSecretUri(reference).provider === "gcp";
+		} catch {
+			return false;
+		}
+	}
+	async getSecret(reference, options, callOptions) {
+		const location = this.parseReference(reference);
+		const secretVersionName = this.buildVersionName(location, options?.version);
+		try {
+			const [result] = await this.client.accessSecretVersion({ name: secretVersionName }, callOptions ?? {});
+			const payload = result.payload;
+			if (!payload?.data) throw new SecretProviderError({
+				message: `Secret payload empty for ${secretVersionName}`,
+				provider: this.id,
+				reference,
+				code: "UNKNOWN"
+			});
+			const version = extractVersionFromName(result.name ?? secretVersionName);
+			return {
+				data: payload.data,
+				version,
+				metadata: payload.dataCrc32c ? { crc32c: payload.dataCrc32c.toString() } : void 0,
+				retrievedAt: /* @__PURE__ */ new Date()
+			};
+		} catch (error) {
+			throw toSecretProviderError({
+				error,
+				provider: this.id,
+				reference,
+				operation: "access"
+			});
+		}
+	}
+	async setSecret(reference, payload) {
+		const location = this.parseReference(reference);
+		const { secretName } = this.buildNames(location);
+		const data = normalizeSecretPayload(payload);
+		await this.ensureSecretExists(location, payload);
+		try {
+			const response = await this.client.addSecretVersion({
+				parent: secretName,
+				payload: { data }
+			});
+			if (!response) throw new SecretProviderError({
+				message: `No version returned when adding secret version for ${secretName}`,
+				provider: this.id,
+				reference,
+				code: "UNKNOWN"
+			});
+			const [version] = response;
+			const versionName = version?.name ?? `${secretName}/versions/latest`;
+			return {
+				reference: `gcp://${versionName}`,
+				version: extractVersionFromName(versionName) ?? "latest"
+			};
+		} catch (error) {
+			throw toSecretProviderError({
+				error,
+				provider: this.id,
+				reference,
+				operation: "addSecretVersion"
+			});
+		}
+	}
+	async rotateSecret(reference, payload) {
+		return this.setSecret(reference, payload);
+	}
+	async deleteSecret(reference) {
+		const location = this.parseReference(reference);
+		const { secretName } = this.buildNames(location);
+		try {
+			await this.client.deleteSecret({ name: secretName });
+		} catch (error) {
+			throw toSecretProviderError({
+				error,
+				provider: this.id,
+				reference,
+				operation: "delete"
+			});
+		}
+	}
+	parseReference(reference) {
+		const parsed = parseSecretUri(reference);
+		if (parsed.provider !== "gcp") throw new SecretProviderError({
+			message: `Unsupported secret provider: ${parsed.provider}`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const segments = parsed.path.split("/").filter(Boolean);
+		if (segments.length < 4 || segments[0] !== "projects") throw new SecretProviderError({
+			message: `Expected secret reference format gcp://projects/{project}/secrets/{secret}[(/versions/{version})] but received "${parsed.path}"`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const projectIdCandidate = segments[1] ?? this.explicitProjectId;
+		if (!projectIdCandidate) throw new SecretProviderError({
+			message: `Unable to resolve project or secret from reference "${parsed.path}"`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const indexOfSecrets = segments.indexOf("secrets");
+		if (indexOfSecrets === -1 || indexOfSecrets + 1 >= segments.length) throw new SecretProviderError({
+			message: `Unable to resolve project or secret from reference "${parsed.path}"`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const resolvedProjectId = projectIdCandidate;
+		const secretIdCandidate = segments[indexOfSecrets + 1];
+		if (!secretIdCandidate) throw new SecretProviderError({
+			message: `Unable to resolve secret ID from reference "${parsed.path}"`,
+			provider: this.id,
+			reference,
+			code: "INVALID"
+		});
+		const secretId = secretIdCandidate;
+		const indexOfVersions = segments.indexOf("versions");
+		return {
+			projectId: resolvedProjectId,
+			secretId,
+			version: parsed.extras?.version ?? (indexOfVersions !== -1 && indexOfVersions + 1 < segments.length ? segments[indexOfVersions + 1] : void 0)
+		};
+	}
+	buildNames(location) {
+		const projectId = location.projectId ?? this.explicitProjectId;
+		if (!projectId) throw new SecretProviderError({
+			message: "Project ID must be provided either in reference or provider configuration",
+			provider: this.id,
+			reference: `gcp://projects//secrets/${location.secretId}`,
+			code: "INVALID"
+		});
+		const projectParent = `projects/${projectId}`;
+		return {
+			projectParent,
+			secretName: `${projectParent}/secrets/${location.secretId}`
+		};
+	}
+	buildVersionName(location, explicitVersion) {
+		const { secretName } = this.buildNames(location);
+		return `${secretName}/versions/${explicitVersion ?? location.version ?? "latest"}`;
+	}
+	async ensureSecretExists(location, payload) {
+		const { secretName, projectParent } = this.buildNames(location);
+		try {
+			await this.client.getSecret({ name: secretName });
+		} catch (error) {
+			const providerError = toSecretProviderError({
+				error,
+				provider: this.id,
+				reference: `gcp://${secretName}`,
+				operation: "getSecret",
+				suppressThrow: true
+			});
+			if (!providerError || providerError.code !== "NOT_FOUND") {
+				if (providerError) throw providerError;
+				throw error;
+			}
+			try {
+				await this.client.createSecret({
+					parent: projectParent,
+					secretId: location.secretId,
+					secret: {
+						replication: this.replication,
+						labels: payload.labels
+					}
+				});
+			} catch (creationError) {
+				throw toSecretProviderError({
+					error: creationError,
+					provider: this.id,
+					reference: `gcp://${secretName}`,
+					operation: "createSecret"
+				});
+			}
+		}
+	}
+};
+function extractVersionFromName(name) {
+	const segments = name.split("/").filter(Boolean);
+	const index = segments.indexOf("versions");
+	if (index === -1 || index + 1 >= segments.length) return;
+	return segments[index + 1];
+}
+function toSecretProviderError(params) {
+	const { error, provider, reference, operation, suppressThrow } = params;
+	if (error instanceof SecretProviderError) return error;
+	const code = deriveErrorCode(error);
+	const providerError = new SecretProviderError({
+		message: error instanceof Error ? error.message : `Unknown error during ${operation}`,
+		provider,
+		reference,
+		code,
+		cause: error
+	});
+	if (suppressThrow) return providerError;
+	throw providerError;
+}
+function deriveErrorCode(error) {
+	if (typeof error !== "object" || error === null) return "UNKNOWN";
+	const code = error.code;
+	if (code === 5 || code === "NOT_FOUND") return "NOT_FOUND";
+	if (code === 6 || code === "ALREADY_EXISTS") return "INVALID";
+	if (code === 7 || code === "PERMISSION_DENIED" || code === 403) return "FORBIDDEN";
+	if (code === 3 || code === "INVALID_ARGUMENT") return "INVALID";
+	return "UNKNOWN";
+}
+
+//#endregion
+export { GcpSecretManagerProvider };

package/dist/secrets/index.js

@@ -1 +1,6 @@
-import{SecretProviderError as e,normalizeSecretPayload as t,parseSecretUri as n}from"./provider.js";import{GcpSecretManagerProvider as r}from"./gcp-secret-manager.js";import{EnvSecretProvider as i}from"./env-secret-provider.js";import{SecretProviderManager as a}from"./manager.js";export{i as EnvSecretProvider,r as GcpSecretManagerProvider,e as SecretProviderError,a as SecretProviderManager,t as normalizeSecretPayload,n as parseSecretUri};
+import { SecretProviderError, normalizeSecretPayload, parseSecretUri } from "./provider.js";
+import { GcpSecretManagerProvider } from "./gcp-secret-manager.js";
+import { EnvSecretProvider } from "./env-secret-provider.js";
+import { SecretProviderManager } from "./manager.js";
+
+export { EnvSecretProvider, GcpSecretManagerProvider, SecretProviderError, SecretProviderManager, normalizeSecretPayload, parseSecretUri };

package/dist/secrets/manager.js

@@ -1 +1,103 @@
-import{SecretProviderError as e}from"./provider.js";var t=class{id;providers=[];registrationCounter=0;constructor(e={}){this.id=e.id??`secret-provider-manager`;let t=e.providers??[];for(let e of t)this.register(e.provider,{priority:e.priority})}register(e,t={}){return this.providers.push({provider:e,priority:t.priority??0,order:this.registrationCounter++}),this.providers.sort((e,t)=>e.priority===t.priority?e.order-t.order:t.priority-e.priority),this}canHandle(e){return this.providers.some(({provider:t})=>n(t,e))}async getSecret(t,r){let i=[];for(let{provider:a}of this.providers)if(n(a,t))try{return await a.getSecret(t,r)}catch(t){if(t instanceof e){if(i.push(t),t.code!==`NOT_FOUND`)break;continue}throw t}throw this.composeError(`getSecret`,t,i,r?.version)}async setSecret(e,t){return this.delegateToFirst(`setSecret`,e,n=>n.setSecret(e,t))}async rotateSecret(e,t){return this.delegateToFirst(`rotateSecret`,e,n=>n.rotateSecret(e,t))}async deleteSecret(e){await this.delegateToFirst(`deleteSecret`,e,t=>t.deleteSecret(e))}async delegateToFirst(t,r,i){let a=[];for(let{provider:t}of this.providers)if(n(t,r))try{return await i(t)}catch(t){if(t instanceof e){a.push(t);continue}throw t}throw this.composeError(t,r,a)}composeError(t,n,r,i){if(r.length===1){let[e]=r;if(e)return e}let a=[`No registered secret provider could ${t}`,`reference "${n}"`];return i&&a.push(`(version: ${i})`),r.length>1&&a.push(`Attempts: ${r.map(e=>`${e.provider}:${e.code}`).join(`, `)}`),new e({message:a.join(` `),provider:this.id,reference:n,code:r.length>0?r[r.length-1].code:`UNKNOWN`,cause:r})}};function n(e,t){try{return e.canHandle(t)}catch{return!1}}export{t as SecretProviderManager};
+import { SecretProviderError } from "./provider.js";
+
+//#region src/secrets/manager.ts
+/**
+* Composite secret provider that delegates to registered providers.
+* Providers are attempted in order of descending priority, respecting the
+* registration order for ties. This enables privileged overrides (e.g.
+* environment variables) while still supporting durable backends like GCP
+* Secret Manager.
+*/
+var SecretProviderManager = class {
+	id;
+	providers = [];
+	registrationCounter = 0;
+	constructor(options = {}) {
+		this.id = options.id ?? "secret-provider-manager";
+		const initialProviders = options.providers ?? [];
+		for (const entry of initialProviders) this.register(entry.provider, { priority: entry.priority });
+	}
+	register(provider, options = {}) {
+		this.providers.push({
+			provider,
+			priority: options.priority ?? 0,
+			order: this.registrationCounter++
+		});
+		this.providers.sort((a, b) => {
+			if (a.priority !== b.priority) return b.priority - a.priority;
+			return a.order - b.order;
+		});
+		return this;
+	}
+	canHandle(reference) {
+		return this.providers.some(({ provider }) => safeCanHandle(provider, reference));
+	}
+	async getSecret(reference, options) {
+		const errors = [];
+		for (const { provider } of this.providers) {
+			if (!safeCanHandle(provider, reference)) continue;
+			try {
+				return await provider.getSecret(reference, options);
+			} catch (error) {
+				if (error instanceof SecretProviderError) {
+					errors.push(error);
+					if (error.code !== "NOT_FOUND") break;
+					continue;
+				}
+				throw error;
+			}
+		}
+		throw this.composeError("getSecret", reference, errors, options?.version);
+	}
+	async setSecret(reference, payload) {
+		return this.delegateToFirst("setSecret", reference, (provider) => provider.setSecret(reference, payload));
+	}
+	async rotateSecret(reference, payload) {
+		return this.delegateToFirst("rotateSecret", reference, (provider) => provider.rotateSecret(reference, payload));
+	}
+	async deleteSecret(reference) {
+		await this.delegateToFirst("deleteSecret", reference, (provider) => provider.deleteSecret(reference));
+	}
+	async delegateToFirst(operation, reference, invoker) {
+		const errors = [];
+		for (const { provider } of this.providers) {
+			if (!safeCanHandle(provider, reference)) continue;
+			try {
+				return await invoker(provider);
+			} catch (error) {
+				if (error instanceof SecretProviderError) {
+					errors.push(error);
+					continue;
+				}
+				throw error;
+			}
+		}
+		throw this.composeError(operation, reference, errors);
+	}
+	composeError(operation, reference, errors, version) {
+		if (errors.length === 1) {
+			const [singleError] = errors;
+			if (singleError) return singleError;
+		}
+		const messageParts = [`No registered secret provider could ${operation}`, `reference "${reference}"`];
+		if (version) messageParts.push(`(version: ${version})`);
+		if (errors.length > 1) messageParts.push(`Attempts: ${errors.map((error) => `${error.provider}:${error.code}`).join(", ")}`);
+		return new SecretProviderError({
+			message: messageParts.join(" "),
+			provider: this.id,
+			reference,
+			code: errors.length > 0 ? errors[errors.length - 1].code : "UNKNOWN",
+			cause: errors
+		});
+	}
+};
+function safeCanHandle(provider, reference) {
+	try {
+		return provider.canHandle(reference);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { SecretProviderManager };

package/dist/secrets/provider.js

@@ -1 +1,58 @@
-import{Buffer as e}from"node:buffer";var t=class extends Error{provider;reference;code;cause;constructor(e){super(e.message),this.name=`SecretProviderError`,this.provider=e.provider,this.reference=e.reference,this.code=e.code??`UNKNOWN`,this.cause=e.cause}};function n(e){if(!e)throw new t({message:`Secret reference cannot be empty`,provider:`unknown`,reference:e,code:`INVALID`});let[n,r]=e.split(`://`);if(!n||!r)throw new t({message:`Invalid secret reference: ${e}`,provider:`unknown`,reference:e,code:`INVALID`});let i=r.indexOf(`?`);if(i===-1)return{provider:n,path:r};let a=r.slice(0,i),o=r.slice(i+1);return{provider:n,path:a,extras:Object.fromEntries(o.split(`&`).filter(Boolean).map(e=>{let[t,n]=e.split(`=`),r=t??``,i=n??``;return[decodeURIComponent(r),decodeURIComponent(i)]}))}}function r(t){return t.data instanceof Uint8Array?t.data:t.encoding===`base64`?e.from(t.data,`base64`):t.encoding===`binary`?e.from(t.data,`binary`):e.from(t.data,`utf-8`)}export{t as SecretProviderError,r as normalizeSecretPayload,n as parseSecretUri};
+import { Buffer } from "node:buffer";
+
+//#region src/secrets/provider.ts
+var SecretProviderError = class extends Error {
+	provider;
+	reference;
+	code;
+	cause;
+	constructor(params) {
+		super(params.message);
+		this.name = "SecretProviderError";
+		this.provider = params.provider;
+		this.reference = params.reference;
+		this.code = params.code ?? "UNKNOWN";
+		this.cause = params.cause;
+	}
+};
+function parseSecretUri(reference) {
+	if (!reference) throw new SecretProviderError({
+		message: "Secret reference cannot be empty",
+		provider: "unknown",
+		reference,
+		code: "INVALID"
+	});
+	const [scheme, rest] = reference.split("://");
+	if (!scheme || !rest) throw new SecretProviderError({
+		message: `Invalid secret reference: ${reference}`,
+		provider: "unknown",
+		reference,
+		code: "INVALID"
+	});
+	const queryIndex = rest.indexOf("?");
+	if (queryIndex === -1) return {
+		provider: scheme,
+		path: rest
+	};
+	const path = rest.slice(0, queryIndex);
+	const query = rest.slice(queryIndex + 1);
+	return {
+		provider: scheme,
+		path,
+		extras: Object.fromEntries(query.split("&").filter(Boolean).map((pair) => {
+			const [keyRaw, valueRaw] = pair.split("=");
+			const key = keyRaw ?? "";
+			const value = valueRaw ?? "";
+			return [decodeURIComponent(key), decodeURIComponent(value)];
+		}))
+	};
+}
+function normalizeSecretPayload(payload) {
+	if (payload.data instanceof Uint8Array) return payload.data;
+	if (payload.encoding === "base64") return Buffer.from(payload.data, "base64");
+	if (payload.encoding === "binary") return Buffer.from(payload.data, "binary");
+	return Buffer.from(payload.data, "utf-8");
+}
+
+//#endregion
+export { SecretProviderError, normalizeSecretPayload, parseSecretUri };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/integration.runtime",
-  "version": "0.0.0-canary-20251217063201",
+  "version": "0.0.0-canary-20251217072406",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,14 +23,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "0.0.0-canary-20251217063201",
-    "@lssm/lib.logger": "0.0.0-canary-20251217063201",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217072406",
+    "@lssm/lib.logger": "0.0.0-canary-20251217072406",
     "@google-cloud/secret-manager": "^6.1.1",
     "google-gax": "^5.0.0"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217063201",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217063201",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217072406",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217072406",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },