okengine 0.2.6 → 0.3.2

package/src/plugins/cors.ts

@@ -0,0 +1,129 @@
+/**
+ * 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.
+   */
+  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`. When set, an `origin`
+   * of `"*"` is answered by reflecting the request origin — browsers
+   * reject `"*"` together with credentials.
+   */
+  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;
+
+/** 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 === "*" && options.credentials !== true ? "*" : 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 {
+  const def = plugin("cors", { version: "0.0.1", config: pluginConfigSnapshot(options) })
+    .edge((request, info) => {
+      if (!isPreflight(request, info.method)) return undefined;
+      const resolved = resolvePluginOptions(options);
+      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);
+      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,105 @@
+/**
+ * `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 first hop is the client; later hops are ignored", 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);
+
+    const spoofedTail = await app.fetch(get("198.51.100.9, 203.0.113.7"));
+    expect(spoofedTail.status).toBe(403);
+  });
+
+  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);
+  });
+});

package/src/plugins/ip-allowlist.ts

@@ -0,0 +1,76 @@
+/**
+ * Official `ip-allowlist` plugin — client-IP allow/deny rules at the edge
+ * of the pipeline. Uses only the public plugin API (unified-theory §14).
+ */
+
+import { fail } from "../kernel/errors.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  isConfigSource,
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  type ConfigSource,
+} from "./config-source.ts";
+
+/** Options for {@link ipAllowlist}. */
+export interface IpAllowlistOptions {
+  /**
+   * Client IPs permitted to call any flow. When set, every other client
+   * gets `Forbidden`. Exact IPv4/IPv6 strings.
+   */
+  readonly allow?: readonly string[];
+  /**
+   * Client IPs blocked from calling any flow. Checked before `allow`, so
+   * a deny always wins on overlap.
+   */
+  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.
+   */
+  readonly header?: string;
+}
+
+/** Extract the client IP from the configured header (first hop for XFF). */
+function clientIp(request: Request, header: string): 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;
+}
+
+/**
+ * Enforce IP allow/deny rules at `onAuth`, before any gate policy or flow
+ * body runs. Denied clients get the same typed `Forbidden` denial the gate
+ * element produces. A missing/empty IP header is denied when `allow` is
+ * set, permitted otherwise. Non-HTTP triggers no-op.
+ *
+ * Accepts static options or a {@link ConfigSource} — block an abusive IP
+ * from the database and have every instance pick it up on the next sync.
+ *
+ * @param options - Allow/deny lists and header name, or a config source
+ */
+export function ipAllowlist(
+  options: IpAllowlistOptions | ConfigSource<IpAllowlistOptions>,
+): PluginDef {
+  const def = plugin("ip-allowlist", {
+    version: "0.0.2",
+    config: pluginConfigSnapshot(options),
+  }).hook("onAuth", (ctx) => {
+    if (!ctx.request) return;
+    const resolved = resolvePluginOptions(options);
+    const header = (resolved.header ?? "x-forwarded-for").toLowerCase();
+    const ip = clientIp(ctx.request, header);
+
+    if (ip !== undefined && (resolved.deny ?? []).includes(ip)) {
+      return fail("Forbidden", { reason: "ip_denied", ip });
+    }
+    if (resolved.allow !== undefined && (ip === undefined || !resolved.allow.includes(ip))) {
+      return fail("Forbidden", { reason: "ip_not_allowed", ip });
+    }
+  });
+
+  return isConfigSource(options) ? withConfigTable(def, options) : def;
+}

package/src/plugins/maintenance-mode.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `maintenance-mode` plugin — 503 drain behavior, allow-paths, bypass
+ * header, and non-HTTP no-op 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 { maintenanceMode } from "./maintenance-mode.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("maintenanceMode plugin", () => {
+  test("returns 503 with ServiceUnavailable envelope and Retry-After", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "maint" }).plug(maintenanceMode({ retryAfter: 120 }));
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.status).toBe(503);
+    expect(res.headers.get("retry-after")).toBe("120");
+    const body = (await res.json()) as {
+      data: null;
+      error: { code: string; data: { retryAfter?: number }; message?: string };
+    };
+    expect(body.data).toBeNull();
+    expect(body.error.code).toBe("ServiceUnavailable");
+    expect(body.error.data.retryAfter).toBe(120);
+    expect(body.error.message).toBe("Service is under maintenance.");
+  });
+
+  test("enabled: false passes traffic through", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "maint-off" }).plug(maintenanceMode({ enabled: false }));
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.status).toBe(200);
+  });
+
+  test("allowPaths prefixes keep serving", async () => {
+    on(http.get("/health"), flow({ name: "health.get", do: () => ({ up: true }) }));
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "maint-allow" }).plug(maintenanceMode({ allowPaths: ["/health"] }));
+
+    const health = await app.fetch(new Request("http://localhost/health"));
+    expect(health.status).toBe(200);
+
+    const x = await app.fetch(new Request("http://localhost/x"));
+    expect(x.status).toBe(503);
+  });
+
+  test("bypass header lets operators through (any non-empty value)", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "maint-bypass" }).plug(
+      maintenanceMode({ bypassHeader: "x-ops-token" }),
+    );
+
+    const blocked = await app.fetch(new Request("http://localhost/x"));
+    expect(blocked.status).toBe(503);
+
+    const allowed = await app.fetch(
+      new Request("http://localhost/x", { headers: { "x-ops-token": "let-me-in" } }),
+    );
+    expect(allowed.status).toBe(200);
+  });
+
+  test("the 503 still flows through onResponse (other plugins stamp it)", async () => {
+    on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
+    const app = oke({ name: "maint-stamp" }).plug(maintenanceMode());
+    app.hook("onResponse", (ctx) => {
+      if (!ctx.response) return;
+      const headers = new Headers(ctx.response.headers);
+      headers.set("x-stamped", "yes");
+      ctx.response = new Response(ctx.response.body, {
+        status: ctx.response.status,
+        headers,
+      });
+    });
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.status).toBe(503);
+    expect(res.headers.get("x-stamped")).toBe("yes");
+  });
+});