okengine 0.15.2 → 0.17.0

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

@@ -0,0 +1,286 @@
+/**
+ * `fx.auth` tenant methods — session-only, lazy-attached like API keys.
+ */
+
+import {
+  AUTH_TENANTS_RESOURCE,
+  addMember,
+  createTenant,
+  deleteTenant,
+  isMember,
+  listMembers,
+  listTenantsForUser,
+  removeMember,
+  TenantError,
+  upsertTenantRole,
+  type TenantMemberRow,
+  type TenantPublicRow,
+  type TenantRoleRow,
+  type TenantRow,
+  type TenantStore,
+} from "../auth/tenants.ts";
+import {
+  issueSession,
+  type IssuedSession,
+  type SessionCrypto,
+  type SessionStore,
+} from "../auth/sessions.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { deriveModuleActions } from "../elements/gate/permissions.ts";
+import type { EffectKind } from "./effects.ts";
+import { fail, type FlowFailure } from "./errors.ts";
+import type { FxAuthIdentity } from "./fx-auth-keys.ts";
+
+/** Options for {@link FxAuth.createTenant}. */
+export interface FxCreateTenantInput {
+  readonly name: string;
+  readonly slug?: string | null;
+  readonly id?: string;
+}
+
+/** Options for {@link FxAuth.addMember}. */
+export interface FxAddMemberInput {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly role?: string;
+}
+
+/** Options for {@link FxAuth.upsertTenantRole}. */
+export interface FxUpsertTenantRoleInput {
+  readonly tenantId: string;
+  readonly roleName: string;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * Session-only tenant primitives attached onto {@link FxAuthIdentity}.
+ */
+export interface FxAuthTenantMethods {
+  listTenants(): Promise<readonly TenantPublicRow[]>;
+  switchTenant(id: string): Promise<IssuedSession>;
+  createTenant(input: FxCreateTenantInput): Promise<TenantRow>;
+  deleteTenant(id: string): Promise<TenantRow>;
+  addMember(input: FxAddMemberInput): Promise<TenantMemberRow>;
+  removeMember(tenantId: string, userId: string): Promise<TenantMemberRow>;
+  listMembers(tenantId: string): Promise<readonly TenantMemberRow[]>;
+  upsertTenantRole(input: FxUpsertTenantRoleInput): Promise<TenantRoleRow>;
+}
+
+/** Dependencies for {@link attachTenantMethods}. */
+export interface AttachAuthTenantMethodsOptions {
+  readonly auth: FxAuthIdentity;
+  readonly store: TenantStore | undefined;
+  readonly sessions: SessionStore | undefined;
+  readonly crypto: SessionCrypto | undefined;
+  readonly manifest: Manifest | 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_TENANTS_RESOURCE, reason: "session_only" });
+  }
+  if (!auth.userId) {
+    return fail("Unauthorized", {});
+  }
+  return null;
+}
+
+function requireStore(store: TenantStore | undefined): TenantStore {
+  if (!store) {
+    throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "no_store" });
+  }
+  return store;
+}
+
+function mapTenantError(err: unknown): never {
+  if (err instanceof TenantError) {
+    throw fail("Forbidden", {
+      gate: AUTH_TENANTS_RESOURCE,
+      reason: err.reason,
+      ...(err.scope !== undefined ? { scope: err.scope } : {}),
+    });
+  }
+  throw err;
+}
+
+/**
+ * Attach tenant primitives onto a live identity bag.
+ *
+ * @param options - Auth bag + tenant store + session crypto
+ */
+export function attach(
+  options: AttachAuthTenantMethodsOptions,
+): FxAuthIdentity & FxAuthTenantMethods {
+  const { auth, now, gated } = options;
+
+  const methods: FxAuthTenantMethods = {
+    listTenants() {
+      return gated("read", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        return listTenantsForUser(store, auth.userId!);
+      });
+    },
+    switchTenant(id) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, id, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        const sessions = options.sessions;
+        const crypto = options.crypto;
+        if (!sessions || !crypto) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "no_sessions" });
+        }
+        // New family — tab A rotation cannot reuse-detect tab B.
+        // Mint from session scopes, never the live tenant-unioned set.
+        const minted = auth.sessionScopes ?? auth.scopes;
+        return issueSession(sessions, crypto, {
+          id: auth.userId!,
+          plane: "user",
+          scopes: [...minted],
+          tenantId: id,
+        });
+      });
+    },
+    createTenant(input) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        try {
+          return await createTenant(store, {
+            name: input.name,
+            createdBy: auth.userId!,
+            ...(input.slug !== undefined ? { slug: input.slug } : {}),
+            ...(input.id !== undefined ? { id: input.id } : {}),
+            now,
+          });
+        } catch (err) {
+          mapTenantError(err);
+        }
+      });
+    },
+    deleteTenant(id) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, id, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        const row = await deleteTenant(store, id);
+        if (!row) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "unknown_tenant" });
+        }
+        return row;
+      });
+    },
+    addMember(input) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, input.tenantId, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        try {
+          return addMember(store, {
+            tenantId: input.tenantId,
+            userId: input.userId,
+            ...(input.role !== undefined ? { role: input.role } : {}),
+            now,
+          });
+        } catch (err) {
+          mapTenantError(err);
+        }
+      });
+    },
+    removeMember(tenantId, userId) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, tenantId, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        const row = removeMember(store, tenantId, userId);
+        if (!row) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        return row;
+      });
+    },
+    listMembers(tenantId) {
+      return gated("read", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, tenantId, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        return listMembers(store, tenantId);
+      });
+    },
+    upsertTenantRole(input) {
+      return gated("write", AUTH_TENANTS_RESOURCE, async () => {
+        const denied = sessionOnly(auth);
+        if (denied) throw denied;
+        const store = requireStore(options.store);
+        if (!isMember(store, input.tenantId, auth.userId!)) {
+          throw fail("Forbidden", { gate: AUTH_TENANTS_RESOURCE, reason: "not_member" });
+        }
+        const catalog = options.manifest ? deriveModuleActions(options.manifest) : [];
+        try {
+          return upsertTenantRole(store, {
+            tenantId: input.tenantId,
+            roleName: input.roleName,
+            scopes: input.scopes,
+            catalog,
+            now,
+          });
+        } catch (err) {
+          mapTenantError(err);
+        }
+      });
+    },
+  };
+
+  return Object.assign(auth, methods);
+}
+
+/**
+ * Compact attach from `createFx` so Store-only graphs do not spell the
+ * tenant store / session crypto field names.
+ *
+ * @param auth - Identity after API-key methods
+ * @param options - createFx options bag
+ * @param now - Clock
+ * @param gated - Capability gate
+ */
+export function bind(
+  auth: FxAuthIdentity,
+  options: {
+    readonly tenantStore?: TenantStore;
+    readonly sessions?: SessionStore;
+    readonly sessionCrypto?: SessionCrypto;
+    readonly manifest?: Manifest;
+  },
+  now: () => number,
+  gated: AttachAuthTenantMethodsOptions["gated"],
+): FxAuthIdentity & FxAuthTenantMethods {
+  return attach({
+    auth,
+    store: options.tenantStore,
+    sessions: options.sessions,
+    crypto: options.sessionCrypto,
+    manifest: options.manifest ?? undefined,
+    now,
+    gated,
+  });
+}

