okengine 0.21.0 → 0.22.0

package/src/elements/vault/audit.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Audit sinks — secret-free stdout/webhook payloads, and chain commands
+ * that exist only for the `db` sink.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createAuditSink, type AuditEntry } from "./audit.ts";
+import { buildVaultBootChain } from "./boot-chain.ts";
+import { createBuiltinVaultAdapter, sqlConnectionAsExec } from "./builtin-adapter.ts";
+import { isVaultError } from "./errors.ts";
+import { createMemoryVaultSql } from "./test-helpers.ts";
+
+const ENTRY: AuditEntry = {
+  action: "set",
+  path: "prod/api",
+  actorType: "flow",
+  actorId: "orders.place",
+  success: true,
+  requestId: "req-1",
+  at: new Date("2026-01-02T03:04:05.000Z"),
+};
+
+const SECRET = "sk_live_do_not_log_me";
+
+describe("webhook audit sink", () => {
+  test("missing or non-http webhookUrl fails at construction", () => {
+    expect(() => createAuditSink("webhook")).toThrow(/webhookUrl/);
+    expect(
+      isVaultError(
+        catchError(() => createAuditSink("webhook")),
+        "MISSING_PEER",
+      ),
+    ).toBe(true);
+    expect(
+      isVaultError(
+        catchError(() => createAuditSink("webhook", { webhookUrl: "/relative" })),
+        "MISSING_PEER",
+      ),
+    ).toBe(true);
+    expect(
+      isVaultError(
+        catchError(() => createAuditSink("webhook", { webhookUrl: "ftp://audit.example/hook" })),
+        "MISSING_PEER",
+      ),
+    ).toBe(true);
+  });
+
+  test("POSTs the stdout-shaped JSON, refuses redirects, and omits secret values", async () => {
+    const bodies: string[] = [];
+    const inits: RequestInit[] = [];
+    const sink = createAuditSink("webhook", {
+      webhookUrl: "https://audit.example/hook",
+      fetch: (async (_url, init) => {
+        inits.push(init ?? {});
+        bodies.push(String(init?.body ?? ""));
+        return new Response(null, { status: 204 });
+      }) as typeof fetch,
+    });
+
+    await sink.append(ENTRY);
+
+    expect(inits[0]?.method).toBe("POST");
+    expect(inits[0]?.redirect).toBe("error");
+    expect(inits[0]?.signal).toBeInstanceOf(AbortSignal);
+    const parsed = JSON.parse(bodies[0] ?? "{}") as Record<string, unknown>;
+    expect(parsed).toEqual({
+      sink: "oke.vault.audit",
+      action: "set",
+      path: "prod/api",
+      actorType: "flow",
+      actorId: "orders.place",
+      success: true,
+      errorCode: null,
+      errorMessage: null,
+      requestId: "req-1",
+      createdAt: "2026-01-02T03:04:05.000Z",
+    });
+    expect(bodies[0]).not.toContain(SECRET);
+    expect(parsed).not.toHaveProperty("value");
+  });
+
+  test("a non-2xx response rejects without echoing the body", async () => {
+    const sink = createAuditSink("webhook", {
+      webhookUrl: "https://audit.example/hook",
+      fetch: (async () => new Response(SECRET, { status: 502 })) as unknown as typeof fetch,
+    });
+    const failure = await sink.append(ENTRY).catch((err: unknown) => err);
+    expect(isVaultError(failure, "BACKEND_ERROR")).toBe(true);
+    expect((failure as Error).message).not.toContain(SECRET);
+    expect((failure as Error).message).toContain("502");
+  });
+});
+
+describe("vault boot chain", () => {
+  test("forwards vault.audit only onto the builtin driver layer", () => {
+    const audit = { sink: "webhook" as const, webhookUrl: "https://audit.example/hook" };
+    const chain = buildVaultBootChain({ driverId: "vault", audit });
+    expect(chain[0]?.driver.id).toBe("vault");
+    expect(chain[0]?.options?.audit).toEqual(audit);
+    expect(chain.slice(1).every((layer) => layer.options?.audit === undefined)).toBe(true);
+  });
+});
+
+describe("non-db audit commands", () => {
+  test("verify refuses a webhook sink before touching the chain", async () => {
+    const sql = createMemoryVaultSql();
+    try {
+      const adapter = createBuiltinVaultAdapter({
+        db: sqlConnectionAsExec(sql),
+        audit: { sink: "webhook", webhookUrl: "https://audit.example/hook" },
+        fetch: (async () => new Response(null, { status: 500 })) as unknown as typeof fetch,
+      });
+      const failure = await adapter.verifyAudit().catch((err: unknown) => err);
+      expect(isVaultError(failure, "UNSUPPORTED")).toBe(true);
+      expect((failure as Error).message).toContain('audit.sink "db"');
+
+      const init = await adapter.initialize();
+      expect(init.masterKey.length).toBeGreaterThan(0);
+    } finally {
+      await sql.close();
+    }
+  });
+});
+
+/**
+ * Capture a thrown construction error.
+ *
+ * @param fn - Throwing call
+ */
+function catchError(fn: () => unknown): unknown {
+  try {
+    fn();
+    return undefined;
+  } catch (err) {
+    return err;
+  }
+}

