okengine 0.16.0 → 0.17.0

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

@@ -0,0 +1,125 @@
+/**
+ * HTTP Last-Event-ID resume and 410 LiveResumeGap before SSE.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { signal, resetSignals } from "../elements/signal/declare.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { stampFlowName } from "./stamp-http.ts";
+import { http } from "./triggers.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetSignals();
+});
+
+describe("live Last-Event-ID resume", () => {
+  afterEach(() => {
+    resetBindings();
+    resetFlowSeq();
+    resetSignals();
+  });
+
+  test("skips through Last-Event-ID and 410s a pruned cursor", async () => {
+    const orderStatus = signal("order-status", { delivery: "live", optional: true });
+    const feed = on(http.get("/feed").public().live(orderStatus));
+    stampFlowName(feed, "orders.feed");
+    on(
+      http.post("/emit").public(),
+      flow("orders.emit", {
+        do: async (_input, fx) => {
+          await fx.emit(orderStatus, { status: "placed" });
+          await fx.emit(orderStatus, { status: "shipped" });
+        },
+      }),
+    );
+
+    const app = oke({ name: "live-resume" });
+    const emitted = await app.fetch(new Request("http://localhost/emit", { method: "POST" }));
+    expect(emitted.status).toBe(204);
+
+    const firstCtrl = new AbortController();
+    const first = await app.fetch(
+      new Request("http://localhost/feed", { signal: firstCtrl.signal }),
+    );
+    expect(first.status).toBe(200);
+    expect(first.headers.get("content-type")).toMatch(/text\/event-stream/);
+    const firstFrames = await readSseFrames(first, 2);
+    firstCtrl.abort();
+    expect(firstFrames.map((f) => f.data)).toEqual([{ status: "placed" }, { status: "shipped" }]);
+    const cursor = firstFrames[0]!.id;
+    expect(cursor).toBeTruthy();
+
+    const resumeCtrl = new AbortController();
+    const resume = await app.fetch(
+      new Request("http://localhost/feed", {
+        signal: resumeCtrl.signal,
+        headers: { "last-event-id": cursor! },
+      }),
+    );
+    expect(resume.status).toBe(200);
+    const rest = await readSseFrames(resume, 1);
+    resumeCtrl.abort();
+    expect(rest.map((f) => f.data)).toEqual([{ status: "shipped" }]);
+
+    const gap = await app.fetch(
+      new Request("http://localhost/feed", {
+        headers: { "last-event-id": "never-existed" },
+      }),
+    );
+    expect(gap.status).toBe(410);
+    expect(gap.headers.get("content-type")).toMatch(/application\/json/);
+    expect(await gap.json()).toMatchObject({
+      data: null,
+      error: {
+        code: "LiveResumeGap",
+        data: { signal: "order-status", afterId: "never-existed" },
+      },
+    });
+  });
+});
+
+async function readSseFrames(
+  res: Response,
+  n: number,
+): Promise<Array<{ id?: string; data: unknown }>> {
+  const reader = res.body?.getReader();
+  if (!reader) throw new Error("no body");
+  const dec = new TextDecoder();
+  let buf = "";
+  const out: Array<{ id?: string; data: unknown }> = [];
+  try {
+    while (out.length < n) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let sep = buf.indexOf("\n\n");
+      while (sep >= 0 && out.length < n) {
+        const raw = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        const frame = parseFrame(raw);
+        if (frame) out.push(frame);
+        sep = buf.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return out;
+}
+
+function parseFrame(raw: string): { id?: string; data: unknown } | undefined {
+  const dataLines: string[] = [];
+  let id: string | undefined;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0) return undefined;
+  const data = dataLines.join("\n");
+  if (data === "[DONE]") return undefined;
+  return { ...(id !== undefined ? { id } : {}), data: JSON.parse(data) as unknown };
+}

package/src/kernel/on.ts

@@ -7,16 +7,28 @@
  */
 
 import { isFlow, type AnyFlowDef, type FlowDef, type FlowErrorMap } from "./flow.ts";
