@contractspec/lib.contracts-integrations 2.0.0

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

@@ -0,0 +1,1128 @@
+// src/integrations/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/integrations/secrets/aws-secret-manager.ts
+import { Buffer as Buffer3 } from "node:buffer";
+import {
+  CreateSecretCommand,
+  DeleteSecretCommand,
+  GetSecretValueCommand,
+  PutSecretValueCommand,
+  SecretsManagerClient
+} from "@aws-sdk/client-secrets-manager";
+var DEFAULT_DELETE_RECOVERY_DAYS = 7;
+
+class AwsSecretsManagerProvider {
+  id = "aws-secrets-manager";
+  explicitRegion;
+  injectedClient;
+  clientConfig;
+  clientsByRegion = new Map;
+  constructor(options = {}) {
+    this.explicitRegion = options.region;
+    this.injectedClient = options.client;
+    this.clientConfig = options.clientConfig;
+  }
+  canHandle(reference) {
+    try {
+      const parsed = parseSecretUri(reference);
+      return parsed.provider === "aws" && (parsed.path === "secretsmanager" || parsed.path.startsWith("secretsmanager/"));
+    } catch {
+      return false;
+    }
+  }
+  async getSecret(reference, options) {
+    const location = this.parseReference(reference);
+    const client = this.getClient(location.region);
+    const requestedVersion = options?.version ?? location.stage ?? location.version;
+    const input = {
+      SecretId: location.secretId,
+      ...this.buildVersionSelector(requestedVersion)
+    };
+    try {
+      const result = await client.send(new GetSecretValueCommand(input));
+      const data = extractAwsSecretBytes(result, reference, this.id);
+      return {
+        data,
+        version: typeof result.VersionId === "string" && result.VersionId ? result.VersionId : requestedVersion,
+        metadata: {
+          region: location.region,
+          secretId: location.secretId,
+          ...requestedVersion ? { requestedVersion } : {}
+        },
+        retrievedAt: new Date
+      };
+    } catch (error) {
+      throw toAwsSecretProviderError({
+        error,
+        provider: this.id,
+        reference,
+        operation: "getSecret"
+      });
+    }
+  }
+  async setSecret(reference, payload) {
+    const location = this.parseReference(reference);
+    const client = this.getClient(location.region);
+    const bytes = normalizeSecretPayload(payload);
+    try {
+      const result = await client.send(new PutSecretValueCommand({
+        SecretId: location.secretId,
+        SecretBinary: bytes
+      }));
+      const versionId = typeof result.VersionId === "string" && result.VersionId ? result.VersionId : "latest";
+      return {
+        reference: this.buildReference(location.region, location.secretId, {
+          version: versionId
+        }),
+        version: versionId
+      };
+    } catch (error) {
+      if (!isAwsNotFound(error)) {
+        throw toAwsSecretProviderError({
+          error,
+          provider: this.id,
+          reference,
+          operation: "putSecretValue"
+        });
+      }
+      if (looksLikeAwsArn(location.secretId)) {
+        throw new SecretProviderError({
+          message: `Secret not found: ${location.secretId}`,
+          provider: this.id,
+          reference,
+          code: "NOT_FOUND",
+          cause: error
+        });
+      }
+      try {
+        const created = await client.send(new CreateSecretCommand({
+          Name: location.secretId,
+          SecretBinary: bytes
+        }));
+        const versionId = typeof created.VersionId === "string" && created.VersionId ? created.VersionId : "latest";
+        return {
+          reference: this.buildReference(location.region, location.secretId, {
+            version: versionId
+          }),
+          version: versionId
+        };
+      } catch (creationError) {
+        throw toAwsSecretProviderError({
+          error: creationError,
+          provider: this.id,
+          reference,
+          operation: "createSecret"
+        });
+      }
+    }
+  }
+  async rotateSecret(reference, payload) {
+    return this.setSecret(reference, payload);
+  }
+  async deleteSecret(reference) {
+    const location = this.parseReference(reference);
+    const client = this.getClient(location.region);
+    try {
+      await client.send(new DeleteSecretCommand({
+        SecretId: location.secretId,
+        RecoveryWindowInDays: DEFAULT_DELETE_RECOVERY_DAYS
+      }));
+    } catch (error) {
+      throw toAwsSecretProviderError({
+        error,
+        provider: this.id,
+        reference,
+        operation: "deleteSecret"
+      });
+    }
+  }
+  getClient(region) {
+    if (this.injectedClient) {
+      return this.injectedClient;
+    }
+    const cached = this.clientsByRegion.get(region);
+    if (cached) {
+      return cached;
+    }
+    const client = new SecretsManagerClient({
+      ...this.clientConfig ?? {},
+      region
+    });
+    this.clientsByRegion.set(region, client);
+    return client;
+  }
+  parseReference(reference) {
+    const parsed = parseSecretUri(reference);
+    if (parsed.provider !== "aws") {
+      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 < 3 || segments[0] !== "secretsmanager") {
+      throw new SecretProviderError({
+        message: "Expected secret reference format aws://secretsmanager/{region}/{secretIdOrArn}[?version=...]",
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    const regionCandidate = segments[1];
+    const region = this.resolveRegion(regionCandidate);
+    const secretId = segments.slice(2).join("/");
+    if (!secretId) {
+      throw new SecretProviderError({
+        message: `Unable to resolve secret id from reference "${parsed.path}"`,
+        provider: this.id,
+        reference,
+        code: "INVALID"
+      });
+    }
+    return {
+      region,
+      secretId,
+      version: parsed.extras?.version,
+      stage: parsed.extras?.stage
+    };
+  }
+  resolveRegion(regionCandidate) {
+    const region = regionCandidate ?? this.explicitRegion ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+    if (!region) {
+      throw new SecretProviderError({
+        message: "AWS region must be provided either in reference (aws://secretsmanager/{region}/...) or via AWS_REGION/AWS_DEFAULT_REGION.",
+        provider: this.id,
+        reference: "aws://secretsmanager//",
+        code: "INVALID"
+      });
+    }
+    return region;
+  }
+  buildVersionSelector(version) {
+    if (!version)
+      return {};
+    if (version === "latest" || version === "current") {
+      return { VersionStage: "AWSCURRENT" };
+    }
+    if (version.startsWith("AWS")) {
+      return { VersionStage: version };
+    }
+    return { VersionId: version };
+  }
+  buildReference(region, secretId, extras) {
+    const base = `aws://secretsmanager/${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 extractAwsSecretBytes(result, reference, provider) {
+  if (!result || typeof result !== "object") {
+    throw new SecretProviderError({
+      message: "Invalid AWS Secrets Manager response",
+      provider,
+      reference,
+      code: "UNKNOWN",
+      cause: result
+    });
+  }
+  const record = result;
+  if (record.SecretBinary instanceof Uint8Array) {
+    return record.SecretBinary;
+  }
+  if (typeof record.SecretBinary === "string") {
+    return Buffer3.from(record.SecretBinary, "base64");
+  }
+  if (typeof record.SecretString === "string") {
+    return Buffer3.from(record.SecretString, "utf-8");
+  }
+  throw new SecretProviderError({
+    message: "AWS secret value is empty",
+    provider,
+    reference,
+    code: "NOT_FOUND",
+    cause: result
+  });
+}
+function looksLikeAwsArn(secretId) {
+  return secretId.startsWith("arn:aws:secretsmanager:");
+}
+function isAwsNotFound(error) {
+  if (!error || typeof error !== "object")
+    return false;
+  const err = error;
+  if (typeof err.$metadata?.httpStatusCode === "number") {
+    return err.$metadata.httpStatusCode === 404;
+  }
+  return err.name === "ResourceNotFoundException";
+}
+function toAwsSecretProviderError(params) {
+  const { error, provider, reference, operation } = params;
+  if (error instanceof SecretProviderError) {
+    return error;
+  }
+  const httpStatusCode = typeof error === "object" && error !== null && "$metadata" in error && typeof error.$metadata === "object" && error.$metadata?.httpStatusCode;
+  const code = httpStatusCode === 404 ? "NOT_FOUND" : httpStatusCode === 401 || httpStatusCode === 403 ? "FORBIDDEN" : httpStatusCode === 400 ? "INVALID" : "UNKNOWN";
+  const message = error instanceof Error ? error.message : `Unknown error during ${operation}`;
+  return new SecretProviderError({
+    message,
+    provider,
+    reference,
+    code,
+    cause: error
+  });
+}
+
+// src/integrations/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"
+    });
+  }
+}
+
+// src/integrations/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";
+}
+
+// src/integrations/secrets/scaleway-secret-manager.ts
+import { Buffer as Buffer4 } 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: Buffer4.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 = Buffer4.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;
+  }
+}
+
+// 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 {
+  parseSecretUri,
+  normalizeSecretPayload,
+  SecretProviderManager,
+  SecretProviderError,
+  ScalewaySecretManagerProvider,
+  GcpSecretManagerProvider,
+  EnvSecretProvider,
+  AwsSecretsManagerProvider
+};