@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/secrets/scaleway-secret-manager.js

@@ -0,0 +1,375 @@
+// @bun
+// src/integrations/secrets/provider.ts
+import { Buffer } from "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/integrations/secrets/scaleway-secret-manager.ts
+import { Buffer as Buffer2 } from "buffer";
+var UUID_V4_LIKE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+class ScalewaySecretManagerProvider {
+  id = "scaleway-secret-manager";
+  token;
+  defaultRegion;
+  defaultProjectId;
+  baseUrl;
+  fetchFn;
+  constructor(options = {}) {
+    this.token = options.token ?? process.env.SCW_SECRET_KEY ?? process.env.SCALEWAY_SECRET_KEY ?? "";
+    this.defaultRegion = options.defaultRegion ?? process.env.SCW_DEFAULT_REGION ?? process.env.SCW_REGION;
+    this.defaultProjectId = options.defaultProjectId ?? process.env.SCW_DEFAULT_PROJECT_ID ?? process.env.SCW_PROJECT_ID;
+    this.baseUrl = options.baseUrl ?? "https://api.scaleway.com";
+    this.fetchFn = options.fetch ?? fetch;
+  }
+  canHandle(reference) {
+    try {
+      const parsed = parseSecretUri(reference);
+      return parsed.provider === "scw" && (parsed.path === "secret-manager" || parsed.path.startsWith("secret-manager/"));
+    } catch {
+      return false;
+    }
+  }
+  async getSecret(reference, options) {
+    const location = this.parseReference(reference);
+    if (!this.token) {
+      throw new SecretProviderError({
+        message: "Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",
+        provider: this.id,
+        reference,
+        code: "FORBIDDEN"
+      });
+    }
+    if (!UUID_V4_LIKE.test(location.secretIdOrName)) {
+      throw new SecretProviderError({
+        message: "Scaleway getSecret requires a secretId (uuid) reference, not a secret name.",
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    const revision = options?.version ?? location.revision ?? "latest";
+    const url = `${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(location.region)}/secrets/${encodeURIComponent(location.secretIdOrName)}/versions/${encodeURIComponent(revision)}/access`;
+    const response = await this.fetchFn(url, {
+      method: "GET",
+      headers: {
+        "X-Auth-Token": this.token
+      }
+    });
+    if (!response.ok) {
+      throw await toScalewayError({
+        response,
+        provider: this.id,
+        reference,
+        operation: "getSecret"
+      });
+    }
+    const payload = await response.json();
+    const dataB64 = extractScalewayData(payload);
+    return {
+      data: Buffer2.from(dataB64, "base64"),
+      version: revision,
+      metadata: {
+        region: location.region,
+        secretId: location.secretIdOrName
+      },
+      retrievedAt: new Date
+    };
+  }
+  async setSecret(reference, payload) {
+    const location = this.parseReference(reference);
+    if (!this.token) {
+      throw new SecretProviderError({
+        message: "Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",
+        provider: this.id,
+        reference,
+        code: "FORBIDDEN"
+      });
+    }
+    const bytes = normalizeSecretPayload(payload);
+    const encoded = Buffer2.from(bytes).toString("base64");
+    const secretId = UUID_V4_LIKE.test(location.secretIdOrName) ? location.secretIdOrName : await this.createSecret({
+      region: location.region,
+      name: location.secretIdOrName,
+      reference
+    });
+    const version = await this.createSecretVersion({
+      region: location.region,
+      secretId,
+      dataB64: encoded,
+      reference
+    });
+    return {
+      reference: this.buildReference(location.region, secretId, {
+        version
+      }),
+      version
+    };
+  }
+  async rotateSecret(reference, payload) {
+    return this.setSecret(reference, payload);
+  }
+  async deleteSecret(reference) {
+    const location = this.parseReference(reference);
+    if (!this.token) {
+      throw new SecretProviderError({
+        message: "Scaleway secret manager token is missing (set SCW_SECRET_KEY / SCALEWAY_SECRET_KEY).",
+        provider: this.id,
+        reference,
+        code: "FORBIDDEN"
+      });
+    }
+    if (!UUID_V4_LIKE.test(location.secretIdOrName)) {
+      throw new SecretProviderError({
+        message: "Scaleway deleteSecret requires a secretId (uuid) reference, not a secret name.",
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    const url = `${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(location.region)}/secrets/${encodeURIComponent(location.secretIdOrName)}`;
+    const response = await this.fetchFn(url, {
+      method: "DELETE",
+      headers: {
+        "X-Auth-Token": this.token
+      }
+    });
+    if (!response.ok) {
+      throw await toScalewayError({
+        response,
+        provider: this.id,
+        reference,
+        operation: "deleteSecret"
+      });
+    }
+  }
+  parseReference(reference) {
+    const parsed = parseSecretUri(reference);
+    if (parsed.provider !== "scw") {
+      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 < 2 || segments[0] !== "secret-manager") {
+      throw new SecretProviderError({
+        message: "Expected secret reference format scw://secret-manager/{region}/{secretIdOrName}[?version=...]",
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    const region = segments[1] ?? this.defaultRegion;
+    if (!region) {
+      throw new SecretProviderError({
+        message: "Scaleway region must be provided either in reference (scw://secret-manager/{region}/...) or via SCW_DEFAULT_REGION/SCW_REGION.",
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    const secretIdOrName = segments.slice(2).join("/");
+    if (!secretIdOrName) {
+      throw new SecretProviderError({
+        message: `Unable to resolve secret id/name from reference "${parsed.path}"`,
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    return {
+      region,
+      secretIdOrName,
+      revision: parsed.extras?.version
+    };
+  }
+  async createSecret(params) {
+    const projectId = this.defaultProjectId;
+    if (!projectId) {
+      throw new SecretProviderError({
+        message: "Scaleway project id is required to create secrets by name (set SCW_DEFAULT_PROJECT_ID/SCW_PROJECT_ID).",
+        provider: this.id,
+        reference: params.reference,
+        code: "INVALID"
+      });
+    }
+    const url = `${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(params.region)}/secrets`;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Auth-Token": this.token
+      },
+      body: JSON.stringify({
+        name: params.name,
+        project_id: projectId
+      })
+    });
+    if (!response.ok) {
+      throw await toScalewayError({
+        response,
+        provider: this.id,
+        reference: params.reference,
+        operation: "createSecret"
+      });
+    }
+    const payload = await response.json();
+    const secretId = extractScalewaySecretId(payload);
+    return secretId;
+  }
+  async createSecretVersion(params) {
+    const url = `${this.baseUrl}/secret-manager/v1beta1/regions/${encodeURIComponent(params.region)}/secrets/${encodeURIComponent(params.secretId)}/versions`;
+    const response = await this.fetchFn(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Auth-Token": this.token
+      },
+      body: JSON.stringify({
+        data: params.dataB64
+      })
+    });
+    if (!response.ok) {
+      throw await toScalewayError({
+        response,
+        provider: this.id,
+        reference: params.reference,
+        operation: "createSecretVersion"
+      });
+    }
+    const payload = await response.json();
+    return extractScalewayRevision(payload) ?? "latest";
+  }
+  buildReference(region, secretId, extras) {
+    const base = `scw://secret-manager/${region}/${secretId}`;
+    const query = extras ? Object.entries(extras).filter(([, value]) => Boolean(value)).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&") : "";
+    return query ? `${base}?${query}` : base;
+  }
+}
+function extractScalewayData(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid scaleway secret payload");
+  }
+  const record = payload;
+  if (typeof record.data === "string" && record.data) {
+    return record.data;
+  }
+  throw new Error("Scaleway secret payload is missing data");
+}
+function extractScalewaySecretId(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid scaleway createSecret payload");
+  }
+  const record = payload;
+  if (typeof record.id === "string" && record.id) {
+    return record.id;
+  }
+  throw new Error("Scaleway createSecret response is missing id");
+}
+function extractScalewayRevision(payload) {
+  if (!payload || typeof payload !== "object") {
+    return;
+  }
+  const record = payload;
+  if (typeof record.revision === "number") {
+    return String(record.revision);
+  }
+  if (typeof record.revision === "string" && record.revision) {
+    return record.revision;
+  }
+  if (typeof record.id === "string" && record.id) {
+    return record.id;
+  }
+  return;
+}
+async function toScalewayError(params) {
+  const { response, provider, reference, operation } = params;
+  const code = response.status === 404 ? "NOT_FOUND" : response.status === 401 || response.status === 403 ? "FORBIDDEN" : response.status >= 400 && response.status < 500 ? "INVALID" : "UNKNOWN";
+  const bodyText = await safeReadBody(response);
+  const message = bodyText ? `Scaleway Secret Manager ${operation} failed (${response.status}): ${bodyText}` : `Scaleway Secret Manager ${operation} failed (${response.status})`;
+  return new SecretProviderError({
+    message,
+    provider,
+    reference,
+    code
+  });
+}
+async function safeReadBody(response) {
+  try {
+    const text = await response.text();
+    const trimmed = text.trim();
+    return trimmed.length ? trimmed : undefined;
+  } catch {
+    return;
+  }
+}
+export {
+  ScalewaySecretManagerProvider
+};

package/dist/integrations/secrets-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Secret Provider types for integrations
+ * These are core type definitions that don't require runtime dependencies.
+ */
+export interface SecretValue {
+    data: Uint8Array;
+    version?: string;
+    metadata?: Record<string, string>;
+}
+export interface SecretProvider {
+    id: string;
+    canHandle(reference: string): boolean;
+    getSecret(reference: string): Promise<SecretValue>;
+}

package/dist/integrations/secrets-types.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/spec.d.ts

@@ -0,0 +1,72 @@
+import type { OwnerShipMeta } from '@contractspec/lib.contracts-spec/ownership';
+import type { CapabilityRef, CapabilityRequirement } from '@contractspec/lib.contracts-spec/capabilities';
+import { SpecContractRegistry } from '@contractspec/lib.contracts-spec/registry';
+export type IntegrationCategory = 'payments' | 'email' | 'calendar' | 'sms' | 'ai-llm' | 'ai-voice' | 'analytics' | 'speech-to-text' | 'vector-db' | 'storage' | 'accounting' | 'crm' | 'helpdesk' | 'project-management' | 'open-banking' | 'meeting-recorder' | 'database' | 'custom';
+export type IntegrationOwnershipMode = 'managed' | 'byok';
+export interface IntegrationMeta extends OwnerShipMeta {
+    category: IntegrationCategory;
+}
+export interface IntegrationCapabilityMapping {
+    /** Which CapabilitySpec this integration provides. */
+    provides: CapabilityRef[];
+    /** Optional: which capabilities it requires (e.g., storage for caching). */
+    requires?: CapabilityRequirement[];
+}
+export interface IntegrationConfigSchema {
+    /** JSON Schema or SchemaModel defining required config fields. */
+    schema: unknown;
+    /** Example configuration (for docs/UI). */
+    example?: Record<string, unknown>;
+}
+export interface IntegrationSecretSchema {
+    /** JSON Schema or SchemaModel describing secret fields. */
+    schema: unknown;
+    /** Redacted example for documentation/UI. */
+    example?: Record<string, string>;
+}
+export interface IntegrationByokSetup {
+    /** Human-readable instructions for tenants configuring BYOK accounts. */
+    setupInstructions?: string;
+    /** Required scopes/permissions for BYOK accounts. */
+    requiredScopes?: string[];
+}
+export interface IntegrationHealthCheck {
+    /** Endpoint or method to validate connection health. */
+    method?: 'ping' | 'list' | 'custom';
+    /** Timeout in ms for health check. */
+    timeoutMs?: number;
+}
+export interface IntegrationSpec {
+    meta: IntegrationMeta;
+    /** Supported ownership modes for this provider. */
+    supportedModes: IntegrationOwnershipMode[];
+    /** Which capabilities this integration provides/requires. */
+    capabilities: IntegrationCapabilityMapping;
+    /** Configuration schema (API keys, endpoints, etc.). */
+    configSchema: IntegrationConfigSchema;
+    /** Secret schema (API/key material stored via secretRef). */
+    secretSchema: IntegrationSecretSchema;
+    /** Optional health check configuration. */
+    healthCheck?: IntegrationHealthCheck;
+    /** Documentation URL. */
+    docsUrl?: string;
+    /** Rate limits or usage constraints. */
+    constraints?: {
+        rateLimit?: {
+            rpm?: number;
+            rph?: number;
+        };
+        quotas?: Record<string, number>;
+    };
+    /** Provider-specific metadata for BYOK setup flows. */
+    byokSetup?: IntegrationByokSetup;
+}
+export declare class IntegrationSpecRegistry extends SpecContractRegistry<'integration', IntegrationSpec> {
+    constructor(items?: IntegrationSpec[]);
+    getByCategory(category: IntegrationCategory): IntegrationSpec[];
+}
+export declare function makeIntegrationSpecKey(meta: IntegrationMeta): string;
+/**
+ * Helper to define an Integration.
+ */
+export declare const defineIntegration: (spec: IntegrationSpec) => IntegrationSpec;

package/dist/integrations/spec.js

@@ -0,0 +1,22 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+export {
+  makeIntegrationSpecKey,
+  defineIntegration,
+  IntegrationSpecRegistry
+};

package/dist/integrations/spec.test.d.ts

@@ -0,0 +1 @@
+export {};