okengine 0.1.4

package/src/runtime/serve.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, 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 { createBunRuntime } from "./bun.ts";
+import { createWebStandardRuntime } from "./web-standard.ts";
+import type { ServerHandle } from "./types.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+/**
+ * Send a raw HTTP/1.1 request so the Host header is not rewritten by fetch.
+ *
+ * @param port - Listening port
+ * @param payload - Full request bytes as text
+ */
+function rawHttp(port: number, payload: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    };
+    Bun.connect({
+      hostname: "127.0.0.1",
+      port,
+      socket: {
+        open(socket) {
+          socket.write(payload);
+        },
+        data(_socket, data) {
+          chunks.push(Buffer.from(data));
+          if (Buffer.concat(chunks).toString("utf8").includes("\r\n\r\n")) {
+            finish();
+          }
+        },
+        close: finish,
+        error(_socket, err) {
+          if (!settled) {
+            settled = true;
+            reject(err);
+          }
+        },
+      },
+    }).catch(reject);
+    setTimeout(() => finish(), 2000);
+  });
+}
+
+function buildApp() {
+  on(
+    http.get("/ping"),
+    flow({
+      name: "ping",
+      do: () => ({ ok: true as const, n: 1 }),
+    }),
+  );
+  on(
+    http.get("/notes/:id"),
+    flow({
+      name: "notes.get",
+      do: ({ id }: { id: string }) => ({ id }),
+    }),
+  );
+  return oke({ name: "runtime-serve" });
+}
+
+describe("Bun.serve — real HTTP", () => {
+  let handle: ServerHandle | undefined;
+
+  afterEach(() => {
+    handle?.stop(true);
+    handle = undefined;
+  });
+
+  test("a request to a flow returns its typed response", async () => {
+    const app = buildApp();
+    const rt = createBunRuntime();
+    handle = rt.serve(app, { port: 0, hostname: "127.0.0.1" });
+
+    const res = await fetch(new URL("/ping", handle.url));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      data: { ok: true, n: 1 },
+      error: null,
+    });
+  });
+
+  test("Host: attacker.com returns 403", async () => {
+    const app = buildApp();
+    const rt = createBunRuntime();
+    handle = rt.serve(app, { port: 0, hostname: "127.0.0.1" });
+
+    // Pipeline-level (fetch() clients rewrite Host to the URL host).
+    const direct = await handle.fetch(
+      new Request(new URL("/ping", handle.url).href, {
+        headers: { host: "attacker.com" },
+      }),
+    );
+    expect(direct.status).toBe(403);
+    expect(await direct.text()).toContain("Host");
+
+    // On the wire — the DNS-rebinding shape (CVE-2025-66414 class).
+    const wire = await rawHttp(handle.port, [
+      "GET /ping HTTP/1.1",
+      "Host: attacker.com",
+      "Connection: close",
+      "",
+      "",
+    ].join("\r\n"));
+    expect(wire).toContain("403");
+    expect(wire).toContain("Host");
+  });
+
+  test("allowedHosts accepts reverse-proxy hostname", async () => {
+    const app = buildApp();
+    const rt = createBunRuntime();
+    handle = rt.serve(app, {
+      port: 0,
+      hostname: "127.0.0.1",
+      allowedHosts: ["app.example.com"],
+    });
+
+    const ok = await handle.fetch(
+      new Request("http://app.example.com/ping", {
+        headers: { host: "app.example.com" },
+      }),
+    );
+    expect(ok.status).toBe(200);
+
+    const bad = await handle.fetch(
+      new Request("http://evil.example.com/ping", {
+        headers: { host: "evil.example.com" },
+      }),
+    );
+    expect(bad.status).toBe(403);
+  });
+
+  test("param route serves through Bun native routes + app pipeline", async () => {
+    const app = buildApp();
+    const rt = createBunRuntime();
+    handle = rt.serve(app, { port: 0, hostname: "127.0.0.1" });
+
+    const res = await fetch(new URL("/notes/abc", handle.url));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      data: { id: "abc" },
+      error: null,
+    });
+  });
+
+  test("sqlite and Bun.password are available", async () => {
+    const rt = createBunRuntime();
+    const db = rt.sqlite(":memory:");
+    db.run("CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)");
+    db.run("INSERT INTO t (v) VALUES (?)", ["hello"]);
+    const row = db.query("SELECT v FROM t").get() as { v: string };
+    expect(row.v).toBe("hello");
+    db.close();
+
+    const hash = await rt.crypto.hashPassword("secret");
+    expect(await rt.crypto.verifyPassword("secret", hash)).toBe(true);
+    expect(await rt.crypto.verifyPassword("nope", hash)).toBe(false);
+  });
+});
+
+describe("web-standard adapter — identical behaviour", () => {
+  test("same app object, same secured responses as Bun handle.fetch", async () => {
+    const app = buildApp();
+    const bun = createBunRuntime().serve(app, {
+      port: 0,
+      hostname: "127.0.0.1",
+      allowedHosts: ["app.example.com"],
+    });
+    const web = createWebStandardRuntime().serve(app, {
+      port: bun.port,
+      hostname: "127.0.0.1",
+      allowedHosts: ["app.example.com"],
+    });
+
+    try {
+      const cases: Request[] = [
+        new Request("http://127.0.0.1/ping", {
+          headers: { host: "127.0.0.1" },
+        }),
+        new Request("http://127.0.0.1/notes/x", {
+          headers: { host: "127.0.0.1" },
+        }),
+        new Request("http://attacker.com/ping", {
+          headers: { host: "attacker.com" },
+        }),
+        new Request("http://127.0.0.1/ping", {
+          headers: {
+            host: "127.0.0.1",
+            origin: "http://attacker.com",
+          },
+        }),
+        new Request("http://app.example.com/ping", {
+          headers: { host: "app.example.com" },
+        }),
+      ];
+
+      for (const req of cases) {
+        const twin = new Request(req.url, {
+          method: req.method,
+          headers: req.headers,
+        });
+        const [a, b] = await Promise.all([bun.fetch(req), web.fetch(twin)]);
+        expect(b.status).toBe(a.status);
+        expect(await b.text()).toBe(await a.text());
+      }
+    } finally {
+      bun.stop(true);
+      web.stop();
+    }
+  });
+});

