okengine 0.1.4

package/src/drivers/vault-openbao.ts

@@ -0,0 +1,80 @@
+/**
+ * `openbao` vault driver — HashiCorp Vault / OpenBao KV v2 HTTP API.
+ *
+ * Protocol-named; image/vendor choice lives in `images`.
+ */
+
+import type {
+  VaultBag,
+  VaultDriver,
+  VaultOpenOptions,
+} from "./vault-types.ts";
+
+/**
+ * OpenBao / Vault KV driver.
+ *
+ * Expects `url` + `token` + optional `mount` (default `secret`).
+ * Fetches `GET {url}/v1/{mount}/data/{name}` for each requested secret
+ * lazily via a cached bag loaded at open when `secrets` seed keys are listed,
+ * or returns empty until {@link VaultBag.get} is called against a remote.
+ *
+ * For boot validation the runtime passes declared names; this driver loads
+ * all keys under `mount` when the LIST API is available, else uses seed names.
+ */
+export const openbaoVaultDriver: VaultDriver = {
+  id: "openbao",
+  async open(options: VaultOpenOptions = {}): Promise<VaultBag> {
+    const url = options.url?.replace(/\/$/, "");
+    const token = options.token;
+    const mount = options.mount ?? "secret";
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const map = new Map<string, string>(
+      Object.entries(options.secrets ?? {}).filter(
+        (e): e is [string, string] => typeof e[1] === "string",
+      ),
+    );
+
+    if (url && token) {
+      // Best-effort LIST; ignore failures (permission / disabled).
+      try {
+        const listRes = await fetchFn(`${url}/v1/${mount}/metadata?list=true`, {
+          headers: { "X-Vault-Token": token },
+        });
+        if (listRes.ok) {
+          const body = (await listRes.json()) as {
+            data?: { keys?: string[] };
+          };
+          for (const key of body.data?.keys ?? []) {
+            const getRes = await fetchFn(`${url}/v1/${mount}/data/${key}`, {
+              headers: { "X-Vault-Token": token },
+            });
+            if (!getRes.ok) continue;
+            const got = (await getRes.json()) as {
+              data?: { data?: Record<string, unknown> };
+            };
+            const data = got.data?.data ?? {};
+            const value =
+              typeof data.value === "string"
+                ? data.value
+                : typeof data[key] === "string"
+                  ? (data[key] as string)
+                  : JSON.stringify(data);
+            map.set(key.replace(/\/$/, ""), value);
+          }
+        }
+      } catch {
+        // Remote unavailable — bag stays at seed / empty; boot validation reports gaps.
+      }
+    }
+
+    return {
+      driverId: "openbao",
+      get(name) {
+        return map.get(name);
+      },
+      names() {
+        return [...map.keys()];
+      },
+    };
+  },
+};

package/src/drivers/vault-sops.ts

