okengine 0.4.3 → 0.5.0

package/src/kernel/fx.ts

@@ -75,6 +75,33 @@ export interface FxOperator {
   readonly id: string | null;
 }
 
+/**
+ * Read-only originating identity for audit / attribution.
+ * Never consulted by gate evaluation — authorization stays on {@link Fx.auth}.
+ */
+export interface FxPrincipal {
+  readonly userId: string | null;
+  readonly operatorId: string | null;
+  readonly scopes: ReadonlySet<string>;
+  readonly verified?: boolean;
+  readonly plane?: "user" | "operator";
+}
+
+/**
+ * Freeze a principal snapshot for propagation across {@link Fx.call}.
+ *
+ * @param p - Live or frozen principal
+ */
+export function freezePrincipal(p: FxPrincipal): FxPrincipal {
+  return {
+    userId: p.userId,
+    operatorId: p.operatorId,
+    scopes: new Set(p.scopes),
+    ...(p.verified !== undefined ? { verified: p.verified } : {}),
+    ...(p.plane !== undefined ? { plane: p.plane } : {}),
+  };
+}
+
 /** Active tenant (multi-tenancy as a dimension of `fx`). */
 export interface FxTenant {
   readonly id: string | null;
@@ -334,6 +361,12 @@ export interface Fx {
   readonly auth: FxAuth;
   /** Operator-plane principal. */
   readonly operator: FxOperator;
+  /**
+   * Read-only originating identity (audit / attribution).
+   * On HTTP entry, tracks the resolved principal; across {@link Fx.call},
+   * propagates explicitly — never copied into {@link Fx.auth}.
+   */
+  readonly principal: FxPrincipal;
   /** Active tenant. */
   readonly tenant: FxTenant;
   /**
@@ -419,6 +452,11 @@ export interface CreateFxOptions {
   readonly auth?: FxAuth;
   /** Operator principal. */
   readonly operator?: FxOperator;
+  /**
+   * Frozen originating principal (e.g. propagated across {@link Fx.call}).
+   * When omitted, {@link Fx.principal} tracks live {@link Fx.auth} / {@link Fx.operator}.
+   */
+  readonly principal?: FxPrincipal;
   /** Tenant. */
   readonly tenant?: FxTenant;
   /** Secret name → value map for `fx.vault`. */
@@ -522,6 +560,27 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   };
   const operator: FxOperator = options.operator ?? { id: null };
   const tenant: FxTenant = options.tenant ?? { id: null };
+  const principal: FxPrincipal =
+    options.principal ??
+    ({
+      get userId() {
+        return auth.userId;
+      },
+      get operatorId() {
+        return operator.id;
+      },
+      get scopes() {
+        return auth.scopes;
+      },
+      get verified() {
+        return auth.verified;
+      },
+      get plane() {
+        if (operator.id) return "operator" as const;
+        if (auth.userId) return "user" as const;
+        return undefined;
+      },
+    } satisfies FxPrincipal);
   const journal = options.journal;
 
   async function gated<T>(
@@ -1069,6 +1128,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
     auth,
     operator,
+    principal,
     tenant,
     fail,
     json: {

package/src/kernel/hooks.test.ts

@@ -74,7 +74,7 @@ describe("hooks — order and composition", () => {
 
     on(http.get("/ordered"), f);
 
-    const app = oke({ name: "hooks-order" })
+    const app = oke({ autoBoot: false, name: "hooks-order" })
       .hook("onRequest", () => {
         order.push("app:onRequest");
       })
@@ -128,7 +128,7 @@ describe("hooks — order and composition", () => {
       }),
     );
 
-    const app = oke({ name: "sc-res" })
+    const app = oke({ autoBoot: false, name: "sc-res" })
       .hook("onAuth", () => {
         order.push("onAuth");
         return new Response("denied", { status: 401 });
@@ -157,7 +157,7 @@ describe("hooks — order and composition", () => {
       }),
     );
 
-    const app = oke({ name: "data-res" }).hook("onResponse", (ctx) => {
+    const app = oke({ autoBoot: false, name: "data-res" }).hook("onResponse", (ctx) => {
       seenAtHook = ctx.response;
       if (!ctx.response) return;
       const headers = new Headers(ctx.response.headers);
@@ -192,7 +192,7 @@ describe("hooks — order and composition", () => {
       }),
     );
 
-    const app = oke({ name: "sc-err" })
+    const app = oke({ autoBoot: false, name: "sc-err" })
       .hook("beforeHandle", () => {
         order.push("beforeHandle");
         return fail("Nope", {});

package/src/kernel/index.ts

@@ -103,6 +103,7 @@ export {
 export {
   createFx,
   createFxContext,
+  freezePrincipal,
   isJsonResult,
   jsonResultBrand,
   resolveName,
@@ -118,6 +119,7 @@ export {
   type FxJson,
   type FxLog,
   type FxOperator,
+  type FxPrincipal,
   type FxRetryOptions,
   type FxSearchOptions,
   type FxSendOptions,
@@ -244,6 +246,16 @@ export {
   type PluginScope,
 } from "./registry.ts";
 
+export {
+  assertPluginNeeds,
+  buildAvailableNeedTokens,
+  collectUnmetPluginNeeds,
+  PluginNeedsError,
+  ELEMENT_NEED_TOKENS,
+  type PluginNeedGap,
+  type PluginNeedsContext,
+} from "./plugin-needs.ts";
+
 export {
   createRouter,
   isUnsupportedByRegExp,

package/src/kernel/pipeline.test.ts

@@ -79,7 +79,7 @@ describe("pipeline — Unauthorized for anonymous", () => {
     const runs = createRunsRuntime({ driver: memoryRunsDriver });
     const app = oke({
       name: "gates-pipeline",
-      gates: [member],
+      gate: { policies: [member] },
       runs,
       env: "test",
     });
@@ -116,7 +116,7 @@ describe("pipeline — Unauthorized for anonymous", () => {
 
     const app = oke({
       name: "gates-forbid",
-      gates: [member, canOrder],
+      gate: { policies: [member, canOrder] },
       env: "test",
     });
     await app.boot({ env: "test", gates: [member, canOrder] });
@@ -157,7 +157,7 @@ describe("pipeline — evaluated gates on the run", () => {
     await runs.open();
     const app = oke({
       name: "gates-eval",
-      gates: [member, canOrder],
+      gate: { policies: [member, canOrder] },
       runs,
       env: "test",
     });
@@ -208,9 +208,11 @@ describe("pipeline — Bearer cryptographic verification", () => {
     const sessions = createSessionStore();
     const app = oke({
       name: "auth-forge",
-      gates: [member],
+      gate: {
+        auth: { secret: "hmac-secret-for-tests", sessions, http: false },
+        policies: [member],
+      },
       env: "local",
-      auth: { secret: "hmac-secret-for-tests", sessions },
       startScheduler: false,
     });
     await app.boot({ env: "local", gates: [member], startScheduler: false });
@@ -262,9 +264,11 @@ describe("pipeline — Bearer cryptographic verification", () => {
     });
     const app = oke({
       name: "auth-expired",
-      gates: [member],
+      gate: {
+        auth: { secret, sessions, now: () => nowMs, http: false },
+        policies: [member],
+      },
       env: "local",
-      auth: { secret, sessions, now: () => nowMs },
       elements: { clock: clockRt },
       startScheduler: false,
     });
@@ -314,7 +318,7 @@ describe("pipeline — Bearer cryptographic verification", () => {
 
     const app = oke({
       name: "no-inject",
-      gates: [member],
+      gate: { policies: [member] },
       env: "local",
       startScheduler: false,
     });

package/src/kernel/pipeline.ts

@@ -52,6 +52,13 @@ export interface PipelineDeps {
    * @throws On forge / expiry / revoke — pipeline maps to `Unauthorized`
    */
   readonly verifyBearer?: (token: string) => Promise<ResolvedPrincipal>;
+  /**
+   * Optional token extraction (e.g. cookie → Bearer when cookies enabled).
+   * When omitted, only `Authorization: Bearer` is read.
+   *
+   * @param request - Incoming HTTP request
+   */
+  readonly resolveToken?: (request: Request) => string | undefined;
   /**
    * When true, `ctx.state.principal` / execute `extras.principal` injection
    * is honoured (test harness only). Must be false for production HTTP.
@@ -158,14 +165,22 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
       delete ctx.state.principal;
     }
 
-    const header = ctx.request?.headers.get("authorization");
-    if (header?.startsWith("Bearer ")) {
-      const token = header.slice("Bearer ".length).trim();
+    let token: string | undefined;
+    if (deps.resolveToken && ctx.request) {
+      token = deps.resolveToken(ctx.request);
+    } else {
+      const header = ctx.request?.headers.get("authorization");
+      if (header?.startsWith("Bearer ")) {
+        token = header.slice("Bearer ".length).trim() || undefined;
+      }
+    }
+
+    if (token !== undefined) {
       if (!token) {
         return fail("Unauthorized", {});
       }
       if (!deps.verifyBearer) {
-        // Bearer present but no auth binding — refuse rather than trust.
+        // Token present but no auth binding — refuse rather than trust.
         return fail("Unauthorized", {});
       }
       try {
@@ -187,6 +202,10 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
 
   const beforeHandle: HookFn = async (ctx, fxOrErr) => {
     const names = gateNamesOf(ctx.trigger);
+    // Empty chain: boot audit should have rejected this when unguardedHttp is
+    // "deny". If we still reach here without a gate runtime, skip only for the
+    // explicit `autoBoot: false` escape hatch. Public sentinel is a normal
+    // named gate in `names`.
     if (names.length === 0 || !deps.gates) return;
 
     const policyCtx = policyContextOf(fxOrErr as Fx, ctx);

package/src/kernel/plugin/decorate.test.ts

@@ -37,7 +37,7 @@ describe("plugin decorate — types and runtime", () => {
       }),
     );
 
-    const app = oke({ name: "decorate" }).plug(audit);
+    const app = oke({ autoBoot: false, name: "decorate" }).plug(audit);
     await app.fetch(new Request("http://localhost/x"));
 
     expect(seen).toEqual({ enabled: true, retain: "2y" });
@@ -51,7 +51,7 @@ describe("plugin decorate — types and runtime", () => {
       currency: "SAR" as const,
     });
 
-    const app = oke({ name: "types" }).plug(withAudit).plug(withBilling);
+    const app = oke({ autoBoot: false, name: "types" }).plug(withAudit).plug(withBilling);
 
     type AppDeco = typeof app extends OkeApp<infer D> ? D : never;
     type HasBoth = ExpectExtends<
@@ -94,7 +94,7 @@ describe("plugin decorate — types and runtime", () => {
       }),
     );
 
-    const app = oke({ name: "deco-scope" });
+    const app = oke({ autoBoot: false, name: "deco-scope" });
     app.unit("orders").plug(plugin("flag", { version: "1.0.0" }).decorate("flag", "orders-only"));
 
     await app.fetch(new Request("http://localhost/orders"));

package/src/kernel/plugin/scoping.test.ts

@@ -48,7 +48,7 @@ describe("plugin scoping — attachment point is the scope", () => {
       fired.push("rate-limit");
     });
 
-    const app = oke({ name: "scoping" });
+    const app = oke({ autoBoot: false, name: "scoping" });
     app.unit("orders").plug(rateLimit);
 
     await app.fetch(new Request("http://localhost/orders"));
@@ -87,7 +87,7 @@ describe("plugin scoping — attachment point is the scope", () => {
       fired.push("audit");
     });
 
-    const app = oke({ name: "app-scope" }).plug(audit);
+    const app = oke({ autoBoot: false, name: "app-scope" }).plug(audit);
 
     await app.fetch(new Request("http://localhost/a"));
     await app.fetch(new Request("http://localhost/b"));
@@ -121,7 +121,7 @@ describe("plugin scoping — attachment point is the scope", () => {
     on(http.get("/marked"), marked);
     on(http.get("/plain"), plain);
 
-    const app = oke({ name: "flow-scope" });
+    const app = oke({ autoBoot: false, name: "flow-scope" });
 
     await app.fetch(new Request("http://localhost/marked"));
     await app.fetch(new Request("http://localhost/plain"));

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

@@ -0,0 +1,51 @@
+import { describe, expect, test, beforeEach } from "bun:test";
+import { clock } from "../elements/clock.ts";
+import { gate } from "../elements/gate.ts";
+import { signal } from "../elements/signal.ts";
+import { vault } from "../elements/vault.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { plugin } from "./plugin.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("plugin element contributions", () => {
+  test("vault / clock / signal / gate merge into boot options", async () => {
+    const otpSecret = vault.secret("OTP_SIGNING_KEY", {
+      description: "2FA HMAC",
+      dev: "test-otp-signing-key",
+    });
+    const expire = clock("expire-otp", { every: "1m" });
+    const bus = signal("otp.events", { delivery: "once" });
+    const member = gate.policy("plugin-member", ({ auth }) => !!auth.verified);
+
+    const twoFactor = plugin("twoFactor-scaffold", { version: "0.0.1" })
+      .vault(otpSecret)
+      .clock(expire)
+      .signal(bus)
+      .gate(member)
+      .table("otp_codes")
+      .needs("store.sql");
+
+    on(http.get("/ok").gate(gate.public), flow({ name: "ok", do: () => ({ ok: true }) }));
+
+    const app = oke({
+      name: "plugin-elements",
+      gate: { policies: [gate.public] },
+      vault: { allowDevFallbacks: true },
+    }).plug(twoFactor);
+
+    await app.boot({ env: "test", unguardedHttp: "allow" });
+    expect(app.booted).toBe(true);
+    expect(app.elements?.vault).toBeDefined();
+    expect(app.elements?.clock).toBeDefined();
+    expect(app.elements?.signal).toBeDefined();
+    expect(app.elements?.gate).toBeDefined();
+    await app.stop();
+  });
+});

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

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import { oke } from "./app.ts";
+import { flow } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { plugin } from "./plugin.ts";
+import { assertPluginNeeds, PluginNeedsError, buildAvailableNeedTokens } from "./plugin-needs.ts";
+import { http } from "./triggers.ts";
+import { resetFlowSeq } from "./flow.ts";
+import { gate } from "../elements/gate.ts";
+
+describe("plugin .needs() resolution", () => {
+  test("plugin-name dependency fails when missing", () => {
+    expect(() =>
+      assertPluginNeeds(
+        {
+          twoFactor: {
+            name: "twoFactor",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: ["auth"],
+          },
+        },
+        { pluginNames: new Set(["twoFactor"]), available: new Set() },
+      ),
+    ).toThrow(PluginNeedsError);
+  });
+
+  test("plugin-name dependency passes when plugged", () => {
+    expect(() =>
+      assertPluginNeeds(
+        {
+          auth: {
+            name: "auth",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: [],
+          },
+          twoFactor: {
+            name: "twoFactor",
+            version: "0.0.1",
+            declares: [],
+            intercepts: [],
+            needs: ["auth"],
+          },
+        },
+        {
+          pluginNames: new Set(["auth", "twoFactor"]),
+          available: new Set(),
+        },
+      ),
+    ).not.toThrow();
+  });
+
+  test("element token store.sql from available set", () => {
+    const available = buildAvailableNeedTokens({ elements: { storeSql: true } });
+    expect(available.has("store.sql")).toBe(true);
+    expect(() =>
+      assertPluginNeeds(
+        {
+          auth: {
+            name: "auth",
+            version: "0.0.1",
+            declares: ["table:oke_sessions"],
+            intercepts: [],
+            needs: ["store.sql"],
+          },
+        },
+        { pluginNames: new Set(["auth"]), available },
+      ),
+    ).not.toThrow();
+  });
+
+  test("boot fails when plugin needs missing peer plugin", async () => {
+    resetBindings();
+    resetFlowSeq();
+    on(http.get("/x").gate(gate.public), flow({ name: "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/plugin-needs.ts

@@ -0,0 +1,129 @@
+/**
+ * Resolve plugin `.needs(dep)` at boot — fail loud when unmet.
+ *
+ * Tokens are either:
+ * - another plugged plugin name (e.g. `"auth"`)
+ * - an element / driver id (e.g. `"store.sql"`, `"postgres"`)
+ */
+
+import type { PluginCapabilities } from "./plugin.ts";
+
+/** Known element / facet dependency tokens. */
+export const ELEMENT_NEED_TOKENS = [
+  "store.sql",
+  "store.kv",
+  "store.files",
+  "store.index",
+  "signal",
+  "clock",
+  "gate",
+  "vault",
+  "channel",
+  "ai",
+  "flow",
+] as const;
+
+/** One unmet `.needs()` dependency. */
+export interface PluginNeedGap {
+  /** Plugin that declared the need. */
+  readonly plugin: string;
+  /** Unmet dependency token. */
+  readonly need: string;
+}
+
+/**
+ * Thrown when installed plugins declare unmet `.needs()` dependencies.
+ */
+export class PluginNeedsError extends Error {
+  readonly gaps: readonly PluginNeedGap[];
+
+  constructor(gaps: readonly PluginNeedGap[]) {
+    const lines = gaps.map((g) => `  - ${g.plugin} needs "${g.need}"`);
+    super(
+      `plugin boot failed — ${gaps.length} unmet .needs() dependenc${gaps.length === 1 ? "y" : "ies"}:\n${lines.join("\n")}`,
+    );
+    this.name = "PluginNeedsError";
+    this.gaps = gaps;
+  }
+}
+
+/** Context for resolving whether a need token is available. */
+export interface PluginNeedsContext {
+  /** Installed plugin names. */
+  readonly pluginNames: ReadonlySet<string>;
+  /**
+   * Available element / driver tokens (e.g. `store.sql`, `postgres`).
+   * Built from boot options, declared drivers, and element needs.
+   */
+  readonly available: ReadonlySet<string>;
+}
+
+/**
+ * Collect unmet needs across all plugin capabilities.
+ *
+ * @param capabilities - Registry capability map
+ * @param ctx - Available plugins + element/driver tokens
+ */
+export function collectUnmetPluginNeeds(
+  capabilities: Readonly<Record<string, PluginCapabilities>>,
+  ctx: PluginNeedsContext,
+): PluginNeedGap[] {
+  const gaps: PluginNeedGap[] = [];
+  for (const caps of Object.values(capabilities)) {
+    for (const need of caps.needs) {
+      if (ctx.pluginNames.has(need) || ctx.available.has(need)) continue;
+      gaps.push({ plugin: caps.name, need });
+    }
+  }
+  return gaps;
+}
+
+/**
+ * Assert every plugin `.needs()` is satisfied. Throws {@link PluginNeedsError}.
+ *
+ * @param capabilities - Registry capability map
+ * @param ctx - Available plugins + element/driver tokens
+ */
+export function assertPluginNeeds(
+  capabilities: Readonly<Record<string, PluginCapabilities>>,
+  ctx: PluginNeedsContext,
+): void {
+  const gaps = collectUnmetPluginNeeds(capabilities, ctx);
+  if (gaps.length > 0) throw new PluginNeedsError(gaps);
+}
+
+/**
+ * Build the available token set from boot-time signals.
+ *
+ * @param input - Element/driver presence flags and declared driver ids
+ */
+export function buildAvailableNeedTokens(input: {
+  readonly elements?: {
+    readonly storeSql?: boolean;
+    readonly storeKv?: boolean;
+    readonly storeFiles?: boolean;
+    readonly storeIndex?: boolean;
+    readonly signal?: boolean;
+    readonly clock?: boolean;
+    readonly gate?: boolean;
+    readonly vault?: boolean;
+    readonly channel?: boolean;
+    readonly ai?: boolean;
+  };
+  readonly driverIds?: readonly string[];
+}): Set<string> {
+  const available = new Set<string>();
+  const e = input.elements ?? {};
+  if (e.storeSql) available.add("store.sql");
+  if (e.storeKv) available.add("store.kv");
+  if (e.storeFiles) available.add("store.files");
+  if (e.storeIndex) available.add("store.index");
+  if (e.signal) available.add("signal");
+  if (e.clock) available.add("clock");
+  if (e.gate) available.add("gate");
+  if (e.vault) available.add("vault");
+  if (e.channel) available.add("channel");
+  if (e.ai) available.add("ai");
+  for (const id of input.driverIds ?? []) available.add(id);
+  return available;
+}