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

package/dist/health.d.ts

@@ -0,0 +1,21 @@
+import { IntegrationContext, IntegrationTelemetryEmitter } from "./runtime.js";
+import { IntegrationConnectionHealth } from "@lssm/lib.contracts/integrations/connection";
+
+//#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
+export { IntegrationHealthCheckExecutor, IntegrationHealthCheckResult, IntegrationHealthService, IntegrationHealthServiceOptions };

package/dist/health.js

@@ -0,0 +1 @@
+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};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, normalizeSecretPayload, parseSecretUri } from "./secrets/provider.js";
+import { IntegrationCallContext, IntegrationCallError, IntegrationCallGuard, IntegrationCallGuardOptions, IntegrationCallResult, IntegrationContext, IntegrationInvocationStatus, IntegrationTelemetryEmitter, IntegrationTelemetryEvent, IntegrationTraceMetadata, connectionStatusLabel, ensureConnectionReady } from "./runtime.js";
+import { IntegrationHealthCheckExecutor, IntegrationHealthCheckResult, IntegrationHealthService, IntegrationHealthServiceOptions } from "./health.js";
+import { GcpSecretManagerProvider } from "./secrets/gcp-secret-manager.js";
+import { EnvSecretProvider } from "./secrets/env-secret-provider.js";
+import { SecretProviderManager, SecretProviderManagerOptions } from "./secrets/manager.js";
+import "./secrets/index.js";
+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.js

@@ -0,0 +1 @@
+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};

package/dist/runtime.d.ts

@@ -0,0 +1,99 @@
+import { SecretProvider } from "./secrets/provider.js";
+import { ConnectionStatus, IntegrationConnection } from "@lssm/lib.contracts/integrations/connection";
+import { ResolvedAppConfig, ResolvedIntegration } from "@lssm/lib.contracts/app-config/runtime";
+import { IntegrationSpec } from "@lssm/lib.contracts/integrations/spec";
+
+//#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
+export { IntegrationCallContext, IntegrationCallError, IntegrationCallGuard, IntegrationCallGuardOptions, IntegrationCallResult, IntegrationContext, IntegrationInvocationStatus, IntegrationTelemetryEmitter, IntegrationTelemetryEvent, IntegrationTraceMetadata, connectionStatusLabel, ensureConnectionReady };

package/dist/runtime.js

@@ -0,0 +1 @@
+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};

package/dist/secrets/env-secret-provider.d.ts

@@ -0,0 +1,31 @@
+import { SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from "./provider.js";
+
+//#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
+export { EnvSecretProvider };

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

@@ -0,0 +1 @@
+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};

package/dist/secrets/gcp-secret-manager.d.ts

@@ -0,0 +1,32 @@
+import { SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from "./provider.js";
+import { SecretManagerServiceClient, protos } from "@google-cloud/secret-manager";
+import { CallOptions } from "google-gax";
+
+//#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
+export { GcpSecretManagerProvider };

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

@@ -0,0 +1 @@
+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};

package/dist/secrets/index.d.ts

@@ -0,0 +1,5 @@
+import { ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, normalizeSecretPayload, parseSecretUri } from "./provider.js";
+import { GcpSecretManagerProvider } from "./gcp-secret-manager.js";
+import { EnvSecretProvider } from "./env-secret-provider.js";
+import { SecretProviderManager, SecretProviderManagerOptions } from "./manager.js";
+export { EnvSecretProvider, GcpSecretManagerProvider, ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretProviderManager, SecretProviderManagerOptions, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, normalizeSecretPayload, parseSecretUri };

package/dist/secrets/index.js

@@ -0,0 +1 @@
+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};

package/dist/secrets/manager.d.ts

@@ -0,0 +1,47 @@
+import { SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from "./provider.js";
+
+//#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): 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 = Parameters<SecretProvider['getSecret']>[1];
+//#endregion
+export { SecretProviderManager, SecretProviderManagerOptions };

package/dist/secrets/manager.js

@@ -0,0 +1 @@
+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};

package/dist/secrets/provider.d.ts

@@ -0,0 +1,52 @@
+//#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
+export { ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, normalizeSecretPayload, parseSecretUri };

package/dist/secrets/provider.js

@@ -0,0 +1 @@
+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};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/integration.runtime",
-  "version": "0.0.0-canary-20251217060834",
+  "version": "0.0.0-canary-20251217063201",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -23,26 +23,26 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "0.0.0-canary-20251217060834",
-    "@lssm/lib.logger": "0.0.0-canary-20251217060834",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217063201",
+    "@lssm/lib.logger": "0.0.0-canary-20251217063201",
     "@google-cloud/secret-manager": "^6.1.1",
     "google-gax": "^5.0.0"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217060834",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217060834",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217063201",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217063201",
     "tsdown": "^0.17.4",
     "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",
+    ".": "./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",
     "./*": "./*"
   },
   "publishConfig": {