okengine 0.15.2 → 0.17.0

package/src/kernel/live-http.ts

@@ -0,0 +1,114 @@
+/**
+ * Live HTTP helpers — path params, auto-match, exposure uniqueness, synthesis.
+ */
+
+import type { SignalDecl } from "../elements/signal/declare.ts";
+import type { SignalResourceRef } from "../manifest/types.ts";
+import type { Fx } from "./fx.ts";
+import { flow, type AnyFlowDef } from "./flow.ts";
+import type { GateRef, SignalSource } from "./triggers.ts";
+
+/** Default GET path for {@link http.live}. */
+export const LIVE_HTTP_PREFIX = "/_oke/live/";
+
+/**
+ * Default HTTP path for a live-signal firehose.
+ *
+ * @param signalName - Signal name
+ */
+export function liveHttpPath(signalName: string): string {
+  return `${LIVE_HTTP_PREFIX}${encodeURIComponent(signalName)}`;
+}
+
+/**
+ * `:param` names on an HTTP path template, first occurrence order.
+ *
+ * @param path - Route path
+ */
+export function httpPathParams(path: string): string[] {
+  const names: string[] = [];
+  const re = /:([A-Za-z_][\w]*)/g;
+  let match: RegExpExecArray | null = re.exec(path);
+  while (match) {
+    const name = match[1];
+    if (name !== undefined && !names.includes(name)) names.push(name);
+    match = re.exec(path);
+  }
+  return names;
+}
+
+/**
+ * Sorted auto-match field list joined for uniqueness (`""` = firehose).
+ *
+ * @param path - HTTP path template
+ */
+export function liveMatchKeyFromPath(path: string): string {
+  return httpPathParams(path).toSorted().join(",");
+}
+
+/**
+ * Sorted flattened gate names (`public` included).
+ *
+ * @param gates - Trigger gates
+ */
+export function liveGatesKey(gates: readonly GateRef[]): string {
+  return gates
+    .map((g) => (typeof g === "string" ? g : g.name))
+    .toSorted()
+    .join(",");
+}
+
+/**
+ * Boot uniqueness key: `(signalName, gatesKey, matchKey)`.
+ *
+ * @param signalName - Signal name
+ * @param gatesKey - {@link liveGatesKey}
+ * @param matchKey - {@link liveMatchKeyFromPath} or `custom:{flow}`
+ */
+export function liveExposureKey(signalName: string, gatesKey: string, matchKey: string): string {
+  return `${signalName}\0${gatesKey}\0${matchKey}`;
+}
+
+/**
+ * Auto-match: payload fields equal same-named input fields.
+ *
+ * @param payload - Signal payload
+ * @param input - HTTP input (path params)
+ * @param fields - Field names (path params)
+ */
+export function payloadAutoMatch(
+  payload: unknown,
+  input: unknown,
+  fields: readonly string[],
+): boolean {
+  if (fields.length === 0) return true;
+  if (payload === null || typeof payload !== "object") return true;
+  const row = payload as Record<string, unknown>;
+  const params =
+    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
+  for (const key of fields) {
+    if (!(key in row)) continue;
+    if (row[key] !== params[key]) return false;
+  }
+  return true;
+}
+
+/**
+ * Synthesize a stream Flow for `on(http.get(path).live(signal))`.
+ *
+ * @param signal - Live signal handle
+ * @param path - HTTP path (auto-match keys)
+ */
+export function synthesizeLiveFlow(signal: SignalSource, path: string): AnyFlowDef {
+  const fields = httpPathParams(path);
+  const name = signal.name;
+  const schema = "schema" in signal ? (signal as SignalDecl).schema : undefined;
+  return flow({
+    effects: { reads: [`signal:${name}` as SignalResourceRef] },
+    ...(schema !== undefined ? { out: schema } : {}),
+    do: (input, fx: Fx) =>
+      fx.live(signal, {
+        match: (payload) => payloadAutoMatch(payload, input, fields),
+      }),
+  });
+}

package/src/kernel/live-resume.test.ts