package/src/kernel/fx-live-stream.ts

@@ -0,0 +1,149 @@
+/**
+ * `fx.live` SSE + Last-Event-ID resume — lazy so Store-only `oke()` graphs
+ * do not pin `checkLiveResume` / 410 encoding.
+ *
+ * Do not import `fx.ts` (type or value): that cycle pulls `createFx` into
+ * this chunk the same way a static `fx-auth-keys` import would.
+ */
+
+import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
+import { isDryRun } from "./dry-run.ts";
+import type { EffectKind } from "./effects.ts";
+
+const jsonResultBrand = Symbol.for("oke.json");
+const sseFrameBrand = Symbol.for("oke.sse.frame");
+
+function sseFrame(data: unknown, id?: string): unknown {
+  return id !== undefined ? { [sseFrameBrand]: true, data, id } : { [sseFrameBrand]: true, data };
+}
+
+/** Minimal bus surface used by {@link createLiveStream}. */
+export interface LiveStreamRuntime {
+  live(
+    name: string,
+    opts?: { readonly afterId?: string },
+  ): AsyncIterable<{ readonly id: string; readonly payload: unknown }>;
+  checkLiveResume(name: string, afterId: string): Promise<void>;
+}
+
+/** Capability gate used by {@link createLiveStream}. */
+export type LiveStreamGate = <T>(
+  kind: EffectKind,
+  resource: string,
+  body: () => T | Promise<T>,
+) => Promise<T>;
+
+/** Options for {@link createLiveStream}. */
+export interface CreateLiveStreamOptions {
+  readonly name: string;
+  readonly afterId?: string;
+  readonly match?: (payload: unknown) => boolean;
+  readonly gated: LiveStreamGate;
+  readonly signalRuntime: LiveStreamRuntime | undefined;
+}
+
+/**
+ * SSE carrier from {@link createLiveStream}.
+ *
+ * Runtime brand is `Symbol.for("oke.json")` — same as `fx.json.stream`.
+ * Callers in `fx.ts` assert this onto `JsonStreamResult`.
+ */
+export interface LiveStreamResult {
+  readonly kind: "stream";
+  readonly status: 200;
+  readonly chunks: AsyncIterable<unknown>;
+  ready?: () => Promise<void>;
+  finalize?: () => Promise<void>;
+}
+
+/**
+ * Build the SSE carrier for `fx.live`.
+ *
+ * @param options - Signal name, cursor, gate, runtime
+ */
+export function createLiveStream(options: CreateLiveStreamOptions): LiveStreamResult {
+  const { name, afterId, match, gated, signalRuntime } = options;
+  const bind = async (): Promise<boolean> => {
+    await gated("read", `signal:${name}`, async () => undefined);
+    if (isDryRun()) return false;
+    if (!signalRuntime) throw new Error("fx.live requires a bound signal runtime");
+    return true;
+  };
+  const chunks = (async function* () {
+    if (!(await bind())) return;
+    const ambient = currentAbortSignal();
+    const local = new AbortController();
+    const unlink = linkAbort(ambient, local);
+    const iter = signalRuntime!.live(name, { afterId })[Symbol.asyncIterator]();
+    const onAbort = (): void => {
+      void iter.return?.();
+    };
+    local.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      for (;;) {
+        if (local.signal.aborted) break;
+        const step = await iter.next();
+        if (step.done || local.signal.aborted) break;
+        if (match && !match(step.value.payload)) continue;
+        yield sseFrame(step.value.payload, step.value.id);
+      }
+    } finally {
+      local.signal.removeEventListener("abort", onAbort);
+      unlink();
+      await iter.return?.();
+      if (!local.signal.aborted) local.abort();
+    }
+  })();
+  const carrier: LiveStreamResult = {
+    kind: "stream",
+    status: 200,
+    chunks,
+    ready: async () => {
+      if (afterId && (await bind())) await signalRuntime!.checkLiveResume(name, afterId);
+    },
+  };
+  // Brand at runtime (`isJsonStreamResult`); not on {@link LiveStreamResult}
+  // so this file does not import `fx.ts` unique-symbol types (cycle / TS2353).
+  return Object.assign(carrier, { [jsonResultBrand]: true });
+}
+
+/**
+ * Map OKE1014 to HTTP 410 `{ error: { code: "LiveResumeGap" } }`.
+ *
+ * @param err - Thrown value
+ */
+export function encodeGap(err: unknown): Response | undefined {
+  const o = err as { code?: unknown; params?: { signal?: string; afterId?: string } };
+  if (o?.code !== 1014) return;
+  return Response.json(
+    {
+      data: null,
+      error: {
+        code: "LiveResumeGap",
+        data: { signal: o.params?.signal ?? "", afterId: o.params?.afterId ?? "" },
+      },
+    },
+    { status: 410 },
+  );
+}
+
+/**
+ * Await stream `ready` before the 200 SSE body.
+ *
+ * @param stream - Live / json.stream carrier
+ * @returns 410 response when the cursor is missing; otherwise `undefined`
+ */
+export async function awaitLiveReady(stream: {
+  readonly ready?: () => Promise<void>;
+  readonly finalize?: () => Promise<void>;
+}): Promise<Response | undefined> {
+  try {
+    await stream.ready?.();
+  } catch (err) {
+    await stream.finalize?.();
+    const gap = encodeGap(err);
+    if (gap) return gap;
+    throw err;
+  }
+  return undefined;
+}

