okengine 0.2.8 → 0.3.4

package/src/plugins/cors.ts

@@ -0,0 +1,153 @@
+/**
+ * Official `cors` plugin — cross-origin rules at the edge: preflight
+ * `OPTIONS` answered even for paths bound to other methods, plus CORS
+ * headers on matched responses. Uses the public plugin API (§14) —
+ * including the edge contribution for requests that match no flow.
+ */
+
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  isConfigSource,
+  type ConfigSource,
+} from "./config-source.ts";
+import { appendVary, withHeaders } from "./headers.ts";
+
+/** Options for {@link cors}. */
+export interface CorsOptions {
+  /**
+   * Origins allowed cross-origin: `"*"` for any, one origin string, or an
+   * 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[];
+  /**
+   * Methods answered on preflight. Default covers the verbs `http.*`
+   * triggers bind: GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS.
+   */
+  readonly methods?: readonly string[];
+  /**
+   * `Access-Control-Allow-Headers` on preflight. Default reflects the
+   * request's `Access-Control-Request-Headers` back to it.
+   */
+  readonly allowedHeaders?: readonly string[];
+  /** `Access-Control-Expose-Headers` on actual responses. Omitted unless provided. */
+  readonly exposedHeaders?: readonly string[];
+  /**
+   * 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. */
+  readonly maxAge?: number;
+}
+
+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;
+  if (rule === "*") return true;
+  if (typeof rule === "string") return origin === rule;
+  return rule.includes(origin);
+}
+
+/** The `Access-Control-Allow-Origin` value for a permitted origin. */
+function allowOriginValue(origin: string, options: CorsOptions): string {
+  return options.origin === "*" ? "*" : origin;
+}
+
+/** Is this request a CORS preflight? */
+function isPreflight(request: Request, method: string): boolean {
+  return (
+    method === "OPTIONS" &&
+    request.headers.get("origin") !== null &&
+    request.headers.get("access-control-request-method") !== null
+  );
+}
+
+/**
+ * Enforce cross-origin rules. A preflight that matches no flow is answered
+ * by the plugin's edge handler; matched responses get their CORS headers
+ * at `onResponse`. A denied preflight returns `204` **without** CORS
+ * headers — the browser blocks it, which is the correct, quiet failure.
+ *
+ * Accepts static options or a {@link ConfigSource} for DB-driven origin
+ * lists (open an emergency integration origin without a redeploy).
+ *
+ * @param options - Origin rules and friends, or a config source
+ */
+export function cors(options: CorsOptions | ConfigSource<CorsOptions> = {}): PluginDef {
+  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 });
+      }
+
+      const headers = new Headers();
+      headers.set("access-control-allow-origin", allowOriginValue(origin, resolved));
+      headers.set("access-control-allow-methods", (resolved.methods ?? DEFAULT_METHODS).join(", "));
+      const allowed =
+        resolved.allowedHeaders?.join(", ") ??
+        request.headers.get("access-control-request-headers");
+      if (allowed !== null && allowed !== undefined && allowed.length > 0) {
+        headers.set("access-control-allow-headers", allowed);
+      }
+      if (resolved.credentials === true) headers.set("access-control-allow-credentials", "true");
+      if (resolved.maxAge !== undefined)
+        headers.set("access-control-max-age", String(resolved.maxAge));
+      appendVary(headers, "origin");
+      appendVary(headers, "access-control-request-method");
+      appendVary(headers, "access-control-request-headers");
+      return new Response(null, { status: 204, headers });
+    })
+    .hook("onResponse", (ctx) => {
+      if (!ctx.request || !ctx.response) return;
+      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) => {
+        headers.set("access-control-allow-origin", allowOriginValue(origin, resolved));
+        if (resolved.credentials === true) headers.set("access-control-allow-credentials", "true");
+        if (resolved.exposedHeaders !== undefined && resolved.exposedHeaders.length > 0) {
+          headers.set("access-control-expose-headers", resolved.exposedHeaders.join(", "));
+        }
+        appendVary(headers, "origin");
+      });
+    });
+
+  return isConfigSource(options) ? withConfigTable(def, options) : def;
+}

package/src/plugins/csrf.test.ts

