okengine 0.15.2 → 0.17.0

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,11 +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. */
@@ -39,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}. */
@@ -53,7 +64,7 @@ export interface PipelineDeps {
    * @returns Principal on success
    * @throws On forge / expiry / revoke — pipeline maps to `Unauthorized`
    */
-  readonly verifyBearer?: (token: string) => Promise<ResolvedPrincipal>;
+  readonly verifyBearer?: (token: string, request?: Request) => Promise<ResolvedPrincipal>;
   /**
    * Optional token extraction (e.g. cookie → Bearer when cookies enabled).
    * When omitted, only `Authorization: Bearer` is read.
@@ -76,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";
 }
 
 /**
@@ -152,10 +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;
 }
 
 /**
@@ -192,12 +221,12 @@ export function createElementPipelineHooks(deps: PipelineDeps): {
         return fail("Unauthorized", {});
       }
       try {
-        const principal = await deps.verifyBearer(token);
+        const principal = await deps.verifyBearer(token, ctx.request);
         applyPrincipal(deps.principals, principal);
         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", {});
@@ -209,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) => {
@@ -233,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;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Tenant-role scope union is conditional — never JWT-melt, never on
+ * `tenantScoped: false` flows.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createTenant, createTenantStore, upsertTenantRole } from "../auth/tenants.ts";
+import { gate } from "../elements/gate.ts";
+import { oke } from "./app.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { isFlowFailure } from "./hooks.ts";
+import { on, resetBindings } from "./on.ts";
+import { http } from "./triggers.ts";
+
+const SECRET = "tenant-roles-test-secret";
+
+describe("tenant-role scope union", () => {
+  test("tenant-granted scope does not authorize a tenantScoped: false route", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const member = gate.policy("member", ({ auth }) => !!auth.verified);
+    const booking = gate.scope("booking:create");
+    const tenantStore = createTenantStore();
+    await createTenant(tenantStore, { name: "Acme", createdBy: "u1", id: "t1" });
+    upsertTenantRole(tenantStore, {
+      tenantId: "t1",
+      roleName: "member",
+      scopes: ["booking:create"],
+      catalog: ["booking:create", "member"],
+    });
+
+    on(
+      http.get("/global").gate(booking),
+      flow("global.ping", {
+        tenantScoped: false,
+        do: () => "global",
+      }),
+    );
+    on(
+      http.get("/tenant").gate(booking),
+      flow("tenant.ping", {
+        do: () => "tenant",
+      }),
+    );
+
+    const app = oke({
+      name: "tenant-roles",
+      env: "test",
+      startScheduler: false,
+      gate: {
+        policies: [member, booking],
+        auth: { secret: SECRET, tenant: true, tenantStore, http: false },
+      },
+    });
+    await app.boot({ env: "test", startScheduler: false });
+
+    const principal = {
+      plane: "user" as const,
+      userId: "u1",
+      scopes: [] as string[],
+      verified: true,
+      tenantId: "t1",
+    };
+
+    const leak = await app.execute(
+      app.flow("global.ping")!,
+      undefined,
+      http.get("/global").gate(booking),
+      { principal },
+    );
+    expect(leak.failure && isFlowFailure(leak.failure)).toBe(true);
+    if (leak.failure && isFlowFailure(leak.failure)) {
+      expect(leak.failure.error.code).toBe("Forbidden");
+    }
+
+    const allowed = await app.execute(
+      app.flow("tenant.ping")!,
+      undefined,
+      http.get("/tenant").gate(booking),
+      { principal },
+    );
+    expect(allowed.failure).toBeUndefined();
+    expect(allowed.output).toBe("tenant");
+
+    await app.bootResult?.close();
+  });
+});

package/src/kernel/triggers.ts

@@ -36,8 +36,10 @@ export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string
   readonly method: M;
   readonly path: P;
   readonly gates: readonly GateRef[];
-  /** Whether `.live()` was applied. */
-  readonly isLive: boolean;
+  /**
+   * Signal this GET exposes as a live SSE feed (`undefined` when not a live route).
+   */
+  readonly liveSignal?: SignalSource;
   /**
    * Attach gates (registration order). `gate.all` handles and arrays flatten.
    */
@@ -47,9 +49,29 @@ export interface HttpTrigger<M extends HttpMethod = HttpMethod, P extends string
    */
   public(): HttpTrigger<M, P>;
   /**
-   * Mark the HTTP trigger as live (push result to subscribers).
+   * Expose a `delivery: "live"` signal as SSE on this GET.
+   *
+   * @param signal - Live signal handle
    */
-  live(): HttpTrigger<M, P>;
+  live(signal: SignalSource): LiveHttpTrigger<M, P>;
+}
+
+/**
+ * HTTP GET trigger that exposes a live signal (`on(trigger)` synthesizes the Flow).
+ *
+ * `.gate` / `.public` keep {@link LiveHttpTrigger.liveSignal} so
+ * `on(http.live(signal).gate(member))` typechecks.
+ *
+ * @typeParam M - HTTP method literal
+ * @typeParam P - Path template literal
+ */
+export interface LiveHttpTrigger<
+  M extends HttpMethod = "GET",
+  P extends string = string,
+> extends HttpTrigger<M, P> {
+  readonly liveSignal: SignalSource;
+  readonly gate: GateAttach<LiveHttpTrigger<M, P>>;
+  public(): LiveHttpTrigger<M, P>;
 }
 
 /** Clock / interval trigger (`every("1h")`). */
