okengine 0.1.4

package/src/kernel/pipeline.ts

@@ -0,0 +1,245 @@
+/**
+ * Request pipeline hooks for element integration.
+ *
+ * - `onAuth` resolves the principal into `fx.auth` / `fx.operator`
+ * - `beforeHandle` evaluates the declared gate chain in registration order,
+ *   short-circuiting on the first denial with a typed error value
+ *   (`Unauthorized` · `Forbidden` · `RateLimited { retryAfterMs }`)
+ *
+ * Every evaluation — pass and deny — is recorded on the run's gates dimension.
+ * Gate denial is a typed error value, never a thrown exception.
+ */
+
+import type { GateEvaluation, GateRuntime } from "../elements/gate.ts";
+import type { GatePolicyContext } from "../elements/gate/declare.ts";
+import { fail, type FlowFailure } from "./errors.ts";
+import type { Fx, FxAuth, FxOperator } from "./fx.ts";
+import type { HookFn, InvocationContext } from "./hooks.ts";
+import type { RunTelemetry } from "./run-telemetry.ts";
+import type { HttpTrigger, Trigger } from "./triggers.ts";
+
+/** Mutable principal bag shared with {@link createFx}. */
+export interface PrincipalBag {
+  readonly auth: {
+    userId: string | null;
+    scopes: Set<string>;
+    verified?: boolean;
+  };
+  readonly operator: {
+    id: string | null;
+  };
+}
+
+/** Resolved identity from auth middleware / test harness. */
+export interface ResolvedPrincipal {
+  readonly plane?: "user" | "operator";
+  readonly userId?: string | null;
+  readonly operatorId?: string | null;
+  readonly scopes?: Iterable<string>;
+  readonly verified?: boolean;
+}
+
+/** Dependencies for {@link createElementPipelineHooks}. */
+export interface PipelineDeps {
+  /** Gate runtime (required for gate evaluation). */
+  readonly gates?: GateRuntime;
+  /**
+   * Cryptographically verify a Bearer access token.
+   * Required in production when an `Authorization` header is present.
+   *
+   * @param token - Raw token (no `Bearer ` prefix)
+   * @returns Principal on success
+   * @throws On forge / expiry / revoke — pipeline maps to `Unauthorized`
+   */
+  readonly verifyBearer?: (token: string) => Promise<ResolvedPrincipal>;
+  /**
+   * When true, `ctx.state.principal` / execute `extras.principal` injection
+   * is honoured (test harness only). Must be false for production HTTP.
+   */
+  readonly allowTestPrincipals?: boolean;
+  /** Per-invocation principal bag (same object passed into createFx). */
+  readonly principals: PrincipalBag;
+  /** Telemetry collector for the current run (gates dimension). */
+  readonly telemetry: RunTelemetry;
+}
+
+/**
+ * Typed gate-denial failures the Gates simulator promises.
+ */
+export type GateDenialCode = "Unauthorized" | "Forbidden" | "RateLimited";
+
+/**
+ * Map a denied gate evaluation to the typed error the simulator promises.
+ *
+ * @param evaluation - First denying evaluation
+ * @param ctx - Policy context at denial time
+ */
+export function gateDenialFailure(
+  evaluation: GateEvaluation,
+  ctx: GatePolicyContext,
+): FlowFailure {
+  if (evaluation.kind === "rate" || evaluation.reason === "rate limited") {
+    return fail("RateLimited", {
+      retryAfterMs: evaluation.retryAfterMs ?? 0,
+    });
+  }
+
+  const authenticated =
+    ctx.auth.userId !== null && ctx.auth.userId !== undefined;
+  if (!authenticated) {
+    return fail("Unauthorized", {});
+  }
+  return fail("Forbidden", {
+    gate: evaluation.name,
+    reason: evaluation.reason ?? "policy denied",
+  });
+}
+
+/**
+ * Collect gate names from an HTTP trigger (registration order).
+ *
+ * @param trigger - Active trigger
+ */
+export function gateNamesOf(trigger: Trigger): string[] {
+  if (trigger.kind !== "http") return [];
+  return (trigger as HttpTrigger).gates.map((g) =>
+    typeof g === "string" ? g : g.name,
+  );
+}
+
+/**
+ * Record evaluations onto run telemetry (pass and deny).
+ *
+ * @param telemetry - Run collector
+ * @param evaluations - Ordered results
+ */
+export function recordGateEvaluations(
+  telemetry: RunTelemetry,
+  evaluations: readonly GateEvaluation[],
+): void {
+  for (const ev of evaluations) {
+    telemetry.gates.push(ev.name);
+    telemetry.dimensions[`gate:${ev.name}`] = ev.allowed ? "pass" : "deny";
+  }
+}
+
+/**
+ * Apply a resolved principal onto the shared bags (and thus `fx`).
+ *
+ * @param bag - Mutable principal bag
+ * @param resolved - Identity
+ */
+export function applyPrincipal(
+  bag: PrincipalBag,
+  resolved: ResolvedPrincipal | undefined,
+): void {
+  if (!resolved) return;
+  if (resolved.plane === "operator" || resolved.operatorId !== undefined) {
+    bag.operator.id = resolved.operatorId ?? null;
+  }
+  if (
+    resolved.plane === "user" ||
+    resolved.userId !== undefined ||
+    resolved.scopes !== undefined ||
+    resolved.verified !== undefined
+  ) {
+    if (resolved.userId !== undefined) bag.auth.userId = resolved.userId;
+    if (resolved.scopes !== undefined) {
+      bag.auth.scopes.clear();
+      for (const s of resolved.scopes) bag.auth.scopes.add(s);
+    }
+    if (resolved.verified !== undefined) bag.auth.verified = resolved.verified;
+  }
+}
+
+/**
+ * Build `onAuth` + `beforeHandle` hooks for element-aware execution.
+ *
+ * @param deps - Gate runtime, principal bag, telemetry
+ */
+export function createElementPipelineHooks(deps: PipelineDeps): {
+  readonly onAuth: HookFn;
+  readonly beforeHandle: HookFn;
+} {
+  const onAuth: HookFn = async (ctx) => {
+    // Production: never honour injected principals on the request bag.
+    if (!deps.allowTestPrincipals && "principal" in ctx.state) {
+      delete ctx.state.principal;
+    }
+
+    const header = ctx.request?.headers.get("authorization");
+    if (header?.startsWith("Bearer ")) {
+      const token = header.slice("Bearer ".length).trim();
+      if (!token) {
+        return fail("Unauthorized", {});
+      }
+      if (!deps.verifyBearer) {
+        // Bearer present but no auth binding — refuse rather than trust.
+        return fail("Unauthorized", {});
+      }
+      try {
+        const principal = await deps.verifyBearer(token);
+        applyPrincipal(deps.principals, principal);
+        return;
+      } catch {
+        // Forge / expiry / revoke → typed Unauthorized (never throw).
+        return fail("Unauthorized", {});
+      }
+    }
+
+    // Test-harness injection only (createTestApp / unit tests).
+    if (deps.allowTestPrincipals) {
+      const fromState = ctx.state.principal as ResolvedPrincipal | undefined;
+      if (fromState) applyPrincipal(deps.principals, fromState);
+    }
+  };
+
+  const beforeHandle: HookFn = async (ctx, fxOrErr) => {
+    const names = gateNamesOf(ctx.trigger);
+    if (names.length === 0 || !deps.gates) return;
+
+    const policyCtx = policyContextOf(fxOrErr as Fx, ctx);
+    const evaluations = await deps.gates.check(names, policyCtx);
+    recordGateEvaluations(deps.telemetry, evaluations);
+
+    const denied = evaluations.find((e) => !e.allowed);
+    if (denied) {
+      return gateDenialFailure(denied, policyCtx);
+    }
+  };
+
+  return { onAuth, beforeHandle };
+}
+
+/**
+ * Build a policy context from the live `fx` principals.
+ *
+ * @param fx - Fx door
+ * @param ctx - Invocation context (for IP / meta)
+ */
+export function policyContextOf(
+  fx: Fx,
+  ctx: InvocationContext,
+): GatePolicyContext {
+  const auth = fx.auth as FxAuth;
+  const operator = fx.operator as FxOperator;
+  const ip =
+    ctx.request?.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+    ctx.request?.headers.get("x-real-ip") ??
+    undefined;
+  return {
+    auth: {
+      userId: auth.userId,
+      scopes: auth.scopes,
+      verified: auth.verified,
+    },
+    operator: { id: operator.id },
+    meta: {
+      ip,
+      userId: auth.userId,
+      ...(typeof ctx.state.meta === "object" && ctx.state.meta !== null
+        ? (ctx.state.meta as Record<string, unknown>)
+        : {}),
+    },
+  };
+}

