@contractspec/integration.runtime 1.56.1 → 1.58.0

package/dist/node/runtime.js

@@ -0,0 +1,208 @@
+// src/runtime.ts
+import { performance } from "node:perf_hooks";
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_BACKOFF_MS = 250;
+
+class IntegrationCallGuard {
+  secretProvider;
+  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 ?? (() => 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
+      }, undefined, {
+        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";
+  }
+}
+export {
+  ensureConnectionReady,
+  connectionStatusLabel,
+  IntegrationCallGuard
+};

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

@@ -0,0 +1,158 @@
+// src/secrets/provider.ts
+import { Buffer as Buffer2 } from "node:buffer";
+
+class SecretProviderError 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);
+  const 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)];
+  }));
+  return {
+    provider: scheme,
+    path,
+    extras
+  };
+}
+function normalizeSecretPayload(payload) {
+  if (payload.data instanceof Uint8Array) {
+    return payload.data;
+  }
+  if (payload.encoding === "base64") {
+    return Buffer2.from(payload.data, "base64");
+  }
+  if (payload.encoding === "binary") {
+    return Buffer2.from(payload.data, "binary");
+  }
+  return Buffer2.from(payload.data, "utf-8");
+}
+
+// src/secrets/env-secret-provider.ts
+class EnvSecretProvider {
+  id = "env";
+  aliases;
+  constructor(options = {}) {
+    this.aliases = options.aliases ?? {};
+  }
+  canHandle(reference) {
+    const envKey = this.resolveEnvKey(reference);
+    return envKey !== undefined && process.env[envKey] !== undefined;
+  }
+  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 === undefined) {
+      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: 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;
+    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"
+    });
+  }
+}
+export {
+  EnvSecretProvider
+};

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

@@ -0,0 +1,346 @@
+// src/secrets/provider.ts
+import { Buffer } from "node:buffer";
+
+class SecretProviderError 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);
+  const 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)];
+  }));
+  return {
+    provider: scheme,
+    path,
+    extras
+  };
+}
+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");
+}
+
+// src/secrets/gcp-secret-manager.ts
+import {
+  SecretManagerServiceClient
+} from "@google-cloud/secret-manager";
+var DEFAULT_REPLICATION = {
+  automatic: {}
+};
+
+class GcpSecretManagerProvider {
+  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 {
+      const parsed = parseSecretUri(reference);
+      return parsed.provider === "gcp";
+    } catch {
+      return false;
+    }
+  }
+  async getSecret(reference, options, callOptions) {
+    const location = this.parseReference(reference);
+    const secretVersionName = this.buildVersionName(location, options?.version);
+    try {
+      const response = await this.client.accessSecretVersion({
+        name: secretVersionName
+      }, callOptions ?? {});
+      const [result] = response;
+      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() } : undefined,
+        retrievedAt: 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");
+    const version = parsed.extras?.version ?? (indexOfVersions !== -1 && indexOfVersions + 1 < segments.length ? segments[indexOfVersions + 1] : undefined);
+    return {
+      projectId: resolvedProjectId,
+      secretId,
+      version
+    };
+  }
+  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}`;
+    const secretName = `${projectParent}/secrets/${location.secretId}`;
+    return {
+      projectParent,
+      secretName
+    };
+  }
+  buildVersionName(location, explicitVersion) {
+    const { secretName } = this.buildNames(location);
+    const version = explicitVersion ?? location.version ?? "latest";
+    return `${secretName}/versions/${version}`;
+  }
+  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) {
+        const creationProviderError = toSecretProviderError({
+          error: creationError,
+          provider: this.id,
+          reference: `gcp://${secretName}`,
+          operation: "createSecret"
+        });
+        throw creationProviderError;
+      }
+    }
+  }
+}
+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 message = error instanceof Error ? error.message : `Unknown error during ${operation}`;
+  const providerError = new SecretProviderError({
+    message,
+    provider,
+    reference,
+    code,
+    cause: error
+  });
+  if (suppressThrow) {
+    return providerError;
+  }
+  throw providerError;
+}
+function deriveErrorCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return "UNKNOWN";
+  }
+  const errorAny = error;
+  const code = errorAny.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";
+}
+export {
+  GcpSecretManagerProvider
+};