okengine 0.14.1 → 0.16.0

package/src/kernel/adopt-barrel-fresh.test.ts

@@ -89,7 +89,7 @@ describe("boot-level: stale barrel through a real oke() boot", () => {
         effects: {},
         do: () => ({ ok: true as const }),
       });
-      on(http.get("/health").gate.public, mainFlow);
+      on(http.get("/health").public(), mainFlow);
       const app = oke({ name: "stale-barrel", gate: { unguardedHttp: "allow" } });
 
       await expect(

package/src/kernel/adopt-routes.ts

@@ -39,10 +39,20 @@ export type AppFlowRoute<
       readonly path?: undefined;
     };
 
-/** Unit → flow → contract. */
+/**
+ * Unit → flow → contract. Leaf is the HTTP / call-only union — do not
+ * index with `AppFlowRoute<any, any, any, any, any>` (`any extends string`
+ * makes `method`/`path` required and rejects cron / signal flows).
+ */
 export type AppRouteMap = {
   readonly [unit: string]: {
-    readonly [flow: string]: AppFlowRoute<any, any, any, any, any>;
+    readonly [flow: string]: {
+      readonly in?: unknown;
+      readonly out?: unknown;
+      readonly errors?: unknown;
+      readonly method?: string;
+      readonly path?: string;
+    };
   };
 };
 
