@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/secrets/manager.d.ts

@@ -0,0 +1,44 @@
+import type { SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from './provider';
+interface RegisterOptions {
+    /**
+     * Larger priority values are attempted first. Defaults to 0.
+     */
+    priority?: number;
+}
+export interface SecretProviderManagerOptions {
+    /**
+     * Override manager identifier. Defaults to "secret-provider-manager".
+     */
+    id?: string;
+    /**
+     * Providers to pre-register. They are registered in array order with
+     * descending priority (first entry wins ties).
+     */
+    providers?: {
+        provider: SecretProvider;
+        priority?: number;
+    }[];
+}
+/**
+ * Composite secret provider that delegates to registered providers.
+ * Providers are attempted in order of descending priority, respecting the
+ * registration order for ties. This enables privileged overrides (e.g.
+ * environment variables) while still supporting durable backends like GCP
+ * Secret Manager.
+ */
+export declare class SecretProviderManager implements SecretProvider {
+    readonly id: string;
+    private readonly providers;
+    private registrationCounter;
+    constructor(options?: SecretProviderManagerOptions);
+    register(provider: SecretProvider, options?: RegisterOptions): this;
+    canHandle(reference: SecretReference): boolean;
+    getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+    setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    deleteSecret(reference: SecretReference): Promise<void>;
+    private delegateToFirst;
+    private composeError;
+}
+type SecretFetchOptions = Parameters<SecretProvider['getSecret']>[1];
+export {};

package/dist/integrations/secrets/manager.js

@@ -0,0 +1,183 @@
+// @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/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/integrations/secrets/provider.d.ts

@@ -0,0 +1,49 @@
+export type SecretReference = string;
+export interface SecretValue {
+    data: Uint8Array;
+    version?: string;
+    metadata?: Record<string, string>;
+    retrievedAt: Date;
+}
+export interface SecretFetchOptions {
+    version?: string;
+}
+export type SecretPayloadEncoding = 'utf-8' | 'base64' | 'binary';
+export interface SecretWritePayload {
+    data: string | Uint8Array;
+    encoding?: SecretPayloadEncoding;
+    contentType?: string;
+    labels?: Record<string, string>;
+}
+export interface SecretRotationResult {
+    reference: SecretReference;
+    version: string;
+}
+export interface SecretProvider {
+    readonly id: string;
+    canHandle(reference: SecretReference): boolean;
+    getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+    setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    deleteSecret(reference: SecretReference): Promise<void>;
+}
+export interface ParsedSecretUri {
+    provider: string;
+    path: string;
+    extras?: Record<string, string>;
+}
+export declare class SecretProviderError extends Error {
+    readonly provider: string;
+    readonly reference: SecretReference;
+    readonly code: 'NOT_FOUND' | 'FORBIDDEN' | 'INVALID' | 'UNKNOWN';
+    readonly cause?: unknown;
+    constructor(params: {
+        message: string;
+        provider: string;
+        reference: SecretReference;
+        code?: SecretProviderError['code'];
+        cause?: unknown;
+    });
+}
+export declare function parseSecretUri(reference: SecretReference): ParsedSecretUri;
+export declare function normalizeSecretPayload(payload: SecretWritePayload): Uint8Array;

package/dist/integrations/secrets/provider.js

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

package/dist/integrations/secrets/provider.test.d.ts

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

package/dist/integrations/secrets/scaleway-secret-manager.d.ts

@@ -0,0 +1,35 @@
+import type { SecretFetchOptions, SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from './provider';
+interface ScalewaySecretManagerProviderOptions {
+    /**
+     * Scaleway API token (SCW secret key). If omitted, uses env vars.
+     * Header: X-Auth-Token
+     */
+    token?: string;
+    /** Default region when not present in reference (e.g. fr-par). */
+    defaultRegion?: string;
+    /** Default project id used when creating secrets by name. */
+    defaultProjectId?: string;
+    /** Override API base url (defaults to https://api.scaleway.com). */
+    baseUrl?: string;
+    /** Inject fetch for tests. */
+    fetch?: typeof fetch;
+}
+export declare class ScalewaySecretManagerProvider implements SecretProvider {
+    readonly id = "scaleway-secret-manager";
+    private readonly token;
+    private readonly defaultRegion?;
+    private readonly defaultProjectId?;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(options?: ScalewaySecretManagerProviderOptions);
+    canHandle(reference: SecretReference): boolean;
+    getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+    setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+    deleteSecret(reference: SecretReference): Promise<void>;
+    private parseReference;
+    private createSecret;
+    private createSecretVersion;
+    private buildReference;
+}
+export {};