@@ -0,0 +1,252 @@
+/**
+ * `sops` vault driver — SOPS/age via Typage (`age-encryption`).
+ *
+ * Pure TypeScript, in-process. No Go `sops` / `age` binary.
+ * Decrypts the SOPS data key with age, then AES-256-GCM value payloads.
+ */
+
+import * as age from "age-encryption";
+import type {
+  VaultBag,
+  VaultDriver,
+  VaultOpenOptions,
+} from "./vault-types.ts";
+
+/** SOPS metadata block. */
+interface SopsMeta {
+  readonly age?: ReadonlyArray<{
+    readonly recipient?: string;
+    readonly enc?: string;
+  }>;
+  readonly mac?: string;
+}
+
+/** Encrypted value marker: `ENC[AES256_GCM,data:…,iv:…,tag:…,type:…]`. */
+const ENC_RE =
+  /^ENC\[AES256_GCM,data:(?<data>[^,]+),iv:(?<iv>[^,]+),tag:(?<tag>[^,]+),type:(?<type>[^\]]+)\]$/;
+
+/**
+ * Decode a URL-safe / standard base64 string to bytes.
+ *
+ * @param input - Base64 text
+ */
+function b64(input: string): Uint8Array {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = normalized.length % 4 === 0
+    ? normalized
+    : normalized + "=".repeat(4 - (normalized.length % 4));
+  const bin = atob(pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Encode bytes as standard base64.
+ *
+ * @param bytes - Input
+ */
+function b64encode(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+/**
+ * Copy into a fresh `Uint8Array` so Web Crypto accepts it as `BufferSource`.
+ *
+ * @param bytes - Input
+ */
+function asBufferSource(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(bytes);
+}
+
+/**
+ * Decrypt a SOPS AES-256-GCM value with the data key.
+ *
+ * @param enc - `ENC[AES256_GCM,…]` string
+ * @param dataKey - 32-byte SOPS data key
+ */
+async function decryptValue(
+  enc: string,
+  dataKey: Uint8Array,
+): Promise<string> {
+  const m = ENC_RE.exec(enc);
+  const dataB64 = m?.groups?.data;
+  const ivB64 = m?.groups?.iv;
+  const tagB64 = m?.groups?.tag;
+  if (!dataB64 || !ivB64 || !tagB64) {
+    throw new Error(`sops: unrecognized ciphertext: ${enc.slice(0, 32)}…`);
+  }
+  const data = b64(dataB64);
+  const iv = asBufferSource(b64(ivB64));
+  const tag = b64(tagB64);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    asBufferSource(dataKey),
+    { name: "AES-GCM" },
+    false,
+    ["decrypt"],
+  );
+  const cipher = new Uint8Array(data.length + tag.length);
+  cipher.set(data, 0);
+  cipher.set(tag, data.length);
+  const plain = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    key,
+    asBufferSource(cipher),
+  );
+  return new TextDecoder().decode(plain);
+}
+
+/**
+ * Decrypt the SOPS data key from an age-encrypted stanza using Typage.
+ *
+ * @param identity - `AGE-SECRET-KEY-…`
+ * @param encBlock - Armored age ciphertext from `sops.age[].enc`
+ */
+async function decryptDataKey(
+  identity: string,
+  encBlock: string,
+): Promise<Uint8Array> {
+  const d = new age.Decrypter();
+  d.addIdentity(identity.trim());
+  const trimmed = encBlock.trim();
+  const file: Uint8Array = trimmed.includes("BEGIN AGE ENCRYPTED FILE")
+    ? age.armor.decode(trimmed)
+    : new TextEncoder().encode(trimmed);
+  const bytes = await d.decrypt(file, "uint8array");
+  return bytes;
+}
+
+/**
+ * Parse a SOPS JSON document into a name→ciphertext map + metadata.
+ *
+ * @param text - File contents
+ */
+function parseSopsJson(text: string): {
+  values: Record<string, string>;
+  meta: SopsMeta;
+} {
+  const doc = JSON.parse(text) as Record<string, unknown>;
+  const meta = (doc.sops ?? {}) as SopsMeta;
+  const values: Record<string, string> = {};
+  for (const [k, v] of Object.entries(doc)) {
+    if (k === "sops") continue;
+    if (typeof v === "string") values[k] = v;
+  }
+  return { values, meta };
+}
+
+/**
+ * Encrypt a plaintext with AES-256-GCM into a SOPS-shaped `ENC[…]` string.
+ * Exported for tests that build fixtures without the Go CLI.
+ *
+ * @param plaintext - Cleartext
+ * @param dataKey - 32-byte key
+ */
+export async function sopsEncryptValue(
+  plaintext: string,
+  dataKey: Uint8Array,
+): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await crypto.subtle.importKey(
+    "raw",
+    asBufferSource(dataKey),
+    { name: "AES-GCM" },
+    false,
+    ["encrypt"],
+  );
+  const cipher = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      new TextEncoder().encode(plaintext),
+    ),
+  );
+  const tag = cipher.slice(cipher.length - 16);
+  const data = cipher.slice(0, cipher.length - 16);
+  return `ENC[AES256_GCM,data:${b64encode(data)},iv:${b64encode(iv)},tag:${b64encode(tag)},type:str]`;
+}
+
+/**
+ * Build a minimal SOPS JSON document encrypted to an age recipient.
+ * Test / fixture helper — not a full `sops` replacement.
+ *
+ * @param secrets - Cleartext map
+ * @param recipient - `age1…` recipient
+ * @param dataKey - Optional 32-byte data key (random when omitted)
+ */
+export async function buildSopsFixture(
+  secrets: Readonly<Record<string, string>>,
+  recipient: string,
+  dataKey?: Uint8Array,
+): Promise<{ json: string; dataKey: Uint8Array }> {
+  const key = dataKey ?? crypto.getRandomValues(new Uint8Array(32));
+  const e = new age.Encrypter();
+  e.addRecipient(recipient);
+  const encKey = await e.encrypt(key);
+  const encBytes =
+    typeof encKey === "string" ? new TextEncoder().encode(encKey) : encKey;
+  const encArmored = age.armor.encode(encBytes);
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(secrets)) {
+    out[name] = await sopsEncryptValue(value, key);
+  }
+  out.sops = {
+    age: [{ recipient, enc: encArmored }],
+    lastmodified: new Date().toISOString(),
+    version: "3.8.0",
+  };
+  return { json: JSON.stringify(out, null, 2), dataKey: key };
+}
+
+/**
+ * SOPS/age vault driver (Typage).
+ */
+export const sopsVaultDriver: VaultDriver = {
+  id: "sops",
+  async open(options: VaultOpenOptions = {}): Promise<VaultBag> {
+    let text: string | undefined;
+    if (typeof options.ciphertext === "string") {
+      text = options.ciphertext;
+    } else if (options.ciphertext instanceof Uint8Array) {
+      text = new TextDecoder().decode(options.ciphertext);
+    } else if (options.path) {
+      text = await Bun.file(options.path).text();
+    }
+    if (!text) {
+      throw new Error("sops vault: path or ciphertext is required");
+    }
+    if (!options.ageIdentity) {
+      throw new Error(
+        "sops vault: ageIdentity (AGE-SECRET-KEY-…) is required — Typage decrypts in-process",
+      );
+    }
+
+    const { values, meta } = parseSopsJson(text);
+    const stanza = meta.age?.[0]?.enc;
+    if (!stanza) {
+      throw new Error("sops vault: no age recipient stanza found");
+    }
+    const dataKey = await decryptDataKey(options.ageIdentity, stanza);
+    const map = new Map<string, string>();
+    for (const [name, enc] of Object.entries(values)) {
+      if (enc.startsWith("ENC[")) {
+        map.set(name, await decryptValue(enc, dataKey));
+      } else {
+        map.set(name, enc);
+      }
+    }
+
+    return {
+      driverId: "sops",
+      get(name) {
+        return map.get(name);
+      },
+      names() {
+        return [...map.keys()];
+      },
+    };
+  },
+};