@@ -170,6 +180,7 @@ export function accumulateAdoptArgs(args: readonly unknown[], into: RuntimeRoute
       const unitBag = into[unit] ?? (into[unit] = {});
       for (const [flowName, flowDef] of Object.entries(value as Record<string, unknown>)) {
         if (!isFlow(flowDef)) continue;
+        stampAdoptedFlow(flowDef, unit, flowName);
         found.push(flowDef);
         unitBag[flowName] = runtimeRouteFromFlow(flowDef);
       }
@@ -178,3 +189,20 @@ export function accumulateAdoptArgs(args: readonly unknown[], into: RuntimeRoute
 
   return found;
 }
+
+/**
+ * Stamp `unit.export` on nameless flows — same rule as {@link unit}.
+ *
+ * @param flowDef - Flow to stamp
+ * @param unit - Client unit (folder / adopt key)
+ * @param exportName - Namespace export
+ */
+function stampAdoptedFlow(flowDef: AnyFlowDef, unit: string, exportName: string): void {
+  const f = flowDef as { name: string; unit: string | undefined };
+  if (!f.name || f.name.startsWith("flow_")) {
+    f.name = `${unit}.${exportName}`;
+  }
+  if (!f.unit) {
+    f.unit = unit;
+  }
+}

package/src/kernel/api-key-host-persist.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Host API-key durability — standalone `oke()` (no Console).
+ *
+ * Creates a key via `fx.auth.createApiKey`, stops, boots a fresh app against
+ * the same SQL URL, and verifies Bearer on the new `gate.auth.apiKeyStore`.
+ * Production uses postgres + `DATABASE_URL`; this suite uses file-backed
+ * PGlite at that same URL so the restart is hermetic.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AUTH_TABLES } from "../auth/tables.ts";
+import { gate } from "../elements/gate.ts";
+import { resetStores, store } from "../elements/store/declare.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+const PEPPER = "oke-host-api-key-persist-pepper";
+const member = gate.policy("member", ({ auth }) => !!auth.verified);
+
+function resetIsolated(): void {
+  resetBindings();
+  resetFlowSeq();
+  resetStores();
+}
+
+afterEach(() => {
+  resetIsolated();
+});
+
+describe("host API key persist via store.sql()", () => {
+  test("standalone oke() persists keys across restart; Bearer verifies on a fresh store", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-host-keys-"));
+    const sqlUrl = join(dir, "pgdata");
+    const prevDb = process.env.DATABASE_URL;
+    const prevPglite = process.env.OKE_PGLITE_URL;
+    process.env.DATABASE_URL = sqlUrl;
+    process.env.OKE_PGLITE_URL = sqlUrl;
+
+    try {
+      resetIsolated();
+      const db1 = store.sql("app", { schema: {} });
+      on(
+        http.post("/keys").gate(member),
+        flow("keys.create", {
+          effects: { writes: ["auth:api-keys"] },
+          do: (_input, fx) => fx.auth.createApiKey({ name: "prod-ci", scopes: ["member"] }),
+        }),
+      );
+      on(
+        http.get("/secure").gate(member),
+        flow("secure.ping", {
+          effects: {},
+          do: () => ({ ok: true }),
+        }),
+      );
+
+      const first = oke({
+        name: "host-keys-first",
+        stores: [db1],
+        gate: {
+          auth: { secret: PEPPER, http: false },
+          policies: [member],
+        },
+        env: "test",
+        startScheduler: false,
+      });
+      await first.boot({ env: "test", startScheduler: false });
+      expect(first.apiKeys?.persist).toBeTypeOf("function");
+
+      const created = await first.execute(
+        first.flow("keys.create")!,
+        {},
+        http.post("/keys").gate(member),
+        {
+          principal: {
+            plane: "user",
+            userId: "u_issuer",
+            scopes: new Set(["member"]),
+            verified: true,
+          },
+        },
+      );
+      expect(created.failure).toBeUndefined();
+      const secret = (created.output as { secret?: string } | undefined)?.secret;
+      expect(secret?.startsWith("oke_")).toBe(true);
+
+      const firstStore = first.bootResult?.store;
+      await first.stop();
+      await firstStore?.close();
+
+      resetIsolated();
+      const db2 = store.sql("app", { schema: {} });
+      on(
+        http.get("/secure").gate(member),
+        flow("secure.ping", {
+          effects: {},
+          do: () => ({ ok: true }),
+        }),
+      );
+      const second = oke({
+        name: "host-keys-second",
+        stores: [db2],
+        gate: {
+          auth: { secret: PEPPER, http: false },
+          policies: [member],
+        },
+        env: "test",
+        startScheduler: false,
+      });
+      await second.boot({ env: "test", startScheduler: false });
+      expect(second.apiKeys).not.toBe(first.apiKeys);
+      expect(second.apiKeys?.keys.size).toBeGreaterThan(0);
+
+      const conn = await second.bootResult?.store?.primarySql();
+      const rows = await conn?.query(`SELECT id, name FROM ${AUTH_TABLES.apiKeys}`);
+      expect(rows?.some((r) => r.name === "prod-ci")).toBe(true);
+
+      const res = await second.fetch(
+        new Request("http://localhost/secure", {
+          method: "GET",
+          headers: { authorization: `Bearer ${secret}` },
+        }),
+      );
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ data: { ok: true }, error: null });
+
+      const secondStore = second.bootResult?.store;
+      await second.stop();
+      await secondStore?.close();
+    } finally {
+      if (prevDb === undefined) delete process.env.DATABASE_URL;
+      else process.env.DATABASE_URL = prevDb;
+      if (prevPglite === undefined) delete process.env.OKE_PGLITE_URL;
+      else process.env.OKE_PGLITE_URL = prevPglite;
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 20_000);
+});

package/src/kernel/app.ts

@@ -14,6 +14,7 @@ import {
   accumulateAdoptArgs,
   type AppRouteMap,
   type RoutesFromAdoptArgs,
+  type RoutesFromNamespace,
   type RuntimeRouteMap,
 } from "./adopt-routes.ts";
 // `./boot.ts` pulls in every element + driver module (vault, store, signal,