@@ -105,31 +127,43 @@ export function createGateAttach<T>(
 }
 
 /**
- * Build an HTTP trigger with `.gate` / `.public` / `.live`.
+ * Build an HTTP trigger with `.gate` / `.public` / `.live(signal)`.
  *
  * @param method - HTTP verb
  * @param path - Route path
  * @param gates - Attached gate refs
- * @param isLive - Live flag
+ * @param liveSignal - Live signal when `.live(signal)` was applied
  */
+export function createHttpTrigger<M extends HttpMethod, P extends string>(
+  method: M,
+  path: P,
+  gates: readonly GateRef[],
+  liveSignal: SignalSource,
+): LiveHttpTrigger<M, P>;
+export function createHttpTrigger<M extends HttpMethod, P extends string>(
+  method: M,
+  path: P,
+  gates?: readonly GateRef[],
+  liveSignal?: SignalSource,
+): HttpTrigger<M, P>;
 export function createHttpTrigger<M extends HttpMethod, P extends string>(
   method: M,
   path: P,
   gates: readonly GateRef[] = [],
-  isLive = false,
+  liveSignal?: SignalSource,
 ): HttpTrigger<M, P> {
   const trigger: HttpTrigger<M, P> = {
     kind: "http",
     method,
     path,
     gates,
-    isLive,
-    gate: createGateAttach((next) => createHttpTrigger(method, path, next, isLive), gates),
+    ...(liveSignal !== undefined ? { liveSignal } : {}),
+    gate: createGateAttach((next) => createHttpTrigger(method, path, next, liveSignal), gates),
     public() {
-      return createHttpTrigger(method, path, [...gates, GATE_PUBLIC_NAME], isLive);
+      return createHttpTrigger(method, path, [...gates, GATE_PUBLIC_NAME], liveSignal);
     },
-    live() {
-      return createHttpTrigger(method, path, gates, true);
+    live(signal: SignalSource) {
+      return createHttpTrigger(method, path, gates, signal);
     },
   };
   return trigger;
@@ -150,14 +184,12 @@ export interface ResourceFlowBag {
 /**
  * A mounted resource — the single argument to the `on(http.resource(…))`
  * overload. Branded so `on` can tell it apart from a plain trigger.
- * Same chain as {@link HttpTrigger}: `.gate(...)` / `.public()` / `.live()`.
+ * Same chain as {@link HttpTrigger}: `.gate(...)` / `.public()`.
  */
 export interface ResourceMount {
   readonly [resourceMountBrand]: true;
   readonly mounts: ReadonlyArray<{ readonly trigger: HttpTrigger; readonly flow: unknown }>;
   readonly gates: readonly GateRef[];
-  /** Whether `.live()` was applied (GET list + get). */
-  readonly isLive: boolean;
   /**
    * Attach gates to every verb (registration order). `gate.all` and arrays flatten.
    */
@@ -166,10 +198,6 @@ export interface ResourceMount {
    * Attach the unauthenticated public sentinel to every verb.
    */
   public(): ResourceMount;
-  /**
-   * Mark list and get as live (GET mounts). Mutations stay request/response.
-   */
-  live(): ResourceMount;
 }
 /** Brand for {@link ResourceMount}. */
 export const resourceMountBrand: unique symbol = Symbol.for("oke.resource.mount");
@@ -254,10 +282,16 @@ export interface HttpTriggerNamespace {
   query<P extends string>(path: P): HttpTrigger<"QUERY", P>;
   /**
    * Mount a CRUD resource (list/create on `path`, get/update/remove on
-   * `path/:id`) for the `on(http.resource(…))` overload. Chain `.gate(...)`,
-   * `.public()`, and `.live()` like {@link HttpTrigger}.
+   * `path/:id`) for the `on(http.resource(…))` overload. Chain `.gate(...)`
+   * and `.public()` like {@link HttpTrigger}.
    */
   resource<P extends string>(path: P, ops: ResourceFlowBag): ResourceMount;
+  /**
+   * Default live firehose: `GET /_oke/live/{signal}`. Chain `.gate(...)`.
+   *
+   * @param signal - `delivery: "live"` handle
+   */
+  live(signal: SignalSource): LiveHttpTrigger<"GET">;
 }
 
 /** Bind an HTTP verb constructor (`http.get`, `http.query`, …). */
@@ -287,6 +321,10 @@ export const http: HttpTriggerNamespace = {
   head: httpVerb("HEAD"),
   query: httpVerb("QUERY"),
   resource: (path, ops) => loadHttpResource().httpResource(path, ops),
+  live(signal) {
+    const path = `/_oke/live/${encodeURIComponent(signal.name)}`;
+    return createHttpTrigger("GET", path, [], signal);
+  },
 };
 
 /**