package/src/drivers/vault-types.ts

@@ -0,0 +1,84 @@
+/**
+ * Protocol-named vault driver contracts.
+ *
+ * Driver ids: `sops` · `env` · `openbao` · `infisical` · `managed` · `memory`.
+ * Never vendor names (`neon`, `infisical-cloud`, …) — vendor choice lives in `images`.
+ */
+
+/** Protocol ids for vault drivers. */
+export type VaultDriverId =
+  | "sops"
+  | "env"
+  | "openbao"
+  | "infisical"
+  | "managed"
+  | "memory";
+
+/** Options when opening a vault backend. */
+export interface VaultOpenOptions {
+  /**
+   * Path to a SOPS-encrypted file (`sops` driver) or a dotenv file (`env` driver).
+   * Prefer JSON / ENV formats produced by `sops -e` for SOPS.
+   */
+  readonly path?: string;
+  /** Inline SOPS ciphertext (tests). */
+  readonly ciphertext?: string | Uint8Array;
+  /** Age identity (`AGE-SECRET-KEY-…`) for Typage decryption. */
+  readonly ageIdentity?: string;
+  /** Env prefix filter for the `env` driver (default: none — whole `process.env`). */
+  readonly envPrefix?: string;
+  /** Injected env map for tests (defaults to `process.env`). */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** OpenBao / Infisical / managed base URL. */
+  readonly url?: string;
+  /** Token / API key for remote vaults. */
+  readonly token?: string;
+  /** Mount / project path for remote vaults. */
+  readonly mount?: string;
+  /** Seed map for `memory` / `managed` drivers. */
+  readonly secrets?: Readonly<Record<string, string>>;
+  /** HTTP fetch override for remote drivers (tests). */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/** Resolved secret bag — names → cleartext values. Never logged. */
+export interface VaultBag {
+  /** Protocol driver id. */
+  readonly driverId: VaultDriverId;
+  /**
+   * Read a secret by name.
+   *
+   * @param name - Secret contract name
+   */
+  get(name: string): string | undefined;
+  /** All names present in this bag. */
+  names(): readonly string[];
+  /**
+   * Write / overwrite a secret (mutable bags: `memory` · `managed`).
+   * Used for per-subject crypto-shred keys in the runs store.
+   *
+   * @param name - Secret name
+   * @param value - Cleartext
+   */
+  set?(name: string, value: string): void;
+  /**
+   * Delete a secret (mutable bags). Erasure deletes the key, not the bytes.
+   *
+   * @param name - Secret name
+   */
+  delete?(name: string): boolean;
+  /** Close remote clients when applicable. */
+  close?(): Promise<void>;
+}
+
+/** Vault driver factory. */
+export interface VaultDriver {
+  /** Protocol id. */
+  readonly id: VaultDriverId;
+  /**
+   * Open a secret bag.
+   *
+   * @param options - Driver-specific open options
+   */
+  open(options?: VaultOpenOptions): Promise<VaultBag>;
+}

package/src/elements/ai/declare.ts

@@ -0,0 +1,206 @@
+/**
+ * AI declaration — models, versioned prompts, embeds, agents.
+ *
+ * Physics: inference · prompts · embeddings · agents.
+ */
+
+/** Budget for a prompt or agent. */
+export interface AiBudgetDecl {
+  readonly maxCostPerCall?: number;
+  readonly maxCostPerRun?: number;
+}
+
+/** Options for {@link ai.model}. */
+export interface AiModelOptions {
+  readonly provider?: string;
+  readonly tier?: string;
+  readonly model?: string;
+}
+
+/** Options for {@link AiModelDecl.prompt}. */
+export interface AiPromptOptions {
+  readonly version?: number;
+  readonly evals?: string;
+  readonly budget?: AiBudgetDecl;
+  readonly in?: unknown;
+  readonly out?: unknown;
+}
+
+/** Options for {@link ai.embed}. */
+export interface AiEmbedOptions {
+  readonly model?: AiModelDecl | string;
+  readonly into?: { readonly name: string; readonly facet?: string } | string;
+}
+
+/** Options for {@link ai.agent}. */
+export interface AiAgentOptions {
+  readonly model?: AiModelDecl | string;
+  readonly tools?: readonly ({ readonly name: string } | string)[];
+  readonly maxSteps?: number;
+  readonly budget?: AiBudgetDecl;
+}
+
+/** Declared model handle — can mint prompts. */
+export interface AiModelDecl {
+  readonly kind: "model";
+  readonly name: string;
+  readonly provider?: string;
+  readonly tier?: string;
+  readonly model?: string;
+  /**
+   * Declare a versioned prompt artifact on this model.
+   *
+   * @param name - Prompt id
+   * @param options - Version / evals / schemas / budget
+   */
+  prompt(name: string, options?: AiPromptOptions): AiPromptDecl;
+}
+
+/** Declared versioned prompt. */
+export interface AiPromptDecl {
+  readonly kind: "prompt";
+  readonly name: string;
+  readonly version?: number;
+  readonly evals?: string;
+  readonly budget?: AiBudgetDecl;
+  readonly model?: string;
+  readonly in?: unknown;
+  readonly out?: unknown;
+}
+
+/** Declared embedding pipeline into `store.index`. */
+export interface AiEmbedDecl {
+  readonly kind: "embed";
+  readonly name: string;
+  readonly model?: string;
+  readonly into?: string;
+}
+
+/** Declared agent whose tools are flows. */
+export interface AiAgentDecl {
+  readonly kind: "agent";
+  readonly name: string;
+  readonly tools: readonly string[];
+  readonly maxSteps?: number;
+  readonly model?: string;
+  readonly budget?: AiBudgetDecl;
+}
+
+/**
+ * Resolve a tool ref to a flow name.
+ *
+ * @param tool - Flow handle or string
+ */
+function toolName(tool: { readonly name: string } | string): string {
+  return typeof tool === "string" ? tool : tool.name;
+}
+
+/**
+ * Shape of the {@link ai} element namespace.
+ */
+export interface AiNamespace {
+  /**
+   * Declare a model binding.
+   *
+   * @param name - Logical model name (`smart`, `fast`, …)
+   * @param options - Provider / tier / model id
+   */
+  model(name: string, options?: AiModelOptions): AiModelDecl;
+  /**
+   * Declare an embedding pipeline into a store.index.
+   *
+   * @param name - Embed id
+   * @param options - Model + destination index
+   */
+  embed(name: string, options?: AiEmbedOptions): AiEmbedDecl;
+  /**
+   * Declare a bounded agent whose tools are the app's own flows.
+   *
+   * @param name - Agent id
+   * @param options - Tools / maxSteps / model / budget
+   */
+  agent(name: string, options?: AiAgentOptions): AiAgentDecl;
+}
+
+/**
+ * AI element namespace.
+ */
+export const ai: AiNamespace = {
+  /**
+   * Declare a model binding.
+   *
+   * @param name - Logical model name (`smart`, `fast`, …)
+   * @param options - Provider / tier / model id
+   */
+  model(name: string, options: AiModelOptions = {}): AiModelDecl {
+    if (!name) throw new TypeError("ai.model: name is required");
+    const decl: AiModelDecl = {
+      kind: "model",
+      name,
+      ...(options.provider !== undefined ? { provider: options.provider } : {}),
+      ...(options.tier !== undefined ? { tier: options.tier } : {}),
+      ...(options.model !== undefined ? { model: options.model } : {}),
+      prompt(promptName, promptOpts = {}) {
+        return {
+          kind: "prompt",
+          name: promptName,
+          model: name,
+          ...(promptOpts.version !== undefined
+            ? { version: promptOpts.version }
+            : {}),
+          ...(promptOpts.evals !== undefined ? { evals: promptOpts.evals } : {}),
+          ...(promptOpts.budget !== undefined
+            ? { budget: promptOpts.budget }
+            : {}),
+          ...(promptOpts.in !== undefined ? { in: promptOpts.in } : {}),
+          ...(promptOpts.out !== undefined ? { out: promptOpts.out } : {}),
+        };
+      },
+    };
+    return decl;
+  },
+
+  /**
+   * Declare an embedding pipeline into a store.index.
+   *
+   * @param name - Embed id
+   * @param options - Model + destination index
+   */
+  embed(name: string, options: AiEmbedOptions = {}): AiEmbedDecl {
+    const model =
+      typeof options.model === "string"
+        ? options.model
+        : options.model?.name;
+    const into =
+      typeof options.into === "string"
+        ? options.into
+        : options.into?.name;
+    return {
+      kind: "embed",
+      name,
+      ...(model !== undefined ? { model } : {}),
+      ...(into !== undefined ? { into } : {}),
+    };
+  },
+
+  /**
+   * Declare a bounded agent whose tools are the app's own flows.
+   *
+   * @param name - Agent id
+   * @param options - Tools / maxSteps / model / budget
+   */
+  agent(name: string, options: AiAgentOptions = {}): AiAgentDecl {
+    return {
+      kind: "agent",
+      name,
+      tools: (options.tools ?? []).map(toolName),
+      ...(options.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
+      ...(options.budget !== undefined ? { budget: options.budget } : {}),
+      ...(typeof options.model === "string"
+        ? { model: options.model }
+        : options.model?.name !== undefined
+          ? { model: options.model.name }
+          : {}),
+    };
+  },
+};