@@ -23,6 +24,7 @@ import {
 import type { BootOptions, BootResult, ElementRuntimes } from "./boot.ts";
 import type { CapabilityToken } from "./capability.ts";
 import type { AppAuthBinding } from "./auth-resolve.ts";
+import type { ApiKeyStore } from "../auth/api-keys.ts";
 import type { AuthHttpMaterialization } from "../auth/bindings.ts";
 import type { WiredGateAuth } from "./app-auth.ts";
 import {
@@ -59,7 +61,8 @@ import {
 } from "../runtime/dev-request-log.ts";
 import { asBrowserJsonCodeBlock, httpNavGroups } from "../runtime/json-code-block.ts";
 import { resolveDurationMs } from "./elapsed.ts";
-import { fail } from "./errors.ts";
+import { fail, throwOke } from "./errors.ts";
+import { consumeRegisteredFlowUnits, type FlowUnitBag } from "./flow-units.ts";
 import {
   isFlowFailure,
   mergeHooks,
@@ -91,6 +94,8 @@ import {
   aiModelRegistry,
   aiPromptRegistry,
   channelTemplateRegistry,
+  clockRegistry,
+  gateRegistry,
   requiredEnvRegistry,
   secretRegistry,
   signalRegistry,
@@ -99,6 +104,7 @@ import {
 import {
   applyPrincipal,
   createElementPipelineHooks,
+  gateNamesOf,
   type PrincipalBag,
   type ResolvedPrincipal,
 } from "./pipeline.ts";
@@ -118,6 +124,7 @@ import {
   type RouterPreset,
   type SmartRouter,
 } from "./router.ts";
+import { isPendingHttpPath } from "./http-path-pending.ts";
 import type {
   CdcTrigger,
   EveryTrigger,
@@ -299,6 +306,21 @@ export interface UnitHooks<D extends Record<string, unknown> = {}> {
   plug<P extends PluginDef>(pluginDef: P): UnitHooks<AccumulateDecorations<D, P>>;
 }
 
+/**
+ * Module-augmentation slot filled by `src/flows/generated.ts`.
+ * Kernel tests do not import an app generated file, so this stays `{}`.
+ */
+export interface RegisteredFlowUnits {}
+
+/**
+ * `$routes` derived from {@link RegisteredFlowUnits} after `import generated`.
+ *
+ * @typeParam U - Augmented unit map
+ */
+export type RoutesFromRegisteredUnits<U = RegisteredFlowUnits> = {
+  [K in keyof U]: U[K] extends Record<string, unknown> ? RoutesFromNamespace<U[K]> : never;
+};
+
 /**
  * Application instance — adopts flows, routes HTTP, runs the pipeline.
  *
@@ -350,6 +372,8 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
    * Builtin auth binding after boot (session store + secret), when configured.
    */
   readonly authBinding: AppAuthBinding | undefined;
+  /** Shared API key store when `gate.auth` is enabled. */
+  readonly apiKeys: ApiKeyStore | undefined;
   /**
    * Attach a plugin app-wide. Scope is the attachment point.
    * Types accumulate — decorations are visible on downstream handlers.
@@ -435,6 +459,8 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
        * Takes effect only with {@link trustedInvoke}.
        */
       readonly revealPii?: boolean;
+      /** Forced RLS bag (Console / Call API). Operator omit = no stamp. */
+      readonly rls?: import("../drivers/pg-rls.ts").RlsIdentity;
       /** Parent WideEvent id when this execution was caused by another. */
       readonly parentId?: string;
       /** Explicit run / WideEvent id (defaults to a new UUID). */
@@ -562,11 +588,57 @@ function mergeAiOptions(
   };
 }
 
+/**
+ * Refuse an unresolved path sentinel or a nameless HTTP flow.
+ *
+ * @param binding - HTTP binding
+ */
+function assertHttpBindingReady(binding: Binding): void {
+  const trigger = binding.trigger;
+  if (trigger.kind !== "http") return;
+  if (isPendingHttpPath(trigger.path)) {
+    throwOke("HTTP_PATH_UNRESOLVED", {
+      flow: binding.flow.name || "(unnamed)",
+      method: trigger.method,
+    });
+  }
+  if (!binding.flow.name || binding.flow.name.startsWith("flow_")) {
+    throwOke("HTTP_FLOW_UNNAMED", {
+      method: trigger.method,
+      path: trigger.path,
+    });
+  }
+}
+
+/**
+ * Fold `generated.ts` units into `$routes` and `flowsByName`.
+ *
+ * @param units - Drained {@link registerFlowUnits} bag
+ * @param routes - Runtime `$routes`
+ * @param registerFlow - App flow index
+ */
+function drainGeneratedUnits(
+  units: Record<string, FlowUnitBag>,
+  routes: RuntimeRouteMap,
+  registerFlow: (flowDef: AnyFlowDef) => void,
+): void {
+  if (Object.keys(units).length === 0) return;
+  const flows = accumulateAdoptArgs([units], routes);
+  for (const flowDef of flows) {
+    registerFlow(flowDef);
+  }
+}
+
 /**
  * Create an application. Adopts bindings registered via {@link on}.
+ * Drains {@link registerFlowUnits} into `$routes` unless `registry: "ignore"`.
  *
  * @param options - App name and router preset
  */
+export function oke(
+  options: OkeOptions & { readonly registry: "ignore" },
+): OkeApp<Record<string, never>, Record<string, never>>;
+export function oke(options: OkeOptions): OkeApp<{}, RoutesFromRegisteredUnits>;
 export function oke(options: OkeOptions): OkeApp {
   const aot = options.aot !== false;
   const registry = options.registry ?? "consume";
@@ -576,11 +648,12 @@ export function oke(options: OkeOptions): OkeApp {
       : [...listBindings(), ...(options.bindings ?? [])];
   if (registry === "consume") resetBindings();
 
-  // Same registry mode drains store.sql/store.files, vault.secret, signal(),
-  // channel.<medium>().template(), and ai.model/prompt/embed/agent/mcpServer —
-  // module-evaluation registries that mirror `on`'s trigger drain
-  // (`listBindings`/`resetBindings` above). Explicit `options.stores` /
-  // `secrets` / `signals` / `channel.templates` / `ai` are additive, never
+  // Same registry mode drains store.*, vault.secret, signal(), clock(),
+  // gate.policy/scope/rate, channel.<medium>().template(), and
+  // ai.model/prompt/embed/agent/mcpServer — module-evaluation registries
+  // that mirror `on`'s trigger drain (`listBindings`/`resetBindings` above).
+  // Explicit `options.stores` / `secrets` / `signals` / `clocks` /
+  // `gate.policies` / `channel.templates` / `ai` are additive, never
   // silently ignored — deduped by reference so an explicitly-passed decl
   // that is also in the registry is not doubled.
   const registrySnapshot =
@@ -590,6 +663,8 @@ export function oke(options: OkeOptions): OkeApp {
           secrets: [],
           requiredEnv: [],
           signals: [],
+          clocks: [],
+          gates: [],
           channelTemplates: [],
           aiModels: [],
           aiPrompts: [],
@@ -602,6 +677,8 @@ export function oke(options: OkeOptions): OkeApp {
           secrets: secretRegistry.slice(),
           requiredEnv: requiredEnvRegistry.slice(),
           signals: signalRegistry.slice(),
+          clocks: clockRegistry.slice(),
+          gates: gateRegistry.slice(),
           channelTemplates: channelTemplateRegistry.slice(),
           aiModels: aiModelRegistry.slice(),
           aiPrompts: aiPromptRegistry.slice(),
@@ -614,6 +691,8 @@ export function oke(options: OkeOptions): OkeApp {
     secretRegistry.length = 0;
     requiredEnvRegistry.length = 0;
     signalRegistry.length = 0;
+    clockRegistry.length = 0;
+    gateRegistry.length = 0;
     channelTemplateRegistry.length = 0;
     aiModelRegistry.length = 0;
     aiPromptRegistry.length = 0;
@@ -624,6 +703,8 @@ export function oke(options: OkeOptions): OkeApp {
   const effectiveStores = mergeUnique(options.stores, registrySnapshot.stores);
   const effectiveSecrets = mergeUnique(options.secrets, registrySnapshot.secrets);
   const effectiveSignals = mergeUnique(options.signals, registrySnapshot.signals);
+  const effectiveClocks = mergeUnique(options.clocks, registrySnapshot.clocks);
+  const effectivePolicies = mergeUnique(options.gate?.policies, registrySnapshot.gates);
   /**
    * Fold registered `vault.env.required` names into the vault boot options so
    * boot reports missing env vars in the same gap list as missing secrets.
@@ -658,16 +739,23 @@ export function oke(options: OkeOptions): OkeApp {
 
   // Resolve Gate bag early so auth HTTP Bindings join `adopted` + the router
   // before posture audit (same ensureBoot → doBoot path — never a side channel).
+  const mergedGate: GateOptions | undefined =
+    effectivePolicies.length > 0 ? { ...options.gate, policies: effectivePolicies } : options.gate;
   const gateConfig: ResolvedGateConfig = resolveGateConfig({
-    gate: options.gate,
+    gate: mergedGate,
     env: options.env,
   });
 
-  /** Retained for test harness / boot merges (includes auto-drained AI decls). */
-  const $options: OkeOptions =
-    effectiveAi === undefined || options.ai === effectiveAi
-      ? options
-      : { ...options, ai: effectiveAi };
+  /** Retained for test harness / boot merges (includes auto-drained decls). */
+  const $options: OkeOptions = {
+    ...options,
+    ...(effectiveAi !== undefined ? { ai: effectiveAi } : {}),
+    ...(effectiveStores.length > 0 ? { stores: effectiveStores } : {}),
+    ...(effectiveSecrets.length > 0 ? { secrets: effectiveSecrets } : {}),
+    ...(effectiveSignals.length > 0 ? { signals: effectiveSignals } : {}),
+    ...(effectiveClocks.length > 0 ? { clocks: effectiveClocks } : {}),
+    ...(mergedGate !== undefined ? { gate: mergedGate } : {}),
+  };
 
   const appHooks: HookMap = {};
   const unitHooks = new Map<string, HookMap>();
@@ -701,8 +789,19 @@ export function oke(options: OkeOptions): OkeApp {
   }
 
   const smart = createRouter<Binding>(options.router ?? "default");
+  const seenHttpRoutes = new Set<string>();
   for (const b of adopted) {
     if (b.trigger.kind === "http") {
+      assertHttpBindingReady(b);
+      const key = `${b.trigger.method} ${b.trigger.path}`;
+      if (seenHttpRoutes.has(key)) {
+        throwOke("HTTP_ROUTE_DUPLICATE", {
+          method: b.trigger.method,
+          path: b.trigger.path,
+          flow: b.flow.name || "(unnamed)",
+        });
+      }
+      seenHttpRoutes.add(key);
       smart.add(b.trigger.method, b.trigger.path, b);
       compiled.set(b, compileHttpBinding(b, aot));
     }
@@ -715,6 +814,16 @@ export function oke(options: OkeOptions): OkeApp {
     adopted.push(b);
     registerFlow(b.flow);
     if (b.trigger.kind === "http") {
+      assertHttpBindingReady(b);
+      const key = `${b.trigger.method} ${b.trigger.path}`;
+      if (seenHttpRoutes.has(key)) {
+        throwOke("HTTP_ROUTE_DUPLICATE", {
+          method: b.trigger.method,
+          path: b.trigger.path,
+          flow: b.flow.name || "(unnamed)",
+        });
+      }
+      seenHttpRoutes.add(key);
       smart.add(b.trigger.method, b.trigger.path, b);
       compiled.set(b, compileHttpBinding(b, aot));
     }
@@ -788,6 +897,11 @@ export function oke(options: OkeOptions): OkeApp {
     registerFlow(b.flow);
   }
 
+  if (registry !== "ignore") {
+    const generatedUnits = consumeRegisteredFlowUnits();
+    drainGeneratedUnits(generatedUnits, routes, registerFlow);
+  }
+
   // --- boot (vault → store → signal → clock → channel → AI → runs → caps) ---
   let bootResult: BootResult | undefined;
   let bootPromise: Promise<BootResult> | undefined;
@@ -963,7 +1077,7 @@ export function oke(options: OkeOptions): OkeApp {
       vault: withRequiredEnv(overrides?.vault ?? options.vault),
       gates: [...baseGates, ...authGates],
       signals: overrides?.signals ?? effectiveSignals,
-      clocks: overrides?.clocks ?? options.clocks,
+      clocks: overrides?.clocks ?? effectiveClocks,
       stores: overrides?.stores ?? effectiveStores,
       channel: overrides?.channel ?? effectiveChannel,
       ai: overrides?.ai ?? effectiveAi,
@@ -1019,7 +1133,7 @@ export function oke(options: OkeOptions): OkeApp {
 
     const baseSecrets = overrides?.secrets ?? effectiveSecrets;
     const baseSignals = overrides?.signals ?? effectiveSignals;
-    const baseClocks = overrides?.clocks ?? options.clocks ?? [];
+    const baseClocks = overrides?.clocks ?? effectiveClocks;
     const baseChannel = overrides?.channel ?? effectiveChannel;
     const mergedCatalog = mergeTemplateCatalogs(baseChannel?.catalog, ...pluginChannelCatalogs);
 
@@ -1065,6 +1179,10 @@ export function oke(options: OkeOptions): OkeApp {
     };
     const result = await bootApplication(merged);
     bootResult = result;
+    if (gateConfig.auth?.apiKeyStore && result.store) {
+      const { bindHostApiKeySqlFromStore } = await import("../auth/api-key-sql.ts");
+      await bindHostApiKeySqlFromStore(result.store, gateConfig.auth.apiKeyStore);
+    }
     // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
@@ -1138,6 +1256,8 @@ export function oke(options: OkeOptions): OkeApp {
       readonly bypassGates?: boolean;
       /** Console Call API — cleartext store PII. Requires {@link trustedInvoke}. */
       readonly revealPii?: boolean;
+      /** Forced RLS bag (Console / Call API). Operator omit = no stamp. */
+      readonly rls?: import("../drivers/pg-rls.ts").RlsIdentity;
       /** Frozen origin identity for {@link Fx.principal} across `fx.call`. */
       readonly originPrincipal?: FxPrincipal;
       /** Explicit locale override for {@link Fx.t} / channel sends. */
@@ -1189,6 +1309,7 @@ export function oke(options: OkeOptions): OkeApp {
       readonly trustedInvoke?: boolean;
       readonly bypassGates?: boolean;
       readonly revealPii?: boolean;
+      readonly rls?: import("../drivers/pg-rls.ts").RlsIdentity;
       readonly originPrincipal?: FxPrincipal;
       readonly locale?: string;
       readonly parentId?: string;
@@ -1251,6 +1372,7 @@ export function oke(options: OkeOptions): OkeApp {
           userId: options.fx?.auth?.userId ?? null,
           scopes: new Set(options.fx?.auth?.scopes ?? []),
           verified: options.fx?.auth?.verified,
+          apiKeyId: options.fx?.auth?.apiKeyId,
         },
         operator: { id: options.fx?.operator?.id ?? null },
       };
@@ -1279,7 +1401,8 @@ export function oke(options: OkeOptions): OkeApp {
           : {}),
         verifyBearer:
           binding && wiredAuth
-            ? async (token) => wiredAuth.verifyBearerOrApiKey(binding, token, apiKeyStore)
+            ? (token, request) =>
+                wiredAuth.verifyBearerOrApiKey(binding, token, apiKeyStore, request)
             : undefined,
         // Phase 1a: opt-in cookie → Bearer when Authorization is absent.
         resolveToken:
@@ -1336,9 +1459,13 @@ export function oke(options: OkeOptions): OkeApp {
         catalogs: loadMessages().getMessageCatalogs(),
         ...options.fx?.i18n,
       },
-      ...(principals ? { auth: principals.auth as FxAuth, operator: principals.operator } : {}),
+      ...(principals ? { auth: principals.auth, operator: principals.operator } : {}),
+      apiKeyStore: gateConfig.auth?.apiKeyStore,
       ...(extras?.originPrincipal ? { principal: extras.originPrincipal } : {}),
       ...(extras?.trustedInvoke === true && extras.revealPii === true ? { revealPii: true } : {}),
+      rlsGateNames: gateNamesOf(trigger),
+      rlsBypass: extras?.bypassGates === true || flowDef.plane === "operator",
+      ...(extras?.rls ? { rls: extras.rls } : {}),
       ...(capability ? { capability } : {}),
       ...(booted
         ? {
@@ -1487,6 +1614,7 @@ export function oke(options: OkeOptions): OkeApp {
           }
           return await invoke(ctx.input);
         } catch (err) {
+          if (isFlowFailure(err)) return err;
           // A durable sleep that has not yet elapsed suspends the run — this
           // is a park, not a pipeline failure, so it must not throw upward.
           if (flowDef.durable && journalSession && isJournalSuspend(err)) {
@@ -1663,6 +1791,7 @@ export function oke(options: OkeOptions): OkeApp {
     get authBinding() {
       return authBinding;
     },
+    apiKeys: gateConfig.auth?.apiKeyStore,
     async resumeDurable(now) {
       const t = now ?? bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
       const { store, instanceId, leaseMs } = activeJournal();

package/src/kernel/auth-resolve.ts

@@ -6,7 +6,7 @@
  * separately in the pipeline (`allowTestPrincipals`).
  */
 
-import { authenticateApiKey, type ApiKeyStore } from "../auth/api-keys.ts";
+import { authenticateApiKey, clientIpFromRequest, type ApiKeyStore } from "../auth/api-keys.ts";
 import type { ApiKeyRow } from "../auth/tables.ts";
 import {
   createSessionStore,
@@ -89,7 +89,9 @@ export function claimsToPrincipal(claims: AccessClaims): ResolvedPrincipal {
 
 /**
  * Map an authenticated API key row to the pipeline principal shape.
- * Uses the bare key id so Access `runTouchesKey` matches `WideEvent.principal`.
+ *
+ * The key is the issuer with fewer gates: `userId` / `operatorId` is
+ * {@link ApiKeyRow.creatorId}. The credential id is {@link ResolvedPrincipal.apiKeyId}.
  *
  * @param row - Authenticated key
  */
@@ -97,7 +99,7 @@ export function apiKeyRowToPrincipal(row: ApiKeyRow): ResolvedPrincipal {
   if (row.plane === "operator") {
     return {
       plane: "operator",
-      operatorId: row.id,
+      operatorId: row.creatorId,
       userId: null,
       scopes: row.scopes,
       verified: true,
@@ -106,7 +108,7 @@ export function apiKeyRowToPrincipal(row: ApiKeyRow): ResolvedPrincipal {
   }
   return {
     plane: "user",
-    userId: row.id,
+    userId: row.creatorId,
     scopes: row.scopes,
     verified: true,
     apiKeyId: row.id,
@@ -119,17 +121,20 @@ export function apiKeyRowToPrincipal(row: ApiKeyRow): ResolvedPrincipal {
  * @param auth - Session binding
  * @param token - Raw Bearer token
  * @param apiKeys - Optional key store
+ * @param request - Incoming request (allowlist IP is read here, not in `oke()`)
  */
 export async function verifyBearerOrApiKey(
   auth: AppAuthBinding,
   token: string,
   apiKeys?: ApiKeyStore,
+  request?: Request,
 ): Promise<ResolvedPrincipal> {
   try {
     return await verifyBearerToken(auth, token);
   } catch (err) {
     if (apiKeys) {
-      const row = await authenticateApiKey(apiKeys, token, auth.now);
+      const ip = request ? clientIpFromRequest(request) : undefined;
+      const row = await authenticateApiKey(apiKeys, token, { now: auth.now, ip });
       if (row) return apiKeyRowToPrincipal(row);
     }
     throw err;