@@ -0,0 +1,102 @@
+/**
+ * `csrf` plugin — fetch-metadata defense with an Origin fallback, through
+ * the real pipeline.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { flow, resetFlowSeq } from "../kernel/flow.ts";
+import { on, resetBindings } from "../kernel/on.ts";
+import { http } from "../kernel/triggers.ts";
+import { csrf } from "./csrf.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function mutating(headers: Record<string, string> = {}): Request {
+  return new Request("http://localhost/transfer", { method: "POST", headers });
+}
+
+function appWith(options: Parameters<typeof csrf>[0]) {
+  on(http.post("/transfer"), flow({ name: "transfer.create", do: () => ({ moved: true }) }));
+  on(http.get("/balance"), flow({ name: "balance.get", do: () => ({ balance: 5 }) }));
+  return oke({ name: `csrf-${crypto.randomUUID()}` }).plug(csrf(options));
+}
+
+describe("csrf plugin", () => {
+  test("safe methods always pass", async () => {
+    const app = appWith({});
+    const res = await app.fetch(
+      new Request("http://localhost/balance", {
+        headers: { "sec-fetch-site": "cross-site", origin: "https://evil.com" },
+      }),
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("same-origin and none pass; cross-site is denied with typed Forbidden", async () => {
+    const app = appWith({});
+
+    const same = await app.fetch(mutating({ "sec-fetch-site": "same-origin" }));
+    expect(same.status).toBe(200);
+
+    const cross = await app.fetch(
+      mutating({ "sec-fetch-site": "cross-site", origin: "https://evil.com" }),
+    );
+    expect(cross.status).toBe(403);
+    const body = (await cross.json()) as { error: { code: string; data: { reason: string } } };
+    expect(body.error.code).toBe("Forbidden");
+    expect(body.error.data.reason).toBe("csrf");
+  });
+
+  test("same-site passes by default, blocked when allowSameSite: false", async () => {
+    const lax = appWith({});
+    expect(
+      (
+        await lax.fetch(
+          mutating({ "sec-fetch-site": "same-site", origin: "https://sub.localhost" }),
+        )
+      ).status,
+    ).toBe(200);
+
+    const strict = appWith({ allowSameSite: false });
+    const res = await strict.fetch(
+      mutating({ "sec-fetch-site": "same-site", origin: "https://sub.localhost" }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("Origin fallback: same-origin host passes, allow-listed origins pass, others fail", async () => {
+    const app = appWith({ allowOrigins: ["https://admin.example.com"] });
+
+    const sameHost = await app.fetch(mutating({ origin: "http://localhost" }));
+    expect(sameHost.status).toBe(200);
+
+    const listed = await app.fetch(mutating({ origin: "https://admin.example.com" }));
+    expect(listed.status).toBe(200);
+
+    const evil = await app.fetch(mutating({ origin: "https://evil.com" }));
+    expect(evil.status).toBe(403);
+  });
+
+  test("headerless mutating requests pass by default (curl, webhooks), fail closed on demand", async () => {
+    const lax = appWith({});
+    expect((await lax.fetch(mutating())).status).toBe(200);
+
+    const closed = appWith({ allowNoHeader: false });
+    const res = await closed.fetch(mutating());
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Forbidden");
+  });
+
+  test("cross-site with an allow-listed origin passes (metadata wins are not required)", async () => {
+    const app = appWith({ allowOrigins: ["https://admin.example.com"] });
+    const res = await app.fetch(
+      mutating({ "sec-fetch-site": "cross-site", origin: "https://admin.example.com" }),
+    );
+    expect(res.status).toBe(200);
+  });
+});

package/src/plugins/csrf.ts

@@ -0,0 +1,86 @@
+/**
+ * Official `csrf` plugin — cross-site request forgery defense using fetch
+ * metadata (`Sec-Fetch-Site`) with an `Origin` fallback. Stateless: no
+ * tokens, no cookies, no session reads. Uses only the public plugin API.
+ */
+
+import { fail } from "../kernel/errors.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  isConfigSource,
+  type ConfigSource,
+} from "./config-source.ts";
+
+/** Options for {@link csrf}. */
+export interface CsrfOptions {
+  /**
+   * Absolute origins allowed to send mutating requests from another site
+   * (e.g. `"https://admin.example.com"` for a separately-hosted console).
+   * Same-origin is always allowed.
+   */
+  readonly allowOrigins?: readonly string[];
+  /**
+   * Allow `Sec-Fetch-Site: same-site` (subdomains of your site). Default
+   * `true`. Set `false` when subdomains host untrusted content.
+   */
+  readonly allowSameSite?: boolean;
+  /**
+   * Allow mutating requests carrying neither `Sec-Fetch-Site` nor `Origin`
+   * — the shape of curl, server-to-server calls, and webhooks, which are
+   * not browser CSRF vectors. Default `true`. Set `false` to fail closed
+   * when your auth is purely cookie-based.
+   */
+  readonly allowNoHeader?: boolean;
+}
+
+/** Methods browsers can mutate state with (safe verbs pass untouched). */
+function isMutating(method: string): boolean {
+  return method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+}
+
+/**
+ * Block cross-site state changes at `onAuth`, before gate policies and the
+ * flow body. Decision order: safe methods pass → `Sec-Fetch-Site`
+ * (`same-origin` / `none` pass; `same-site` per option) → `Origin`
+ * fallback (must be same-origin or allow-listed) → headerless clients per
+ * `allowNoHeader`. Denials are the gate element's typed `Forbidden`.
+ *
+ * Accepts static options or a {@link ConfigSource} for DB-driven origin
+ * rules.
+ *
+ * @param options - Origin rules, or a config source
+ */
+export function csrf(options: CsrfOptions | ConfigSource<CsrfOptions> = {}): PluginDef {
+  const def = plugin("csrf", { version: "0.0.1", config: pluginConfigSnapshot(options) }).hook(
+    "onAuth",
+    (ctx) => {
+      if (!ctx.request) return;
+      const method = ctx.request.method.toUpperCase();
+      if (!isMutating(method)) return;
+
+      const resolved = resolvePluginOptions(options);
+      const site = ctx.request.headers.get("sec-fetch-site")?.toLowerCase();
+      if (site === "same-origin" || site === "none") return;
+      if (site === "same-site" && (resolved.allowSameSite ?? true)) return;
+
+      const origin = ctx.request.headers.get("origin");
+      if (origin !== null) {
+        const host = new URL(ctx.request.url).origin;
+        if (origin === host || resolved.allowOrigins?.includes(origin) === true) return;
+        return fail("Forbidden", {
+          reason: "csrf",
+          site: site ?? "unknown",
+          origin,
+        });
+      }
+
+      if (resolved.allowNoHeader ?? true) return;
+      return fail("Forbidden", { reason: "csrf", site: site ?? "unknown" });
+    },
+  );
+
+  return isConfigSource(options) ? withConfigTable(def, options) : def;
+}

