okengine 0.4.3 → 0.5.1

package/src/plugins/{security-headers.test.ts → headers.test.ts}

@@ -1,5 +1,5 @@
 /**
- * `security-headers` plugin — defaults on success, presence on failure,
+ * `headers` plugin — defaults on success, presence on failure,
  * and app-wins override semantics through the real pipeline.
  */
 
@@ -9,17 +9,17 @@ import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { fail } from "../kernel/index.ts";
 import { on, resetBindings } from "../kernel/on.ts";
 import { http } from "../kernel/triggers.ts";
-import { defaultCspDirectives, securityHeaders } from "./security-headers.ts";
+import { defaultCspDirectives, headers } from "./headers.ts";
 
 beforeEach(() => {
   resetBindings();
   resetFlowSeq();
 });
 
-describe("securityHeaders plugin", () => {
+describe("headers plugin", () => {
   test("sets the default trio on a successful response", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec" }).plug(securityHeaders());
+    const app = oke({ autoBoot: false, name: "sec" }).plug(headers());
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -32,7 +32,7 @@ describe("securityHeaders plugin", () => {
 
   test("helmet-parity defaults: agent cluster, dns prefetch, download, cross-domain, xss filter", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-parity" }).plug(securityHeaders());
+    const app = oke({ autoBoot: false, name: "sec-parity" }).plug(headers());
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -45,8 +45,8 @@ describe("securityHeaders plugin", () => {
 
   test("each parity default can be switched off", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-off" }).plug(
-      securityHeaders({
+    const app = oke({ autoBoot: false, name: "sec-off" }).plug(
+      headers({
         originAgentCluster: false,
         dnsPrefetchControl: false,
         downloadOptions: false,
@@ -65,8 +65,8 @@ describe("securityHeaders plugin", () => {
 
   test("dnsPrefetchControl allow, custom cross-domain policy, COEP stamps when configured", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-tuned" }).plug(
-      securityHeaders({
+    const app = oke({ autoBoot: false, name: "sec-tuned" }).plug(
+      headers({
         dnsPrefetchControl: { allow: true },
         permittedCrossDomainPolicies: "by-content-type",
         crossOriginEmbedderPolicy: "require-corp",
@@ -81,7 +81,7 @@ describe("securityHeaders plugin", () => {
   });
 
   test("x-powered-by is removed by default; a string sets a decoy; false keeps the app's", async () => {
-    const poweredByApp = (options: Parameters<typeof securityHeaders>[0], name: string) => {
+    const poweredByApp = (options: Parameters<typeof headers>[0], name: string) => {
       on(
         http.get("/x"),
         flow({
@@ -92,7 +92,7 @@ describe("securityHeaders plugin", () => {
             }),
         }),
       );
-      return oke({ name }).plug(securityHeaders(options));
+      return oke({ autoBoot: false, name }).plug(headers(options));
     };
 
     const removed = await poweredByApp({}, "sec-pb-off").fetch(new Request("http://localhost/x"));
@@ -112,8 +112,8 @@ describe("securityHeaders plugin", () => {
 
   test("structured CSP merges over helmet's defaults, camelCase keys, report-only mode", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-csp-builder" }).plug(
-      securityHeaders({
+    const app = oke({ autoBoot: false, name: "sec-csp-builder" }).plug(
+      headers({
         contentSecurityPolicy: {
           directives: { scriptSrc: ["'self'", "https://cdn.example.com"] },
           reportOnly: true,
@@ -132,8 +132,8 @@ describe("securityHeaders plugin", () => {
 
   test("structured CSP with useDefaults: false emits exactly the given directives", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-csp-bare" }).plug(
-      securityHeaders({
+    const app = oke({ autoBoot: false, name: "sec-csp-bare" }).plug(
+      headers({
         contentSecurityPolicy: { useDefaults: false, directives: { "default-src": ["'none'"] } },
       }),
     );
@@ -155,7 +155,7 @@ describe("securityHeaders plugin", () => {
         fail("Forbidden", {}),
       ),
     );
-    const app = oke({ name: "sec-fail" }).plug(securityHeaders());
+    const app = oke({ autoBoot: false, name: "sec-fail" }).plug(headers());
 
     const res = await app.fetch(new Request("http://localhost/deny"));
 
@@ -165,8 +165,8 @@ describe("securityHeaders plugin", () => {
 
   test("adds CSP only when configured", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-csp" }).plug(
-      securityHeaders({ contentSecurityPolicy: "default-src 'self'" }),
+    const app = oke({ autoBoot: false, name: "sec-csp" }).plug(
+      headers({ contentSecurityPolicy: "default-src 'self'" }),
     );
 
     const res = await app.fetch(new Request("http://localhost/x"));
@@ -176,7 +176,7 @@ describe("securityHeaders plugin", () => {
 
   test("HSTS is off by default", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-hsts-off" }).plug(securityHeaders());
+    const app = oke({ autoBoot: false, name: "sec-hsts-off" }).plug(headers());
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -185,7 +185,7 @@ describe("securityHeaders plugin", () => {
 
   test("hsts: true stamps a one-year max-age", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-hsts-on" }).plug(securityHeaders({ hsts: true }));
+    const app = oke({ autoBoot: false, name: "sec-hsts-on" }).plug(headers({ hsts: true }));
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -194,8 +194,8 @@ describe("securityHeaders plugin", () => {
 
   test("hsts object tunes max-age, subdomains, preload", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-hsts-tuned" }).plug(
-      securityHeaders({ hsts: { maxAge: 63072000, includeSubDomains: true, preload: true } }),
+    const app = oke({ autoBoot: false, name: "sec-hsts-tuned" }).plug(
+      headers({ hsts: { maxAge: 63072000, includeSubDomains: true, preload: true } }),
     );
 
     const res = await app.fetch(new Request("http://localhost/x"));
@@ -207,8 +207,8 @@ describe("securityHeaders plugin", () => {
 
   test("permissions-policy and cross-origin policies stamp when configured", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-extra" }).plug(
-      securityHeaders({
+    const app = oke({ autoBoot: false, name: "sec-extra" }).plug(
+      headers({
         permissionsPolicy: "camera=(), microphone=()",
         crossOriginOpenerPolicy: "same-origin",
         crossOriginResourcePolicy: "same-site",
@@ -224,7 +224,7 @@ describe("securityHeaders plugin", () => {
 
   test("an explicit app-set value wins by default", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "sec-keep" });
+    const app = oke({ autoBoot: false, name: "sec-keep" });
     app.hook("onResponse", (ctx) => {
       if (!ctx.response) return;
       const headers = new Headers(ctx.response.headers);
@@ -234,7 +234,7 @@ describe("securityHeaders plugin", () => {
         headers,
       });
     });
-    app.plug(securityHeaders());
+    app.plug(headers());
 
     const res = await app.fetch(new Request("http://localhost/x"));
 

package/src/plugins/headers.ts

@@ -1,54 +1,253 @@
 /**
- * Shared response-header mutation for HTTP middleware plugins.
- * `Headers` are immutable-in-place on a built `Response` — rebuild instead.
+ * Official `headers` plugin — the complete secure-headers set on every HTTP
+ * response (helmet parity, API-first defaults). Uses only the public plugin
+ * API (unified-theory §14).
  */
 
-/**
- * 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,
-  });
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  isConfigSource,
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  type ConfigSource,
+} from "./config-source.ts";
+import { setUnlessPresent, withHeaders } from "./response-headers.ts";
+
+/** HSTS value options (see {@link HeadersOptions.hsts}). */
+export interface HstsOptions {
+  /** `max-age` in seconds. Default `31536000` (one year). */
+  readonly maxAge?: number;
+  /** Append `includeSubDomains`. Default `false`. */
+  readonly includeSubDomains?: boolean;
+  /** Append `preload`. Only meaningful with subdomains + a ≥1-year max-age. */
+  readonly preload?: boolean;
+}
+
+/** Structured CSP (see {@link HeadersOptions.contentSecurityPolicy}). */
+export interface CspOptions {
+  /**
+   * Directive map — kebab-case (`script-src`) or camelCase (`scriptSrc`)
+   * keys, values as string arrays. An empty array emits a bare directive
+   * (e.g. `upgrade-insecure-requests`).
+   */
+  readonly directives: Readonly<Record<string, readonly string[]>>;
+  /** Merge over {@link defaultCspDirectives}. Default `true`. */
+  readonly useDefaults?: boolean;
+  /** Emit as `Content-Security-Policy-Report-Only`. Default `false`. */
+  readonly reportOnly?: boolean;
 }
 
 /**
- * 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
+ * Helmet's default CSP — the baseline `directives` merge over unless
+ * `useDefaults: false`.
  */
-export function setUnlessPresent(
-  headers: Headers,
-  name: string,
-  value: string,
-  override: boolean,
-): void {
-  if (!override && headers.has(name)) return;
-  headers.set(name, value);
+export const defaultCspDirectives: Readonly<Record<string, readonly string[]>> = {
+  "default-src": ["'self'"],
+  "base-uri": ["'self'"],
+  "font-src": ["'self'", "https:", "data:"],
+  "form-action": ["'self'"],
+  "frame-ancestors": ["'self'"],
+  "img-src": ["'self'", "data:"],
+  "object-src": ["'none'"],
+  "script-src": ["'self'"],
+  "script-src-attr": ["'none'"],
+  "style-src": ["'self'", "https:", "'unsafe-inline'"],
+  "upgrade-insecure-requests": [],
+};
+
+/** Options for {@link headers}. */
+export interface HeadersOptions {
+  /**
+   * Content-Security-Policy — a raw header string, or a structured
+   * {@link CspOptions} (directive builder over helmet's defaults, optional
+   * report-only mode). Omitted unless provided.
+   */
+  readonly contentSecurityPolicy?: string | CspOptions;
+  /** X-Frame-Options value. Default `"DENY"`. */
+  readonly frameOptions?: "DENY" | "SAMEORIGIN";
+  /** Referrer-Policy value. Default `"no-referrer"`. */
+  readonly referrerPolicy?: string;
+  /**
+   * Strict-Transport-Security. `true` → one-year `max-age`; pass an object
+   * to tune. Default off — HSTS is sticky, and local dev is plain HTTP, so
+   * enable it deliberately for HTTPS deployments.
+   */
+  readonly hsts?: boolean | HstsOptions;
+  /** Permissions-Policy value (e.g. `"camera=(), microphone=()"`). Omitted unless provided. */
+  readonly permissionsPolicy?: string;
+  /**
+   * Cross-Origin-Opener-Policy value. Omitted unless provided — opt-in
+   * because OKE serves APIs, where cross-origin clients are legitimate
+   * (helmet targets web pages and defaults it on).
+   */
+  readonly crossOriginOpenerPolicy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
+  /** Cross-Origin-Resource-Policy value. Omitted unless provided (same API rationale). */
+  readonly crossOriginResourcePolicy?: "same-origin" | "same-site" | "cross-origin";
+  /** Cross-Origin-Embedder-Policy value. Omitted unless provided (helmet also defaults it off). */
+  readonly crossOriginEmbedderPolicy?: "require-corp" | "credentialless";
+  /** Origin-Agent-Cluster header. Default `true` → `?1`. */
+  readonly originAgentCluster?: boolean;
+  /**
+   * X-DNS-Prefetch-Control. Default `true` → `off` (privacy-preserving);
+   * `{ allow: true }` → `on`; `false` omits the header.
+   */
+  readonly dnsPrefetchControl?: boolean | { readonly allow: boolean };
+  /** X-Download-Options: noopen (legacy IE8 mitigation, helmet parity). Default `true`. */
+  readonly downloadOptions?: boolean;
+  /** X-Permitted-Cross-Domain-Policies value. Default `"none"`. */
+  readonly permittedCrossDomainPolicies?: "none" | "master-only" | "by-content-type" | "all";
+  /**
+   * X-Powered-By handling. Default `true` → remove the header (it leaks
+   * framework fingerprints). A string sets a custom value; `false` keeps it.
+   */
+  readonly poweredBy?: boolean | string;
+  /**
+   * X-XSS-Protection: 0 — disables the legacy, buggy browser XSS auditor
+   * (helmet parity; modern defense is CSP). Default `true`.
+   */
+  readonly xssProtection?: boolean;
+  /**
+   * Replace headers the app already set. Default `false` — an explicit
+   * app-level value always wins.
+   */
+  readonly override?: boolean;
+}
+
+/** Render the Strict-Transport-Security header value. */
+function hstsValue(hsts: boolean | HstsOptions): string {
+  const opts: HstsOptions = typeof hsts === "object" ? hsts : {};
+  let value = `max-age=${opts.maxAge ?? 31536000}`;
+  if (opts.includeSubDomains) value += "; includeSubDomains";
+  if (opts.preload) value += "; preload";
+  return value;
+}
+
+/** camelCase directive keys → kebab-case (`scriptSrc` → `script-src`). */
+function directiveName(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+/** Build a CSP header value from a directive map. */
+function buildCsp(directives: Readonly<Record<string, readonly string[]>>): string {
+  return Object.entries(directives)
+    .map(([name, values]) => {
+      const kebab = directiveName(name);
+      return values.length === 0 ? kebab : `${kebab} ${values.join(" ")}`;
+    })
+    .join("; ");
+}
+
+/** Resolve the CSP option into header name + value. */
+function cspEntry(option: string | CspOptions): { readonly name: string; readonly value: string } {
+  if (typeof option === "string") return { name: "content-security-policy", value: option };
+  const useDefaults = option.useDefaults ?? true;
+  const merged: Record<string, readonly string[]> = useDefaults
+    ? { ...defaultCspDirectives, ...option.directives }
+    : { ...option.directives };
+  return {
+    name:
+      (option.reportOnly ?? false)
+        ? "content-security-policy-report-only"
+        : "content-security-policy",
+    value: buildCsp(merged),
+  };
 }
 
 /**
- * Append a token to `Vary` without duplicating it.
+ * Apply the complete secure-headers set to every HTTP response, including
+ * failures (runs at `onResponse`, which fires after `onError` too). Covers
+ * every helmet.js middleware; API-first deviations (opt-in HSTS, COOP,
+ * CORP) are documented per option.
+ *
+ * Accepts static options or a {@link ConfigSource} for DB-driven config
+ * (e.g. flip `hsts` from the database without a redeploy).
  *
- * @param headers - Mutable headers
- * @param token - Vary token (e.g. `"origin"`)
+ * @param options - Header values, or a config source
  */
-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}`);
+export function headers(options: HeadersOptions | ConfigSource<HeadersOptions> = {}): PluginDef {
+  const def = plugin("headers", {
+    version: "0.1.0",
+    config: pluginConfigSnapshot(options),
+  }).hook("onResponse", (ctx) => {
+    if (!ctx.response) return;
+    const resolved = resolvePluginOptions(options);
+    const override = resolved.override ?? false;
+
+    ctx.response = withHeaders(ctx.response, (headers) => {
+      setUnlessPresent(headers, "x-content-type-options", "nosniff", override);
+      setUnlessPresent(headers, "x-frame-options", resolved.frameOptions ?? "DENY", override);
+      setUnlessPresent(
+        headers,
+        "referrer-policy",
+        resolved.referrerPolicy ?? "no-referrer",
+        override,
+      );
+
+      if (resolved.originAgentCluster ?? true) {
+        setUnlessPresent(headers, "origin-agent-cluster", "?1", override);
+      }
+      const dns = resolved.dnsPrefetchControl ?? true;
+      if (dns !== false) {
+        const allow = typeof dns === "object" ? dns.allow : false;
+        setUnlessPresent(headers, "x-dns-prefetch-control", allow ? "on" : "off", override);
+      }
+      if (resolved.downloadOptions ?? true) {
+        setUnlessPresent(headers, "x-download-options", "noopen", override);
+      }
+      setUnlessPresent(
+        headers,
+        "x-permitted-cross-domain-policies",
+        resolved.permittedCrossDomainPolicies ?? "none",
+        override,
+      );
+      if (resolved.xssProtection ?? true) {
+        setUnlessPresent(headers, "x-xss-protection", "0", override);
+      }
+
+      const poweredBy = resolved.poweredBy ?? true;
+      if (poweredBy === true) {
+        headers.delete("x-powered-by");
+      } else if (typeof poweredBy === "string") {
+        setUnlessPresent(headers, "x-powered-by", poweredBy, override);
+      }
+
+      if (resolved.contentSecurityPolicy !== undefined) {
+        const csp = cspEntry(resolved.contentSecurityPolicy);
+        setUnlessPresent(headers, csp.name, csp.value, override);
+      }
+      if (resolved.hsts !== undefined && resolved.hsts !== false) {
+        setUnlessPresent(headers, "strict-transport-security", hstsValue(resolved.hsts), override);
+      }
+      if (resolved.permissionsPolicy !== undefined) {
+        setUnlessPresent(headers, "permissions-policy", resolved.permissionsPolicy, override);
+      }
+      if (resolved.crossOriginOpenerPolicy !== undefined) {
+        setUnlessPresent(
+          headers,
+          "cross-origin-opener-policy",
+          resolved.crossOriginOpenerPolicy,
+          override,
+        );
+      }
+      if (resolved.crossOriginResourcePolicy !== undefined) {
+        setUnlessPresent(
+          headers,
+          "cross-origin-resource-policy",
+          resolved.crossOriginResourcePolicy,
+          override,
+        );
+      }
+      if (resolved.crossOriginEmbedderPolicy !== undefined) {
+        setUnlessPresent(
+          headers,
+          "cross-origin-embedder-policy",
+          resolved.crossOriginEmbedderPolicy,
+          override,
+        );
+      }
+    });
+  });
+
+  return isConfigSource(options) ? withConfigTable(def, options) : def;
 }

package/src/plugins/index.ts

@@ -4,6 +4,7 @@
  * `.plug()`.
  */
 
+export { anonymous, type AnonymousPluginOptions } from "./anonymous.ts";
 export { compression, type CompressionOptions } from "./compression.ts";
 export {
   configSource,
@@ -15,12 +16,50 @@ export {
 } from "./config-source.ts";
 export { cors, type CorsOptions } from "./cors.ts";
 export { csrf, type CsrfOptions } from "./csrf.ts";
+export { emailOtp, type EmailOtpOptions } from "./email-otp.ts";
 export { ipAllowlist, type IpAllowlistOptions } from "./ip-allowlist.ts";
+export { magicLink, type MagicLinkOptions } from "./magic-link.ts";
 export { maintenanceMode, type MaintenanceModeOptions } from "./maintenance-mode.ts";
+export {
+  createPasskeyStore,
+  passkey,
+  type PasskeyCredential,
+  type PasskeyOptions,
+  type PasskeyStore,
+} from "./passkey.ts";
+export {
+  b64urlDecode,
+  b64urlEncode,
+  buildAuthenticatorData,
+  signWebAuthnAssertion,
+  verifyWebAuthnCeremony,
+  type WebAuthnVerifyOptions,
+} from "./passkey-webauthn.ts";
+export {
+  createPhoneStore,
+  phoneNumber,
+  type PhoneNumberOptions,
+  type PhoneStore,
+} from "./phone-number.ts";
 export {
   defaultCspDirectives,
-  securityHeaders,
+  headers,
   type CspOptions,
+  type HeadersOptions,
   type HstsOptions,
-  type SecurityHeadersOptions,
-} from "./security-headers.ts";
+} from "./headers.ts";
+export {
+  createTwoFactorStore,
+  twoFactor,
+  verifyTotp,
+  type TwoFactorOptions,
+  type TwoFactorRow,
+  type TwoFactorStore,
+} from "./two-factor.ts";
+export {
+  createUsernameStore,
+  username,
+  type UsernamePluginOptions,
+  type UsernameRow,
+  type UsernameStore,
+} from "./username.ts";

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

@@ -26,7 +26,7 @@ function get(ip?: string): Request {
 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 app = oke({ autoBoot: false, name: "ips" }).plug(ipAllowlist({ allow: ["203.0.113.7"] }));
 
     const ok = await app.fetch(get("203.0.113.7"));
     expect(ok.status).toBe(200);
@@ -40,7 +40,9 @@ describe("ipAllowlist plugin", () => {
 
   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 app = oke({ autoBoot: false, 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);
@@ -53,7 +55,7 @@ describe("ipAllowlist plugin", () => {
 
   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(
+    const app = oke({ autoBoot: false, name: "ips-both" }).plug(
       ipAllowlist({ allow: ["203.0.113.7"], deny: ["203.0.113.7"] }),
     );
 
@@ -63,7 +65,9 @@ describe("ipAllowlist plugin", () => {
 
   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 app = oke({ autoBoot: false, 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"));
@@ -75,7 +79,9 @@ describe("ipAllowlist plugin", () => {
 
   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"] }));
+    const app = oke({ autoBoot: false, 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"));
@@ -88,7 +94,7 @@ describe("ipAllowlist plugin", () => {
   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(
+    const app = oke({ autoBoot: false, name: "ips-depth" }).plug(
       ipAllowlist({ allow: ["203.0.113.7"], trustedProxyDepth: 2 }),
     );
 
@@ -108,7 +114,9 @@ describe("ipAllowlist plugin", () => {
 
   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 strict = oke({ autoBoot: false, name: "ips-missing-allow" }).plug(
+      ipAllowlist({ allow: ["203.0.113.7"] }),
+    );
 
     const denied = await strict.fetch(get());
     expect(denied.status).toBe(403);
@@ -117,14 +125,16 @@ describe("ipAllowlist plugin", () => {
     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 lax = oke({ autoBoot: false, 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(
+    const app = oke({ autoBoot: false, name: "ips-custom" }).plug(
       ipAllowlist({ allow: ["203.0.113.7"], header: "x-real-ip" }),
     );