package/src/runtime/types.ts

@@ -0,0 +1,217 @@
+/**
+ * Runtime adapter contract — WinterTC Minimum Common Web API surface
+ * plus the few host capabilities (serve, env, files, password) every
+ * adapter must expose.
+ *
+ * Bun is primary (`Bun.serve`); Node / Deno / edge use the web-standard
+ * fetch-handler path. Program against Web APIs (`Request`, `Response`,
+ * `crypto`, timers); native clients live behind this interface.
+ */
+
+/** Default application listen port (O·K·E mnemonic). */
+export const APP_PORT = 6530;
+
+/** Default Console listen port (O·K·E mnemonic). */
+export const CONSOLE_PORT = 6533;
+
+/** Default MCP listen port (O·K·E mnemonic). */
+export const MCP_PORT = 6535;
+
+/**
+ * Minimal app surface a runtime can serve.
+ * Satisfied by {@link import("../kernel/app.ts").OkeApp}.
+ */
+export interface FetchApp {
+  /** Application name (Manifest `app`). */
+  readonly name: string;
+  /**
+   * Web-standard fetch handler — the single request pipeline.
+   *
+   * @param request - Incoming request
+   */
+  fetch(request: Request): Response | Promise<Response>;
+  /**
+   * Adopted bindings (used by the Bun adapter for native `routes`).
+   * Optional so plain `{ fetch }` apps still serve.
+   */
+  readonly bindings?: ReadonlyArray<{
+    readonly trigger: {
+      readonly kind: string;
+      readonly method?: string;
+      readonly path?: string;
+    };
+  }>;
+}
+
+/**
+ * Options for {@link Runtime.serve}.
+ *
+ * Host / Origin validation is **mandatory and always on** (console §10.1).
+ * There is no flag to disable it.
+ */
+export interface ServeOptions {
+  /** Listen port. Defaults to {@link APP_PORT}. Use `0` for an ephemeral port. */
+  readonly port?: number;
+  /** Listen hostname. Defaults to `127.0.0.1`. */
+  readonly hostname?: string;
+  /**
+   * Stable {@link Bun.serve} identity for `bun --hot` soft reload.
+   * When set, Bun updates handlers on the existing socket instead of
+   * opening a second listener.
+   */
+  readonly id?: string;
+  /**
+   * Extra hostnames accepted in `Host` / `Origin` (reverse proxies).
+   * Always merged with loopback defaults and the listen hostname —
+   * never replaces the mandatory check.
+   */
+  readonly allowedHosts?: readonly string[];
+}
+
+/** Handle returned by {@link Runtime.serve}. */
+export interface ServerHandle {
+  /** Base URL of the listening server (`http://hostname:port/`). */
+  readonly url: URL;
+  /** Bound port (resolved when `port: 0`). */
+  readonly port: number;
+  /** Listen hostname. */
+  readonly hostname: string;
+  /**
+   * Secured fetch pipeline — identical to what the listener runs.
+   * Edge / Node / Deno adapters expose this as the exportable handler.
+   *
+   * @param request - Incoming request
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Stop accepting connections.
+   *
+   * @param closeActiveConnections - When true, abort in-flight work
+   */
+  stop(closeActiveConnections?: boolean): void | Promise<void>;
+}
+
+/** Timer primitives (WinterTC / HTML timers). */
+export interface RuntimeTimers {
+  /**
+   * Resolve after `ms` milliseconds.
+   *
+   * @param ms - Delay
+   */
+  sleep(ms: number): Promise<void>;
+  /**
+   * @param fn - Callback
+   * @param ms - Delay
+   */
+  setTimeout(fn: () => void, ms: number): unknown;
+  /**
+   * @param id - Handle from {@link RuntimeTimers.setTimeout}
+   */
+  clearTimeout(id: unknown): void;
+  /**
+   * @param fn - Callback
+   * @param ms - Interval
+   */
+  setInterval(fn: () => void, ms: number): unknown;
+  /**
+   * @param id - Handle from {@link RuntimeTimers.setInterval}
+   */
+  clearInterval(id: unknown): void;
+  /** High-resolution monotonic time in milliseconds. */
+  now(): number;
+}
+
+/** Password algorithm accepted by {@link RuntimeCrypto.hashPassword}. */
+export type PasswordAlgorithm = "argon2id" | "bcrypt" | "pbkdf2";
+
+/**
+ * Crypto surface — Web Crypto plus password hash/verify.
+ * Bun binds `Bun.password`; web-standard uses PBKDF2 via SubtleCrypto.
+ */
+export interface RuntimeCrypto {
+  /** Web Crypto `subtle`. */
+  readonly subtle: SubtleCrypto;
+  /** RFC 4122 UUID via `crypto.randomUUID`. */
+  randomUUID(): string;
+  /**
+   * Fill a typed array with cryptographically strong random values.
+   *
+   * @param array - Destination buffer
+   */
+  getRandomValues<T extends ArrayBufferView>(array: T): T;
+  /**
+   * Hash a password.
+   *
+   * @param password - Plaintext
+   * @param algorithm - Hash algorithm (Bun default `argon2id`)
+   */
+  hashPassword(
+    password: string,
+    algorithm?: PasswordAlgorithm,
+  ): Promise<string>;
+  /**
+   * Verify a password against a hash from {@link RuntimeCrypto.hashPassword}.
+   *
+   * @param password - Plaintext
+   * @param hash - Stored hash
+   */
+  verifyPassword(password: string, hash: string): Promise<boolean>;
+}
+
+/** Process environment access. */
+export interface RuntimeEnv {
+  /**
+   * @param key - Variable name
+   */
+  get(key: string): string | undefined;
+  /**
+   * @param key - Variable name
+   */
+  has(key: string): boolean;
+}
+
+/** Filesystem access for runtime adapters (not flow code — flows use `fx`). */
+export interface RuntimeFiles {
+  /**
+   * Read a file as bytes.
+   *
+   * @param path - Absolute or cwd-relative path
+   */
+  read(path: string): Promise<Uint8Array>;
+  /**
+   * Write bytes or UTF-8 text to a file.
+   *
+   * @param path - Destination path
+   * @param data - Contents
+   */
+  write(path: string, data: Uint8Array | string): Promise<void>;
+  /**
+   * @param path - Path to test
+   */
+  exists(path: string): Promise<boolean>;
+}
+
+/** Discriminator for the active adapter. */
+export type RuntimeName = "bun" | "web-standard";
+
+/**
+ * Runtime adapter — serve HTTP and expose host primitives.
+ *
+ * All world-facing I/O for the process goes through an adapter; flow code
+ * still reaches the world only via `fx`.
+ */
+export interface Runtime {
+  /** Adapter id. */
+  readonly name: RuntimeName;
+  /**
+   * Serve an app. Host / Origin checks run on every request.
+   *
+   * @param app - Fetch-capable application
+   * @param options - Listen + `allowedHosts`
+   */
+  serve(app: FetchApp, options?: ServeOptions): ServerHandle;
+  readonly timers: RuntimeTimers;
+  readonly crypto: RuntimeCrypto;
+  readonly env: RuntimeEnv;
+  readonly files: RuntimeFiles;
+}

