okengine 0.3.6 → 0.5.0

package/src/kernel/concurrency.test.ts

@@ -92,6 +92,64 @@ describe("fx.race — structured concurrency", () => {
   });
 });
 
+describe("fx.using — scoped cleanup", () => {
+  test("release runs on success and on thrown error", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    const released: string[] = [];
+
+    const ok = await fx.using(
+      async () => "res-a",
+      (r) => {
+        released.push(`ok:${r}`);
+      },
+      async (r) => r.toUpperCase(),
+    );
+    expect(ok).toBe("RES-A");
+    expect(released).toEqual(["ok:res-a"]);
+
+    await expect(
+      fx.using(
+        async () => "res-b",
+        async (r) => {
+          released.push(`err:${r}`);
+        },
+        async () => {
+          throw new Error("boom");
+        },
+      ),
+    ).rejects.toThrow("boom");
+    expect(released).toEqual(["ok:res-a", "err:res-b"]);
+  });
+
+  test("release runs when a sibling fx.race winner aborts mid-use", async () => {
+    const fx = createFx({ flow: "t", effects: {} });
+    let released = false;
+
+    const winner = await fx.race([
+      () =>
+        fx.using(
+          async () => "lock",
+          () => {
+            released = true;
+          },
+          () =>
+            new Promise<never>(() => {
+              // Stay pending until ambient abort releases us.
+            }),
+        ),
+      async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        return "fast";
+      },
+    ]);
+
+    expect(winner).toBe("fast");
+    // Let the abort listener settle.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(released).toBe(true);
+  });
+});
+
 describe("fx.retry", () => {
   test("retries then succeeds", async () => {
     const fx = createFx({ flow: "t", effects: {} });

package/src/kernel/concurrency.ts

@@ -8,6 +8,7 @@
 import { parseDurationMs } from "../elements/clock/duration.ts";
 import {
   abortableSleep,
+  abortError,
   currentAbortSignal,
   isAbortError,
   linkAbort,
@@ -144,6 +145,53 @@ export async function fxRace<T>(thunks: ReadonlyArray<FxThunk<T>>): Promise<T> {
   });
 }
 
+/**
+ * Scope a resource to a unit of work — `release` runs exactly once when
+ * `use` settles or when the ambient abort signal fires, whichever comes
+ * first. Uses the same AbortSignal as {@link Fx.signal}; no second
+ * cancellation channel.
+ *
+ * Process-local only: do not journal acquire/release, and do not hold
+ * handles across durable park/resume — journal replay returns values and
+ * never re-enters step bodies.
+ *
+ * @param acquire - Open the resource
+ * @param release - Cleanup, always run
+ * @param use - Work with the resource
+ */
+export async function fxUsing<A, T>(
+  acquire: () => A | Promise<A>,
+  release: (resource: A) => void | Promise<void>,
+  use: (resource: A) => T | Promise<T>,
+): Promise<T> {
+  const resource = await acquire();
+  const signal = currentAbortSignal();
+  let released = false;
+
+  const releaseOnce = async (): Promise<void> => {
+    if (released) return;
+    released = true;
+    await release(resource);
+  };
+
+  const onAbort = (): void => {
+    void releaseOnce();
+  };
+
+  if (signal.aborted) {
+    await releaseOnce();
+    throw abortError(signal.reason);
+  }
+  signal.addEventListener("abort", onAbort);
+
+  try {
+    return await use(resource);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    await releaseOnce();
+  }
+}
+
 /**
  * Retry a thunk with exponential backoff and optional full jitter.
  *

package/src/kernel/edge.test.ts

@@ -26,7 +26,7 @@ describe("plugin edge handlers", () => {
       }
       return undefined;
     });
-    const app = oke({ name: "edge" }).plug(edge);
+    const app = oke({ autoBoot: false, name: "edge" }).plug(edge);
 
     const preflight = await app.fetch(new Request("http://localhost/x", { method: "OPTIONS" }));
     expect(preflight.status).toBe(204);
@@ -42,13 +42,13 @@ describe("plugin edge handlers", () => {
     const answer = plugin("edge-answer", { version: "0.0.1" }).edge(
       () => new Response("answered", { status: 418 }),
     );
-    const app = oke({ name: "edge-order" }).plug(pass).plug(answer);
+    const app = oke({ autoBoot: false, name: "edge-order" }).plug(pass).plug(answer);
 
     const res = await app.fetch(new Request("http://localhost/nowhere", { method: "OPTIONS" }));
     expect(res.status).toBe(418);
     expect(await res.text()).toBe("answered");
 
-    const noPlugins = oke({ name: "edge-none" });
+    const noPlugins = oke({ autoBoot: false, name: "edge-none" });
     const missing = await noPlugins.fetch(
       new Request("http://localhost/nowhere", { method: "OPTIONS" }),
     );

package/src/kernel/flow.test.ts

@@ -45,7 +45,7 @@ describe("flow — one species", () => {
     on(http.post("/work"), shared);
     on(signal, shared);
 
-    const app = oke({ name: "one-species" });
+    const app = oke({ autoBoot: false, name: "one-species" });
     expect(app.bindings).toHaveLength(2);
     expect(app.bindings[0]?.flow).toBe(shared);
     expect(app.bindings[1]?.flow).toBe(shared);
@@ -115,7 +115,7 @@ describe("five trigger kinds", () => {
       }),
     );
 
-    const app = oke({ name: "five" });
+    const app = oke({ autoBoot: false, name: "five" });
 
     const res = await app.fetch(new Request("http://localhost/abc", { method: "GET" }));
     expect(res.status).toBe(200);

package/src/kernel/fx.test.ts

@@ -9,6 +9,7 @@ import {
   type Fx,
   type FxStubStoreHandle,
 } from "./fx.ts";
+import { Redacted } from "./redacted.ts";
 
 /** Narrow stub handle for tests that exercise the in-memory store. */
 function stub(fx: Fx, ref: string): FxStubStoreHandle {
@@ -99,7 +100,7 @@ describe("fx — effect ledger", () => {
     await fx.emit("order-placed", {});
     await fx.send("order-confirmed", { to: "u1" });
     await fx.ask("triage@1", {});
-    expect(fx.vault("STRIPE_KEY")).toBe("sk_test");
+    expect(fx.vault("STRIPE_KEY").reveal()).toBe("sk_test");
     await fx.call("payments.charge", {});
 
     expect(ledger.entries).toHaveLength(7);
@@ -130,7 +131,7 @@ describe("fx — wholesale swap", () => {
         sleep: async () => undefined,
       },
       vault() {
-        return "";
+        return new Redacted("");
       },
       cache: {
         get: async () => undefined,
@@ -162,6 +163,7 @@ describe("fx — wholesale swap", () => {
       id: () => "fixed-id",
       auth: { userId: "u1", scopes: new Set(["a"]) },
       operator: { id: null },
+      principal: { userId: "u1", operatorId: null, scopes: new Set(["a"]) },
       tenant: { id: "t1" },
       fail,
       json: {
@@ -193,6 +195,14 @@ describe("fx — wholesale swap", () => {
       retry(fn) {
         return Promise.resolve().then(fn);
       },
+      async using(acquire, release, use) {
+        const resource = await acquire();
+        try {
+          return await use(resource);
+        } finally {
+          await release(resource);
+        }
+      },
     };
 
     // Any code that accepts `Fx` can run against a total replacement.

package/src/kernel/fx.ts

@@ -33,7 +33,15 @@ import {
 } from "./dry-run.ts";
 import { fail, type FailOptions, type FlowFailure } from "./errors.ts";
 import { currentAbortSignal } from "./abort-scope.ts";
-import { fxAll, fxRace, fxRetry, type FxRetryOptions, type FxThunk } from "./concurrency.ts";
+import {
+  fxAll,
+  fxRace,
+  fxRetry,
+  fxUsing,
+  type FxRetryOptions,
+  type FxThunk,
+} from "./concurrency.ts";
+import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession } from "./journal.ts";
 import type { RunTelemetry } from "./run-telemetry.ts";
 
@@ -67,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;
@@ -262,9 +297,13 @@ export interface Fx {
   /**
    * Read a vault secret (records `secret`).
    *
+   * Returns a {@link Redacted} — printing / logging / serializing it yields a
+   * placeholder, never the value. Call `.reveal()` at the one boundary that
+   * needs the real value (e.g. passing a credential to a driver).
+   *
    * @param secret - Secret name or handle
    */
-  vault(secret: NamedRef): string;
+  vault(secret: NamedRef): Redacted<string>;
   /** Cache surface. */
   readonly cache: FxCache;
   /**
@@ -322,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;
   /**
@@ -369,6 +414,20 @@ export interface Fx {
    * @param opts - Retry policy
    */
   retry<T>(fn: FxThunk<T>, opts?: FxRetryOptions): Promise<T>;
+  /**
+   * Scope a resource to `use` — `release` runs exactly once when `use`
+   * settles or the ambient abort signal fires (e.g. a sibling `fx.race`
+   * winner). Same-attempt cleanup; not journaled.
+   *
+   * @param acquire - Open the resource
+   * @param release - Cleanup, always run
+   * @param use - Work with the resource
+   */
+  using<A, T>(
+    acquire: () => A | Promise<A>,
+    release: (resource: A) => void | Promise<void>,
+    use: (resource: A) => T | Promise<T>,
+  ): Promise<T>;
 }
 
 /**
@@ -393,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`. */
@@ -496,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>(
@@ -850,9 +935,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     data?: Record<string, unknown>,
   ): { message: string; data?: Record<string, unknown> } {
     const vault = options.vaultRuntime;
-    if (!vault) return { message, data };
+    // Redacted<T> never yields the real value, but replace instances with a
+    // placeholder so payloads stay plain JSON (and never re-wrap on replay).
+    const maskedData = data ? maskRedactedDeep(data) : undefined;
+    if (!vault) return { message, data: maskedData };
     const safeMessage = vault.redactString(message);
-    const safeData = data ? (vault.redact(data) as Record<string, unknown>) : undefined;
+    const safeData = maskedData ? (vault.redact(maskedData) as Record<string, unknown>) : undefined;
     return { message: safeMessage, data: safeData };
   }
 
@@ -925,7 +1013,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         duration: Math.max(0, now() - timestamp),
         reversibility: reversibilityOf("secret"),
       });
-      return value;
+      return new Redacted(value);
     },
     cache,
     send(template, opts) {
@@ -1040,6 +1128,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     },
     auth,
     operator,
+    principal,
     tenant,
     fail,
     json: {
@@ -1079,6 +1168,9 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     retry(fn, opts) {
       return fxRetry(fn, opts);
     },
+    using(acquire, release, use) {
+      return fxUsing(acquire, release, use);
+    },
   };
 
   return { fx, ledger, capability };

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,
@@ -137,7 +139,16 @@ export {
   withAbortSignal,
 } from "./abort-scope.ts";
 
-export { defaultRetryWhen, fxAll, fxRace, fxRetry, resolveRetryDelayMs } from "./concurrency.ts";
+export {
+  defaultRetryWhen,
+  fxAll,
+  fxRace,
+  fxRetry,
+  fxUsing,
+  resolveRetryDelayMs,
+} from "./concurrency.ts";
+
+export { isRedacted, maskRedactedDeep, REDACTED_PLACEHOLDER, Redacted } from "./redacted.ts";
 
 export {
   DryRunWriteIsolationError,
@@ -235,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"));