okengine 0.3.2 → 0.3.5

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="site/public/OKE-W.svg" />
-    <img alt="OKE" src="site/public/OKE-B.svg" width="220" />
+    <source media="(prefers-color-scheme: dark)" srcset="site/public/logo/OKE-W.svg" />
+    <img alt="OKE" src="site/public/logo/OKE-B.svg" width="220" />
   </picture>
 </p>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -59,7 +59,6 @@
     "gate": "bun test src/cli/doc-staleness.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
-    "ci:workflow": "bun scripts/ci.ts --workflow",
     "ci": "bun scripts/ci.ts",
     "bump": "bun run scripts/bump-version.ts",
     "release": "bun run scripts/publish.ts",

package/site/content/docs/plugins/cors.mdx

@@ -27,14 +27,14 @@ Browsers on `https://app.example.com` can now call every flow; every other origi
 
 ## Options
 
-| Option           | Type                          | Default                                                | Does                                                                        |
-| ---------------- | ----------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
-| `origin`         | `"*"` · `string` · `string[]` | none (closed)                                          | Origins allowed cross-origin; lists are exact matches                       |
-| `methods`        | `string[]`                    | GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS     | Methods answered on preflight                                               |
-| `allowedHeaders` | `string[]`                    | reflect the request's `Access-Control-Request-Headers` | `Access-Control-Allow-Headers` on preflight                                 |
-| `exposedHeaders` | `string[]`                    | omit                                                   | `Access-Control-Expose-Headers` on actual responses                         |
-| `credentials`    | `boolean`                     | `false`                                                | Send `Access-Control-Allow-Credentials`; `"*"` is then reflected per-origin |
-| `maxAge`         | `number`                      | omit                                                   | `Access-Control-Max-Age` seconds on preflight                               |
+| Option           | Type                          | Default                                                | Does                                                                      |
+| ---------------- | ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
+| `origin`         | `"*"` · `string` · `string[]` | none (closed)                                          | Origins allowed cross-origin; lists are exact matches                     |
+| `methods`        | `string[]`                    | GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS     | Methods answered on preflight                                             |
+| `allowedHeaders` | `string[]`                    | reflect the request's `Access-Control-Request-Headers` | `Access-Control-Allow-Headers` on preflight                               |
+| `exposedHeaders` | `string[]`                    | omit                                                   | `Access-Control-Expose-Headers` on actual responses                       |
+| `credentials`    | `boolean`                     | `false`                                                | Send `Access-Control-Allow-Credentials`; requires an explicit origin list |
+| `maxAge`         | `number`                      | omit                                                   | `Access-Control-Max-Age` seconds on preflight                             |
 
 ```typescript
 .plug(cors({
@@ -44,13 +44,19 @@ Browsers on `https://app.example.com` can now call every flow; every other origi
 }))
 ```
 
+<Callout type="error">
+  `cors({ origin: "*", credentials: true })` throws at construction. Browsers reject that literal
+  pair; reflecting the request origin would grant **any** site credentialed access. List exact
+  origins for cookies/`Authorization` — no any-origin + credentials shortcut.
+</Callout>
+
 ## Notes
 
 | Behavior          | Detail                                                                                     |
 | ----------------- | ------------------------------------------------------------------------------------------ |
 | Preflight         | Answered by the plugin's **edge handler** — runs even when no flow matches the path/method |
 | Denied preflight  | `204` with no CORS headers — the correct, quiet failure; the browser blocks it             |
-| Credentials + `*` | Browsers reject that pair, so the plugin reflects the request origin instead               |
+| Credentials + `*` | Construction throws — enumerate origins; never reflect `*` into credentialed access        |
 | `Vary`            | `Origin` (plus request-method/headers on preflight) is appended, never duplicated          |
 | Non-HTTP triggers | No-op                                                                                      |
 

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -32,28 +32,29 @@ A client whose IP is not on the list receives `403` with a typed denial:
 
 ## Options
 
-| Option   | Type       | Default             | Does                                                       |
-| -------- | ---------- | ------------------- | ---------------------------------------------------------- |
-| `allow`  | `string[]` | — (everyone passes) | Exact IPs permitted — every other client is denied         |
-| `deny`   | `string[]` | — (nobody blocked)  | Exact IPs blocked — checked first, so deny wins on overlap |
-| `header` | `string`   | `"x-forwarded-for"` | Header carrying the client IP (first hop wins)             |
+| Option              | Type       | Default             | Does                                                                   |
+| ------------------- | ---------- | ------------------- | ---------------------------------------------------------------------- |
+| `allow`             | `string[]` | — (everyone passes) | Exact IPs permitted — every other client is denied                     |
+| `deny`              | `string[]` | — (nobody blocked)  | Exact IPs blocked — checked first, so deny wins on overlap             |
+| `header`            | `string`   | `"x-forwarded-for"` | Header carrying the client IP                                          |
+| `trustedProxyDepth` | `number`   | `1`                 | Trusted proxies that append XFF; client IP is that many from the right |
 
 ```typescript
