@lssm/integration.runtime 0.0.0-canary-20251213172311

package/README.md

@@ -0,0 +1,7 @@
+# `@lssm/integration.runtime`
+
+Runtime layer for ContractSpec integrations (secret providers, call guards, health checks).
+
+This package depends on `@lssm/lib.contracts` for integration specs, connections, and provider interface types.
+
+

package/dist/index.d.mts

@@ -0,0 +1,267 @@
+import { SecretManagerServiceClient, protos } from "@google-cloud/secret-manager";
+import { ResolvedAppConfig, ResolvedIntegration } from "@lssm/lib.contracts/app-config/runtime";
+import { ConnectionStatus, IntegrationConnection, IntegrationConnectionHealth } from "@lssm/lib.contracts/integrations/connection";
+import { IntegrationSpec } from "@lssm/lib.contracts/integrations/spec";
+import { CallOptions } from "google-gax";
+
+//#region src/secrets/provider.d.ts
+type SecretReference = string;
+interface SecretValue {
+  data: Uint8Array;
+  version?: string;
+  metadata?: Record<string, string>;
+  retrievedAt: Date;
+}
+interface SecretFetchOptions {
+  version?: string;
+}
+type SecretPayloadEncoding = 'utf-8' | 'base64' | 'binary';
+interface SecretWritePayload {
+  data: string | Uint8Array;
+  encoding?: SecretPayloadEncoding;
+  contentType?: string;
+  labels?: Record<string, string>;
+}
+interface SecretRotationResult {
+  reference: SecretReference;
+  version: string;
+}
+interface SecretProvider {
+  readonly id: string;
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+}
+interface ParsedSecretUri {
+  provider: string;
+  path: string;
+  extras?: Record<string, string>;
+}
+declare class SecretProviderError extends Error {
+  readonly provider: string;
+  readonly reference: SecretReference;
+  readonly code: 'NOT_FOUND' | 'FORBIDDEN' | 'INVALID' | 'UNKNOWN';
+  readonly cause?: unknown;
+  constructor(params: {
+    message: string;
+    provider: string;
+    reference: SecretReference;
+    code?: SecretProviderError['code'];
+    cause?: unknown;
+  });
+}
+declare function parseSecretUri(reference: SecretReference): ParsedSecretUri;
+declare function normalizeSecretPayload(payload: SecretWritePayload): Uint8Array;
+//#endregion
+//#region src/runtime.d.ts
+interface IntegrationTraceMetadata {
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+}
+interface IntegrationTelemetryEvent {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  integrationKey: string;
+  integrationVersion: number;
+  connectionId: string;
+  status: 'success' | 'error';
+  durationMs?: number;
+  errorCode?: string;
+  errorMessage?: string;
+  occurredAt: Date;
+  metadata?: Record<string, string | number | boolean>;
+}
+interface IntegrationTelemetryEmitter {
+  record(event: IntegrationTelemetryEvent): Promise<void> | void;
+}
+type IntegrationInvocationStatus = 'success' | 'error';
+interface IntegrationContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  spec: IntegrationSpec;
+  connection: IntegrationConnection;
+  secretProvider: SecretProvider;
+  secretReference: string;
+  trace: IntegrationTraceMetadata;
+  config?: Record<string, unknown>;
+}
+interface IntegrationCallContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  slotId: string;
+  operation: string;
+}
+interface IntegrationCallError {
+  code: string;
+  message: string;
+  retryable: boolean;
+  cause?: unknown;
+}
+interface IntegrationCallResult<T> {
+  success: boolean;
+  data?: T;
+  error?: IntegrationCallError;
+  metadata: {
+    latencyMs: number;
+    connectionId: string;
+    ownershipMode: IntegrationConnection['ownershipMode'];
+    attempts: number;
+  };
+}
+interface IntegrationCallGuardOptions {
+  telemetry?: IntegrationTelemetryEmitter;
+  maxAttempts?: number;
+  backoffMs?: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+}
+declare class IntegrationCallGuard {
+  private readonly secretProvider;
+  private readonly telemetry?;
+  private readonly maxAttempts;
+  private readonly backoffMs;
+  private readonly shouldRetry;
+  private readonly sleep;
+  private readonly now;
+  constructor(secretProvider: SecretProvider, options?: IntegrationCallGuardOptions);
+  executeWithGuards<T>(slotId: string, operation: string, _input: unknown, resolvedConfig: ResolvedAppConfig, executor: (connection: IntegrationConnection, secrets: Record<string, string>) => Promise<T>): Promise<IntegrationCallResult<T>>;
+  private findIntegration;
+  private fetchSecrets;
+  private parseSecret;
+  private emitTelemetry;
+  private failure;
+  private makeContext;
+  private errorCodeFor;
+}
+declare function ensureConnectionReady(integration: ResolvedIntegration): void;
+declare function connectionStatusLabel(status: ConnectionStatus): string;
+//#endregion
+//#region src/health.d.ts
+interface IntegrationHealthCheckResult extends IntegrationConnectionHealth {
+  metadata?: Record<string, string>;
+}
+type IntegrationHealthCheckExecutor = (context: IntegrationContext) => Promise<void>;
+interface IntegrationHealthServiceOptions {
+  telemetry?: IntegrationTelemetryEmitter;
+  now?: () => Date;
+}
+declare class IntegrationHealthService {
+  private readonly telemetry?;
+  private readonly nowFn;
+  constructor(options?: IntegrationHealthServiceOptions);
+  check(context: IntegrationContext, executor: IntegrationHealthCheckExecutor): Promise<IntegrationHealthCheckResult>;
+  private emitTelemetry;
+}
+//#endregion
+//#region src/secrets/gcp-secret-manager.d.ts
+type SecretManagerClient = SecretManagerServiceClient;
+interface GcpSecretManagerProviderOptions {
+  projectId?: string;
+  client?: SecretManagerClient;
+  clientOptions?: ConstructorParameters<typeof SecretManagerServiceClient>[0];
+  defaultReplication?: protos.google.cloud.secretmanager.v1.IReplication;
+}
+declare class GcpSecretManagerProvider implements SecretProvider {
+  readonly id = "gcp-secret-manager";
+  private readonly client;
+  private readonly explicitProjectId?;
+  private readonly replication;
+  constructor(options?: GcpSecretManagerProviderOptions);
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: {
+    version?: string;
+  }, callOptions?: CallOptions): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private parseReference;
+  private buildNames;
+  private buildVersionName;
+  private ensureSecretExists;
+}
+//#endregion
+//#region src/secrets/env-secret-provider.d.ts
+interface EnvSecretProviderOptions {
+  /**
+   * Optional map to alias secret references to environment variable names.
+   * Useful when referencing secrets from other providers (e.g. gcp://...)
+   * while still allowing local overrides.
+   */
+  aliases?: Record<string, string>;
+}
+/**
+ * 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).
+ */
+declare class EnvSecretProvider implements SecretProvider {
+  readonly id = "env";
+  private readonly aliases;
+  constructor(options?: EnvSecretProviderOptions);
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference): Promise<SecretValue>;
+  setSecret(reference: SecretReference, _payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, _payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private resolveEnvKey;
+  private deriveEnvKey;
+  private forbiddenError;
+}
+//#endregion
+//#region src/secrets/manager.d.ts
+interface RegisterOptions {
+  /**
+   * Larger priority values are attempted first. Defaults to 0.
+   */
+  priority?: number;
+}
+interface SecretProviderManagerOptions {
+  /**
+   * Override manager identifier. Defaults to "secret-provider-manager".
+   */
+  id?: string;
+  /**
+   * Providers to pre-register. They are registered in array order with
+   * descending priority (first entry wins ties).
+   */
+  providers?: {
+    provider: SecretProvider;
+    priority?: number;
+  }[];
+}
+/**
+ * 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.
+ */
+declare class SecretProviderManager implements SecretProvider {
+  readonly id: string;
+  private readonly providers;
+  private registrationCounter;
+  constructor(options?: SecretProviderManagerOptions);
+  register(provider: SecretProvider, options?: RegisterOptions): this;
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: SecretFetchOptions$1): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private delegateToFirst;
+  private composeError;
+}
+type SecretFetchOptions$1 = Parameters<SecretProvider['getSecret']>[1];
+//#endregion
+export { EnvSecretProvider, GcpSecretManagerProvider, IntegrationCallContext, IntegrationCallError, IntegrationCallGuard, IntegrationCallGuardOptions, IntegrationCallResult, IntegrationContext, IntegrationHealthCheckExecutor, IntegrationHealthCheckResult, IntegrationHealthService, IntegrationHealthServiceOptions, IntegrationInvocationStatus, IntegrationTelemetryEmitter, IntegrationTelemetryEvent, IntegrationTraceMetadata, ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretProviderManager, SecretProviderManagerOptions, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, connectionStatusLabel, ensureConnectionReady, normalizeSecretPayload, parseSecretUri };