package/src/kernel/fx-live.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+import { encodeExecuteResult } from "../compiler/response.ts";
+import { memorySignalDriver } from "../drivers/index.ts";
+import { createSignalRuntime, signal, type SignalDecl } from "../elements/signal.ts";
+import { withAbortSignal } from "./abort-scope.ts";
+import { OkeError } from "./errors.ts";
+import { createFx, createFxContext, isSseFrame, signalReadRef } from "./fx.ts";
+
+describe("fx.live", () => {
+  test("undeclared signal read throws OKE1001", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const other = signal("other-status", { delivery: "live", optional: true });
+    let err: unknown;
+    try {
+      const stream = fx.live(other);
+      await stream.chunks[Symbol.asyncIterator]().next();
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(OkeError);
+    const oke = err as OkeError;
+    expect(oke.code).toBe(1001);
+    expect(oke.causeText).toBe(
+      'Flow "orders.events" reads "signal:other-status" without declaring it.',
+    );
+    await runtime.close();
+  });
+
+  test("throws when no signal runtime is bound", async () => {
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+    });
+    const stream = fx.live("order-status");
+    await expect(stream.chunks[Symbol.asyncIterator]().next()).rejects.toThrow(
+      "fx.live requires a bound signal runtime",
+    );
+  });
+
+  test("ALS abort unsubscribes the live handler", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    const { fx } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+
+    const ctrl = new AbortController();
+    await withAbortSignal(ctrl.signal, async () => {
+      const stream = fx.live(orderStatus);
+      const it = stream.chunks[Symbol.asyncIterator]();
+      const pending = it.next();
+      const started = Date.now();
+      while ((await bus.inspect("order-status"))[0]?.connections !== 1) {
+        if (Date.now() - started > 500) throw new Error("live handler did not attach");
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      ctrl.abort();
+      const step = await pending;
+      expect(step.done).toBe(true);
+    });
+
+    const after = await bus.inspect("order-status");
+    expect(after[0]?.connections).toBe(0);
+    await runtime.close();
+  });
+
+  test("yields branded SSE frames with id + payload", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    await runtime.emit("order-status", { orderId: "ord_1", status: "placed" });
+    await bus.drain();
+
+    const { fx, ledger } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus);
+    const it = stream.chunks[Symbol.asyncIterator]();
+    const step = await it.next();
+    expect(step.done).toBe(false);
+    expect(isSseFrame(step.value)).toBe(true);
+    if (isSseFrame(step.value)) {
+      expect(step.value.data).toEqual({ orderId: "ord_1", status: "placed" });
+      expect(typeof step.value.id).toBe("string");
+    }
+    expect(ledger.entries.map((e) => `${e.kind}:${e.resource}`)).toEqual([
+      "read:signal:order-status",
+    ]);
+    await it.return?.();
+    await runtime.close();
+  });
+
+  test("afterId skips already-delivered events", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const bus = await runtime.start();
+    await runtime.emit("order-status", { orderId: "ord_1", status: "placed" });
+    await runtime.emit("order-status", { orderId: "ord_1", status: "shipped" });
+    await bus.drain();
+
+    const first = bus.live("order-status")[Symbol.asyncIterator]();
+    const a = await first.next();
+    await first.return?.();
+    const firstId = a.value?.id as string;
+
+    const { fx } = createFxContext({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus, { afterId: firstId });
+    const it = stream.chunks[Symbol.asyncIterator]();
+    const step = await it.next();
+    expect(isSseFrame(step.value) && step.value.data).toEqual({
+      orderId: "ord_1",
+      status: "shipped",
+    });
+    await it.return?.();
+    await runtime.close();
+  });
+
+  test("ready throws OKE1014 for a missing afterId", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const runtime = openRuntime(orderStatus);
+    const fx = createFx({
+      flow: "orders.events",
+      effects: { reads: [signalReadRef("order-status")] },
+      signalRuntime: runtime,
+    });
+    const stream = fx.live(orderStatus, { afterId: "missing" });
+    await expect(stream.ready?.()).rejects.toMatchObject({ code: 1014 });
+    const res = await encodeExecuteResult({ output: stream });
+    expect(res.status).toBe(410);
+    expect(await res.json()).toMatchObject({
+      data: null,
+      error: { code: "LiveResumeGap", data: { signal: "order-status", afterId: "missing" } },
+    });
+    await runtime.close();
+  });
+});
+
+function openRuntime(decl: SignalDecl) {
+  const runtime = createSignalRuntime({ driver: memorySignalDriver });
+  runtime.register(decl);
+  return runtime;
+}

package/src/kernel/fx-runtime.ts

@@ -0,0 +1,15 @@
+/**
+ * Execute-time `fx` helpers — lazy chunk off Store-only `oke()` construction.
+ *
+ * `app.ts` / HTTP encode load this via computed require so `createFx` does
+ * not sit on graphs that never run a Flow.
+ */
+
+export {
+  createFxContext,
+  freezePrincipal,
+  isJsonResult,
+  isJsonStreamResult,
+  isSseFrame,
+  resolveName,
+} from "./fx.ts";