+import { lazyRequire } from "./lazy-require.ts";
 import {
   isResourceMount,
   normalizeTrigger,
   type BoundTriggerOf,
+  type HttpMethod,
+  type HttpTrigger,
+  type LiveHttpTrigger,
   type ResourceFlowBag,
   type ResourceMount,
   type SignalSource,
   type Trigger,
 } from "./triggers.ts";
 
+/**
+ * Sync-load live HTTP synthesis only when `on(http.*.live(signal))` runs.
+ * A static import would pin that graph on every `on` / edge ping bundle.
+ */
+function loadLiveHttp(): typeof import("./live-http.ts") {
+  return lazyRequire(import.meta.dir, ["live", "http"].join("-"));
+}
+
 /** One registered `on(trigger, flow)` binding. */
 export interface Binding {
   readonly trigger: Trigger;
@@ -43,6 +55,15 @@ export function on<
   trigger: T,
   flowDef: FlowDef<I, O, E, D, Trigger | undefined>,
 ): FlowDef<I, O, E, D, BoundTriggerOf<T>>;
+/**
+ * Expose a live signal: `on(http.get(path).gate(g).live(signal))`.
+ * Synthesizes the stream Flow (name stamped by `.adopt`).
+ *
+ * @param trigger - HTTP GET with `.live(signal)`
+ */
+export function on<T extends LiveHttpTrigger<HttpMethod, string>>(
+  trigger: T,
+): FlowDef<unknown, unknown, FlowErrorMap, {}, T>;
 /**
  * Mount a CRUD resource (`http.resource(path, ops)`): registers the five
  * verb bindings and returns the ops bag (unit keys `list` · `create` ·
@@ -81,10 +102,40 @@ export function on(
     }
     return ops as unknown as ResourceFlowBag;
   }
+  const asHttp =
+    typeof triggerOrMount === "object" &&
+    triggerOrMount !== null &&
+    "kind" in triggerOrMount &&
+    (triggerOrMount as HttpTrigger).kind === "http"
+      ? (triggerOrMount as HttpTrigger)
+      : undefined;
+  const liveSignal = asHttp?.liveSignal;
+  const synthesized = liveSignal !== undefined && flowDef === undefined;
+  if (synthesized && asHttp && liveSignal !== undefined) {
+    if (asHttp.method !== "GET") {
+      throw new TypeError("on(http.*.live(signal)): live exposure must be GET");
+    }
+    flowDef = loadLiveHttp().synthesizeLiveFlow(liveSignal, asHttp.path) as FlowDef<
+      any,
+      any,
+      any,
+      any,
+      Trigger | undefined
+    >;
+  }
   if (!isFlow(flowDef)) {
     throw new TypeError("on() expected a flow() definition as the second argument");
   }
   const normalized = normalizeTrigger(triggerOrMount as Trigger | SignalSource);
+  if (normalized.kind === "http" && normalized.liveSignal !== undefined) {
+    if (normalized.method !== "GET") {
+      throw new TypeError("on(http.*.live(signal)): live exposure must be GET");
+    }
+    (flowDef as { live: string | undefined }).live = normalized.liveSignal.name;
+    if (!synthesized) {
+      (flowDef as { liveCustomMatch: boolean }).liveCustomMatch = true;
+    }
+  }
   const list = flowDef.triggers as Trigger[];
   list.push(normalized);
   // Stamp runtime carrier for the first bound trigger (type follows BoundTriggerOf).

package/src/kernel/pipeline-tenant.ts

@@ -0,0 +1,49 @@
+/**
+ * Tenant identity + role-scope union — lazy chunk.
+ *
+ * A static import from {@link ./pipeline.ts} would pin tenant-resolve and
+ * the tenant store (and `isApplicationScope`) on every `oke()` graph,
+ * including Store-only apps that never enable `gate.auth.tenant`.
+ */
+
+import { tenantScopesForMember } from "../auth/tenants.ts";
+import type { FlowFailure } from "./errors.ts";
+import type { PipelineDeps } from "./pipeline.ts";
+import type { InvocationContext } from "./hooks.ts";
+import { resolveRequestTenant } from "./tenant-resolve.ts";
+
+/**
+ * Resolve tenant id and conditionally union tenant-role scopes.
+ *
+ * @param deps - Pipeline deps (`tenant` must be set)
+ * @param ctx - Invocation
+ */
+export function applyPipelineTenant(
+  deps: PipelineDeps,
+  ctx: InvocationContext,
+): FlowFailure | undefined {
+  const tenant = deps.tenant;
+  if (!tenant) return undefined;
+  const auth = deps.principals.auth;
+  auth.sessionScopes ??= new Set(auth.scopes);
+  const claimTenantId = deps.principals.tenant.id;
+  const result = resolveRequestTenant({
+    config: tenant.config,
+    auth: deps.principals.auth,
+    claimTenantId,
+    request: ctx.request,
+    store: tenant.store,
+  });
+  if (result.failure) return result.failure;
+  deps.principals.tenant.id = result.id;
+  const userId = deps.principals.auth.userId;
+  if (result.id && userId && tenant.flowTenantScoped && tenant.flowPlane !== "operator") {
+    for (const scope of tenantScopesForMember(tenant.store, result.id, userId)) {
+      deps.principals.auth.scopes.add(scope);
+    }
+  }
+  return undefined;
+}
+
+/** Short name so the Store-only `oke()` graph does not spell {@link applyPipelineTenant}. */
+export { applyPipelineTenant as run };