@@ -0,0 +1,125 @@
+/**
+ * HTTP Last-Event-ID resume and 410 LiveResumeGap before SSE.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { signal, resetSignals } from "../elements/signal/declare.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { stampFlowName } from "./stamp-http.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetSignals();
+});
+
+describe("live Last-Event-ID resume", () => {
+  afterEach(() => {
+    resetBindings();
+    resetFlowSeq();
+    resetSignals();
+  });
+
+  test("skips through Last-Event-ID and 410s a pruned cursor", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const feed = on(http.get("/feed").public().live(orderStatus));
+    stampFlowName(feed, "orders.feed");
+    on(
+      http.post("/emit").public(),
+      flow("orders.emit", {
+        do: async (_input, fx) => {
+          await fx.emit(orderStatus, { status: "placed" });
+          await fx.emit(orderStatus, { status: "shipped" });
+        },
+      }),
+    );
+
+    const app = oke({ name: "live-resume" });
+    const emitted = await app.fetch(new Request("http://localhost/emit", { method: "POST" }));
+    expect(emitted.status).toBe(204);
+
+    const firstCtrl = new AbortController();
+    const first = await app.fetch(
+      new Request("http://localhost/feed", { signal: firstCtrl.signal }),
+    );
+    expect(first.status).toBe(200);
+    expect(first.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const firstFrames = await readSseFrames(first, 2);
+    firstCtrl.abort();
+    expect(firstFrames.map((f) => f.data)).toEqual([{ status: "placed" }, { status: "shipped" }]);
+    const cursor = firstFrames[0]!.id;
+    expect(cursor).toBeTruthy();
+
+    const resumeCtrl = new AbortController();
+    const resume = await app.fetch(
+      new Request("http://localhost/feed", {
+        signal: resumeCtrl.signal,
+        headers: { "last-event-id": cursor! },
+      }),
+    );
+    expect(resume.status).toBe(200);
+    const rest = await readSseFrames(resume, 1);
+    resumeCtrl.abort();
+    expect(rest.map((f) => f.data)).toEqual([{ status: "shipped" }]);
+
+    const gap = await app.fetch(
+      new Request("http://localhost/feed", {
+        headers: { "last-event-id": "never-existed" },
+      }),
+    );
+    expect(gap.status).toBe(410);
+    expect(gap.headers.get("content-type")).toMatch(/application\/json/);
+    expect(await gap.json()).toMatchObject({
+      data: null,
+      error: {
+        code: "LiveResumeGap",
+        data: { signal: "order-status", afterId: "never-existed" },
+      },
+    });
+  });
+});
+
+async function readSseFrames(
+  res: Response,
+  n: number,
+): Promise<Array<{ id?: string; data: unknown }>> {
+  const reader = res.body?.getReader();
+  if (!reader) throw new Error("no body");
+  const dec = new TextDecoder();
+  let buf = "";
+  const out: Array<{ id?: string; data: unknown }> = [];
+  try {
+    while (out.length < n) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let sep = buf.indexOf("\n\n");
+      while (sep >= 0 && out.length < n) {
+        const raw = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        const frame = parseFrame(raw);
+        if (frame) out.push(frame);
+        sep = buf.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return out;
+}
+
+function parseFrame(raw: string): { id?: string; data: unknown } | undefined {
+  const dataLines: string[] = [];
+  let id: string | undefined;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0) return undefined;
+  const data = dataLines.join("\n");
+  if (data === "[DONE]") return undefined;
+  return { ...(id !== undefined ? { id } : {}), data: JSON.parse(data) as unknown };
+}

package/src/kernel/on.ts

@@ -7,16 +7,28 @@
  */
 
 import { isFlow, type AnyFlowDef, type FlowDef, type FlowErrorMap } from "./flow.ts";
+import { lazyRequire } from "./lazy-require.ts";
 import {
   isResourceMount,
   normalizeTrigger,
   type BoundTriggerOf,
+  type HttpMethod,
+  type HttpTrigger,
+  type LiveHttpTrigger,
   type ResourceFlowBag,
   type ResourceMount,
   type SignalSource,
   type Trigger,
 } from "./triggers.ts";
 
