okengine 0.14.1 → 0.16.0

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.test.ts

@@ -65,9 +65,9 @@ describe("gateDenialFailure", () => {
   });
 });
 
-describe("http trigger — .gate.public", () => {
+describe("http trigger — .public()", () => {
   test("attaches the public sentinel without calling gate()", () => {
-    const trigger = http.get("/health").gate.public;
+    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);
   });

package/src/kernel/pipeline.ts

@@ -24,6 +24,7 @@ export interface PrincipalBag {
     userId: string | null;
     scopes: Set<string>;
     verified?: boolean;
+    apiKeyId?: string | null;
   };
   readonly operator: {
     id: string | null;
@@ -53,7 +54,7 @@ export interface PipelineDeps {
    * @returns Principal on success
    * @throws On forge / expiry / revoke — pipeline maps to `Unauthorized`
    */
-  readonly verifyBearer?: (token: string) => Promise<ResolvedPrincipal>;
+  readonly verifyBearer?: (token: string, request?: Request) => Promise<ResolvedPrincipal>;
   /**
    * Optional token extraction (e.g. cookie → Bearer when cookies enabled).
    * When omitted, only `Authorization: Bearer` is read.
@@ -155,6 +156,7 @@ export function applyPrincipal(bag: PrincipalBag, resolved: ResolvedPrincipal |
       for (const s of resolved.scopes) bag.auth.scopes.add(s);
     }
     if (resolved.verified !== undefined) bag.auth.verified = resolved.verified;
+    bag.auth.apiKeyId = resolved.apiKeyId ?? null;
   }
 }
 
@@ -192,7 +194,7 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
         return fail("Unauthorized", {});
       }
       try {
-        const principal = await deps.verifyBearer(token);
+        const principal = await deps.verifyBearer(token, ctx.request);
         applyPrincipal(deps.principals, principal);
         if (principal.apiKeyId) {
           deps.telemetry.dimensions.api_key = principal.apiKeyId;

package/src/kernel/plugin-elements.test.ts

@@ -32,7 +32,7 @@ describe("plugin element contributions", () => {
       .table("otp_codes")
       .needs("store.sql");
 
-    on(http.get("/ok").gate.public, flow("ok", { do: () => ({ ok: true }) }));
+    on(http.get("/ok").public(), flow("ok", { do: () => ({ ok: true }) }));
 
     const app = oke({
       name: "plugin-elements",

package/src/kernel/plugin-needs.test.ts

@@ -75,7 +75,7 @@ describe("plugin .needs() resolution", () => {
   test("boot fails when plugin needs missing peer plugin", async () => {
     resetBindings();
     resetFlowSeq();
-    on(http.get("/x").gate.public, flow("x", { do: () => ({ ok: true }) }));
+    on(http.get("/x").public(), flow("x", { do: () => ({ ok: true }) }));
     const dependent = plugin("needs-auth", { version: "0.0.1" }).needs("auth");
     const app = oke({ name: "needs-boot", gate: { policies: [gate.public] } }).plug(dependent);
     await expect(app.boot({ env: "test" })).rejects.toThrow(PluginNeedsError);

package/src/kernel/ready.test.ts

@@ -38,7 +38,7 @@ describe("GET /_/ready", () => {
     });
     const bindings: Binding[] = [
       {
-        trigger: http.post("/charge").gate.public,
+        trigger: http.post("/charge").public(),
         flow: charge as AnyFlowDef,
       },
     ];
@@ -82,7 +82,7 @@ describe("GET /_oke/client.json", () => {
       startScheduler: false,
       env: "test",
       gate: { unguardedHttp: "allow" },
-      bindings: [{ trigger: http.get("/ping").gate.public, flow: ping as AnyFlowDef }],
+      bindings: [{ trigger: http.get("/ping").public(), flow: ping as AnyFlowDef }],
     });
     await app.boot();
     const res = await app.fetch(new Request("http://127.0.0.1/_oke/client.json"));

package/src/kernel/resource-mount.test.ts

@@ -63,6 +63,20 @@ describe("http.resource — gate / live", () => {
     expect(remove?.isLive).toBe(false);
   });
 
+  test(".public().live() stamps the sentinel on every verb", () => {
+    resetBindings();
+    resetFlowSeq();
+    on(http.resource("/notes", bag()).public().live());
+    expect(httpOf("/notes", "GET")?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(
+      ["public"],
+    );
+    expect(
+      httpOf("/notes", "POST")?.gates.map((g) => (typeof g === "string" ? g : g.name)),
+    ).toEqual(["public"]);
+    expect(httpOf("/notes", "GET")?.isLive).toBe(true);
+    expect(httpOf("/notes", "POST")?.isLive).toBe(false);
+  });
+
   test(".live().gate(member) order does not matter", () => {
     resetBindings();
     resetFlowSeq();

package/src/kernel/run-duration.test.ts

@@ -23,7 +23,7 @@ describe("execute run duration", () => {
     await runs.open();
 
     on(
-      http.get("/ping").gate.public,
+      http.get("/ping").public(),
       flow("demo.ping", {
         do: () => ({ ok: true }),
       }),
@@ -68,7 +68,7 @@ describe("execute run duration", () => {
     await runs.open();
     try {
       on(
-        http.get("/ping").gate.public,
+        http.get("/ping").public(),
         flow("demo.ping", {
           do: () => ({ ok: true }),
         }),

package/src/kernel/stamp-http.test.ts

@@ -0,0 +1,79 @@
+/**
+ * In-place path / name stamps and fail-loud HTTP boot.
+ */
+
+import { describe, expect, test, beforeEach } from "bun:test";
+import type { RuntimeRouteMap } from "./adopt-routes.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { resetRegisteredFlowUnits, registerFlowUnits } from "./flow-units.ts";
+import { listBindings, on, resetBindings } from "./on.ts";
+import { stampFlowName, stampHttpPath } from "./stamp-http.ts";
+import { HTTP_PATH_PENDING } from "./http-path-pending.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetRegisteredFlowUnits();
+});
+
+describe("stampHttpPath", () => {
+  test("mutates the on() binding in place — listBindings sees the stamped path", () => {
+    const f = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe(HTTP_PATH_PENDING);
+    stampHttpPath(f, "/notes/:id");
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe("/notes/:id");
+    const bound = listBindings()[0];
+    expect(bound?.trigger.kind === "http" && bound.trigger.path).toBe("/notes/:id");
+  });
+
+  test("explicit http.get('/x') wins — stamp does not overwrite", () => {
+    const f = on(http.get("/me/tasks").public(), flow("notes.get", { do: () => 1 }));
+    stampHttpPath(f, "/notes/:id");
+    expect(f.$trigger && f.$trigger.kind === "http" && f.$trigger.path).toBe("/me/tasks");
+  });
+});
+
+describe("stampFlowName", () => {
+  test("fills a nameless flow as unit.export", () => {
+    const f = flow({ do: () => 1 });
+    expect(f.name).toBe("");
+    stampFlowName(f, "notes.get");
+    expect(f.name).toBe("notes.get");
+    expect(f.unit).toBe("notes");
+  });
+
+  test("explicit flow('notes.get') wins", () => {
+    const f = flow("notes.get", { do: () => 1 });
+    stampFlowName(f, "notes.list");
+    expect(f.name).toBe("notes.get");
+  });
+});
+
+describe("oke — unresolved sentinel and duplicate routes", () => {
+  test("unresolved http.get() fails construction", () => {
+    on(http.get().public(), flow("notes.get", { do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1010/);
+  });
+
+  test("duplicate GET /notes fails construction", () => {
+    on(http.get("/notes").public(), flow("notes.list", { do: () => 1 }));
+    on(http.get("/notes").public(), flow("notes.also", { do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1011/);
+  });
+
+  test("nameless HTTP flow fails construction", () => {
+    on(http.get("/notes").public(), flow({ do: () => 1 }));
+    expect(() => oke({ name: "t", autoBoot: false })).toThrow(/OKE1012/);
+  });
+
+  test("registerFlowUnits drains into $routes; registry ignore does not", () => {
+    const get = on(http.get("/notes/:id").public(), flow("notes.get", { do: () => 1 }));
+    registerFlowUnits({ notes: { get } });
+    const ignored = oke({ name: "t", autoBoot: false, registry: "ignore" });
+    expect(ignored.$routes).toEqual({});
+    const app = oke({ name: "t", autoBoot: false });
+    expect((app.$routes as RuntimeRouteMap).notes?.get?.path).toBe("/notes/:id");
+  });
+});

package/src/kernel/stamp-http.ts

@@ -0,0 +1,75 @@
+/**
+ * In-place HTTP path + Flow name stamps.
+ *
+ * `on()` already registered the trigger (possibly still on the pending-path
+ * sentinel). A wrapper that returned a new trigger would leave `listBindings()`
+ * on the sentinel — mutate the existing object.
+ */
+
+import { isFlow, type AnyFlowDef, type FlowDef } from "./flow.ts";
+import { isPendingHttpPath, type HttpPathPending } from "./http-path-pending.ts";
+import type { HttpTrigger, Trigger } from "./triggers.ts";
+
+/**
+ * Replace a pending HTTP path on {@link FlowDef} with the file-tree stamp.
+ *
+ * Explicit `http.get("/x")` wins — the pending sentinel is the only path
+ * this function overwrites. Returns the same object with a tighter trigger
+ * type when the original path was pending.
+ *
+ * @param flow - Bound flow (already passed through `on()`)
+ * @param path - Inferred URL (`/notes/:id`)
+ */
+export function stampHttpPath<F extends AnyFlowDef, P extends string>(
+  flow: F,
+  path: P,
+): StampHttpPath<F, P> {
+  if (!isFlow(flow)) return flow as StampHttpPath<F, P>;
+  const apply = (trigger: Trigger): void => {
+    if (trigger.kind !== "http") return;
+    if (!isPendingHttpPath(trigger.path)) return;
+    (trigger as { path: string }).path = path;
+  };
+  if (flow.$trigger) apply(flow.$trigger);
+  for (const trigger of flow.triggers) apply(trigger);
+  return flow as StampHttpPath<F, P>;
+}
+
+/**
+ * Stamp `unit.export` onto a nameless (or `flow_*`) Flow.
+ *
+ * Explicit `flow("notes.get")` wins. Fills `unit` when missing.
+ *
+ * @param flow - Flow definition
+ * @param name - `notes.get`
+ */
+export function stampFlowName<F extends AnyFlowDef>(flow: F, name: string): F {
+  if (!isFlow(flow)) return flow;
+  const f = flow as { name: string; unit: string | undefined };
+  if (!f.name || f.name.startsWith("flow_")) {
+    f.name = name;
+  }
+  if (!f.unit) {
+    const resolved = f.name || name;
+    const dot = resolved.indexOf(".");
+    f.unit = dot > 0 ? resolved.slice(0, dot) : resolved;
+  }
+  return flow;
+}
+
+/**
+ * Type-level path replacement — only when the bound trigger is still pending.
+ *
+ * @typeParam F - Flow definition
+ * @typeParam P - Stamped path
+ */
+export type StampHttpPath<F, P extends string> =
+  F extends FlowDef<infer I, infer O, infer E, infer D, infer T>
+    ? T extends HttpTrigger<infer M, infer Cur>
+      ? [Cur] extends [HttpPathPending]
+        ? FlowDef<I, O, E, D, HttpTrigger<M, P>>
+        : F
+      : F
+    : F;
+
+export { HTTP_PATH_PENDING, isPendingHttpPath } from "./http-path-pending.ts";