package/src/kernel/pipeline.test.ts

@@ -69,7 +69,7 @@ describe("http trigger — .public()", () => {
   test("attaches the public sentinel without calling gate()", () => {
     const trigger = http.get("/health").public();
     expect(trigger.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["public"]);
-    expect(trigger.live().isLive).toBe(true);
+    expect(trigger.liveSignal).toBeUndefined();
   });
 });
 

package/src/kernel/pipeline.ts

@@ -10,11 +10,14 @@
  * Gate denial is a typed error value, never a thrown exception.
  */
 
+import type { ResolvedTenantAuth } from "../auth/tenant-config.ts";
+import type { TenantStore } from "../auth/tenants.ts";
 import type { GateEvaluation, GateRuntime } from "../elements/gate.ts";
 import type { GatePolicyContext } from "../elements/gate/declare.ts";
 import { fail, type FlowFailure } from "./errors.ts";
 import type { Fx, FxAuth, FxOperator } from "./fx.ts";
 import type { HookFn, InvocationContext } from "./hooks.ts";
+import { lazyRequire } from "./lazy-require.ts";
 import type { RunTelemetry } from "./run-telemetry.ts";
 import type { HttpTrigger, Trigger } from "./triggers.ts";
 
@@ -23,12 +26,17 @@ export interface PrincipalBag {
   readonly auth: {
     userId: string | null;
     scopes: Set<string>;
+    /** JWT / session scopes — never mutated by tenant-role union. */
+    sessionScopes?: Set<string>;
     verified?: boolean;
     apiKeyId?: string | null;
   };
   readonly operator: {
     id: string | null;
   };
+  readonly tenant: {
+    id: string | null;
+  };
 }
 
 /** Resolved identity from auth middleware / test harness. */
@@ -40,6 +48,8 @@ export interface ResolvedPrincipal {
   readonly verified?: boolean;
   /** Authenticating API key id when Bearer was a key secret. */
   readonly apiKeyId?: string;
+  /** Signed `tid` / API-key tenant claim (tier 1). */
+  readonly tenantId?: string | null;
 }
 
 /** Dependencies for {@link createElementPipelineHooks}. */