+/**
+ * Sync-load live HTTP synthesis only when `on(http.*.live(signal))` runs.
+ * A static import would pin that graph on every `on` / edge ping bundle.
+ */
+function loadLiveHttp(): typeof import("./live-http.ts") {
+  return lazyRequire(import.meta.dir, ["live", "http"].join("-"));
+}
+
 /** One registered `on(trigger, flow)` binding. */
 export interface Binding {
   readonly trigger: Trigger;
@@ -43,6 +55,15 @@ export function on<
   trigger: T,
   flowDef: FlowDef<I, O, E, D, Trigger | undefined>,
 ): FlowDef<I, O, E, D, BoundTriggerOf<T>>;
+/**
+ * Expose a live signal: `on(http.get(path).gate(g).live(signal))`.
+ * Synthesizes the stream Flow (name stamped by `.adopt`).
+ *
+ * @param trigger - HTTP GET with `.live(signal)`
+ */
+export function on<T extends LiveHttpTrigger<HttpMethod, string>>(
+  trigger: T,
+): FlowDef<unknown, unknown, FlowErrorMap, {}, T>;
 /**
  * Mount a CRUD resource (`http.resource(path, ops)`): registers the five
  * verb bindings and returns the ops bag (unit keys `list` · `create` ·
@@ -81,10 +102,40 @@ export function on(
     }
     return ops as unknown as ResourceFlowBag;
   }
+  const asHttp =
+    typeof triggerOrMount === "object" &&
+    triggerOrMount !== null &&
+    "kind" in triggerOrMount &&
+    (triggerOrMount as HttpTrigger).kind === "http"
+      ? (triggerOrMount as HttpTrigger)
+      : undefined;
+  const liveSignal = asHttp?.liveSignal;
+  const synthesized = liveSignal !== undefined && flowDef === undefined;
+  if (synthesized && asHttp && liveSignal !== undefined) {
+    if (asHttp.method !== "GET") {
+      throw new TypeError("on(http.*.live(signal)): live exposure must be GET");
+    }
+    flowDef = loadLiveHttp().synthesizeLiveFlow(liveSignal, asHttp.path) as FlowDef<
+      any,
+      any,
+      any,
+      any,
+      Trigger | undefined
+    >;
+  }
   if (!isFlow(flowDef)) {
     throw new TypeError("on() expected a flow() definition as the second argument");
   }
   const normalized = normalizeTrigger(triggerOrMount as Trigger | SignalSource);
+  if (normalized.kind === "http" && normalized.liveSignal !== undefined) {
+    if (normalized.method !== "GET") {
+      throw new TypeError("on(http.*.live(signal)): live exposure must be GET");
+    }
+    (flowDef as { live: string | undefined }).live = normalized.liveSignal.name;
+    if (!synthesized) {
+      (flowDef as { liveCustomMatch: boolean }).liveCustomMatch = true;
+    }
+  }
   const list = flowDef.triggers as Trigger[];
   list.push(normalized);
   // Stamp runtime carrier for the first bound trigger (type follows BoundTriggerOf).

package/src/kernel/pipeline-api-key.test.ts

@@ -1,5 +1,6 @@
 /**
- * Boot-level: API-key Bearer stamps WideEvent.principal with the key id.
+ * Boot-level: API-key Bearer stamps WideEvent.principal with the issuer
+ * (`creatorId`) and `dimensions.api_key` with the key id.
  * Session JWT stamps the session subject — never a key id.
  */
 