-.plug(ipAllowlist({ deny: ["198.51.100.9"], header: "x-real-ip" }))
+.plug(ipAllowlist({ deny: ["198.51.100.9"], trustedProxyDepth: 1 }))
 ```
 
-<Callout type="warn">
-  The IP header is only trustworthy behind a proxy that **sets or overwrites** it (your load
-  balancer, reverse proxy, or platform edge). A client connecting directly can send any
-  `x-forwarded-for` value it likes — an allowlist is a strong boundary only when the proxy owns the
-  header.
+<Callout type="error">
+  Standard reverse proxies **append** to `X-Forwarded-For` — left-side hops are attacker-controlled.
+  The plugin trusts the hop `trustedProxyDepth` from the **right** (default `1` = last hop). Set
+  this to your real proxy count; wrong depth bypasses the allowlist — topology-dependent, not
+  drop-in.
 </Callout>
 
 ## Notes
 
 | Behavior          | Detail                                                                             |
 | ----------------- | ---------------------------------------------------------------------------------- |
-| XFF parsing       | First comma-separated hop is the client; proxy-appended tails are ignored          |
+| XFF parsing       | Last hop (depth `1`) is the client; left-side spoofed entries are ignored          |
 | Missing header    | Denied when `allow` is set (unknown is not allowed); permitted for deny-only rules |
 | Deny wins         | An IP in both lists is blocked                                                     |
 | Non-HTTP triggers | No-op — there is no client IP outside HTTP                                         |

package/src/cli/openbao-bootstrap.test.ts

@@ -34,6 +34,8 @@ function fakeOpenBao(calls: { url: string; method: string; body?: string }[]) {
   const routes: Record<string, () => Response> = {
     "GET /v1/sys/seal-status": () =>
       Response.json({ sealed: false, initialized: false, t: 1, n: 1, progress: 0 }),
+    "GET /v1/sys/health": () =>
+      Response.json({ initialized: true, sealed: false, standby: false }, { status: 200 }),
     "POST /v1/sys/init": () =>
       Response.json({ keys: ["unseal-key-1"], keys_base64: ["dW5zZWFs"], root_token: "root-tok" }),
     "POST /v1/sys/unseal": () => Response.json({ sealed: false, t: 1, n: 1, progress: 0 }),

package/src/cli/openbao-bootstrap.ts

@@ -122,6 +122,36 @@ async function api<T>(fetchFn: OpenBaoFetch, url: string, init?: RequestInit): P
   return (text ? JSON.parse(text) : {}) as T;
 }
 
+/**
+ * Wait until OpenBao Raft storage is active (writable).
+ *
+ * `/v1/sys/health` returns 200 only when initialized, unsealed, and the
+ * active leader — not while sealed (503) or standby (429). Polling seal-status
+ * alone is not enough after restart.
+ *
+ * @param fetchFn - Injected fetch
+ * @param url - Base URL without trailing slash
+ */
+async function waitForActiveStorage(fetchFn: OpenBaoFetch, url: string): Promise<void> {
+  const deadline = Date.now() + 60_000;
+  let lastStatus = 0;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetchFn(`${url}/v1/sys/health`);
+      lastStatus = res.status;
+      // Drain the body so keep-alive clients don't stall.
+      await res.arrayBuffer().catch(() => undefined);
+      if (res.status === 200) return;
+    } catch {
+      // process up, Raft not ready yet
+    }
+    await Bun.sleep(250);
+  }
+  throw new OpenBaoBootstrapError(
+    `openbao bootstrap: storage not active after unseal (health → ${lastStatus || "unreachable"})`,
+  );
+}
+
 /**
  * Ensure OpenBao is initialized + unsealed, mint/reuse the app token.
  *
@@ -218,6 +248,10 @@ export async function ensureOpenBao(
     }
   }
 
+  // Single-node Raft can report unsealed before storage is writable
+  // (`cannot write to readonly storage` / `cannot find peer` during election).
+  await waitForActiveStorage(fetchFn, url);
+
   const rootHeaders = { "X-Vault-Token": rootToken, "content-type": "application/json" };
 
   // Enable KV v2 at `secret/` once (mount exists after our first init).

package/src/plugins/cors.test.ts

@@ -80,13 +80,26 @@ describe("cors plugin — preflight", () => {
     expect(reflected.headers.get("access-control-allow-origin")).toBe("*");
   });
 
-  test("credentials reflect the origin instead of stamping *", async () => {
+  test('origin: "*" + credentials: true throws at construction — no silent reflect', () => {
+    expect(() => cors({ origin: "*", credentials: true })).toThrow(
+      /origin:\s*"\*"\s+cannot be combined with credentials:\s*true/i,
+    );
+  });
+
+  test("allowlist + credentials reflects only listed origins", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "cors-cred" }).plug(cors({ origin: "*", credentials: true }));
+    const app = oke({ name: "cors-cred" }).plug(
+      cors({ origin: ["https://app.example.com", "https://admin.example.com"], credentials: true }),
+    );
 
-    const res = await app.fetch(preflight());
-    expect(res.headers.get("access-control-allow-origin")).toBe("https://app.example.com");
-    expect(res.headers.get("access-control-allow-credentials")).toBe("true");
+    const allowed = await app.fetch(preflight());
+    expect(allowed.headers.get("access-control-allow-origin")).toBe("https://app.example.com");
+    expect(allowed.headers.get("access-control-allow-credentials")).toBe("true");
+
+    const denied = await app.fetch(preflight("/x", { origin: "https://evil.example.com" }));
+    expect(denied.status).toBe(204);
+    expect(denied.headers.get("access-control-allow-origin")).toBeNull();
+    expect(denied.headers.get("access-control-allow-credentials")).toBeNull();
   });
 });
 
@@ -106,6 +119,27 @@ describe("cors plugin — actual requests", () => {
     expect(res.headers.get("access-control-expose-headers")).toBe("x-total");
   });
 
+  test("allowlist + credentials on matched responses reflects only listed origins", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "cors-actual-cred" }).plug(
+      cors({ origin: ["https://app.example.com"], credentials: true }),
+    );
+
+    const ok = await app.fetch(
+      new Request("http://localhost/x", { headers: { origin: "https://app.example.com" } }),
+    );
+    expect(ok.status).toBe(200);
+    expect(ok.headers.get("access-control-allow-origin")).toBe("https://app.example.com");
+    expect(ok.headers.get("access-control-allow-credentials")).toBe("true");
+
+    const denied = await app.fetch(
+      new Request("http://localhost/x", { headers: { origin: "https://evil.example.com" } }),
+    );
+    expect(denied.status).toBe(200);
+    expect(denied.headers.get("access-control-allow-origin")).toBeNull();
+    expect(denied.headers.get("access-control-allow-credentials")).toBeNull();
+  });
+
   test("denied origins get no CORS headers on matched responses", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
     const app = oke({ name: "cors-actual-deny" }).plug(cors({ origin: "https://ok.example.com" }));

package/src/plugins/cors.ts

@@ -22,6 +22,10 @@ export interface CorsOptions {
    * exact-match list (`"https://app.example.com"`). Default **none** —
    * cross-origin is closed until you open it. Same-origin traffic needs
    * no CORS headers at all.
+   *
+   * `"*"` cannot be combined with {@link CorsOptions.credentials} —
+   * construction throws. List exact origins when cookies/auth headers are
+   * involved; there is no "any origin + credentials" shortcut.
    */
   readonly origin?: "*" | string | readonly string[];
   /**
@@ -37,9 +41,10 @@ export interface CorsOptions {
   /** `Access-Control-Expose-Headers` on actual responses. Omitted unless provided. */
   readonly exposedHeaders?: readonly string[];
   /**
-   * Send `Access-Control-Allow-Credentials: true`. When set, an `origin`
-   * of `"*"` is answered by reflecting the request origin — browsers
-   * reject `"*"` together with credentials.
+   * Send `Access-Control-Allow-Credentials: true`. Requires an explicit
+   * origin allowlist (string or list) — never `"*"`. Construction throws
+   * on `origin: "*" + credentials: true` (that pair would otherwise be
+   * silently rewritten into reflected-origin access for every site).
    */
   readonly credentials?: boolean;
   /** `Access-Control-Max-Age` seconds on preflight. Omitted unless provided. */
@@ -48,6 +53,21 @@ export interface CorsOptions {
 
 const DEFAULT_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"] as const;
 
+const WILDCARD_CREDENTIALS_ERROR =
+  'cors: origin: "*" cannot be combined with credentials: true — list exact origins instead ' +
+  '(browsers reject "*" with credentials; reflecting the request origin would grant any site ' +
+  "credentialed access)";
+
+/**
+ * Reject the dangerous `origin: "*" + credentials: true` pair.
+ * Fail loud at construction (and again if runtime config introduces it).
+ */
+function assertSafeCorsOptions(options: CorsOptions): void {
+  if (options.origin === "*" && options.credentials === true) {
+    throw new Error(WILDCARD_CREDENTIALS_ERROR);
+  }
+}
+
 /** True when `origin` is permitted by the configured origin rule. */
 export function originAllowed(origin: string, rule: CorsOptions["origin"]): boolean {
   if (rule === undefined) return false;
@@ -58,7 +78,7 @@ export function originAllowed(origin: string, rule: CorsOptions["origin"]): bool
 
 /** The `Access-Control-Allow-Origin` value for a permitted origin. */
 function allowOriginValue(origin: string, options: CorsOptions): string {
-  return options.origin === "*" && options.credentials !== true ? "*" : origin;
+  return options.origin === "*" ? "*" : origin;
 }
 
 /** Is this request a CORS preflight? */
@@ -82,10 +102,13 @@ function isPreflight(request: Request, method: string): boolean {
  * @param options - Origin rules and friends, or a config source
  */
 export function cors(options: CorsOptions | ConfigSource<CorsOptions> = {}): PluginDef {
-  const def = plugin("cors", { version: "0.0.1", config: pluginConfigSnapshot(options) })
+  assertSafeCorsOptions(pluginConfigSnapshot(options));
+
+  const def = plugin("cors", { version: "0.0.2", config: pluginConfigSnapshot(options) })
     .edge((request, info) => {
       if (!isPreflight(request, info.method)) return undefined;
       const resolved = resolvePluginOptions(options);
+      assertSafeCorsOptions(resolved);
       const origin = request.headers.get("origin")!;
       if (!originAllowed(origin, resolved.origin)) {
         return new Response(null, { status: 204 });
@@ -113,6 +136,7 @@ export function cors(options: CorsOptions | ConfigSource<CorsOptions> = {}): Plu
       const origin = ctx.request.headers.get("origin");
       if (origin === null) return;
       const resolved = resolvePluginOptions(options);
+      assertSafeCorsOptions(resolved);
       if (!originAllowed(origin, resolved.origin)) return;
 
       ctx.response = withHeaders(ctx.response, (headers) => {

package/src/plugins/ip-allowlist.test.ts

@@ -61,15 +61,49 @@ describe("ipAllowlist plugin", () => {
     expect(res.status).toBe(403);
   });
 
-  test("XFF first hop is the client; later hops are ignored", async () => {
+  test("XFF last hop is the client; a spoofed first hop cannot bypass allow", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
     const app = oke({ name: "ips-xff" }).plug(ipAllowlist({ allow: ["203.0.113.7"] }));
 
-    const proxied = await app.fetch(get("203.0.113.7, 10.0.0.1, 10.0.0.2"));
-    expect(proxied.status).toBe(200);
+    // Attacker-controlled first hop + trusted proxy appended the real client (last).
+    const spoofedFirst = await app.fetch(get("203.0.113.7, 198.51.100.9"));
+    expect(spoofedFirst.status).toBe(403);
 
-    const spoofedTail = await app.fetch(get("198.51.100.9, 203.0.113.7"));
-    expect(spoofedTail.status).toBe(403);
+    const realLast = await app.fetch(get("198.51.100.9, 203.0.113.7"));
+    expect(realLast.status).toBe(200);
+  });
+
+  test("spoofed first hop cannot bypass a deny rule", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "ips-xff-deny" }).plug(ipAllowlist({ deny: ["198.51.100.9"] }));
+
+    // Spoof a non-denied IP first; proxy appended the real (denied) client last.
+    const spoofed = await app.fetch(get("203.0.113.7, 198.51.100.9"));
+    expect(spoofed.status).toBe(403);
+    const body = (await spoofed.json()) as { error: { data: { reason: string; ip: string } } };
+    expect(body.error.data.reason).toBe("ip_denied");
+    expect(body.error.data.ip).toBe("198.51.100.9");
+  });
+
+  test("trustedProxyDepth selects the hop behind N trusted proxies", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    // Chain: spoofed, real-client, cdn-egress — depth 2 skips the nearest proxy hop.
+    const app = oke({ name: "ips-depth" }).plug(
+      ipAllowlist({ allow: ["203.0.113.7"], trustedProxyDepth: 2 }),
+    );
+
+    const ok = await app.fetch(get("198.51.100.1, 203.0.113.7, 10.0.0.2"));
+    expect(ok.status).toBe(200);
+
+    // Second-from-last is not allow-listed → denied (depth must match topology).
+    const denied = await app.fetch(get("198.51.100.1, 198.51.100.9, 10.0.0.2"));
+    expect(denied.status).toBe(403);
+  });
+
+  test("trustedProxyDepth < 1 throws at construction", () => {
+    expect(() => ipAllowlist({ allow: ["203.0.113.7"], trustedProxyDepth: 0 })).toThrow(
+      /trustedProxyDepth/i,
+    );
   });
 
   test("missing header: denied when allow is set, permitted for deny-only", async () => {

package/src/plugins/ip-allowlist.ts

@@ -26,19 +26,68 @@ export interface IpAllowlistOptions {
    */
   readonly deny?: readonly string[];
   /**
-   * Header carrying the client IP. Default `"x-forwarded-for"` (first hop
-   * wins, the value your proxy appends). Only trustworthy behind a proxy
-   * that sets or overwrites this header — a direct client can lie.
+   * Header carrying the client IP. Default `"x-forwarded-for"`.
+   *
+   * For XFF, reverse proxies (nginx `$proxy_add_x_forwarded_for`, etc.)
+   * **append** the connecting peer — they do not overwrite. The trusted
+   * client IP is therefore taken from the **right** of the chain (see
+   * {@link IpAllowlistOptions.trustedProxyDepth}), not the left. A client
+   * connecting directly can still forge the whole header; this plugin is
+   * only trustworthy behind a proxy that appends (or sets) it.
    */
   readonly header?: string;
+  /**
+   * How many trusted proxies sit in front of the app and append to XFF.
+   * Default `1` (single reverse proxy — the usual docker / edge shape).
+   *
+   * The client IP is the hop `trustedProxyDepth` entries from the right:
+   * depth `1` = last hop (what the nearest proxy observed); depth `2` =
+   * second-from-last (CDN + internal LB both appending), and so on.
+   *
+   * **This must match the real number of trusted proxies in your
+   * deployment.** Too low trusts a spoofable left-side hop; too high may
+   * pick a proxy address instead of the client. Wrong depth bypasses the
+   * allowlist — this is a topology-dependent security control, not a
+   * drop-in default you can ignore.
+   */
+  readonly trustedProxyDepth?: number;
+}
+
+/**
+ * Reject a non-positive or non-integer `trustedProxyDepth`.
+ * Fail loud at construction (and again if runtime config introduces it).
+ */
+function assertSafeIpAllowlistOptions(options: IpAllowlistOptions): void {
+  const depth = options.trustedProxyDepth;
+  if (depth === undefined) return;
+  if (!Number.isInteger(depth) || depth < 1) {
+    throw new Error(
+      `ip-allowlist: trustedProxyDepth must be an integer >= 1 (got ${String(depth)}) — ` +
+        "set it to the real number of trusted proxies that append X-Forwarded-For",
+    );
+  }
 }
 
-/** Extract the client IP from the configured header (first hop for XFF). */
-function clientIp(request: Request, header: string): string | undefined {
+/**
+ * Extract the client IP from the configured header.
+ *
+ * For comma-separated XFF chains, trust the hop `trustedProxyDepth` from
+ * the right (nearest trusted proxy's observation at depth 1). Left-side
+ * entries are attacker-controlled when clients can set the header before
+ * a proxy that appends. Fewer hops than `trustedProxyDepth` → undefined
+ * (fail closed).
+ */
+function clientIp(request: Request, header: string, trustedProxyDepth: number): string | undefined {
   const raw = request.headers.get(header);
   if (raw === null) return undefined;
-  const first = raw.split(",")[0]?.trim();
-  return first === undefined || first.length === 0 ? undefined : first;
+  const hops = raw
+    .split(",")
+    .map((h) => h.trim())
+    .filter((h) => h.length > 0);
+  if (hops.length === 0) return undefined;
+  const index = hops.length - trustedProxyDepth;
+  if (index < 0) return undefined;
+  return hops[index];
 }
 
 /**
@@ -55,14 +104,18 @@ function clientIp(request: Request, header: string): string | undefined {
 export function ipAllowlist(
   options: IpAllowlistOptions | ConfigSource<IpAllowlistOptions>,
 ): PluginDef {
+  assertSafeIpAllowlistOptions(pluginConfigSnapshot(options));
+
   const def = plugin("ip-allowlist", {
-    version: "0.0.2",
+    version: "0.0.3",
     config: pluginConfigSnapshot(options),
   }).hook("onAuth", (ctx) => {
     if (!ctx.request) return;
     const resolved = resolvePluginOptions(options);
+    assertSafeIpAllowlistOptions(resolved);
     const header = (resolved.header ?? "x-forwarded-for").toLowerCase();
-    const ip = clientIp(ctx.request, header);
+    const depth = resolved.trustedProxyDepth ?? 1;
+    const ip = clientIp(ctx.request, header, depth);
 
     if (ip !== undefined && (resolved.deny ?? []).includes(ip)) {
       return fail("Forbidden", { reason: "ip_denied", ip });