okengine 0.14.1 → 0.16.0

package/src/kernel/fx-auth-keys.ts

@@ -0,0 +1,198 @@
+/**
+ * `fx.auth` key-management methods — session-only, attenuated, one store.
+ */
+
+import {
+  AUTH_API_KEYS_RESOURCE,
+  createApiKey,
+  getApiKey,
+  listApiKeys,
+  revokeApiKey,
+  rotateApiKey,
+  toApiKeyPublicRow,
+  updateApiKey,
+  type ApiKeyPublicRow,
+  type ApiKeyStore,
+  type CreatedApiKey,
+} from "../auth/api-keys.ts";
+import { parseDurationMs } from "../elements/clock/duration.ts";
+import type { EffectKind } from "./effects.ts";
+import { fail, type FlowFailure } from "./errors.ts";
+
+/**
+ * Identity bag on {@link FxAuth} before key-management methods attach.
+ * Passed into {@link createFx} / {@link attach}.
+ */
+export interface FxAuthIdentity {
+  /** User-plane subject id, or null when unauthenticated. */
+  readonly userId: string | null;
+  /** Granted scopes for the live principal. */
+  readonly scopes: ReadonlySet<string>;
+  /** Whether the identity has completed verification (email / MFA). */
+  readonly verified?: boolean;
+  /** Authenticating API key id when Bearer was a key secret; otherwise null. */
+  readonly apiKeyId?: string | null;
+}
+
+/** Options for {@link FxAuth.createApiKey}. */
+export interface FxCreateApiKeyInput {
+  readonly name: string;
+  readonly scopes: readonly string[];
+  readonly expiresIn?: string;
+  readonly ipAllowlist?: readonly string[];
+  readonly rateLimit?: { max: number; per: string } | null;
+}
+
+/** Options for {@link FxAuth.updateApiKey}. */
+export interface FxUpdateApiKeyInput {
+  readonly name?: string;
+  readonly scopes?: readonly string[];
+  readonly expiresIn?: string;
+  readonly ipAllowlist?: readonly string[];
+  readonly rateLimit?: { max: number; per: string } | null;
+}
+
+/** Create result for `fx.auth.createApiKey` / `rotateApiKey`. */
+export interface FxCreatedApiKey {
+  readonly key: ApiKeyPublicRow;
+  readonly secret: string;
+}
+
+/**
+ * Session-only key management attached onto {@link FxAuthIdentity}.
+ * Methods throw {@link FlowFailure} values (`Unauthorized` / `Forbidden`).
+ */
+export interface FxAuthKeyMethods {
+  createApiKey(input: FxCreateApiKeyInput): Promise<FxCreatedApiKey>;
+  listApiKeys(): Promise<readonly ApiKeyPublicRow[]>;
+  revokeApiKey(id: string): Promise<ApiKeyPublicRow>;
+  rotateApiKey(id: string): Promise<FxCreatedApiKey>;
+  updateApiKey(id: string, input: FxUpdateApiKeyInput): Promise<ApiKeyPublicRow>;
+}
+
+/** Dependencies for {@link attach}. */
+export interface AttachAuthKeyMethodsOptions {
+  readonly auth: FxAuthIdentity;
+  readonly store: ApiKeyStore | undefined;
+  readonly now: () => number;
+  readonly gated: <T>(kind: EffectKind, resource: string, body: () => T | Promise<T>) => Promise<T>;
+}
+
+function sessionOnly(auth: FxAuthIdentity): FlowFailure | null {
+  if (auth.apiKeyId) {
+    return fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "session_only" });
+  }
+  if (!auth.userId) {
+    return fail("Unauthorized", {});
+  }
+  return null;
+}
+
+function requireStore(store: ApiKeyStore | undefined): ApiKeyStore {
+  if (!store) {
+    throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "no_store" });
+  }
+  return store;
+}
+
+function requireOwned(
+  store: ApiKeyStore,
+  id: string,
+  userId: string,
+): ReturnType<typeof getApiKey> {
+  const row = getApiKey(store, id);
+  if (!row || row.creatorId !== userId) {
+    throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "not_owner" });
+  }
+  return row;
+}
+
+function expiresAtFrom(expiresIn: string | undefined, now: () => number): number | undefined {
+  if (expiresIn === undefined) return undefined;
+  return now() + parseDurationMs(expiresIn);
+}
+
+/**
+ * Attach create / list / revoke / rotate / update onto a live identity bag.
+ *
+ * @param options - Auth bag + store + capability gate
+ */
+export function attach(options: AttachAuthKeyMethodsOptions): FxAuthIdentity & FxAuthKeyMethods {
+  const { auth, now, gated } = options;
+
+  const methods: FxAuthKeyMethods = {
+    createApiKey(input) {
+      return gated("write", AUTH_API_KEYS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        const created: CreatedApiKey = await createApiKey(store, {
+          plane: "user",
+          name: input.name,
+          scopes: input.scopes,
+          creatorId: auth.userId!,
+          creatorScopes: auth.scopes,
+          expiresAt: expiresAtFrom(input.expiresIn, now) ?? null,
+          rateLimit: input.rateLimit ?? null,
+          ipAllowlist: input.ipAllowlist,
+          now,
+        });
+        return { key: toApiKeyPublicRow(created.row), secret: created.secret };
+      });
+    },
+    listApiKeys() {
+      return gated("read", AUTH_API_KEYS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        return listApiKeys(store, auth.userId!).map(toApiKeyPublicRow);
+      });
+    },
+    revokeApiKey(id) {
+      return gated("write", AUTH_API_KEYS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        requireOwned(store, id, auth.userId!);
+        const row = revokeApiKey(store, id, now);
+        if (!row) throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "not_owner" });
+        return toApiKeyPublicRow(row);
+      });
+    },
+    rotateApiKey(id) {
+      return gated("write", AUTH_API_KEYS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        requireOwned(store, id, auth.userId!);
+        const rotated = await rotateApiKey(store, id, { now });
+        if (!rotated)
+          throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "not_owner" });
+        return { key: toApiKeyPublicRow(rotated.row), secret: rotated.secret };
+      });
+    },
+    updateApiKey(id, input) {
+      return gated("write", AUTH_API_KEYS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        const existing = requireOwned(store, id, auth.userId!);
+        if (!existing)
+          throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "not_owner" });
+        const ceiling = new Set([...existing.creatorScopes].filter((s) => auth.scopes.has(s)));
+        const row = updateApiKey(store, id, {
+          ceiling,
+          name: input.name,
+          scopes: input.scopes,
+          expiresAt: expiresAtFrom(input.expiresIn, now),
+          rateLimit: input.rateLimit,
+          ipAllowlist: input.ipAllowlist,
+        });
+        if (!row) throw fail("Forbidden", { gate: AUTH_API_KEYS_RESOURCE, reason: "not_owner" });
+        return toApiKeyPublicRow(row);
+      });
+    },
+  };
+
+  return Object.assign(auth, methods);
+}