package/src/elements/vault/audit.ts

@@ -9,8 +9,10 @@
 
 import { VaultError } from "./errors.ts";
 import type { VaultErrorCode } from "./errors.ts";
-import type { VaultActorType } from "./types.ts";
-import type { VaultAuditSinkKind } from "./types.ts";
+import type { VaultActorType, VaultAuditConfig, VaultAuditSinkKind } from "./types.ts";
+
+/** Bound on a webhook audit POST so a dead receiver cannot stall a write. */
+const AUDIT_WEBHOOK_TIMEOUT_MS = 5_000;
 
 /** Operations recorded in the audit chain. */
 export type AuditAction =
@@ -110,8 +112,10 @@ export interface AuditWriter {
 export interface CreateAuditSinkOptions {
   /** Required for the `db` sink. */
   readonly writer?: AuditWriter;
-  /** Required for the `webhook` sink (not yet implemented). */
+  /** Required for the `webhook` sink. Absolute `http:` or `https:` URL. */
   readonly webhookUrl?: string;
+  /** Fetch implementation for the `webhook` sink (tests). */
+  readonly fetch?: typeof globalThis.fetch;
   /** Line writer for the `stdout` sink (tests). */
   readonly write?: (line: string) => void;
   /** Clock for `stdout` timestamps (tests). */
@@ -169,23 +173,98 @@ export async function computeAuditRowHash(
   return Buffer.from(new Uint8Array(digest)).toString("hex");
 }
 
+/**
+ * Reject a webhook URL that is missing or not an absolute http(s) URL.
+ *
+ * @param webhookUrl - Configured destination
+ * @returns Absolute URL string
+ * @throws VaultError `MISSING_PEER` when the URL is absent or not http(s)
+ */
+function requireWebhookUrl(webhookUrl: string | undefined): string {
+  const raw = webhookUrl?.trim() ?? "";
+  if (raw.length === 0) {
+    throw new VaultError("MISSING_PEER", "vault: webhook audit sink requires webhookUrl");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new VaultError(
+      "MISSING_PEER",
+      "vault: webhook audit sink requires an absolute http(s) webhookUrl",
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new VaultError(
+      "MISSING_PEER",
+      "vault: webhook audit sink requires an absolute http(s) webhookUrl",
+    );
+  }
+  return parsed.href;
+}
+
+/**
+ * JSON body shared by the `stdout` and `webhook` sinks.
+ *
+ * Only normalized metadata is serialized — an entry never holds a value.
+ *
+ * @param entry - Operation to record
+ * @param now - Clock when the entry has no `at`
+ */
+function auditEventJson(entry: AuditEntry, now: () => Date): string {
+  return JSON.stringify({
+    sink: "oke.vault.audit",
+    ...toAuditHashPayload(entry, entry.at ?? now()),
+  });
+}
+
 /**
  * Build an audit sink.
  *
  * - `db` delegates to an {@link AuditWriter} supplied by storage.
  * - `stdout` writes one secret-free JSON line per operation.
- * - `webhook` is not implemented yet and throws `UNSUPPORTED`.
+ * - `webhook` POSTs that same JSON. Delivery failure throws; callers that
+ *   record after a successful operation swallow it.
+ *
+ * Hash-chain verify and purge apply only to the `db` sink.
  *
  * @param kind - Sink kind from `audit.sink`
  * @param opts - Writer / webhook URL / test seams
- * @throws VaultError `UNSUPPORTED` for `webhook`, or `MISSING_PEER` when `db` has no writer
+ * @throws VaultError `MISSING_PEER` when `db` has no writer or `webhook` has no absolute URL
  */
 export function createAuditSink(
   kind: VaultAuditSinkKind,
   opts: CreateAuditSinkOptions = {},
 ): AuditSink {
   if (kind === "webhook") {
-    throw new VaultError("UNSUPPORTED", "vault: webhook audit sink is not implemented");
+    const url = requireWebhookUrl(opts.webhookUrl);
+    const fetchFn = opts.fetch ?? globalThis.fetch;
+    const now = opts.now ?? (() => new Date());
+    return {
+      kind: "webhook",
+      async append(entry) {
+        const body = auditEventJson(entry, now);
+        let response: Response;
+        try {
+          response = await fetchFn(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body,
+            redirect: "error",
+            signal: AbortSignal.timeout(AUDIT_WEBHOOK_TIMEOUT_MS),
+          });
+        } catch (err) {
+          if (err instanceof VaultError) throw err;
+          throw new VaultError("BACKEND_ERROR", "vault: webhook audit sink request failed");
+        }
+        if (!response.ok) {
+          throw new VaultError(
+            "BACKEND_ERROR",
+            `vault: webhook audit sink failed (${response.status})`,
+          );
+        }
+      },
+    };
   }
 
   if (kind === "db") {
@@ -206,17 +285,31 @@ export function createAuditSink(
   return {
     kind: "stdout",
     async append(entry) {
-      // Only normalized metadata is serialized — an entry never holds a value.
-      write(
-        JSON.stringify({
-          sink: "oke.vault.audit",
-          ...toAuditHashPayload(entry, entry.at ?? now()),
-        }),
-      );
+      write(auditEventJson(entry, now));
     },
   };
 }
 
+/**
+ * Pick the sink for a built-in adapter from `vault.audit`.
+ *
+ * `enabled: false` drops every row. Omitted config is the `db` chain.
+ *
+ * @param config - `vault.audit` block, when present
+ * @param opts - SQL writer and optional fetch
+ */
+export function auditSinkForConfig(
+  config: VaultAuditConfig | undefined,
+  opts: { readonly writer: AuditWriter; readonly fetch?: typeof globalThis.fetch },
+): AuditSink {
+  if (config?.enabled === false) return createNullAuditSink();
+  return createAuditSink(config?.sink ?? "db", {
+    writer: opts.writer,
+    ...(config?.webhookUrl === undefined ? {} : { webhookUrl: config.webhookUrl }),
+    ...(opts.fetch === undefined ? {} : { fetch: opts.fetch }),
+  });
+}
+
 /**
  * Sink that drops every entry (`audit.enabled: false`).
  *

package/src/elements/vault/boot-chain.ts

@@ -22,6 +22,7 @@ import {
 import { parseDotenv } from "../../drivers/vault-dotenv-parse.ts";
 import type { VaultDriverId } from "../../drivers/vault-types.ts";
 import { resolveComposeEnvPath } from "./chain.ts";
+import type { VaultAuditConfig } from "./types.ts";
 import type { VaultChainLayer } from "./runtime.ts";
 
 /** Options for {@link buildVaultBootChain}. */
@@ -34,6 +35,10 @@ export interface BuildVaultBootChainOptions {
   readonly env?: ConfigEnv;
   /** Seed secrets for the terminal memory / managed layer. */
   readonly seed?: Readonly<Record<string, string>>;
+  /**
+   * Built-in store audit block. Forwarded only to the `vault` driver layer.
+   */
+  readonly audit?: VaultAuditConfig;
 }
 
 /**
@@ -142,7 +147,10 @@ export function buildVaultBootChain(options: BuildVaultBootChainOptions): VaultC
         {
           driver: builtinVaultDriver,
           source: "driver",
-          options: { secrets: seed },
+          options: {
+            secrets: seed,
+            ...(options.audit === undefined ? {} : { audit: options.audit }),
+          },
         },
         ...envLayers,
       ];

package/src/elements/vault/builtin-adapter.ts

@@ -20,7 +20,7 @@
  * cleartext value ever reaches the log, an error message, or a `VaultError`.
  */
 
-import { createAuditSink, type AuditAction, type AuditSink } from "./audit.ts";
+import { auditSinkForConfig, type AuditAction, type AuditSink } from "./audit.ts";
 import {
   ALGORITHM,
   buildAad,
@@ -66,6 +66,7 @@ import type {
   VaultActor,
   VaultAdapter,
   VaultAlgorithm,
+  VaultAuditConfig,
   VaultGetOptions,
   VaultInitResult,
   VaultListEntry,
@@ -96,8 +97,15 @@ export interface CreateBuiltinVaultOptions {
    * {@link VaultAdapter.unseal} is not required.
    */
   readonly unsealer?: Unsealer;
-  /** Audit destination. Defaults to a `db` sink over `oke_vault_audit`. */
+  /** Audit destination. Wins over {@link audit} when both are set. */
   readonly auditSink?: AuditSink;
+  /**
+   * `vault.audit` from config. Omitted means the `db` hash chain.
+   * Ignored when {@link auditSink} is set.
+   */
+  readonly audit?: VaultAuditConfig;
+  /** Fetch override for the `webhook` audit sink (tests). */
+  readonly fetch?: typeof globalThis.fetch;
   /** DEKs re-wrapped per rotation batch. Defaults to {@link DEFAULT_KEK_REWRAP_BATCH_SIZE}. */
   readonly kekRewrapBatchSize?: number;
   /**
@@ -306,7 +314,25 @@ export function createBuiltinVaultAdapter(opts: CreateBuiltinVaultOptions): Buil
   const db = createResilientSqlExec(rawDb);
   const batchSize = Math.max(1, opts.kekRewrapBatchSize ?? DEFAULT_KEK_REWRAP_BATCH_SIZE);
   const rotateLeaseMs = Math.max(50, opts.rotateLeaseMs ?? DEFAULT_ROTATE_LEASE_MS);
-  const audit = opts.auditSink ?? createAuditSink("db", { writer: createSqlAuditWriter(rawDb) });
+  const audit =
+    opts.auditSink ??
+    auditSinkForConfig(opts.audit, {
+      writer: createSqlAuditWriter(rawDb),
+      ...(opts.fetch === undefined ? {} : { fetch: opts.fetch }),
+    });
+
+  /**
+   * Hash-chain commands only exist for the `db` sink.
+   *
+   * @param op - Command name for the error
+   */
+  function requireDbAudit(op: string): void {
+    if (audit.kind === "db") return;
+    throw new VaultError(
+      "UNSUPPORTED",
+      `vault: ${op} requires audit.sink "db" (got "${audit.kind}")`,
+    );
+  }
 
   let unsealer: Unsealer | null = opts.unsealer ?? null;
   let pending: PendingRotation | null = null;
@@ -1018,6 +1044,7 @@ export function createBuiltinVaultAdapter(opts: CreateBuiltinVaultOptions): Buil
     },
 
     async purgeAuditBefore(before: Date): Promise<number> {
+      requireDbAudit("audit purge");
       await ensureReady();
       const removed = await purgeAuditRows(db, before);
       await record("purge", undefined);
@@ -1043,16 +1070,19 @@ export function createBuiltinVaultAdapter(opts: CreateBuiltinVaultOptions): Buil
     },
 
     async verifyAudit(): Promise<AuditChainResult> {
+      requireDbAudit("audit verify");
       await ensureReady();
       return verifyAuditChain(db);
     },
 
     async listAudit(options?: AuditPageOptions): Promise<readonly VaultAuditRecord[]> {
+      requireDbAudit("audit list");
       await ensureReady();
       return readAuditPage(db, options ?? {});
     },
 
     async readAuditRow(id: string): Promise<VaultAuditRecord | null> {
+      requireDbAudit("audit read");
       await ensureReady();
       return readAuditRow(db, id);
     },

package/src/i18n/catalogs/ar.ts

@@ -86,6 +86,10 @@ export const builtinAr = {
     "DatabaseError.retryable": "قاعدة البيانات مشغولة. حاول بعد قليل.",
     ServiceUnavailable: "الخدمة غير متاحة مؤقتاً.",
     InternalError: "حدث خطأ. حاول مرة أخرى.",
+    IdempotencyKeyMissing: "هذا الاستدعاء يتطلب ترويسة Idempotency-Key.",
+    IdempotencyKeyInvalid: "يجب أن يكون Idempotency-Key من 16 إلى 255 حرفًا ASCII قابلًا للطباعة.",
+    IdempotencyKeyReused: "استُخدم Idempotency-Key هذا من قبل مع طلب مختلف.",
+    IdempotencyInProgress: "ما زال Idempotency-Key هذا قيد التنفيذ. أعد المحاولة بعد المهلة.",
     InvalidQuery: "الاستعلام غير صالح.",
     UnsupportedMediaType: "نوع المحتوى هذا غير مدعوم.",
     AuthFailed: "فشلت المصادقة.",

package/src/i18n/catalogs/en.ts

@@ -86,6 +86,10 @@ export const builtinEn = {
     "DatabaseError.retryable": "The database is busy. Try again shortly.",
     ServiceUnavailable: "The service is temporarily unavailable.",
     InternalError: "Something went wrong. Try again.",
+    IdempotencyKeyMissing: "This call requires an Idempotency-Key header.",
+    IdempotencyKeyInvalid: "Idempotency-Key must be 16–255 printable ASCII characters.",
+    IdempotencyKeyReused: "This Idempotency-Key was already used with a different request.",
+    IdempotencyInProgress: "This Idempotency-Key is still running. Retry after the given delay.",
     InvalidQuery: "The query is not valid.",
     UnsupportedMediaType: "That content type is not supported.",
     AuthFailed: "Authentication failed.",

package/src/kernel/abort-scope.ts

@@ -2,8 +2,8 @@
  * Ambient AbortSignal scope for structured concurrency.
  *
  * Same ALS pattern as dry-run: `fx.all` / `fx.race` enter a child signal so
- * cooperative branches (and future driver plumbing) can observe cancellation
- * without every call site passing a signal argument.
+ * cooperative branches and outbound HTTP can observe cancellation without
+ * every call site passing a signal argument.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -34,6 +34,21 @@ export async function withAbortSignal<T>(
   return storage.run(signal, fn);
 }
 
+/** Never-aborted signal for work that must outlive the caller connection. */
+const DETACHED: AbortSignal = new AbortController().signal;
+
+/**
+ * Run `fn` without the request abort signal.
+ *
+ * A claimed idempotent `do` keeps running when the client times out. The
+ * lease, not the socket, is what detects a crash.
+ *
+ * @param fn - Work to detach
+ */
+export function runDetached<T>(fn: () => T | Promise<T>): Promise<T> {
+  return withAbortSignal(DETACHED, fn);
+}
+
 /**
  * When `parent` aborts, abort `child` with the same reason.
  *
@@ -88,6 +103,22 @@ export function abortError(reason?: unknown): Error {
   return err;
 }
 
+/**
+ * Signal for one outbound request: the ambient scope, the caller's signal, or both.
+ *
+ * Read at request time, not at driver `open`, so an `fx.race` / `fx.all` abort
+ * reaches HTTP that is already in flight.
+ *
+ * @param explicit - Caller-supplied signal, when the API already accepts one
+ */
+export function requestSignal(explicit?: AbortSignal | null): AbortSignal {
+  const ambient = currentAbortSignal();
+  if (explicit == null || explicit === ambient) return ambient;
+  if (ambient.aborted) return ambient;
+  if (explicit.aborted) return explicit;
+  return AbortSignal.any([ambient, explicit]);
+}
+
 /**
  * Sleep that rejects promptly when `signal` aborts.
  *