okengine 0.2.8 → 0.3.4

package/src/plugins/ip-allowlist.ts

@@ -0,0 +1,129 @@
+/**
+ * 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"`.
+   *
+   * 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.
+ *
+ * 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 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];
+}
+
+/**
+ * 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 {
+  assertSafeIpAllowlistOptions(pluginConfigSnapshot(options));
+
+  const def = plugin("ip-allowlist", {
+    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 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 });
+    }
+    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");
+  });
+});

package/src/plugins/maintenance-mode.ts

@@ -0,0 +1,85 @@
+/**
+ * Official `maintenance-mode` plugin — drain HTTP traffic with one flag.
+ * Uses only the public plugin API (unified-theory §14).
+ */
+
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  isConfigSource,
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  type ConfigSource,
+} from "./config-source.ts";
+
+/** Options for {@link maintenanceMode}. */
+export interface MaintenanceModeOptions {
+  /**
+   * Whether the mode is active. Default `true` — plugging the plugin turns
+   * it on. Drive it from the environment to flip without a code change:
+   * `enabled: process.env.MAINTENANCE_MODE === "1"`.
+   */
+  readonly enabled?: boolean;
+  /** `Retry-After` value in seconds on the 503. Omitted unless provided. */
+  readonly retryAfter?: number;
+  /**
+   * Path prefixes that keep serving while the mode is active (e.g.
+   * `["/health"]` so load-balancer checks stay green).
+   */
+  readonly allowPaths?: readonly string[];
+  /**
+   * Operator bypass: requests carrying this header name (any non-empty
+   * value) pass through. Presence-based — an ops convenience, not auth.
+   */
+  readonly bypassHeader?: string;
+  /** Failure message in the envelope. Default `"Service is under maintenance."` */
+  readonly message?: string;
+}
+
+/**
+ * Short-circuit every HTTP invocation at `onRequest` with a 503 failure
+ * envelope (`ServiceUnavailable`) plus an optional `Retry-After`. Excluded
+ * prefixes and the bypass header keep ops paths alive. The 503 still flows
+ * through `onResponse`, so response-shaping plugins (security headers,
+ * compression) apply to it too. Non-HTTP triggers no-op — clock flows and
+ * signal subscribers keep running.
+ *
+ * Accepts static options or a {@link ConfigSource} — the flagship use
+ * case: flip `enabled` from the database and drain traffic without a
+ * redeploy.
+ *
+ * @param options - Flag, retry hint, allow-list, bypass — or a config source
+ */
+export function maintenanceMode(
+  options: MaintenanceModeOptions | ConfigSource<MaintenanceModeOptions> = {},
+): PluginDef {
+  const def = plugin("maintenance-mode", {
+    version: "0.0.2",
+    config: pluginConfigSnapshot(options),
+  }).hook("onRequest", (ctx) => {
+    const resolved = resolvePluginOptions(options);
+    if ((resolved.enabled ?? true) === false || !ctx.request) return;
+    const message = resolved.message ?? "Service is under maintenance.";
+
+    const { pathname } = new URL(ctx.request.url);
+    if (resolved.allowPaths?.some((prefix) => pathname.startsWith(prefix))) return;
+
+    const bypass = resolved.bypassHeader;
+    if (bypass !== undefined) {
+      const value = ctx.request.headers.get(bypass);
+      if (value !== null && value.length > 0) return;
+    }
+
+    const headers: Record<string, string> = {};
+    if (resolved.retryAfter !== undefined) headers["retry-after"] = String(resolved.retryAfter);
+    return Response.json(
+      {
+        data: null,
+        error: { code: "ServiceUnavailable", data: { retryAfter: resolved.retryAfter }, message },
+      },
+      { status: 503, headers },
+    );
+  });
+
+  return isConfigSource(options) ? withConfigTable(def, options) : def;
+}

package/src/plugins/security-headers.test.ts