package/src/kernel/plug.ts

@@ -0,0 +1,82 @@
+/**
+ * `.plug()` — attach a plugin at an attachment point.
+ *
+ * Scope is the attachment point:
+ * - `app.plug()` — app-wide
+ * - `unit.plug()` — that unit only
+ * - `flow.plug()` — one flow only
+ *
+ * No `global: true`, no escape hatch, no inheritance rule.
+ * The position is the scope.
+ *
+ * @see docs/spec/console.md §9.15
+ */
+
+import type { AnyFlowDef } from "./flow.ts";
+import { isPlugin, type DecorationsOf, type PluginDef } from "./plugin.ts";
+import {
+  type PluginRegistry,
+  type PluginScope,
+} from "./registry.ts";
+
+/**
+ * Apply a plugin to a registry at the given scope.
+ *
+ * @param registry - App plugin registry
+ * @param pluginDef - Plugin definition
+ * @param scope - Attachment point
+ */
+export function applyPlugin(
+  registry: PluginRegistry,
+  pluginDef: PluginDef,
+  scope: PluginScope,
+): void {
+  if (!isPlugin(pluginDef)) {
+    throw new TypeError(".plug() expected a plugin() definition");
+  }
+  registry.plug(pluginDef, scope);
+}
+
+/**
+ * Type-level accumulation helper: merge decorations from a plugged plugin.
+ *
+ * @typeParam Base - Existing decorations
+ * @typeParam P - Plugin being plugged
+ */
+export type AccumulateDecorations<
+  Base extends Record<string, unknown>,
+  P,
+> = Base & DecorationsOf<P>;
+
+/** Something that can receive `.plug()` with type accumulation. */
+export interface Pluggable<D extends Record<string, unknown> = {}> {
+  /**
+   * Attach a plugin. Scope is this attachment point.
+   *
+   * @param pluginDef - Plugin from {@link plugin}
+   */
+  plug<P extends PluginDef>(
+    pluginDef: P,
+  ): Pluggable<AccumulateDecorations<D, P>>;
+}
+
+/**
+ * Resolve the plugin scope for a flow attachment.
+ *
+ * @param flowDef - Flow being plugged into
+ */
+export function flowPluginScope(flowDef: AnyFlowDef): PluginScope {
+  return { kind: "flow", name: flowDef.name };
+}
+
+/**
+ * Resolve the plugin scope for a unit attachment.
+ *
+ * @param unitName - Unit name
+ */
+export function unitPluginScope(unitName: string): PluginScope {
+  return { kind: "unit", name: unitName };
+}
+
+/** App-wide plugin scope. */
+export const appPluginScope: PluginScope = { kind: "app" };

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