package/src/runtime/web-standard.ts

@@ -0,0 +1,77 @@
+/**
+ * Web-standard runtime adapter — fetch-handler path for Node / Deno / edge.
+ *
+ * Does not open a socket. {@link Runtime.serve} returns a {@link ServerHandle}
+ * whose `fetch` is the secured pipeline; hosts wire it as:
+ *
+ * ```ts
+ * const handle = createWebStandardRuntime().serve(app);
+ * export default { fetch: handle.fetch }; // edge
+ * Deno.serve(handle.fetch);
+ * ```
+ *
+ * Host / Origin validation is identical to the Bun adapter (console §10.1).
+ */
+
+import {
+  createEnv,
+  createFiles,
+  createTimers,
+  createWebCrypto,
+} from "./primitives.ts";
+import { secureFetch } from "./security.ts";
+import {
+  APP_PORT,
+  type FetchApp,
+  type Runtime,
+  type ServeOptions,
+  type ServerHandle,
+} from "./types.ts";
+
+/**
+ * Create the web-standard (Node / Deno / edge) runtime adapter.
+ */
+export function createWebStandardRuntime(): Runtime {
+  return {
+    name: "web-standard",
+    timers: createTimers(),
+    crypto: createWebCrypto(),
+    env: createEnv(),
+    files: createFiles(),
+    serve(app, options) {
+      return createFetchHandle(app, options);
+    },
+  };
+}
+
+/**
+ * Build a secured fetch handle without listening.
+ *
+ * @param app - Application
+ * @param options - Port/hostname metadata + `allowedHosts`
+ */
+function createFetchHandle(
+  app: FetchApp,
+  options?: ServeOptions,
+): ServerHandle {
+  const port = options?.port ?? APP_PORT;
+  const hostname = options?.hostname ?? "127.0.0.1";
+  const fetchHandler = secureFetch(
+    (req) => app.fetch(req),
+    options,
+    hostname,
+  );
+  const url = new URL(
+    `http://${hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname}:${port}/`,
+  );
+
+  return {
+    url,
+    port,
+    hostname,
+    fetch: fetchHandler,
+    stop() {
+      // No socket — nothing to close.
+    },
+  };
+}

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