package/src/plugins/headers.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared response-header mutation for HTTP middleware plugins.
+ * `Headers` are immutable-in-place on a built `Response` — rebuild instead.
+ */
+
+/**
+ * Rebuild a response with headers mutated by `fn`.
+ *
+ * @param response - Original response
+ * @param fn - Header mutation
+ */
+export function withHeaders(response: Response, fn: (headers: Headers) => void): Response {
+  const headers = new Headers(response.headers);
+  fn(headers);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/**
+ * Set a header only when absent (or when `override` is on).
+ *
+ * @param headers - Mutable headers
+ * @param name - Header name
+ * @param value - Header value
+ * @param override - Replace an app-set value
+ */
+export function setUnlessPresent(
+  headers: Headers,
+  name: string,
+  value: string,
+  override: boolean,
+): void {
+  if (!override && headers.has(name)) return;
+  headers.set(name, value);
+}
+
+/**
+ * Append a token to `Vary` without duplicating it.
+ *
+ * @param headers - Mutable headers
+ * @param token - Vary token (e.g. `"origin"`)
+ */
+export function appendVary(headers: Headers, token: string): void {
+  const vary = headers.get("vary");
+  if (vary === null) {
+    headers.set("vary", token);
+    return;
+  }
+  const pattern = new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+  if (!pattern.test(vary)) headers.set("vary", `${vary}, ${token}`);
+}

package/src/plugins/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Official plugins — first-party extensions built entirely on the public
+ * plugin API (`okengine/plugins`). Import what you need; attach with
+ * `.plug()`.
+ */
+
+export { compression, type CompressionOptions } from "./compression.ts";
+export {
+  configSource,
+  isConfigSource,
+  resolvePluginOptions,
+  type ConfigSource,
+  type ConfigSourceDb,
+  type ConfigSourceOptions,
+} from "./config-source.ts";
+export { cors, type CorsOptions } from "./cors.ts";
+export { csrf, type CsrfOptions } from "./csrf.ts";
+export { ipAllowlist, type IpAllowlistOptions } from "./ip-allowlist.ts";
+export { maintenanceMode, type MaintenanceModeOptions } from "./maintenance-mode.ts";
+export {
+  defaultCspDirectives,
+  securityHeaders,
+  type CspOptions,
+  type HstsOptions,
+  type SecurityHeadersOptions,
+} from "./security-headers.ts";

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

@@ -0,0 +1,139 @@
+/**
+ * `ip-allowlist` plugin — allow/deny semantics, XFF parsing, and
+ * missing-header behavior through the real pipeline.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { flow, resetFlowSeq } from "../kernel/flow.ts";
+import { on, resetBindings } from "../kernel/on.ts";
+import { http } from "../kernel/triggers.ts";
+import { ipAllowlist } from "./ip-allowlist.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+/** Shorthand: GET /x with an optional x-forwarded-for header. */
+function get(ip?: string): Request {
+  return new Request(
+    "http://localhost/x",
+    ip === undefined ? undefined : { headers: { "x-forwarded-for": ip } },
+  );
+}
+
+describe("ipAllowlist plugin", () => {
+  test("allow list: listed IPs pass, others get 403 Forbidden", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "ips" }).plug(ipAllowlist({ allow: ["203.0.113.7"] }));
+
+    const ok = await app.fetch(get("203.0.113.7"));
+    expect(ok.status).toBe(200);
+
+    const denied = await app.fetch(get("198.51.100.9"));
+    expect(denied.status).toBe(403);
+    const body = (await denied.json()) as { error: { code: string; data: { reason: string } } };
+    expect(body.error.code).toBe("Forbidden");
+    expect(body.error.data.reason).toBe("ip_not_allowed");
+  });
+
+  test("deny list: blocked IPs get 403 ip_denied, others pass", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "ips-deny" }).plug(ipAllowlist({ deny: ["198.51.100.9"] }));
+
+    const blocked = await app.fetch(get("198.51.100.9"));
+    expect(blocked.status).toBe(403);
+    const body = (await blocked.json()) as { error: { data: { reason: string } } };
+    expect(body.error.data.reason).toBe("ip_denied");
+
+    const ok = await app.fetch(get("203.0.113.7"));
+    expect(ok.status).toBe(200);
+  });
+
+  test("deny wins over allow on overlap", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "ips-both" }).plug(
+      ipAllowlist({ allow: ["203.0.113.7"], deny: ["203.0.113.7"] }),
+    );
+
+    const res = await app.fetch(get("203.0.113.7"));
+    expect(res.status).toBe(403);
+  });
+
+  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"] }));
+
+    // 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 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 () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const strict = oke({ name: "ips-missing-allow" }).plug(ipAllowlist({ allow: ["203.0.113.7"] }));
+
+    const denied = await strict.fetch(get());
+    expect(denied.status).toBe(403);
+
+    resetBindings();
+    resetFlowSeq();
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+
+    const lax = oke({ name: "ips-missing-deny" }).plug(ipAllowlist({ deny: ["198.51.100.9"] }));
+    const ok = await lax.fetch(get());
+    expect(ok.status).toBe(200);
+  });
+
+  test("custom header name is honored", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "ips-custom" }).plug(
+      ipAllowlist({ allow: ["203.0.113.7"], header: "x-real-ip" }),
+    );
+
+    const res = await app.fetch(
+      new Request("http://localhost/x", { headers: { "x-real-ip": "203.0.113.7" } }),
+    );
+    expect(res.status).toBe(200);
+
+    const wrongHeader = await app.fetch(get("203.0.113.7"));
+    expect(wrongHeader.status).toBe(403);
+  });
+});