@@ -77,6 +87,20 @@ export interface PipelineDeps {
   readonly principals: PrincipalBag;
   /** Telemetry collector for the current run (gates dimension). */
   readonly telemetry: RunTelemetry;
+  /**
+   * When set, resolve `fx.tenant` after the principal and optionally union
+   * tenant-role scopes into the live auth bag.
+   */
+  readonly tenant?: PipelineTenantDeps;
+}
+
+/** Tenant identity + conditional scope union (user-plane tenant-scoped flows). */
+export interface PipelineTenantDeps {
+  readonly config: ResolvedTenantAuth;
+  readonly store: TenantStore;
+  /** Default true when tenancy is on; `flow({ tenantScoped: false })` opts out. */
+  readonly flowTenantScoped: boolean;
+  readonly flowPlane?: "user" | "operator";
 }
 
 /**
@@ -153,11 +177,14 @@ export function applyPrincipal(bag: PrincipalBag, resolved: ResolvedPrincipal |
     if (resolved.userId !== undefined) bag.auth.userId = resolved.userId;
     if (resolved.scopes !== undefined) {
       bag.auth.scopes.clear();
-      for (const s of resolved.scopes) bag.auth.scopes.add(s);
+      for (const s of resolved.scopes) {
+        bag.auth.scopes.add(s);
+      }
     }
     if (resolved.verified !== undefined) bag.auth.verified = resolved.verified;
     bag.auth.apiKeyId = resolved.apiKeyId ?? null;
   }
+  if (resolved.tenantId !== undefined) bag.tenant.id = resolved.tenantId;
 }
 
 /**
@@ -199,7 +226,7 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
         if (principal.apiKeyId) {
           deps.telemetry.dimensions.api_key = principal.apiKeyId;
         }
-        return;
+        return applyTenant(deps, ctx);
       } catch {
         // Forge / expiry / revoke → typed Unauthorized (never throw).
         return fail("Unauthorized", {});
@@ -211,6 +238,7 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
       const fromState = ctx.state.principal as ResolvedPrincipal | undefined;
       if (fromState) applyPrincipal(deps.principals, fromState);
     }
+    return applyTenant(deps, ctx);
   };
 
   const beforeHandle: HookFn = async (ctx, fxOrErr) => {
@@ -235,6 +263,13 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
   return { onAuth, beforeHandle };
 }
 
+function applyTenant(deps: PipelineDeps, ctx: InvocationContext): FlowFailure | undefined {
+  if (!deps.tenant) return undefined;
+  return lazyRequire<{
+    run: (d: PipelineDeps, c: InvocationContext) => FlowFailure | undefined;
+  }>(import.meta.dir, ["pipeline", "tenant"].join("-")).run(deps, ctx);
+}
+
 /**
  * Build a policy context from the live `fx` principals.
  *

package/src/kernel/resource-mount.test.ts

@@ -1,5 +1,5 @@
 /**
- * `http.resource(path, ops).gate(...).live()` — same chain as `http.get`.
+ * `http.resource(path, ops).gate(...)` — same chain as `http.get`.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -28,21 +28,21 @@ function httpOf(path: string, method: string): HttpTrigger | undefined {
   return hit?.trigger.kind === "http" ? hit.trigger : undefined;
 }
 
-describe("http.resource — gate / live", () => {
-  test("bare mount has no gates and is not live", () => {
+describe("http.resource — gate", () => {
+  test("bare mount has no gates and is not a live exposure", () => {
     resetBindings();
     resetFlowSeq();
     on(http.resource("/notes", bag()));
     const list = httpOf("/notes", "GET");
     expect(list?.gates).toEqual([]);
-    expect(list?.isLive).toBe(false);
-    expect(httpOf("/notes", "POST")?.isLive).toBe(false);
+    expect(list?.liveSignal).toBeUndefined();
+    expect(httpOf("/notes", "POST")?.liveSignal).toBeUndefined();
   });
 
-  test(".gate(member).live() stamps every verb; live is GET only", () => {
+  test(".gate(member) stamps every verb", () => {
     resetBindings();
     resetFlowSeq();
-    on(http.resource("/notes", bag()).gate(member).live());
+    on(http.resource("/notes", bag()).gate(member));
 
     const list = httpOf("/notes", "GET");
     const create = httpOf("/notes", "POST");
@@ -55,35 +55,18 @@ describe("http.resource — gate / live", () => {
     expect(get?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["member"]);
     expect(update?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["member"]);
     expect(remove?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(["member"]);
-
-    expect(list?.isLive).toBe(true);
-    expect(get?.isLive).toBe(true);
-    expect(create?.isLive).toBe(false);
-    expect(update?.isLive).toBe(false);
-    expect(remove?.isLive).toBe(false);
+    expect(list?.liveSignal).toBeUndefined();
   });
 
-  test(".public().live() stamps the sentinel on every verb", () => {
+  test(".public() stamps the sentinel on every verb", () => {
     resetBindings();
     resetFlowSeq();
-    on(http.resource("/notes", bag()).public().live());
+    on(http.resource("/notes", bag()).public());
     expect(httpOf("/notes", "GET")?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(
       ["public"],
     );
     expect(
       httpOf("/notes", "POST")?.gates.map((g) => (typeof g === "string" ? g : g.name)),
     ).toEqual(["public"]);
-    expect(httpOf("/notes", "GET")?.isLive).toBe(true);
-    expect(httpOf("/notes", "POST")?.isLive).toBe(false);
-  });
-
-  test(".live().gate(member) order does not matter", () => {
-    resetBindings();
-    resetFlowSeq();
-    on(http.resource("/notes", bag()).live().gate(member));
-    expect(httpOf("/notes", "GET")?.isLive).toBe(true);
-    expect(httpOf("/notes", "GET")?.gates.map((g) => (typeof g === "string" ? g : g.name))).toEqual(
-      ["member"],
-    );
   });
 });

package/src/kernel/tenant-resolve.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Three-tier tenant identity resolution.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createTenant, createTenantStore } from "../auth/tenants.ts";
+import { resolveTenantAuth } from "../auth/tenant-config.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { resolveRequestTenant } from "./tenant-resolve.ts";
+
+describe("resolveRequestTenant", () => {
+  test("claim trusts tid without a membership query", async () => {
+    const store = createTenantStore();
+    const result = resolveRequestTenant({
+      config: resolveTenantAuth(true),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: "not-a-member",
+      store,
+    });
+    expect(result.id).toBe("not-a-member");
+    expect(result.failure).toBeUndefined();
+  });
+
+  test("header never trusts a non-member", async () => {
+    const store = createTenantStore();
+    await createTenant(store, { name: "Acme", createdBy: "owner", id: "acme" });
+    const result = resolveRequestTenant({
+      config: resolveTenantAuth({ source: "header" }),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: null,
+      request: new Request("https://app.example/x", { headers: { "x-oke-tenant": "acme" } }),
+      store,
+    });
+    expect(result.id).toBeNull();
+    expect(result.failure && isFlowFailure(result.failure)).toBe(true);
+    if (result.failure && isFlowFailure(result.failure)) {
+      expect(result.failure.error.code).toBe("Forbidden");
+      expect(result.failure.error.data).toEqual({
+        gate: "auth:tenants",
+        reason: "not_member",
+      });
+    }
+  });
+
+  test("header accepts a real membership", async () => {
+    const store = createTenantStore();
+    await createTenant(store, { name: "Acme", createdBy: "u1", id: "acme" });
+    const result = resolveRequestTenant({
+      config: resolveTenantAuth({ source: "header" }),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: null,
+      request: new Request("https://app.example/x", { headers: { "x-oke-tenant": "acme" } }),
+      store,
+    });
+    expect(result.id).toBe("acme");
+  });
+
+  test("required + authenticated + no tenant is Forbidden tenant_required", () => {
+    const store = createTenantStore();
+    const result = resolveRequestTenant({
+      config: resolveTenantAuth({ required: true }),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: null,
+      store,
+    });
+    expect(result.failure && isFlowFailure(result.failure)).toBe(true);
+    if (result.failure && isFlowFailure(result.failure)) {
+      expect(result.failure.error.data).toEqual({
+        gate: "auth:tenants",
+        reason: "tenant_required",
+      });
+    }
+  });
+
+  test("resolve callback still checks membership unless authoritative", async () => {
+    const store = createTenantStore();
+    const denied = resolveRequestTenant({
+      config: resolveTenantAuth({
+        source: "resolve",
+        resolve: () => "ghost",
+      }),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: null,
+      store,
+    });
+    expect(denied.failure && isFlowFailure(denied.failure)).toBe(true);
+
+    await createTenant(store, { name: "Acme", createdBy: "u1", id: "acme" });
+    const trusted = resolveRequestTenant({
+      config: resolveTenantAuth({
+        source: "resolve",
+        authoritative: true,
+        resolve: () => "ghost",
+      }),
+      auth: { userId: "u1", scopes: new Set() },
+      claimTenantId: null,
+      store,
+    });
+    expect(trusted.id).toBe("ghost");
+  });
+});

package/src/kernel/tenant-resolve.ts

@@ -0,0 +1,124 @@
+/**
+ * Per-request tenant identity resolution (three tiers).
+ *
+ * Tenant is an identity dimension like `fx.auth` — not a second authz system.
+ */
+
+import { isMember, type TenantStore } from "../auth/tenants.ts";
+import {
+  type ResolvedTenantAuth,
+  type TenantAuthOptions,
+  type TenantSource,
+} from "../auth/tenant-config.ts";
+import { fail, type FlowFailure } from "./errors.ts";
+import type { FxAuthIdentity } from "./fx-auth-keys.ts";
+
+export type { ResolvedTenantAuth, TenantAuthOptions, TenantSource };
+
+/** Result of {@link resolveRequestTenant}. */
+export interface RequestTenantResult {
+  readonly id: string | null;
+  readonly failure?: FlowFailure;
+}
+
+/** Options for {@link resolveRequestTenant}. */
+export interface ResolveRequestTenantOptions {
+  readonly config: ResolvedTenantAuth;
+  readonly auth: FxAuthIdentity;
+  readonly claimTenantId: string | null;
+  readonly request?: Request;
+  readonly store: TenantStore;
+}
+
+/**
+ * Resolve tenant id for this request.
+ *
+ * Tier 1 (`claim`): signed `tid` / API-key `tenantId` — no membership query.
+ * Tier 2 (`header` / `subdomain`): client-supplied — membership required.
+ * Tier 3 (`resolve`): callback; membership required unless `authoritative`.
+ *
+ * @param options - Config + live identity + request
+ */
+export function resolveRequestTenant(options: ResolveRequestTenantOptions): RequestTenantResult {
+  const { config, auth, claimTenantId, request, store } = options;
+  const userId = auth.userId;
+  const supplied = sourceValue(config, claimTenantId, request, auth);
+
+  if (supplied === null || supplied === "") {
+    if (config.required && userId) {
+      return {
+        id: null,
+        failure: fail("Forbidden", { gate: "auth:tenants", reason: "tenant_required" }),
+      };
+    }
+    return { id: null };
+  }
+
+  if (config.source === "claim") {
+    return { id: supplied };
+  }
+
+  if (config.source === "resolve" && config.authoritative) {
+    return { id: supplied };
+  }
+
+  if (!userId) {
+    return {
+      id: null,
+      failure: fail("Unauthorized", {}),
+    };
+  }
+  if (!isMember(store, supplied, userId)) {
+    return {
+      id: null,
+      failure: fail("Forbidden", { gate: "auth:tenants", reason: "not_member" }),
+    };
+  }
+  return { id: supplied };
+}
+
+function sourceValue(
+  config: ResolvedTenantAuth,
+  claimTenantId: string | null,
+  request: Request | undefined,
+  auth: FxAuthIdentity,
+): string | null {
+  if (config.source === "claim") {
+    return claimTenantId;
+  }
+  // Internal / cron / fx.call have no HTTP request — keep the stamped claim.
+  if (!request && (config.source === "header" || config.source === "subdomain")) {
+    return claimTenantId;
+  }
+  if (config.source === "header") {
+    const raw = request?.headers.get(config.header)?.trim();
+    return raw && raw.length > 0 ? raw : null;
+  }
+  if (config.source === "subdomain") {
+    return subdomainLabel(request);
+  }
+  if (config.source === "resolve" && config.resolve) {
+    const out = config.resolve({
+      auth: { userId: auth.userId, tenantId: claimTenantId },
+      request,
+      claimTenantId,
+    });
+    return out ?? null;
+  }
+  return claimTenantId;
+}
+
+/**
+ * First Host label as a tenant slug/id (`acme.example.com` → `acme`).
+ *
+ * @param request - Incoming request
+ */
+export function subdomainLabel(request: Request | undefined): string | null {
+  const host = request?.headers.get("host")?.split(":")[0]?.trim().toLowerCase();
+  if (!host) return null;
+  const parts = host.split(".");
+  if (parts.length < 3) return null;
+  const label = parts[0];
+  if (!label || label === "www") return null;
+  return label;
+}