okengine 0.11.2 → 0.12.0

package/src/drivers/vault-managed.test.ts

@@ -1,14 +1,18 @@
 /**
- * Managed vault driver — provider selection, deferred providers, delegation.
+ * Managed vault driver — provider selection, official backends, delegation.
  */
 
 import { describe, expect, test } from "bun:test";
 import { isVaultError } from "../elements/vault/errors.ts";
-import { createManagedVaultBag, managedVaultDriver } from "./vault-managed.ts";
-import type { AwsSecretsManagerClient } from "./vault-aws-secrets-manager.ts";
+import {
+  createManagedVaultBag,
+  MANAGED_VAULT_PROVIDER_IDS,
+  managedVaultDriver,
+} from "./vault-managed.ts";
+import type { RemoteSecretClient } from "./vault-remote-bag.ts";
 
-/** In-memory stand-in for the AWS Secrets Manager API. */
-function fakeAwsClient(seed: Record<string, string>): AwsSecretsManagerClient {
+/** In-memory stand-in for any remote secret API. */
+function fakeClient(seed: Record<string, string>): RemoteSecretClient {
   const store = new Map(Object.entries(seed));
   return {
     async list() {
@@ -37,19 +41,21 @@ describe("managed vault driver", () => {
     expect(bag.get("SEEDED")).toBe("from-seed");
   });
 
-  test("aws-secrets-manager provider reads through the injected client", async () => {
-    const bag = await createManagedVaultBag({
-      provider: "aws-secrets-manager",
-      client: fakeAwsClient({ STRIPE_KEY: "sk_live" }),
-    });
-    expect(bag.driverId).toBe("managed");
-    expect(bag.get("STRIPE_KEY")).toBe("sk_live");
+  test("every official provider reads through the injected client", async () => {
+    for (const provider of MANAGED_VAULT_PROVIDER_IDS) {
+      const bag = await createManagedVaultBag({
+        provider,
+        client: fakeClient({ STRIPE_KEY: "sk_live" }),
+      });
+      expect(bag.driverId).toBe("managed");
+      expect(bag.get("STRIPE_KEY")).toBe("sk_live");
+    }
   });
 
   test("provider id is case- and space-insensitive", async () => {
     const bag = await createManagedVaultBag({
       provider: "  AWS-Secrets-Manager ",
-      client: fakeAwsClient({ A: "1" }),
+      client: fakeClient({ A: "1" }),
     });
     expect(bag.get("A")).toBe("1");
   });
@@ -69,19 +75,6 @@ describe("managed vault driver", () => {
     }
   });
 
-  test("deferred providers fail UNSUPPORTED, never silently empty", async () => {
-    for (const provider of ["azure-key-vault", "gcp-secret-manager", "doppler", "1password"]) {
-      let failed: unknown;
-      try {
-        await createManagedVaultBag({ provider });
-      } catch (error) {
-        failed = error;
-      }
-      expect(isVaultError(failed, "UNSUPPORTED")).toBe(true);
-      expect((failed as Error).message).toContain(provider);
-    }
-  });
-
   test("unknown provider fails UNSUPPORTED with the supported list", async () => {
     let failed: unknown;
     try {
@@ -91,5 +84,9 @@ describe("managed vault driver", () => {
     }
     expect(isVaultError(failed, "UNSUPPORTED")).toBe(true);
     expect((failed as Error).message).toContain("aws-secrets-manager");
+    expect((failed as Error).message).toContain("azure-key-vault");
+    expect((failed as Error).message).toContain("gcp-secret-manager");
+    expect((failed as Error).message).toContain("doppler");
+    expect((failed as Error).message).toContain("1password");
   });
 });

package/src/drivers/vault-managed.ts

@@ -9,39 +9,41 @@
  * own protocol id — `managed` is a selector, not a protocol. Backends load
  * dynamically so a project on one provider never pays for the others.
  *
- * Official provider: `aws-secrets-manager`. Community plugins can implement
- * additional adapters; unknown ids fail loud with {@link VaultError} `UNSUPPORTED`.
+ * Official providers: AWS Secrets Manager, Azure Key Vault, GCP Secret
+ * Manager, Doppler, 1Password Connect. Unknown ids fail loud with
+ * {@link VaultError} `UNSUPPORTED`.
  */
 
 import { VaultError } from "../elements/vault/errors.ts";
-import type { AwsSecretsManagerClient } from "./vault-aws-secrets-manager.ts";
+import type { RemoteSecretClient } from "./vault-remote-bag.ts";
 import type { VaultBag, VaultDriver, VaultOpenOptions } from "./vault-types.ts";
 
 /** Official backends `managed` ships today. */
-export type ManagedVaultProviderId = "aws-secrets-manager";
-
-/** Providers named in config but not implemented in core — reported, not guessed. */
-const DEFERRED_PROVIDERS: readonly string[] = [
+export const MANAGED_VAULT_PROVIDER_IDS = [
+  "aws-secrets-manager",
   "azure-key-vault",
   "gcp-secret-manager",
   "doppler",
   "1password",
-];
+] as const;
+
+/** Official backends `managed` ships today. */
+export type ManagedVaultProviderId = (typeof MANAGED_VAULT_PROVIDER_IDS)[number];
 
 /** Supported provider ids, for error messages. */
-const SUPPORTED_PROVIDERS = "aws-secrets-manager";
+export const MANAGED_VAULT_PROVIDER_LIST: string = MANAGED_VAULT_PROVIDER_IDS.join(" · ");
 
 /** Options for {@link createManagedVaultBag}. */
 export interface ManagedVaultOptions extends VaultOpenOptions {
-  /** Injected AWS Secrets Manager client for tests. */
-  readonly client?: AwsSecretsManagerClient;
+  /** Injected remote client for tests. */
+  readonly client?: RemoteSecretClient;
 }
 
 /**
  * Open the bag for the selected managed provider.
  *
  * @param options - Provider id plus that provider's connection options
- * @throws VaultError `UNSUPPORTED` for a deferred or unknown provider
+ * @throws VaultError `UNSUPPORTED` for an unknown provider
  */
 export async function createManagedVaultBag(options: ManagedVaultOptions = {}): Promise<VaultBag> {
   const provider = options.provider?.trim().toLowerCase();
@@ -58,18 +60,54 @@ export async function createManagedVaultBag(options: ManagedVaultOptions = {}):
     });
   }
 
-  if (DEFERRED_PROVIDERS.includes(provider)) {
-    throw new VaultError(
-      "UNSUPPORTED",
-      `vault: managed provider "${provider}" is not implemented yet — official: ${SUPPORTED_PROVIDERS}. ` +
-        "Community adapters can implement ManagedAdapter / open via a plugin.",
-    );
+  if (provider === "azure-key-vault") {
+    const { openAzureKeyVaultBag } = await import("./vault-azure-key-vault.ts");
+    return openAzureKeyVaultBag({
+      ...(options.url === undefined ? {} : { url: options.url }),
+      ...(options.mount === undefined ? {} : { prefix: options.mount }),
+      ...(options.client === undefined ? {} : { client: options.client }),
+      ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+    });
+  }
+
+  if (provider === "gcp-secret-manager") {
+    const { openGcpSecretManagerBag } = await import("./vault-gcp-secret-manager.ts");
+    return openGcpSecretManagerBag({
+      ...(options.mount === undefined ? {} : { mount: options.mount }),
+      ...(options.region === undefined ? {} : { region: options.region }),
+      ...(options.client === undefined ? {} : { client: options.client }),
+      ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+    });
+  }
+
+  if (provider === "doppler") {
+    const { openDopplerBag } = await import("./vault-doppler.ts");
+    return openDopplerBag({
+      ...(options.token === undefined ? {} : { token: options.token }),
+      ...(options.url === undefined ? {} : { url: options.url }),
+      ...(options.mount === undefined ? {} : { mount: options.mount }),
+      ...(options.client === undefined ? {} : { client: options.client }),
+      ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+      ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    });
+  }
+
+  if (provider === "1password") {
+    const { openOnePasswordBag } = await import("./vault-1password.ts");
+    return openOnePasswordBag({
+      ...(options.url === undefined ? {} : { url: options.url }),
+      ...(options.token === undefined ? {} : { token: options.token }),
+      ...(options.mount === undefined ? {} : { mount: options.mount }),
+      ...(options.client === undefined ? {} : { client: options.client }),
+      ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
+      ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    });
   }
 
   throw new VaultError(
     "UNSUPPORTED",
-    `vault: unknown managed provider "${provider}" (expected ${SUPPORTED_PROVIDERS}). ` +
-      'Official backends: aws-secrets-manager or built-in vault (drivers.vault: "vault").',
+    `vault: unknown managed provider "${provider}" (expected ${MANAGED_VAULT_PROVIDER_LIST}). ` +
+      'Official backends: managed providers above, or built-in vault (drivers.vault: "vault").',
   );
 }
 

package/src/drivers/vault-remote-bag.ts

@@ -0,0 +1,242 @@
+/**
+ * Shared remote-provider bag — snapshot at `open`, write-through, settle on `close`.
+ *
+ * Every official managed backend (AWS, Azure, GCP, Doppler, 1Password) uses
+ * this physics so a credentials outage never degrades to a silently empty
+ * seed-only view. SDK / HTTP errors are translated here; their messages are
+ * never copied, because they can echo secret material.
+ */
+
+import { VaultError } from "../elements/vault/errors.ts";
+import type { VaultBag } from "./vault-types.ts";
+
+/**
+ * Secret-name-addressed client a remote bag talks to.
+ *
+ * Names are bag names (`STRIPE_KEY`), never fully-qualified vendor ids —
+ * prefix / project / vault scoping belongs to the client.
+ */
+export interface RemoteSecretClient {
+  /** Bag names visible to this credential under the configured scope. */
+  list(): Promise<readonly string[]>;
+  /**
+   * Read one secret's string value.
+   *
+   * @param name - Bag name
+   */
+  get(name: string): Promise<string | undefined>;
+  /**
+   * Create or overwrite one secret.
+   *
+   * @param name - Bag name
+   * @param value - Cleartext
+   */
+  put(name: string, value: string): Promise<void>;
+  /**
+   * Delete one secret. A missing secret is not an error.
+   *
+   * @param name - Secret name
+   */
+  remove(name: string): Promise<void>;
+  /** Release the underlying SDK / HTTP client. */
+  close?(): Promise<void>;
+}
+
+/** Translate a foreign failure into a secret-free {@link VaultError}. */
+export type VaultErrorTranslator = (error: unknown, message: string) => VaultError;
+
+/** Options for {@link openRemoteSecretBag}. */
+export interface OpenRemoteSecretBagOptions {
+  /** Vendor client. */
+  readonly client: RemoteSecretClient;
+  /**
+   * Declared names, used as the read set when list is denied so a
+   * least-privilege credential still boots.
+   */
+  readonly secrets?: Readonly<Record<string, string>>;
+  /** Lowercase vendor label interpolated into authored error messages. */
+  readonly label: string;
+  /** Override the default translator (vendor-specific permission codes). */
+  readonly asError?: VaultErrorTranslator;
+}
+
+/**
+ * Default translator — keeps {@link VaultError} as-is, otherwise `BACKEND_ERROR`.
+ *
+ * @param error - Thrown value
+ * @param message - Safe message authored by the caller
+ */
+export function asRemoteVaultError(error: unknown, message: string): VaultError {
+  if (error instanceof VaultError) return error;
+  return new VaultError("BACKEND_ERROR", message);
+}
+
+/**
+ * Open a secret bag backed by a remote {@link RemoteSecretClient}.
+ *
+ * An unreachable or unauthorized API is fatal: the bag never silently
+ * degrades to a seed-only view, because that turns a credentials outage into
+ * a "missing secret contract" message pointing at the wrong thing.
+ *
+ * @param options - Client / seed / label / translator
+ * @throws VaultError `BACKEND_ERROR` or `PERMISSION_DENIED` when the API rejects the read
+ */
+export async function openRemoteSecretBag(options: OpenRemoteSecretBagOptions): Promise<VaultBag> {
+  const translate = options.asError ?? asRemoteVaultError;
+  const client = options.client;
+  const map = new Map<string, string>(
+    Object.entries(options.secrets ?? {}).filter(
+      (e): e is [string, string] => typeof e[1] === "string",
+    ),
+  );
+
+  let listed: readonly string[] = [];
+  try {
+    listed = await client.list();
+  } catch (error) {
+    // List is commonly denied on least-privilege roles; only fail when
+    // there is no declared read set to fall back to.
+    if (map.size === 0) throw translate(error, `vault: ${options.label} list failed`);
+  }
+
+  const names = listed.length > 0 ? listed : [...map.keys()];
+  for (const name of names) {
+    let value: string | undefined;
+    try {
+      value = await client.get(name);
+    } catch (error) {
+      throw translate(error, `vault: ${options.label} read of "${name}" failed`);
+    }
+    if (value !== undefined) map.set(name, value);
+  }
+
+  const pending: Promise<void>[] = [];
+  let failure: VaultError | undefined;
+  /**
+   * Run a write in the background, holding its failure for `close`.
+   *
+   * @param work - In-flight API call
+   * @param message - Safe message when it rejects
+   */
+  function track(work: Promise<void>, message: string): void {
+    pending.push(
+      work.catch((error: unknown) => {
+        failure ??= translate(error, message);
+      }),
+    );
+  }
+
+  return {
+    driverId: "managed",
+    get(name) {
+      return map.get(name);
+    },
+    names() {
+      return [...map.keys()];
+    },
+    set(name, value) {
+      map.set(name, value);
+      track(client.put(name, value), `vault: ${options.label} write of "${name}" failed`);
+    },
+    delete(name) {
+      const had = map.delete(name);
+      track(client.remove(name), `vault: ${options.label} delete of "${name}" failed`);
+      return had;
+    },
+    async close() {
+      await Promise.all(pending);
+      await client.close?.();
+      if (failure) throw failure;
+    },
+  };
+}
+
+/** Options for {@link vaultHttpJson}. */
+export interface VaultHttpJsonOptions {
+  /** HTTP statuses that return instead of throwing (e.g. 404 on get). */
+  readonly allow?: readonly number[];
+}
+
+/** Result of {@link vaultHttpJson}. */
+export interface VaultHttpJsonResult {
+  /** Response status. */
+  readonly status: number;
+  /** Parsed JSON, or `undefined` when the body is empty / not JSON. */
+  readonly body: unknown;
+}
+
+/**
+ * `fetch` + JSON parse that never copies the response body into {@link VaultError}.
+ *
+ * @param fetchFn - Fetch implementation
+ * @param url - Absolute URL
+ * @param init - Request init
+ * @param message - Safe message when the call fails
+ * @param options - Statuses to allow through
+ */
+export async function vaultHttpJson(
+  fetchFn: typeof fetch,
+  url: string,
+  init: RequestInit,
+  message: string,
+  options: VaultHttpJsonOptions = {},
+): Promise<VaultHttpJsonResult> {
+  let response: Response;
+  try {
+    response = await fetchFn(url, init);
+  } catch (error) {
+    throw asRemoteVaultError(error, message);
+  }
+  const allowed = options.allow ?? [];
+  if (allowed.includes(response.status)) {
+    return { status: response.status, body: await readJsonSilent(response) };
+  }
+  if (response.status === 401 || response.status === 403) {
+    throw new VaultError("PERMISSION_DENIED", `${message} — credentials denied`);
+  }
+  if (!response.ok) {
+    throw new VaultError("BACKEND_ERROR", message);
+  }
+  return { status: response.status, body: await readJsonSilent(response) };
+}
+
+/**
+ * Parse JSON without turning a malformed body into a leaky error message.
+ *
+ * @param response - Fetch response
+ */
+async function readJsonSilent(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (text.length === 0) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read a structural `name` / `code` / `status` off a foreign error.
+ *
+ * Never reads `message`: vendor SDKs quote request payloads there.
+ *
+ * @param error - Thrown value
+ */
+export function remoteErrorCode(error: unknown): string | number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const record = error as {
+    name?: unknown;
+    code?: unknown;
+    statusCode?: unknown;
+    status?: unknown;
+  };
+  // Numeric status/code first — GCP gRPC uses `code: 7` on a generic `Error`.
+  if (typeof record.code === "number") return record.code;
+  if (typeof record.statusCode === "number") return record.statusCode;
+  if (typeof record.status === "number") return record.status;
+  if (typeof record.name === "string" && record.name !== "Error") return record.name;
+  if (typeof record.code === "string") return record.code;
+  if (typeof record.status === "string") return record.status;
+  if (typeof record.name === "string") return record.name;
+  return undefined;
+}

package/src/drivers/vault-types.ts

@@ -9,7 +9,8 @@
  * Protocol ids for vault drivers.
  *
  * `vault` is okengine's own encrypted-at-rest store; `managed` selects a
- * remote provider (official: `aws-secrets-manager`) or a platform-injected bag.
+ * remote provider (AWS / Azure / GCP / Doppler / 1Password) or a
+ * platform-injected bag.
  */
 export type VaultDriverId = "env" | "vault" | "managed" | "memory";
 
@@ -27,17 +28,18 @@ export interface VaultOpenOptions {
   /** Injected env map for tests (defaults to `process.env`). */
   readonly env?: Readonly<Record<string, string | undefined>>;
   /**
-   * Backend behind the `managed` driver — official: `aws-secrets-manager`.
-   * Omit for platform-injected secrets. Community adapters may accept other ids.
+   * Backend behind the `managed` driver — official: `aws-secrets-manager`,
+   * `azure-key-vault`, `gcp-secret-manager`, `doppler`, `1password`.
+   * Omit for platform-injected secrets.
    */
   readonly provider?: string;
-  /** Base URL for remote managed providers (community adapters). */
+  /** Base URL — Azure Key Vault URI, 1Password Connect host, Doppler origin. */
   readonly url?: string;
-  /** Token / API key for remote vaults. */
+  /** Token / API key — Doppler service token, 1Password Connect token. */
   readonly token?: string;
   /**
-   * Mount / project path for remote vaults. Doubles as the secret-name prefix
-   * for `aws-secrets-manager` (`oke/prod/` → `oke/prod/STRIPE_KEY`).
+   * Provider scope: AWS/Azure name prefix, GCP `project` or `project/prefix`,
+   * Doppler `project/config`, 1Password vault name or UUID.
    */
   readonly mount?: string;
   /** Cloud region for regional managed providers. */