okengine 0.2.8 → 0.3.4

package/src/plugins/security-headers.ts

@@ -0,0 +1,255 @@
+/**
+ * Official `security-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).
+ */
+
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  isConfigSource,
+  pluginConfigSnapshot,
+  resolvePluginOptions,
+  withConfigTable,
+  type ConfigSource,
+} from "./config-source.ts";
+import { setUnlessPresent, withHeaders } from "./headers.ts";
+
+/** HSTS value options (see {@link SecurityHeadersOptions.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 SecurityHeadersOptions.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;
+}
+
+/**
+ * Helmet's default CSP — the baseline `directives` merge over unless
+ * `useDefaults: false`.
+ */
+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 securityHeaders}. */
+export interface SecurityHeadersOptions {
+  /**
+   * 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),
+  };
+}
+
+/**
+ * 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 options - Header values, or a config source
+ */
+export function securityHeaders(
+  options: SecurityHeadersOptions | ConfigSource<SecurityHeadersOptions> = {},
+): PluginDef {
+  const def = plugin("security-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/release/measure.ts

@@ -29,7 +29,6 @@ const BUILD_EXTERNALS = ["@duckdb/node-api", "@duckdb/*"] as const;
 /** Heavy optional / peer packages — not counted in export:* gzip samples. */
 const EXPORT_BUILD_EXTERNALS = [
   ...BUILD_EXTERNALS,
-  "age-encryption",
   "sently",
   "sently/*",
   "ajv",
@@ -515,7 +514,7 @@ export function formatBudgetsMarkdown(snapshot: BudgetsSnapshot): string {
     "",
     `_okengine v${snapshot.version} · measured ${snapshot.measuredAt}_`,
     "",
-    "Core rows are absolute AGENTS caps. Exports and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `age-encryption`, `sently`, `oxc-parser`, `ajv`).",
+    "Core rows are absolute AGENTS caps. Exports and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `sently`, `oxc-parser`, `ajv`).",
   ];
   const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
   for (const group of order) {

package/src/test/create-test-app.ts

@@ -32,6 +32,7 @@ import type { OkeApp } from "../kernel/app.ts";
 import type { BootOptions } from "../kernel/boot.ts";
 import type { EffectEntry } from "../kernel/effects.ts";
 import { fail, type FlowFailure } from "../kernel/errors.ts";
+import { isJsonResult } from "../kernel/fx.ts";
 import { isFlowFailure } from "../kernel/hooks.ts";
 import type { ResolvedPrincipal } from "../kernel/pipeline.ts";
 import type { InternalTrigger, Trigger } from "../kernel/triggers.ts";
@@ -151,7 +152,7 @@ export interface TestApp<App extends OkeApp = OkeApp> {
 export type TestApiCall = (
   input?: unknown,
   opts?: TestCallOptions,
-) => Promise<{ data: unknown; error: FlowFailure["error"] | null }>;
+) => Promise<{ data: unknown; error: FlowFailure["error"] | null; meta?: Record<string, unknown> }>;
 
 /** Loose API proxy — units/flows resolve at runtime from the booted app. */
 export type TestApi = Record<string, Record<string, TestApiCall>>;
@@ -341,7 +342,11 @@ function createTestApi(app: OkeApp, now: () => number): TestApi {
     flowName: string,
     input: unknown,
     opts?: TestCallOptions,
-  ): Promise<{ data: unknown; error: FlowFailure["error"] | null }> => {
+  ): Promise<{
+    data: unknown;
+    error: FlowFailure["error"] | null;
+    meta?: Record<string, unknown>;
+  }> => {
     const flowDef =
       app.flow(`${unit}.${flowName}`) ?? app.flow(flowName) ?? findFlowByUnit(app, unit, flowName);
     if (!flowDef) {
@@ -373,6 +378,13 @@ function createTestApi(app: OkeApp, now: () => number): TestApi {
     if (result.output !== undefined && isFlowFailure(result.output)) {
       return { data: null, error: result.output.error };
     }
+    if (isJsonResult(result.output)) {
+      return {
+        data: result.output.value,
+        error: null,
+        meta: result.output.meta,
+      };
+    }
     return { data: result.output ?? null, error: null };
   };