@@ -0,0 +1,84 @@
+/**
+ * Capability capture — registration against the builder we supply.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { flow } from "../flow.ts";
+import { plugin } from "../plugin.ts";
+import { createPluginRegistry, createRecordingApi } from "../registry.ts";
+
+describe("plugin capability capture", () => {
+  test("recording api captures declares vs intercepts", () => {
+    const audit = plugin("audit", { version: "1.0.0" })
+      .config({} as never)
+      .element({ kind: "store.sql", name: "audit" })
+      .needs("store.kv")
+      .decorate("audit", { enabled: true })
+      .hook("afterHandle", async () => {})
+      .errors({ AuditWriteFailed: {} as never })
+      .consolePanel({
+        id: "audit",
+        title: "Audit Trail",
+        entry: "./panel.tsx",
+      })
+      .cli("audit:export", () => undefined)
+      .table("audit_events")
+      .driver("postgres")
+      .image("store.sql", "postgres:16")
+      .flow(flow({ name: "audit.flush", do: () => undefined }))
+      .client("audit", { subscribe: true });
+
+    const { api, snapshot } = createRecordingApi({
+      name: "audit",
+      version: "1.0.0",
+    });
+    audit.register(api);
+    const caps = snapshot().capabilities;
+
+    const expected = {
+      name: "audit",
+      version: "1.0.0",
+      declares: [
+        "config",
+        "store.sql:audit",
+        "decorate:audit",
+        "errors:AuditWriteFailed",
+        "consolePanel:audit",
+        "cli:audit:export",
+        "table:audit_events",
+        "driver:postgres",
+        "image:store.sql",
+        "flow:audit.flush",
+        "client:audit",
+      ],
+      intercepts: ["afterHandle"],
+      needs: ["store.kv"],
+    };
+
+    expect(caps).toEqual(expected);
+  });
+
+  test("registry.capabilities matches hand-written expectation after plug", () => {
+    const registry = createPluginRegistry();
+    const p = plugin("audit", { version: "1.0.0" })
+      .element({ kind: "store.sql", name: "audit" })
+      .consolePanel({
+        id: "audit",
+        title: "Audit Trail",
+        entry: "./panel.tsx",
+      })
+      .hook("afterHandle", () => {});
+
+    registry.plug(p, { kind: "app" });
+
+    expect(registry.capabilities()).toEqual({
+      audit: {
+        name: "audit",
+        version: "1.0.0",
+        declares: ["store.sql:audit", "consolePanel:audit"],
+        intercepts: ["afterHandle"],
+        needs: [],
+      },
+    });
+  });
+});

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

@@ -0,0 +1,106 @@
+/**
+ * Conflict detection — never last-write-wins.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { plugin } from "../plugin.ts";
+import { createPluginRegistry } from "../registry.ts";
+
+describe("plugin conflict detection", () => {
+  test("table-name collision fails the boot with both plugin names", () => {
+    const registry = createPluginRegistry();
+
+    registry.plug(
+      plugin("audit", { version: "1.0.0" }).table("events"),
+      { kind: "app" },
+    );
+
+    expect(() =>
+      registry.plug(
+        plugin("billing", { version: "1.0.0" }).table("events"),
+        { kind: "app" },
+      ),
+    ).toThrow(
+      'Plugin conflict: table "events" claimed by "audit" and "billing"',
+    );
+  });
+
+  test("panel-id collision names both sides", () => {
+    const registry = createPluginRegistry();
+
+    registry.plug(
+      plugin("a", { version: "1.0.0" }).consolePanel({
+        id: "trail",
+        title: "A",
+        entry: "./a.tsx",
+      }),
+      { kind: "app" },
+    );
+
+    expect(() =>
+      registry.plug(
+        plugin("b", { version: "1.0.0" }).consolePanel({
+          id: "trail",
+          title: "B",
+          entry: "./b.tsx",
+        }),
+        { kind: "app" },
+      ),
+    ).toThrow('Plugin conflict: panel "trail" claimed by "a" and "b"');
+  });
+
+  test("driver-id collision names both sides", () => {
+    const registry = createPluginRegistry();
+
+    registry.plug(plugin("a", { version: "1.0.0" }).driver("postgres"), {
+      kind: "app",
+    });
+
+    expect(() =>
+      registry.plug(plugin("b", { version: "1.0.0" }).driver("postgres"), {
+        kind: "app",
+      }),
+    ).toThrow('Plugin conflict: driver "postgres" claimed by "a" and "b"');
+  });
+
+  test("same plugin twice at the same scope is a no-op", () => {
+    const registry = createPluginRegistry();
+    const p = plugin("audit", { version: "1.0.0" }).table("audit_log");
+
+    expect(registry.plug(p, { kind: "app" })).toBeDefined();
+    expect(registry.plug(p, { kind: "app" })).toBeUndefined();
+    expect(registry.installed).toHaveLength(1);
+  });
+
+  test("same plugin+config at two scopes is allowed", () => {
+    const registry = createPluginRegistry();
+    const p = plugin("rate-limit", {
+      version: "1.0.0",
+      config: { max: 30 },
+    }).hook("onRequest", () => {});
+
+    expect(
+      registry.plug(p, { kind: "unit", name: "orders" }),
+    ).toBeDefined();
+    expect(
+      registry.plug(p, { kind: "unit", name: "payments" }),
+    ).toBeDefined();
+    expect(registry.installed).toHaveLength(2);
+  });
+
+  test("same plugin twice with conflicting config is a boot error", () => {
+    const registry = createPluginRegistry();
+
+    registry.plug(
+      plugin("rate-limit", { version: "1.0.0", config: { max: 30 } }),
+      { kind: "unit", name: "orders" },
+    );
+
+    expect(() =>
+      registry.plug(
+        plugin("rate-limit", { version: "1.0.0", config: { max: 60 } }),
+        { kind: "unit", name: "payments" },
+      ),
+    ).toThrow(/conflicting config/);
+  });
+});

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

@@ -0,0 +1,111 @@
+/**
+ * Type accumulation through `.plug()` — decorations visible downstream.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { oke, type OkeApp } from "../app.ts";
+import { flow, resetFlowSeq } from "../flow.ts";
+import { on, resetBindings } from "../on.ts";
+import { plugin, type PluginDef } from "../plugin.ts";
+import { http } from "../triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+/** Compile-time assert: `Actual` extends `Expected`. */
+type ExpectExtends<Actual, Expected> =
+  Actual extends Expected ? true : false;
+
+describe("plugin decorate — types and runtime", () => {
+  test("decoration is visible in downstream handlers", async () => {
+    const audit = plugin("audit", { version: "1.0.0" }).decorate("audit", {
+      enabled: true,
+      retain: "2y",
+    });
+
+    let seen: unknown;
+    on(
+      http.get("/x"),
+      flow({
+        name: "x",
+        do: (_input, _fx) => {
+          return { ok: true };
+        },
+      }).hook("beforeHandle", (ctx) => {
+        seen = ctx.decorations.audit;
+      }),
+    );
+
+    const app = oke({ name: "decorate" }).plug(audit);
+    await app.fetch(new Request("http://localhost/x"));
+
+    expect(seen).toEqual({ enabled: true, retain: "2y" });
+  });
+
+  test("types accumulate through .plug()", () => {
+    const withAudit = plugin("audit", { version: "1.0.0" }).decorate(
+      "audit",
+      { enabled: true as const },
+    );
+    const withBilling = plugin("billing", { version: "1.0.0" }).decorate(
+      "billing",
+      { currency: "SAR" as const },
+    );
+
+    const app = oke({ name: "types" }).plug(withAudit).plug(withBilling);
+
+    type AppDeco = typeof app extends OkeApp<infer D> ? D : never;
+    type HasBoth = ExpectExtends<
+      AppDeco,
+      { audit: { enabled: true }; billing: { currency: "SAR" } }
+    >;
+
+    const _typeCheck: HasBoth = true;
+    expect(_typeCheck).toBe(true);
+
+    // PluginDef decoration param also accumulates on the builder itself.
+    type AuditPlugin = typeof withAudit;
+    type AuditDeco = AuditPlugin extends PluginDef<infer D> ? D : never;
+    type HasAudit = ExpectExtends<AuditDeco, { audit: { enabled: true } }>;
+    const _pluginType: HasAudit = true;
+    expect(_pluginType).toBe(true);
+  });
+
+  test("unit-scoped decoration does not leak to another unit", async () => {
+    const seen: Record<string, unknown> = {};
+
+    on(
+      http.get("/orders"),
+      flow({
+        name: "orders.list",
+        unit: "orders",
+        do: () => ({}),
+      }).hook("beforeHandle", (ctx) => {
+        seen.orders = ctx.decorations.flag;
+      }),
+    );
+    on(
+      http.get("/payments"),
+      flow({
+        name: "payments.list",
+        unit: "payments",
+        do: () => ({}),
+      }).hook("beforeHandle", (ctx) => {
+        seen.payments = ctx.decorations.flag;
+      }),
+    );
+
+    const app = oke({ 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"));
+    await app.fetch(new Request("http://localhost/payments"));
+
+    expect(seen.orders).toBe("orders-only");
+    expect(seen.payments).toBeUndefined();
+  });
+});