@@ -0,0 +1,243 @@
+/**
+ * `security-headers` plugin — defaults on success, presence on failure,
+ * and app-wins override semantics 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 { 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";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("securityHeaders 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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(res.headers.get("x-frame-options")).toBe("DENY");
+    expect(res.headers.get("referrer-policy")).toBe("no-referrer");
+    expect(res.headers.get("content-security-policy")).toBeNull();
+  });
+
+  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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("origin-agent-cluster")).toBe("?1");
+    expect(res.headers.get("x-dns-prefetch-control")).toBe("off");
+    expect(res.headers.get("x-download-options")).toBe("noopen");
+    expect(res.headers.get("x-permitted-cross-domain-policies")).toBe("none");
+    expect(res.headers.get("x-xss-protection")).toBe("0");
+  });
+
+  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({
+        originAgentCluster: false,
+        dnsPrefetchControl: false,
+        downloadOptions: false,
+        xssProtection: false,
+      }),
+    );
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("origin-agent-cluster")).toBeNull();
+    expect(res.headers.get("x-dns-prefetch-control")).toBeNull();
+    expect(res.headers.get("x-download-options")).toBeNull();
+    expect(res.headers.get("x-xss-protection")).toBeNull();
+    expect(res.headers.get("x-permitted-cross-domain-policies")).toBe("none");
+  });
+
+  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({
+        dnsPrefetchControl: { allow: true },
+        permittedCrossDomainPolicies: "by-content-type",
+        crossOriginEmbedderPolicy: "require-corp",
+      }),
+    );
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("x-dns-prefetch-control")).toBe("on");
+    expect(res.headers.get("x-permitted-cross-domain-policies")).toBe("by-content-type");
+    expect(res.headers.get("cross-origin-embedder-policy")).toBe("require-corp");
+  });
+
+  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) => {
+      on(
+        http.get("/x"),
+        flow({
+          name: "x.get",
+          do: () =>
+            new Response("{}", {
+              headers: { "content-type": "application/json", "x-powered-by": "Express" },
+            }),
+        }),
+      );
+      return oke({ name }).plug(securityHeaders(options));
+    };
+
+    const removed = await poweredByApp({}, "sec-pb-off").fetch(new Request("http://localhost/x"));
+    expect(removed.headers.get("x-powered-by")).toBeNull();
+
+    const decoy = await poweredByApp(
+      { poweredBy: "PHP 4.2.0", override: true },
+      "sec-pb-decoy",
+    ).fetch(new Request("http://localhost/x"));
+    expect(decoy.headers.get("x-powered-by")).toBe("PHP 4.2.0");
+
+    const kept = await poweredByApp({ poweredBy: false }, "sec-pb-keep").fetch(
+      new Request("http://localhost/x"),
+    );
+    expect(kept.headers.get("x-powered-by")).toBe("Express");
+  });
+
+  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({
+        contentSecurityPolicy: {
+          directives: { scriptSrc: ["'self'", "https://cdn.example.com"] },
+          reportOnly: true,
+        },
+      }),
+    );
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("content-security-policy")).toBeNull();
+    const reportOnly = res.headers.get("content-security-policy-report-only");
+    expect(reportOnly).toContain("script-src 'self' https://cdn.example.com");
+    expect(reportOnly).toContain("default-src 'self'");
+    expect(reportOnly).toContain("upgrade-insecure-requests");
+  });
+
+  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({
+        contentSecurityPolicy: { useDefaults: false, directives: { "default-src": ["'none'"] } },
+      }),
+    );
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+    expect(res.headers.get("content-security-policy")).toBe("default-src 'none'");
+  });
+
+  test("defaultCspDirectives matches helmet's documented default policy", () => {
+    expect(defaultCspDirectives["upgrade-insecure-requests"]).toEqual([]);
+    expect(defaultCspDirectives["script-src-attr"]).toEqual(["'none'"]);
+    expect(Object.keys(defaultCspDirectives)).toHaveLength(11);
+  });
+
+  test("headers land on failures too (onResponse runs after onError)", async () => {
+    on(
+      http.get("/deny"),
+      flow({ name: "x.deny", do: () => ({ ok: true }) }).hook("beforeHandle", () =>
+        fail("Forbidden", {}),
+      ),
+    );
+    const app = oke({ name: "sec-fail" }).plug(securityHeaders());
+
+    const res = await app.fetch(new Request("http://localhost/deny"));
+
+    expect(res.status).not.toBe(200);
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+  });
+
+  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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("content-security-policy")).toBe("default-src 'self'");
+  });
+
+  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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("strict-transport-security")).toBeNull();
+  });
+
+  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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("strict-transport-security")).toBe("max-age=31536000");
+  });
+
+  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 res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("strict-transport-security")).toBe(
+      "max-age=63072000; includeSubDomains; preload",
+    );
+  });
+
+  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({
+        permissionsPolicy: "camera=(), microphone=()",
+        crossOriginOpenerPolicy: "same-origin",
+        crossOriginResourcePolicy: "same-site",
+      }),
+    );
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("permissions-policy")).toBe("camera=(), microphone=()");
+    expect(res.headers.get("cross-origin-opener-policy")).toBe("same-origin");
+    expect(res.headers.get("cross-origin-resource-policy")).toBe("same-site");
+  });
+
+  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" });
+    app.hook("onResponse", (ctx) => {
+      if (!ctx.response) return;
+      const headers = new Headers(ctx.response.headers);
+      headers.set("x-frame-options", "SAMEORIGIN");
+      ctx.response = new Response(ctx.response.body, {
+        status: ctx.response.status,
+        headers,
+      });
+    });
+    app.plug(securityHeaders());
+
+    const res = await app.fetch(new Request("http://localhost/x"));
+
+    expect(res.headers.get("x-frame-options")).toBe("SAMEORIGIN");
+  });
+});