package/dist/index.mjs

@@ -0,0 +1,714 @@
+import { performance } from "node:perf_hooks";
+import { Buffer as Buffer$1 } from "node:buffer";
+import { SecretManagerServiceClient, protos } from "@google-cloud/secret-manager";
+
+//#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
+//#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
+//#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$1.from(payload.data, "base64");
+	if (payload.encoding === "binary") return Buffer$1.from(payload.data, "binary");
+	return Buffer$1.from(payload.data, "utf-8");
+}
+
+//#endregion
+//#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
+//#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
+//#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 { EnvSecretProvider, GcpSecretManagerProvider, IntegrationCallGuard, IntegrationHealthService, SecretProviderError, SecretProviderManager, connectionStatusLabel, ensureConnectionReady, normalizeSecretPayload, parseSecretUri };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lssm/integration.runtime",
+  "version": "0.0.0-canary-20251213172311",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.logger": "workspace:*",
+    "@google-cloud/secret-manager": "^6.1.1",
+    "google-gax": "^5.0.0"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./health": "./src/health.ts",
+    "./runtime": "./src/runtime.ts",
+    "./secrets": "./src/secrets/index.ts",
+    "./secrets/env-secret-provider": "./src/secrets/env-secret-provider.ts",
+    "./secrets/gcp-secret-manager": "./src/secrets/gcp-secret-manager.ts",
+    "./secrets/manager": "./src/secrets/manager.ts",
+    "./secrets/provider": "./src/secrets/provider.ts",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./health": "./dist/health.js",
+      "./runtime": "./dist/runtime.js",
+      "./secrets": "./dist/secrets/index.js",
+      "./secrets/env-secret-provider": "./dist/secrets/env-secret-provider.js",
+      "./secrets/gcp-secret-manager": "./dist/secrets/gcp-secret-manager.js",
+      "./secrets/manager": "./dist/secrets/manager.js",
+      "./secrets/provider": "./dist/secrets/provider.js",
+      "./*": "./*"
+    }
+  }
+}