okengine 0.16.0 → 0.17.1

package/src/kernel/errors.registry.test.ts

@@ -6,11 +6,23 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { OKE_ERRORS, OkeError, type OkeErrorDefinition } from "./errors.ts";
+import { OKE_ERRORS, OkeError, lookupOkeError, type OkeErrorDefinition } from "./errors.ts";
+import { LIVE_RESUME_GAP } from "./errors-live-resume.ts";
+import { TENANT_NOT_MEMBER, TENANT_REQUIRED, TENANT_UNKNOWN_SCOPE } from "./errors-tenant.ts";
+
+const LAZY_DEFS: readonly OkeErrorDefinition[] = [
+  LIVE_RESUME_GAP,
+  TENANT_REQUIRED,
+  TENANT_NOT_MEMBER,
+  TENANT_UNKNOWN_SCOPE,
+];
 
 describe("OKE error-code registry", () => {
   test("every code is unique", () => {
-    const codes = Object.values(OKE_ERRORS).map((d) => d.code);
+    const codes = [
+      ...Object.values(OKE_ERRORS).map((d) => d.code),
+      ...LAZY_DEFS.map((d) => d.code),
+    ];
     expect(new Set(codes).size).toBe(codes.length);
   });
 
@@ -21,10 +33,16 @@ describe("OKE error-code registry", () => {
       expect(Number.isInteger(def.code), `${key}.code`).toBe(true);
       expect(def.code, `${key}.code`).toBeGreaterThan(0);
     }
+    expect(LIVE_RESUME_GAP.cause.trim().length).toBeGreaterThan(0);
+    expect(LIVE_RESUME_GAP.fix.trim().length).toBeGreaterThan(0);
+    for (const def of LAZY_DEFS) {
+      expect(def.cause.trim().length, `${def.code}.cause`).toBeGreaterThan(0);
+      expect(def.fix.trim().length, `${def.code}.fix`).toBeGreaterThan(0);
+    }
   });
 
   test("OkeError docsUrl matches docs origin /e/{code}", () => {
-    for (const def of Object.values(OKE_ERRORS) as OkeErrorDefinition[]) {
+    for (const def of [...Object.values(OKE_ERRORS), ...LAZY_DEFS] as OkeErrorDefinition[]) {
       const err = new OkeError(def);
       expect(err.docsUrl).toBe(`https://oke.omqkhafi.dev/e/${def.code}`);
       expect(err.message).toContain(err.docsUrl);
@@ -32,4 +50,14 @@ describe("OKE error-code registry", () => {
       expect(err.message).toContain("→");
     }
   });
+
+  test("lookupOkeError finds the lazy LIVE_RESUME_GAP entry", () => {
+    expect(lookupOkeError(1014)).toEqual(LIVE_RESUME_GAP);
+  });
+
+  test("lookupOkeError finds lazy tenant entries", () => {
+    expect(lookupOkeError(1015)).toEqual(TENANT_REQUIRED);
+    expect(lookupOkeError(1016)).toEqual(TENANT_NOT_MEMBER);
+    expect(lookupOkeError(1017)).toEqual(TENANT_UNKNOWN_SCOPE);
+  });
 });

package/src/kernel/errors.ts

@@ -207,6 +207,15 @@ export const OKE_ERRORS = {
     cause: "An HTTP flow on {method} {path} has no name.",
     fix: 'Use `flow("unit.export", {…})` or export it from a `src/flows/<unit>/` file so the tree can stamp `unit.export`.',
   },
+  /**
+   * Two live HTTP exposures of the same signal share gates + match shape.
+   */
+  LIVE_EXPOSURE_DUPLICATE: {
+    code: 1013,
+    cause:
+      'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
+    fix: "Use a different gate or path-param filter, or drop the extra route.",
+  },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.
@@ -233,15 +242,37 @@ export const OKE_ERRORS = {
   },
 } as const satisfies Record<string, OkeErrorDefinition>;
 
+/** Tenant error keys — definitions live in the lazy `errors-tenant` chunk. */
+export type TenantOkeErrorKey = "TENANT_REQUIRED" | "TENANT_NOT_MEMBER" | "TENANT_UNKNOWN_SCOPE";
+
+type TenantErrorChunk = {
+  readonly TENANT_REQUIRED: OkeErrorDefinition;
+  readonly TENANT_NOT_MEMBER: OkeErrorDefinition;
+  readonly TENANT_UNKNOWN_SCOPE: OkeErrorDefinition;
+};
+
+/**
+ * Load OKE1015–1017. Computed stem so Bun.build cannot inline the chunk.
+ */
+function loadTenantErrors(): TenantErrorChunk {
+  return lazyRequire(import.meta.dir, ["errors", "tenant"].join("-"));
+}
+
 /**
  * Build and throw a registered framework error.
  *
- * @param key - Key into {@link OKE_ERRORS}
+ * @param key - Key into {@link OKE_ERRORS} or a lazy tenant code
  * @param params - Interpolation params
  * @returns Never
  */
-export function throwOke(key: keyof typeof OKE_ERRORS, params: OkeErrorParams = {}): never {
-  throw new OkeError(OKE_ERRORS[key], params);
+export function throwOke(
+  key: keyof typeof OKE_ERRORS | TenantOkeErrorKey,
+  params: OkeErrorParams = {},
+): never {
+  if (typeof key === "string" && key.startsWith("TENANT_")) {
+    throw new OkeError(loadTenantErrors()[key as TenantOkeErrorKey], params);
+  }
+  throw new OkeError(OKE_ERRORS[key as keyof typeof OKE_ERRORS], params);
 }
 
 /**
@@ -250,6 +281,15 @@ export function throwOke(key: keyof typeof OKE_ERRORS, params: OkeErrorParams =
  * @param code - Permanent numeric code
  */
 export function lookupOkeError(code: OkeErrorCode): OkeErrorDefinition | undefined {
+  if (code === 1014) {
+    return lazyRequire<typeof import("./errors-live-resume.ts")>(
+      import.meta.dir,
+      ["errors", "live", "resume"].join("-"),
+    ).LIVE_RESUME_GAP;
+  }
+  if (code === 1015) return loadTenantErrors().TENANT_REQUIRED;
+  if (code === 1016) return loadTenantErrors().TENANT_NOT_MEMBER;
+  if (code === 1017) return loadTenantErrors().TENANT_UNKNOWN_SCOPE;
   for (const def of Object.values(OKE_ERRORS)) {
     if (def.code === code) return def;
   }

package/src/kernel/flow.ts

@@ -48,13 +48,15 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
   readonly effects?: Effects;
   /** Journal every effect call. */
   readonly durable?: boolean;
+  /**
+   * Retry the whole `do` body on thrown errors (same journal session when
+   * durable). Prefer {@link Fx.retry} inside {@link Fx.step} for fine control.
+   */
   /**
    * Retry the whole `do` body on thrown errors (same journal session when
    * durable). Prefer {@link Fx.retry} inside {@link Fx.step} for fine control.
    */
   readonly retry?: FxRetryOptions;
-  /** Live-query / push result. */
-  readonly live?: boolean;
   /**
    * Cache policy. Read-only flows cache automatically from inferred
    * effects (`true` / omitted). `false` opts out; a duration string
@@ -89,6 +91,11 @@ export interface FlowOptions<I = unknown, O = unknown, E extends FlowErrorMap =
     },
     fx: import("./fx.ts").Fx,
   ) => unknown | Promise<unknown>;
+  /**
+   * When `false`, skip tenant-role scope union even if `fx.tenant.id` is set.
+   * Default `true` when `gate.auth.tenant` is on.
+   */
+  readonly tenantScoped?: boolean;
   /** The behavior. */
   readonly do: FlowHandler<I, O>;
 }
@@ -171,8 +178,15 @@ export interface FlowDef<
   readonly durable: boolean;
   /** Whole-body retry policy (runtime). */
   readonly retry: FxRetryOptions | undefined;
-  /** Live flag. */
-  readonly live: boolean;
+  /**
+   * Live signal name when this HTTP flow streams {@link SignalDecl} SSE.
+   */
+  readonly live: string | undefined;
+  /**
+   * True when `.live(signal)` is bound to a custom `do` (not synthesized).
+   * Boot uniqueness uses `custom:{flowName}` instead of path-param match.
+   */
+  readonly liveCustomMatch: boolean;
   /** Cache option. */
   readonly cache: boolean | string | undefined;
   /** SLO. */
@@ -181,6 +195,11 @@ export interface FlowDef<
   readonly plane: FlowPlane | undefined;
   /** Intentional contract-break acknowledgement for Manifest Diff. */
   readonly breaking: boolean;
+  /**
+   * When `false`, this flow is tenant-unaware (no tenant-role scope union).
+   * Default `true` when `gate.auth.tenant` is on.
+   */
+  readonly tenantScoped: boolean | undefined;
   /**
    * Optional compensation phase after terminal durable failure.
    * See {@link FlowOptions.compensate}.
@@ -284,11 +303,13 @@ export function flow(
     effects: options.effects,
     durable: options.durable ?? false,
     retry: options.retry,
-    live: options.live ?? false,
+    live: undefined,
+    liveCustomMatch: false,
     cache: options.cache,
     slo: options.slo,
     plane: options.plane,
     breaking: options.breaking ?? false,
+    tenantScoped: options.tenantScoped,
     compensate: options.compensate as FlowDef["compensate"],
     do: options.do as FlowHandler,
     triggers,

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

@@ -26,8 +26,13 @@ import { fail, type FlowFailure } from "./errors.ts";
 export interface FxAuthIdentity {
   /** User-plane subject id, or null when unauthenticated. */
   readonly userId: string | null;
-  /** Granted scopes for the live principal. */
+  /** Granted scopes for the live principal (may include tenant-role union). */
   readonly scopes: ReadonlySet<string>;
+  /**
+   * Session / JWT scopes before tenant-role union.
+   * `switchTenant` mints from this set so tenant grants never melt into the token.
+   */
+  readonly sessionScopes?: 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. */

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

@@ -0,0 +1,87 @@
+/**
+ * Session-only tenant methods — switchTenant mints a new family; listTenants refuses keys.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createSessionStore, issueSession, verifyAccess } from "../auth/sessions.ts";
+import { createTenant, createTenantStore } from "../auth/tenants.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { createFx } from "./fx.ts";
+
+const SECRET = "tenant-methods-test-secret";
+
+describe("fx.auth tenant methods", () => {
+  test("listTenants is session-only", async () => {
+    const store = createTenantStore();
+    await createTenant(store, { name: "Acme", createdBy: "u1", id: "t1" });
+    const asKey = createFx({
+      flow: "tenants.list",
+      effects: { reads: ["auth:tenants"] },
+      tenantStore: store,
+      tenantEnabled: true,
+      auth: { userId: "u1", scopes: new Set(), apiKeyId: "key_1" },
+    });
+    try {
+      await asKey.auth.listTenants();
+      throw new Error("expected Forbidden");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      if (isFlowFailure(err)) {
+        expect(err.error.code).toBe("Forbidden");
+        expect(err.error.data).toEqual({ gate: "auth:tenants", reason: "session_only" });
+      }
+    }
+
+    const asSession = createFx({
+      flow: "tenants.list.session",
+      effects: { reads: ["auth:tenants"] },
+      tenantStore: store,
+      tenantEnabled: true,
+      auth: { userId: "u1", scopes: new Set(), apiKeyId: null },
+    });
+    const listed = await asSession.auth.listTenants();
+    expect(listed.map((t) => t.id)).toEqual(["t1"]);
+  });
+
+  test("switchTenant issues a new family and copies tid without melting tenant scopes", async () => {
+    const tenantStore = createTenantStore();
+    await createTenant(tenantStore, { name: "Acme", createdBy: "u1", id: "t1" });
+    await createTenant(tenantStore, { name: "Globex", createdBy: "u1", id: "t2" });
+    const sessions = createSessionStore();
+    const crypto = { secret: SECRET };
+    const first = await issueSession(sessions, crypto, {
+      id: "u1",
+      plane: "user",
+      scopes: ["member"],
+      tenantId: "t1",
+    });
+
+    const liveScopes = new Set(["member", "booking:create"]);
+    const fx = createFx({
+      flow: "tenants.switch",
+      effects: { writes: ["auth:tenants"] },
+      tenantStore,
+      tenantEnabled: true,
+      sessions,
+      sessionCrypto: crypto,
+      auth: {
+        userId: "u1",
+        scopes: liveScopes,
+        sessionScopes: new Set(["member"]),
+        apiKeyId: null,
+      },
+    });
+    const switched = await fx.auth.switchTenant("t2");
+    expect(switched.session.familyId).not.toBe(first.session.familyId);
+    expect(switched.session.id).not.toBe(first.session.id);
+
+    const claims = await verifyAccess(sessions, SECRET, switched.accessToken);
+    expect(claims.tid).toBe("t2");
+    expect(claims.scopes).toEqual(["member"]);
+    expect(claims.sid).toBe(switched.session.id);
+
+    const firstStill = await verifyAccess(sessions, SECRET, first.accessToken);
+    expect(firstStill.tid).toBe("t1");
+    expect(firstStill.sid).toBe(first.session.id);
+  });
+});

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,
+  });
+}