okengine 0.15.2 → 0.17.0

package/src/kernel/budget.test.ts

@@ -1,6 +1,6 @@
 /**
  * Kernel edge profile budget — AGENTS.md / unified-theory §24.
- * Limit: < 15 kB gzipped (minified bundle).
+ * Limit: < 16 kB gzipped (minified bundle).
  */
 
 import { describe, expect, test } from "bun:test";

package/src/kernel/clock-durable.ts

@@ -0,0 +1,8 @@
+/**
+ * Durable runner — lazy chunk off Store-only `oke()` construction.
+ *
+ * `runDurable` statically imports `createFx`; keeping that edge off graphs
+ * that never run a durable Flow.
+ */
+
+export { runDurable } from "../elements/clock/durable.ts";

package/src/kernel/clock-per-tenant-name.ts

@@ -0,0 +1,5 @@
+/**
+ * Parse `{template}#{tenantId}` — lazy chunk off Store-only `oke()` graphs.
+ */
+
+export { parsePerTenantCronName } from "../elements/clock/declare.ts";

package/src/kernel/clock-reconcile.ts

@@ -0,0 +1,8 @@
+/**
+ * Clock per-tenant row hooks — lazy chunk.
+ *
+ * A static import from `app.ts` would pin Clock reconcile on every `oke()`
+ * graph, including Store-only apps that never enable `gate.auth.tenant`.
+ */
+
+export { orphanPerTenantCronRows, putPerTenantCronRows } from "../elements/clock/reconcile.ts";

package/src/kernel/errors-live-resume.ts

@@ -0,0 +1,15 @@
+/**
+ * OKE1014 — kept off the Store-only `oke()` graph.
+ *
+ * Signal drivers throw this when a Last-Event-ID is missing from the tape.
+ * Loaded via computed `import.meta.require` from {@link lookupOkeError}.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/** Last-Event-ID is missing from the retained live tape. */
+export const LIVE_RESUME_GAP: OkeErrorDefinition = {
+  code: 1014,
+  cause: 'Cursor "{afterId}" missing on "{signal}".',
+  fix: "Reconnect without Last-Event-ID.",
+};

package/src/kernel/errors-tenant.ts

@@ -0,0 +1,29 @@
+/**
+ * OKE1015–1017 — kept off the Store-only `oke()` graph.
+ *
+ * Tenant KV/vault and membership failures. Loaded via computed
+ * `import.meta.require` from {@link throwOke} / {@link lookupOkeError}.
+ */
+
+import type { OkeErrorDefinition } from "./errors.ts";
+
+/** Tenant-scoped op ran with no resolved `fx.tenant.id`. */
+export const TENANT_REQUIRED: OkeErrorDefinition = {
+  code: 1015,
+  cause: "This operation needs a tenant, but none is resolved for this request.",
+  fix: "Call fx.auth.switchTenant(id), send a signed tid claim, or pass the tenant header.",
+};
+
+/** Client-supplied tenant id is not a real membership. */
+export const TENANT_NOT_MEMBER: OkeErrorDefinition = {
+  code: 1016,
+  cause: 'The caller is not a member of tenant "{tenant}".',
+  fix: "Pick a tenant from fx.auth.listTenants() or add the user as a member.",
+};
+
+/** Tenant role mapped an invented or operator-plane scope. */
+export const TENANT_UNKNOWN_SCOPE: OkeErrorDefinition = {
+  code: 1017,
+  cause: 'Tenant role scope "{scope}" is not a declared application scope.',
+  fix: "Use a name from this app's Manifest catalog (never console:*).",
+};

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.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Session-only `fx.auth` key methods — issuer derived, never from flow input.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AttenuationError } from "../auth/attenuation.ts";
+import { createApiKey, createApiKeyStore } from "../auth/api-keys.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { createFx } from "./fx.ts";
+
+describe("fx.auth key methods", () => {
+  test("createApiKey derives creator from the live session and rejects broader scopes", async () => {
+    const store = createApiKeyStore();
+    const fx = createFx({
+      flow: "keys.create",
+      effects: { writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: null },
+    });
+    const created = await fx.auth.createApiKey({ name: "mine", scopes: ["member"] });
+    expect(created.key.scopes).toEqual(["member"]);
+    expect(created.secret.startsWith("oke_")).toBe(true);
+    expect(store.keys.get(created.key.id)?.creatorId).toBe("u1");
+
+    await expect(fx.auth.createApiKey({ name: "wide", scopes: ["admin"] })).rejects.toBeInstanceOf(
+      AttenuationError,
+    );
+  });
+
+  test("key-authenticated caller cannot create / list / revoke / rotate / update", async () => {
+    const store = createApiKeyStore();
+    await createApiKey(store, {
+      plane: "user",
+      name: "existing",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_existing",
+    });
+    const fx = createFx({
+      flow: "keys.as-key",
+      effects: { reads: ["auth:api-keys"], writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: "key_existing" },
+    });
+    for (const call of [
+      () => fx.auth.createApiKey({ name: "nested", scopes: ["member"] }),
+      () => fx.auth.listApiKeys(),
+      () => fx.auth.revokeApiKey("key_existing"),
+      () => fx.auth.rotateApiKey("key_existing"),
+      () => fx.auth.updateApiKey("key_existing", { name: "nope" }),
+    ]) {
+      try {
+        await call();
+        throw new Error("expected Forbidden");
+      } catch (err) {
+        expect(isFlowFailure(err)).toBe(true);
+        if (isFlowFailure(err)) expect(err.error.code).toBe("Forbidden");
+      }
+    }
+  });
+
+  test("list is self-only; cross-user revoke is Forbidden", async () => {
+    const store = createApiKeyStore();
+    await createApiKey(store, {
+      plane: "user",
+      name: "theirs",
+      scopes: ["member"],
+      creatorId: "u2",
+      creatorScopes: ["member"],
+      id: "key_theirs",
+    });
+    const fx = createFx({
+      flow: "keys.list",
+      effects: { reads: ["auth:api-keys"], writes: ["auth:api-keys"] },
+      apiKeyStore: store,
+      auth: { userId: "u1", scopes: new Set(["member"]), apiKeyId: null },
+    });
+    expect(await fx.auth.listApiKeys()).toEqual([]);
+    try {
+      await fx.auth.revokeApiKey("key_theirs");
+      throw new Error("expected Forbidden");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      if (isFlowFailure(err)) expect(err.error.code).toBe("Forbidden");
+    }
+  });
+});

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

@@ -0,0 +1,203 @@
+/**
+ * `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 (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. */
+  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-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);
+  });
+});