@@ -0,0 +1,161 @@
+/**
+ * `createTestApp` surface assumed by four-applications test blocks.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { channel } from "../elements/channel.ts";
+import { clock } from "../elements/clock.ts";
+import { gate } from "../elements/gate.ts";
+import { signal } from "../elements/signal.ts";
+import { vault, VaultBootError } from "../elements/vault.ts";
+import { oke } from "../kernel/app.ts";
+import { flow, resetFlowSeq } from "../kernel/flow.ts";
+import { on, resetBindings } from "../kernel/on.ts";
+import { every, http } from "../kernel/triggers.ts";
+import { createTestApp } from "./create-test-app.ts";
+
+describe("createTestApp — four-applications surface", () => {
+  test("auth.loginAs · api · signals.drain · clock.advance · cron.run · channels.sent · effects.of", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const member = gate.policy("member", ({ auth }) => !!auth.verified);
+    const orderPlaced = signal("order-placed", {
+      delivery: "once",
+      retries: 2,
+      deadLetter: true,
+    });
+    const mail = channel.email({ from: "test@oke.dev" });
+    const orderConfirmed = mail.template("order-confirmed", {
+      schema: z.object({
+        name: z.string(),
+        orderId: z.string(),
+        total: z.number(),
+      }),
+    });
+
+    on(
+      http.post("/orders").gate(member),
+      flow({
+        name: "orders.create",
+        unit: "orders",
+        in: z.object({ sku: z.string(), qty: z.number() }),
+        out: z.object({ id: z.string() }),
+        effects: { emits: ["order-placed"] },
+        do: async (input, fx) => {
+          const id = fx.id();
+          await fx.emit(orderPlaced, { orderId: id, ...input });
+          return { id };
+        },
+      }),
+    );
+
+    on(
+      orderPlaced,
+      flow({
+        name: "orders.onPlaced",
+        effects: { sends: ["order-confirmed"] },
+        do: async ({ orderId }, fx) => {
+          await fx.send(orderConfirmed, {
+            to: fx.auth.userId ?? "anon",
+            data: { name: "Ali", orderId, total: 10 },
+          });
+        },
+      }),
+    );
+
+    on(
+      every("1h"),
+      flow({
+        name: "orders.expire",
+        do: (_i, fx) => {
+          fx.log.info("expire");
+        },
+      }),
+    );
+
+    const app = oke({
+      name: "harness",
+      gates: [member],
+      signals: [orderPlaced],
+      clocks: [clock("expire-stale", { every: "1h" })],
+      channel: { templates: [orderConfirmed] },
+      env: "test",
+    });
+
+    const t = await createTestApp(app, {
+      gates: [member],
+      signals: [orderPlaced],
+      boot: {
+        clocks: [clock("expire-stale", { every: "1h" })],
+        channel: { templates: [orderConfirmed] },
+      },
+    });
+
+    const u = await t.auth.loginAs({ scopes: ["order:create"] });
+    expect(u.verified).toBe(true);
+
+    const { data, error } = await t.api.orders!.create!(
+      { sku: "COFFEE", qty: 2 },
+      { as: u },
+    );
+    expect(error).toBeNull();
+    expect(data).toMatchObject({ id: expect.any(String) });
+
+    await t.signals.drain();
+    const sent = t.channels.sent();
+    expect(sent.length).toBeGreaterThanOrEqual(1);
+    expect(
+      sent.some((s) => "template" in s && s.template === "order-confirmed"),
+    ).toBe(true);
+
+    await t.clock.advance("2m");
+    expect(await t.cron.run("expire-stale")).toBe(true);
+
+    const events = await t.runs();
+    expect(events.some((e) => e.flow === "orders.create")).toBe(true);
+    const createRun = events.find((e) => e.flow === "orders.create")!;
+    expect(t.effects.of(createRun.id).some((e) => e.kind === "emit")).toBe(
+      true,
+    );
+
+    await t.close();
+  });
+
+  test("ai.mock and ai.cost are assertable", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const app = oke({ name: "ai-harness", env: "test" });
+    const t = await createTestApp(app);
+    t.ai.mock("ticket-triage", { urgency: "high", team: "ops" });
+    expect(t.ai.cost()).toBeLessThan(0.02);
+    await t.close();
+  });
+});
+
+describe("createTestApp — vault gaps still fail boot", () => {
+  test("missing secrets listed together", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const app = oke({ name: "vault-fail", env: "prod" });
+
+    try {
+      await createTestApp(app, {
+        secrets: [
+          vault("A", { description: "alpha" }),
+          vault("B", { description: "beta" }),
+        ],
+        boot: {
+          env: "prod",
+          vault: { allowDevFallbacks: false, chain: [] },
+        },
+      });
+      expect.unreachable("should fail");
+    } catch (err) {
+      expect(err).toBeInstanceOf(VaultBootError);
+      const gaps = (err as VaultBootError).gaps.map((g) => g.name).sort();
+      expect(gaps).toEqual(["A", "B"]);
+    }
+  });
+});