@@ -22,7 +23,7 @@ async function lastEvent(runs: ReturnType<typeof createRunsRuntime>) {
 }
 
 describe("pipeline — API key Bearer identity", () => {
-  test("API key Bearer stamps WideEvent.principal with the key id", async () => {
+  test("API key Bearer stamps WideEvent.principal with the issuer", async () => {
     resetBindings();
     resetFlowSeq();
 
@@ -70,9 +71,193 @@ describe("pipeline — API key Bearer identity", () => {
     expect(res.status).toBe(200);
 
     const event = await lastEvent(runs);
-    expect(event?.principal).toBe("key_demo");
+    expect(event?.principal).toBe("u1");
     expect(event?.dimensions.api_key).toBe("key_demo");
-    expect(event?.dimensions.principal).toBe("key_demo");
+    expect(event?.dimensions.principal).toBe("u1");
+
+    await app.stop();
+  });
+
+  test("key-authenticated request stamps fx.auth.userId as issuer and apiKeyId as the key", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    on(
+      http.get("/who").gate(member),
+      flow("secure.who", {
+        do: (_input, fx) => ({
+          userId: fx.auth.userId,
+          apiKeyId: fx.auth.apiKeyId ?? null,
+        }),
+      }),
+    );
+
+    const apiKeys = createApiKeyStore();
+    const created = await createApiKey(apiKeys, {
+      plane: "user",
+      name: "who",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_who",
+    });
+    const app = oke({
+      name: "api-key-who",
+      gate: {
+        auth: {
+          secret: "hmac-secret-for-tests",
+          sessions: createSessionStore(),
+          apiKeyStore: apiKeys,
+          http: false,
+        },
+        policies: [member],
+      },
+      env: "test",
+      startScheduler: false,
+    });
+    await app.boot({ env: "test", gates: [member], startScheduler: false });
+
+    const res = await app.fetch(
+      new Request("http://localhost/who", {
+        method: "GET",
+        headers: { authorization: `Bearer ${created.secret}` },
+      }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string; apiKeyId: string } };
+    expect(body.data.userId).toBe("u1");
+    expect(body.data.apiKeyId).toBe("key_who");
+
+    await app.stop();
+  });
+
+  test("scope A is Forbidden on gate.scope(B) and 200 on gate.scope(A)", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const scopeA = gate.scope("scope:a");
+    const scopeB = gate.scope("scope:b");
+    on(http.get("/a").gate(scopeA), flow("secure.a", { do: () => ({ ok: true }) }));
+    on(http.get("/b").gate(scopeB), flow("secure.b", { do: () => ({ ok: true }) }));
+
+    const apiKeys = createApiKeyStore();
+    const created = await createApiKey(apiKeys, {
+      plane: "user",
+      name: "scoped",
+      scopes: ["scope:a"],
+      creatorId: "u1",
+      creatorScopes: ["scope:a", "scope:b"],
+    });
+    const app = oke({
+      name: "api-key-scopes",
+      gate: {
+        auth: {
+          secret: "hmac-secret-for-tests",
+          sessions: createSessionStore(),
+          apiKeyStore: apiKeys,
+          http: false,
+        },
+        policies: [scopeA, scopeB],
+      },
+      env: "test",
+      startScheduler: false,
+    });
+    await app.boot({ env: "test", gates: [scopeA, scopeB], startScheduler: false });
+
+    const a = await app.fetch(
+      new Request("http://localhost/a", {
+        method: "GET",
+        headers: { authorization: `Bearer ${created.secret}` },
+      }),
+    );
+    const b = await app.fetch(
+      new Request("http://localhost/b", {
+        method: "GET",
+        headers: { authorization: `Bearer ${created.secret}` },
+      }),
+    );
+    expect(a.status).toBe(200);
+    expect(b.status).toBe(403);
+
+    await app.stop();
+  });
+
+  test("allowlist miss and over-rate → 401, no api_key dimension", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    on(http.get("/secure").gate(member), flow("secure.limit", { do: () => ({ ok: true }) }));
+
+    const apiKeys = createApiKeyStore();
+    const allowlisted = await createApiKey(apiKeys, {
+      plane: "user",
+      name: "allow",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_allow",
+      ipAllowlist: ["203.0.113.10"],
+    });
+    const rated = await createApiKey(apiKeys, {
+      plane: "user",
+      name: "rated",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_rate",
+      rateLimit: { max: 1, per: "1m" },
+    });
+    const runs = createRunsRuntime({ driver: memoryRunsDriver });
+    await runs.open();
+    const app = oke({
+      name: "api-key-limits",
+      gate: {
+        auth: {
+          secret: "hmac-secret-for-tests",
+          sessions: createSessionStore(),
+          apiKeyStore: apiKeys,
+          http: false,
+        },
+        policies: [member],
+      },
+      runs,
+      env: "test",
+      startScheduler: false,
+    });
+    await app.boot({ env: "test", gates: [member], runs, startScheduler: false });
+
+    const miss = await app.fetch(
+      new Request("http://localhost/secure", {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${allowlisted.secret}`,
+          "x-forwarded-for": "198.51.100.7",
+        },
+      }),
+    );
+    expect(miss.status).toBe(401);
+
+    const first = await app.fetch(
+      new Request("http://localhost/secure", {
+        method: "GET",
+        headers: { authorization: `Bearer ${rated.secret}` },
+      }),
+    );
+    const second = await app.fetch(
+      new Request("http://localhost/secure", {
+        method: "GET",
+        headers: { authorization: `Bearer ${rated.secret}` },
+      }),
+    );
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(401);
+
+    const events = await runs.all();
+    for (const event of events) {
+      if (event.dimensions.error_code) {
+        expect(event.dimensions.api_key).toBeUndefined();
+      }
+    }
 
     await app.stop();
   });
@@ -206,7 +391,7 @@ describe("pipeline — API key Bearer identity", () => {
     await app.stop();
   });
 
-  test("operator-plane key stamps fx.operator.id as the key id", async () => {
+  test("operator-plane key stamps fx.operator.id as the issuer", async () => {
     resetBindings();
     resetFlowSeq();
 
@@ -254,10 +439,10 @@ describe("pipeline — API key Bearer identity", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as { data: { operatorId: string } };
-    expect(body.data.operatorId).toBe("key_ops");
+    expect(body.data.operatorId).toBe("op1");
 
     const event = await lastEvent(runs);
-    expect(event?.principal).toBe("key_ops");
+    expect(event?.principal).toBe("op1");
     expect(event?.plane).toBe("operator");
     expect(event?.dimensions.api_key).toBe("key_ops");
 

package/src/kernel/pipeline-tenant.ts

@@ -0,0 +1,49 @@
+/**
+ * Tenant identity + role-scope union — lazy chunk.
+ *
+ * A static import from {@link ./pipeline.ts} would pin tenant-resolve and
+ * the tenant store (and `isApplicationScope`) on every `oke()` graph,
+ * including Store-only apps that never enable `gate.auth.tenant`.
+ */
+
+import { tenantScopesForMember } from "../auth/tenants.ts";
+import type { FlowFailure } from "./errors.ts";
+import type { PipelineDeps } from "./pipeline.ts";
+import type { InvocationContext } from "./hooks.ts";
+import { resolveRequestTenant } from "./tenant-resolve.ts";
+
+/**
+ * Resolve tenant id and conditionally union tenant-role scopes.
+ *
+ * @param deps - Pipeline deps (`tenant` must be set)
+ * @param ctx - Invocation
+ */
+export function applyPipelineTenant(
+  deps: PipelineDeps,
+  ctx: InvocationContext,
+): FlowFailure | undefined {
+  const tenant = deps.tenant;
+  if (!tenant) return undefined;
+  const auth = deps.principals.auth;
+  auth.sessionScopes ??= new Set(auth.scopes);
+  const claimTenantId = deps.principals.tenant.id;
+  const result = resolveRequestTenant({
+    config: tenant.config,
+    auth: deps.principals.auth,
+    claimTenantId,
+    request: ctx.request,
+    store: tenant.store,
+  });
+  if (result.failure) return result.failure;
+  deps.principals.tenant.id = result.id;
+  const userId = deps.principals.auth.userId;
+  if (result.id && userId && tenant.flowTenantScoped && tenant.flowPlane !== "operator") {
+    for (const scope of tenantScopesForMember(tenant.store, result.id, userId)) {
+      deps.principals.auth.scopes.add(scope);
+    }
+  }
+  return undefined;
+}
+
+/** Short name so the Store-only `oke()` graph does not spell {@link applyPipelineTenant}. */
+export { applyPipelineTenant as run };

package/src/kernel/pipeline.test.ts

@@ -69,7 +69,7 @@ describe("http trigger — .public()", () => {
   test("attaches the public sentinel without calling gate()", () => {
     const trigger = http.get("/health").public();
     expect(trigger.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["public"]);
-    expect(trigger.live().isLive).toBe(true);
+    expect(trigger.liveSignal).toBeUndefined();
   });
 });