@contractspec/lib.contracts-integrations 2.0.0

package/dist/node/integrations/secrets/manager.js

@@ -0,0 +1,182 @@
+// src/integrations/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/integrations/secrets/manager.ts
+class SecretProviderManager {
+  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" : "UNKNOWN",
+      cause: errors
+    });
+  }
+}
+function safeCanHandle(provider, reference) {
+  try {
+    return provider.canHandle(reference);
+  } catch {
+    return false;
+  }
+}
+export {
+  SecretProviderManager
+};

package/dist/node/integrations/secrets/provider.js

@@ -0,0 +1,73 @@
+// src/integrations/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");
+}
+export {
+  parseSecretUri,
+  normalizeSecretPayload,
+  SecretProviderError
+};

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

@@ -0,0 +1,374 @@
+// src/integrations/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/integrations/secrets/scaleway-secret-manager.ts
+import { Buffer as Buffer2 } from "node: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/node/integrations/spec.js

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