package/src/kernel/fx.test.ts

@@ -432,7 +432,23 @@ describe("fx — wholesale swap", () => {
       t: (key) => key,
       locale: "en",
       id: () => "fixed-id",
-      auth: { userId: "u1", scopes: new Set(["a"]) },
+      auth: {
+        userId: "u1",
+        scopes: new Set(["a"]),
+        createApiKey: async () => {
+          throw new Error("auth.createApiKey must not be used");
+        },
+        listApiKeys: async () => [],
+        revokeApiKey: async () => {
+          throw new Error("auth.revokeApiKey must not be used");
+        },
+        rotateApiKey: async () => {
+          throw new Error("auth.rotateApiKey must not be used");
+        },
+        updateApiKey: async () => {
+          throw new Error("auth.updateApiKey must not be used");
+        },
+      },
       operator: { id: null },
       principal: { userId: "u1", operatorId: null, scopes: new Set(["a"]) },
       tenant: { id: "t1" },

package/src/kernel/fx.ts

@@ -20,6 +20,7 @@ import type {
   IndexStoreFxHandle,
   KvStoreDecl,
   KvStoreFxHandle,
+  SelectFromBuilder,
   SelectOrderBuilder,
   SqlStoreDecl,
   StoreDecl,
@@ -27,6 +28,8 @@ import type {
   StoreRuntime,
   SqlStoreHandle,
 } from "../elements/store.ts";
+import { rlsIdentityFromAuth } from "../elements/store.ts";
+import type { RlsIdentity } from "../drivers/pg-rls.ts";
 import type { SqlRow } from "../drivers/types.ts";
 import type { SignalDecl, SignalRuntime } from "../elements/signal.ts";
 import type { DeadLetter, SignalEmitOptions } from "../drivers/signal-types.ts";
@@ -34,6 +37,8 @@ import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.t
 import type { ChannelRuntime } from "../elements/channel.ts";
 import type { AiRuntime } from "../elements/ai.ts";
 import { parseDurationMs } from "../elements/clock/duration.ts";
+import type { ApiKeyStore } from "../auth/api-keys.ts";
+import type { FxAuthIdentity, FxAuthKeyMethods } from "./fx-auth-keys.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
 import { createEffectLedger, recordEffect, reversibilityOf, type EffectLedger } from "./effects.ts";
 import { resolveDurationMs } from "./elapsed.ts";
@@ -74,6 +79,13 @@ async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
 /** Resource ref Flows declare to read the Runs store via {@link Fx.runs}. */
 export const RUNS_RESOURCE = "runs";
 
+/**
+ * Resource ref Flows declare for {@link Fx.auth} key management.
+ * Same string as `src/auth/api-keys.ts` — defined here so the HMAC / key-store
+ * module stays off the edge and Store-only graphs.
+ */
+export const AUTH_API_KEYS_RESOURCE = "auth:api-keys";
+
 /**
  * Capability ref for {@link Fx.deadLetters} — `signal:<name>`, never a store facet.
  *
@@ -101,13 +113,10 @@ export function resolveStoreRef(ref: NamedRef | { readonly ref: ResourceRef }):
   return ref.name as ResourceRef;
 }
 
+export type { FxAuthIdentity } from "./fx-auth-keys.ts";
+
 /** Auth principal on the user plane. */
-export interface FxAuth {
-  readonly userId: string | null;
-  readonly scopes: ReadonlySet<string>;
-  /** Whether the identity has completed verification (email / MFA). */
-  readonly verified?: boolean;
-}
+export interface FxAuth extends FxAuthIdentity, FxAuthKeyMethods {}
 
 /** Operator principal on the Console plane. */
 export interface FxOperator {
@@ -835,8 +844,10 @@ export interface CreateFxOptions {
   readonly capability?: CapabilityToken;
   /** Injectable clock for timestamps / `fx.clock.now`. */
   readonly now?: () => number;
-  /** Auth principal. */
-  readonly auth?: FxAuth;
+  /** Auth principal bag (key methods attach at create time). */
+  readonly auth?: FxAuthIdentity;
+  /** Shared API key store for {@link Fx.auth} key methods. */
+  readonly apiKeyStore?: ApiKeyStore;
   /** Operator principal. */
   readonly operator?: FxOperator;
   /**
@@ -911,6 +922,12 @@ export interface CreateFxOptions {
   readonly runId?: string;
   /** Reveal PII through the store runtime (requires `pii:reveal` upstream). */
   readonly revealPii?: boolean;
+  /** Trigger gate names for RLS (`oke.gate` = first policy/public). */
+  readonly rlsGateNames?: readonly string[];
+  /** Skip RLS stamp (Operator / `bypassGates` / operator-plane flows). */
+  readonly rlsBypass?: boolean;
+  /** Forced bag (Console / Call API). Wins over {@link rlsGateNames}. */
+  readonly rls?: import("../drivers/pg-rls.ts").RlsIdentity;
   /**
    * Active journal session when the flow is durable. Every `fx` call is
    * recorded; `step` / `sleep` replay from the journal on resume.
@@ -993,10 +1010,16 @@ export function createFxContext(options: CreateFxOptions): FxContext {
   }
   const cacheStore = new Map<string, unknown>();
 
-  const auth: FxAuth = options.auth ?? {
-    userId: null,
-    scopes: new Set(),
-  };
+  // Computed stem — a static import would pin HMAC / api-keys on every createFx.
+  const auth: FxAuth = lazyRequire<typeof import("./fx-auth-keys.ts")>(
+    import.meta.dir,
+    ["fx", "auth", "keys"].join("-"),
+  ).attach({
+    auth: options.auth ?? { userId: null, scopes: new Set() },
+    store: options.apiKeyStore,
+    now,
+    gated,
+  });
   const operator: FxOperator = options.operator ?? { id: null };
   const tenant: FxTenant = options.tenant ?? { id: null };
   const defaultLocale = options.i18n?.defaultLocale ?? "en";
@@ -1025,6 +1048,19 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     } satisfies FxPrincipal);
   const journal = options.journal;
 
+  function rlsInvokeContext(): { rls?: RlsIdentity } {
+    if (options.rlsBypass === true) return {};
+    if (options.rls) return { rls: options.rls };
+    const identity = rlsIdentityFromAuth({
+      userId: auth.userId,
+      scopes: auth.scopes,
+      gateNames: options.rlsGateNames ?? [],
+      bypass: false,
+      operator: false,
+    });
+    return identity ? { rls: identity } : {};
+  }
+
   async function gated<T>(
     kind: Parameters<CapabilityToken["assert"]>[0],
     resource: string,
@@ -1150,9 +1186,9 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       get driverId() {
         return cached?.driverId ?? "memory";
       },
-      select(columns?) {
+      select: ((columns?: unknown) => {
         return {
-          from(table) {
+          from(table: unknown) {
             const run = (plan: {
               where?: unknown;
               orders?: readonly unknown[];
@@ -1161,7 +1197,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             }): Promise<SqlRow[]> =>
               gatedTable("read", table, async () => {
                 const h = await ensure();
-                const from = h.select(columns).from(table);
+                const from = h.select(columns).from(table) as SelectFromBuilder;
                 const filtered = plan.where === undefined ? from : from.where(plan.where);
                 const ordered =
                   plan.orders === undefined ? filtered : filtered.orderBy(...plan.orders);
@@ -1185,7 +1221,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
             });
 
             return {
-              where(where) {
+              where(where: unknown) {
                 return {
                   ...tail({ where }),
                   orderBy: (...orders: readonly unknown[]) => tail({ where, orders }),
@@ -1198,13 +1234,16 @@ export function createFxContext(options: CreateFxOptions): FxContext {
               offset(n: number) {
                 return run({ offset: n });
               },
-              then(onfulfilled, onrejected) {
+              then(
+                onfulfilled: (value: SqlRow[]) => unknown,
+                onrejected?: (reason: unknown) => unknown,
+              ) {
                 return run({}).then(onfulfilled, onrejected);
               },
             };
           },
         };
-      },
+      }) as SqlStoreHandle["select"],
       insert(table) {
         return {
           values(row) {
@@ -1342,6 +1381,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           cache.handle = await runtime.open(decl, {
             effects: options.effects ?? {},
             revealPii: options.revealPii,
+            ...rlsInvokeContext(),
           });
         }
         return cache.handle;
@@ -1361,6 +1401,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           {
             effects: options.effects ?? {},
             revealPii: options.revealPii,
+            ...rlsInvokeContext(),
           },
           {
             gate: gated,

package/src/kernel/horizontal-child.ts

@@ -190,11 +190,11 @@ const charge = flow("horizontal.charge", {
 });
 
 const bindings: Binding[] = [
-  { trigger: http.get("/ping").gate.public, flow: ping as AnyFlowDef },
+  { trigger: http.get("/ping").public(), flow: ping as AnyFlowDef },
   { trigger: http.get("/rate").gate(rateGate), flow: rate as AnyFlowDef },
-  { trigger: http.post("/write").gate.public, flow: write as AnyFlowDef },
-  { trigger: http.post("/emit").gate.public, flow: emit as AnyFlowDef },
-  { trigger: http.post("/charge").gate.public, flow: charge as AnyFlowDef },
+  { trigger: http.post("/write").public(), flow: write as AnyFlowDef },
+  { trigger: http.post("/emit").public(), flow: emit as AnyFlowDef },
+  { trigger: http.post("/charge").public(), flow: charge as AnyFlowDef },
 ];
 
 const app = oke({

package/src/kernel/http-path-pending.ts

@@ -0,0 +1,20 @@
+/**
+ * Branded sentinel for `http.get()` with no path — never `"/"`.
+ * Lives in a leaf module so `oke()` can refuse leftovers without pulling
+ * the HTTP trigger constructors onto a Store-only graph.
+ */
+
+/** Unresolved path token. {@link stampHttpPath} replaces it from the file tree. */
+export const HTTP_PATH_PENDING = "__oke_http_path_pending__" as const;
+
+/** Type of {@link HTTP_PATH_PENDING}. */
+export type HttpPathPending = typeof HTTP_PATH_PENDING;
+
+/**
+ * True when an HTTP trigger still carries the unresolved path sentinel.
+ *
+ * @param path - Trigger path
+ */
+export function isPendingHttpPath(path: string): boolean {
+  return path === HTTP_PATH_PENDING;
+}

package/src/kernel/http-resource.ts

@@ -3,6 +3,7 @@
  * apps do not pay for the five-verb CRUD helper.
  */
 
+import { GATE_PUBLIC_NAME } from "../elements/gate/flatten.ts";
 import {
   createGateAttach,
   createHttpTrigger,
@@ -47,6 +48,9 @@ export function httpResource<P extends string>(
       { trigger: verb("DELETE", id, false), flow: ops.remove },
     ],
     gate: createGateAttach((next) => httpResource(path, ops, next, isLive), gates),
+    public() {
+      return httpResource(path, ops, [...gates, GATE_PUBLIC_NAME], isLive);
+    },
     live() {
       return httpResource(path, ops, gates, true);
     },

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

@@ -83,12 +83,12 @@ describe("fx.json.stream HTTP SSE", () => {
   test("encodes token chunks as SSE and leaves JSON flows buffered", async () => {
     const smart = ai.model("smart");
     on(
-      http.get("/chat").gate.public,
+      http.get("/chat").public(),
       flow("chat.stream", {
         do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
       }),
     );
-    on(http.get("/ping").gate.public, flow("ping", { do: () => ({ ok: true as const }) }));
+    on(http.get("/ping").public(), flow("ping", { do: () => ({ ok: true as const }) }));
 
     const app = oke({
       name: "http-stream",
@@ -111,7 +111,7 @@ describe("fx.json.stream HTTP SSE", () => {
     let providerAborted = false;
     const smart = ai.model("smart");
     on(
-      http.get("/slow").gate.public,
+      http.get("/slow").public(),
       flow("chat.slow", {
         do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "long" })),
       }),
@@ -139,7 +139,7 @@ describe("fx.json.stream HTTP SSE", () => {
     await runs.open();
     const smart = ai.model("smart");
     on(
-      http.get("/chat").gate.public,
+      http.get("/chat").public(),
       flow("chat.stream", {
         do: (_input, fx) => fx.json.stream(fx.stream(smart, { prompt: "hi" })),
       }),