okengine 0.16.0 → 0.17.1

package/site/content/docs/reference/client.mdx

@@ -172,7 +172,7 @@ const { data } = await api.auth.signInEmail({ email, password });
 if (data) session.set(data);
 ```
 
-React: `useSession(api, session)` from `okengine/client-react`.
+React: `useSession(api, session)` and `useLive(api, signal, input?)` from `okengine/client-react`.
 
 | Step                   | What happens                                                     |
 | ---------------------- | ---------------------------------------------------------------- |
@@ -204,6 +204,7 @@ A 401 with no `{ data, error }` body becomes `TransportError` with `data.status:
 | `memorySession`             | `okengine/client/auth`  | In-memory access/refresh bag for `auth.getToken` |
 | `AUTH_ERROR_CODES`          | `okengine/client/auth`  | Common auth Flow / gate codes                    |
 | `useSession(api, session?)` | `okengine/client-react` | React status + `auth.me`                         |
+| `useLive(api, signal, …)`   | `okengine/client-react` | React `events` / `latest` / `isConnected`        |
 
 Core `okengine/client` stays under the size budget — helpers are separate exports. Not in
 core today: cookie jars or plugin `.client()` decorations. Browser apps: also see
@@ -221,7 +222,7 @@ core today: cookie jars or plugin `.client()` decorations. Browser apps: also se
 | [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                           |
 | [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`                 |
 | [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows on `$routes` |
-| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                        |
+| [Signal](/docs/elements/signal)   | Live SSE      | `api.live(signal, input?, { onEvent })` — HTTP GET, callback + unsubscribe                 |
 | [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                              |
 | [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                           |
 | [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                              |
@@ -233,7 +234,7 @@ Mount a resource, adopt the returned ops, then call the five Flows like any othe
 
 ```typescript
 const notesR = store.resource(db, notes, {/* in, out, list */});
-const mounted = on(http.resource("/notes", notesR.all()).public().live());
+const mounted = on(http.resource("/notes", notesR.all()).public());
 // .adopt({ notes: mounted }) →
 const page = await api.notes.list({ limit: 20 });
 const more = await page.next();
@@ -259,24 +260,63 @@ See [Store](/docs/elements/store) for the list query language and schemas. Handw
 `fx.json.withQuery(rows, input)` for the same envelope. Auth posture for HTTP triggers is
 covered under [Gate](/docs/elements/gate).
 
-### Signal and live queries
+### Live signals
 
-`delivery: "live"` and `http.get(…).live()` are Manifest / driver flags today. `okengine/client`
-does **not** expose WebSocket, SSE, or `api.*.subscribe`. Until that ships, poll or call an HTTP
-Flow that returns the current state.
+`delivery: "live"` is HTTP SSE. Expose with `.live(signal)` on GET (or `http.live(signal)` for
+`GET /_oke/live/{name}`), then subscribe with a callback. `for await` stays on the server.
+
+```typescript
+const stop = api.live(
+  orderStatus,
+  { orderId: "ord_1" },
+  {
+    onEvent: (event) => {
+      /* event: { orderId, status } */
+    },
+    onError: (err) => {
+      /* optional — 4xx, envelope, network drop */
+    },
+    autoResubscribe: false, // default — true reopens after a drop (500ms…30s backoff)
+  },
+);
+stop(); // useEffect cleanup
+```
+
+`api.orders.events({ orderId }, { onEvent })` is the same shape on the exposing flow.
+
+The client picks the unique exposure whose `matchKey` fields are a subset of the input, preferring
+the largest match (`{ orderId }` beats firehose). A tie needs `via: "unit.flow"`.
+
+Reconnects send `Last-Event-ID` from the last `id:` the client actually received.
+
+A **410** `LiveResumeGap` (**OKE1014**) means that cursor is gone — `onError` fires, the
+cursor is dropped, and `autoResubscribe` replays the remaining tape after backoff.
+
+```typescript
+import { useLive } from "okengine/client-react";
+
+const { events, latest, error, isConnected } = useLive(
+  api,
+  orderStatus,
+  { orderId: "ord_1" },
+  {
+    autoResubscribe: true,
+  },
+);
+```
 
 ## Exports
 
-| Export                                    | Kind      | Role                                               |
-| ----------------------------------------- | --------- | -------------------------------------------------- |
-| `createClient`                            | function  | Typed proxy `api.unit.flow(input?)`                |
-| `flattenRoutes`                           | function  | `$routes` → flat `unit.flow` REST table            |
-| `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)  |
-| `isOk` / `isFail`                         | function  | Envelope predicates                                |
-| `isErrorCode` / `isTransportError`        | function  | Error narrowing                                    |
-| `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()` |
-| `Register`                                | interface | Module-augmentation slot for ambient App types     |
-| `AppOf`                                   | type      | Brand a bare route map as an App                   |
+| Export                                    | Kind      | Role                                                |
+| ----------------------------------------- | --------- | --------------------------------------------------- |
+| `createClient`                            | function  | Typed proxy `api.unit.flow(input?)` plus `api.live` |
+| `flattenRoutes`                           | function  | `$routes` → flat `unit.flow` REST table             |
+| `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)   |
+| `isOk` / `isFail`                         | function  | Envelope predicates                                 |
+| `isErrorCode` / `isTransportError`        | function  | Error narrowing                                     |
+| `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()`  |
+| `Register`                                | interface | Module-augmentation slot for ambient App types      |
+| `AppOf`                                   | type      | Brand a bare route map as an App                    |
 
 Budget: the `./client` export stays under the measured client-runtime cap (hard gate in CI).
 
@@ -323,6 +363,20 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 
 </Accordion>
 
+<Accordion title="api.live throws Multiple live exposures">
+
+Two routes share the same match shape. Pass `via: "unit.flow"` or call the exposing flow
+(`api.orders.events(input, { onEvent })`).
+
+</Accordion>
+
+<Accordion title="onError sees LiveResumeGap / HTTP 410">
+
+The last `id:` is not on the server tape. The client drops the cursor. With `autoResubscribe: true`
+the next request omits `Last-Event-ID` and replays what remains.
+
+</Accordion>
+
 </Accordions>
 
 ## Learn more
@@ -332,6 +386,7 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 - [Gate](/docs/elements/gate) — policies, `gate.public`, denials
 - [Store](/docs/elements/store) — `store.resource` and list query language
 - [Flow](/docs/elements/flow) — `in` / `out` / `errors` and `fx.fail`
+- [Signal](/docs/elements/signal) — `api.live` for `delivery: "live"` SSE
 - [Errors](/docs/reference/errors) — framework codes vs failure values
 - [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) — browser callers
 - [CLI Reference](/docs/reference/cli) — `oke client add`, `oke dev`

package/site/content/docs/reference/configuration.mdx

@@ -181,10 +181,13 @@ i18n: { locales: ["en"], default: "en" },
 
 ## tenancy
 
-| Option      | Type                              | Meaning                                  |
-| ----------- | --------------------------------- | ---------------------------------------- |
-| `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store   |
-| `resolve`   | string \| function                | Tenant resolver — reads `ctx.auth.orgId` |
+`oke.config.ts` `tenancy` is **isolation posture** (how rows are separated). Identity —
+who the tenant is — is `gate.auth.tenant` on [Gate](/docs/elements/gate#tenants-identity-dimension).
+
+| Option      | Type                              | Meaning                                           |
+| ----------- | --------------------------------- | ------------------------------------------------- |
+| `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store            |
+| `resolve`   | string \| function                | Observational resolver (isolation-only manifests) |
 
 ## privacy
 

package/site/content/docs/reference/errors.mdx

@@ -29,18 +29,25 @@ string. Custom app codes stay message-less until registered.
 
 ## OKE numeric codes
 
-| Code   | Name              | Cause                                           | Fix                                                |
-| ------ | ----------------- | ----------------------------------------------- | -------------------------------------------------- |
-| `1001` | undeclared read   | Flow reads a resource not in `effects.reads`    | Add it to the flow's `effects.reads`               |
-| `1002` | undeclared write  | Flow writes a resource not in `effects.writes`  | Add it to the flow's `effects.writes`              |
-| `1003` | undeclared emit   | Flow emits a signal not in `effects.emits`      | Add it to the flow's `effects.emits`               |
-| `1004` | undeclared send   | Flow sends a template not in `effects.sends`    | Add it to the flow's `effects.sends`               |
-| `1005` | undeclared ask    | Flow asks a prompt not in `effects.asks`        | Add it to the flow's `effects.asks`                |
-| `1006` | undeclared secret | Flow reads a secret not in `effects.secrets`    | Add it to the flow's `effects.secrets`             |
-| `1007` | undeclared call   | Flow calls a flow not in `effects.calls`        | Add it to the flow's `effects.calls`               |
-| `1042` | orphan emit       | Emit with zero subscribers and `optional` false | Add `on(signal, …)` or declare `optional: true`    |
-| `1043` | signal schema     | Emit payload failed the signal's `schema`       | Pass a payload that matches `schema`, or remove it |
-| `1101` | schema missing    | Domain table absent in `prod` — no auto-DDL     | Run `oke db migrate` against this environment      |
+| Code   | Name                 | Cause                                             | Fix                                                  |
+| ------ | -------------------- | ------------------------------------------------- | ---------------------------------------------------- |
+| `1001` | undeclared read      | Flow reads a resource not in `effects.reads`      | Add it to the flow's `effects.reads`                 |
+| `1002` | undeclared write     | Flow writes a resource not in `effects.writes`    | Add it to the flow's `effects.writes`                |
+| `1003` | undeclared emit      | Flow emits a signal not in `effects.emits`        | Add it to the flow's `effects.emits`                 |
+| `1004` | undeclared send      | Flow sends a template not in `effects.sends`      | Add it to the flow's `effects.sends`                 |
+| `1005` | undeclared ask       | Flow asks a prompt not in `effects.asks`          | Add it to the flow's `effects.asks`                  |
+| `1006` | undeclared secret    | Flow reads a secret not in `effects.secrets`      | Add it to the flow's `effects.secrets`               |
+| `1007` | undeclared call      | Flow calls a flow not in `effects.calls`          | Add it to the flow's `effects.calls`                 |
+| `1011` | HTTP route clash     | Two HTTP flows share the same method + path       | Give each flow a unique method + path                |
+| `1012` | HTTP flow unnamed    | Adopted HTTP flow still has no `unit.export`      | Export from `flows/<unit>/` or pass a named `flow`   |
+| `1013` | live exposure dup    | Same signal, gates, and match on two GET routes   | Change the gate or path-param filter                 |
+| `1014` | live resume gap      | `Last-Event-ID` is not on the retained tape       | Reconnect without the cursor; remaining tape replays |
+| `1015` | tenant required      | Tenant-scoped op with no `fx.tenant.id`           | `switchTenant`, signed `tid`, or tenant header       |
+| `1016` | tenant not member    | Client-supplied tenant id is not a membership     | Pick from `listTenants` or add the user as a member  |
+| `1017` | tenant unknown scope | Tenant role used an invented or `console:*` scope | Use a declared application scope                     |
+| `1042` | orphan emit          | Emit with zero subscribers and `optional` false   | Add `on(signal, …)` or declare `optional: true`      |
+| `1043` | signal schema        | Emit payload failed the signal's `schema`         | Pass a payload that matches `schema`, or remove it   |
+| `1101` | schema missing       | Domain table absent in `prod` — no auto-DDL       | Run `oke db migrate` against this environment        |
 
 <Callout title="Effects are usually inferred">
   The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an
@@ -52,11 +59,11 @@ string. Custom app codes stay message-less until registered.
 
 Returned, not thrown — the request never reached `do`:
 
-| Code           | When                                         | Payload          |
-| -------------- | -------------------------------------------- | ---------------- |
-| `Unauthorized` | Policy denied, request not authenticated     | —                |
-| `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` |
-| `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`   |
+| Code           | When                                         | Payload                                                                                    |
+| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `Unauthorized` | Policy denied, request not authenticated     | —                                                                                          |
+| `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` (`tenant_required` · `not_member` · `unknown_scope` · `session_only` · …) |
+| `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`                                                                             |
 
 ## Framework validation failures
 

package/site/content/docs/reference/fx.mdx

@@ -42,6 +42,7 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
 | `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                               |
+| `fx.live(signal, { match? })`         | `read` `signal:<name>` | Live tape as SSE. Returns `JsonStreamResult` (object chunks, `id:` on the wire). Cross-signal throws **OKE1001**. Do not wrap with `fx.json.stream`.                                                      |
 
 ## Runs (observability read)
 
@@ -92,10 +93,14 @@ on(
 | `fx.auth.revokeApiKey(id)`                                                     | `write` `auth:api-keys` | Owner only                                                                                         |
 | `fx.auth.rotateApiKey(id)`                                                     | `write` `auth:api-keys` | New secret once. Owner only                                                                        |
 | `fx.auth.updateApiKey(id, …)`                                                  | `write` `auth:api-keys` | Name / scopes / expiry / allowlist / rate. Re-attenuates                                           |
+| `fx.auth.listTenants()`                                                        | `read` `auth:tenants`   | Memberships for the live session. Session only                                                     |
+| `fx.auth.switchTenant(id)`                                                     | `write` `auth:tenants`  | New access+refresh, new family, `tid` on both. Never Set-Cookie. Session only                      |
+| `fx.auth.createTenant({ name, slug?, id? })`                                   | `write` `auth:tenants`  | Creator becomes a member. Session only                                                             |
+| `fx.auth.upsertTenantRole({ tenantId, roleName, scopes })`                     | `write` `auth:tenants`  | Application scopes only — `console:*` is unknown_scope                                             |
 
-`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization). For
-audit/attribution only, read `fx.principal` — it propagates the originating identity without
-copying into `fx.auth`. Gates never consult `fx.principal`.
+`fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization) and
+propagates `fx.tenant.id`. For audit/attribution only, read `fx.principal` — it propagates the
+originating identity without copying into `fx.auth`. Gates never consult `fx.principal`.
 
 ## Concurrency and retry
 
@@ -214,6 +219,7 @@ keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
 | `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager            |
 | `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST    |
 | `fx.json.stream(chunks)`                  | 200    | `text/event-stream` — JSON `data:` frames, then `data: [DONE]` |
+| `fx.live(signal)`                         | 200    | Same SSE carrier for a live signal (payload frames + `id:`)    |
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control. Pass `fx.stream(...)` into `fx.json.stream` to reach the HTTP client token-by-token.
 
@@ -275,12 +281,12 @@ Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
 
 ## Principals
 
-| Property       | Shape                                                                      |
-| -------------- | -------------------------------------------------------------------------- |
-| `fx.auth`      | `{ userId, scopes, verified?, apiKeyId? }` plus key methods (session only) |
-| `fx.operator`  | `{ id: string \| null }` — Console plane                                   |
-| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?`  |
-| `fx.tenant`    | `{ id: string \| null }` — active tenant                                   |
+| Property       | Shape                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `fx.auth`      | `{ userId, scopes, verified?, apiKeyId? }` plus key and tenant methods (session only) |
+| `fx.operator`  | `{ id: string \| null }` — Console plane                                              |
+| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?`             |
+| `fx.tenant`    | `{ id: string \| null }` — active tenant (propagates on `fx.call`)                    |
 
 **Consequence:** use `fx.auth` / gates for authorization; use `fx.principal` only when a callee
 must log who started the call chain. A key Bearer sets `userId` to the issuer and `apiKeyId`

package/src/auth/api-key-sql.ts

@@ -32,8 +32,8 @@ export async function persistApiKeyRow(
   await sql.execute(
     `INSERT INTO ${table} (
       id, plane, hash, name, scopes, expires_at, rate_limit, ip_allowlist,
-      creator_id, creator_scopes, created_at, last_used_at, revoked_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      creator_id, creator_scopes, created_at, last_used_at, revoked_at, tenant_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(id) DO UPDATE SET
       hash = excluded.hash,
       name = excluded.name,
@@ -44,7 +44,8 @@ export async function persistApiKeyRow(
       creator_id = excluded.creator_id,
       creator_scopes = excluded.creator_scopes,
       last_used_at = excluded.last_used_at,
-      revoked_at = excluded.revoked_at`,
+      revoked_at = excluded.revoked_at,
+      tenant_id = excluded.tenant_id`,
     [
       row.id,
       row.plane,
@@ -59,6 +60,7 @@ export async function persistApiKeyRow(
       row.createdAt,
       row.lastUsedAt,
       row.revokedAt,
+      row.tenantId ?? null,
     ],
   );
 }
@@ -140,9 +142,11 @@ export async function ensureApiKeyTable(
       creator_scopes TEXT NOT NULL DEFAULT '[]',
       created_at BIGINT NOT NULL,
       last_used_at BIGINT,
-      revoked_at BIGINT
+      revoked_at BIGINT,
+      tenant_id TEXT
     )
   `);
+  await conn.exec(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS tenant_id TEXT`);
 }
 
 /**
@@ -203,6 +207,9 @@ function rowFromSql(raw: Record<string, unknown>): ApiKeyRow | null {
     createdAt: asNumberOrNull(raw.created_at ?? raw.createdAt) ?? 0,
     lastUsedAt: asNumberOrNull(raw.last_used_at ?? raw.lastUsedAt),
     revokedAt: asNumberOrNull(raw.revoked_at ?? raw.revokedAt),
+    ...(asString(raw.tenant_id ?? raw.tenantId) !== null
+      ? { tenantId: asString(raw.tenant_id ?? raw.tenantId) }
+      : {}),
   };
 }
 

package/src/auth/api-keys.ts

@@ -31,6 +31,8 @@ export interface CreateApiKeyOptions {
   readonly expiresAt?: number | null;
   readonly rateLimit?: { max: number; per: string } | null;
   readonly ipAllowlist?: readonly string[];
+  /** Optional tenant claim copied onto the key principal. */
+  readonly tenantId?: string | null;
   /** Injectable id / secret / hash (tests). */
   readonly id?: string;
   readonly secret?: string;
@@ -163,6 +165,7 @@ export async function createApiKey(
     createdAt: now(),
     lastUsedAt: null,
     revokedAt: null,
+    ...(options.tenantId !== undefined ? { tenantId: options.tenantId } : {}),
   };
   store.keys.set(id, row);
   await persistRow(store, row);

package/src/auth/config.ts

@@ -16,6 +16,12 @@ import {
   type ResolvedAuthSchema,
 } from "./schema.ts";
 import { sessionCryptoFromAuthOptions, type AuthSessionOptions } from "./plugin.ts";
+import { createTenantStore, type TenantStore } from "./tenants.ts";
+import {
+  resolveTenantAuth,
+  type ResolvedTenantAuth,
+  type TenantAuthOptions,
+} from "./tenant-config.ts";
 
 /** Email + password method knobs. */
 export interface EmailAndPasswordOptions {
@@ -115,6 +121,15 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    * (`gate.auth.secret` is the HMAC pepper).
    */
   readonly apiKeyStore?: ApiKeyStore;
+  /**
+   * Multi-tenancy as an identity dimension. `true` enables defaults
+   * (`source: "claim"`, `required: false`). Off when omitted.
+   */
+  readonly tenant?: boolean | TenantAuthOptions;
+  /**
+   * Shared tenant registry. Created automatically when {@link tenant} is on.
+   */
+  readonly tenantStore?: TenantStore;
   /** Injectable clock. */
   readonly now?: () => number;
 }
@@ -171,6 +186,8 @@ export interface ResolvedGateAuth {
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
   readonly apiKeyStore: ApiKeyStore;
+  readonly tenant: ResolvedTenantAuth | undefined;
+  readonly tenantStore: TenantStore | undefined;
   readonly now: (() => number) | undefined;
 }
 
@@ -279,6 +296,8 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     hooks: auth.hooks,
     sessions: auth.sessions,
     apiKeyStore: auth.apiKeyStore ?? createApiKeyStore({ pepper: secret }),
+    tenant: auth.tenant ? resolveTenantAuth(auth.tenant) : undefined,
+    tenantStore: auth.tenant ? (auth.tenantStore ?? createTenantStore()) : auth.tenantStore,
     now: auth.now,
   };
 }

package/src/auth/index.ts

@@ -260,4 +260,41 @@ export {
   type RoleRow,
   type SessionRow,
   type TablePlane,
+  type TenantMemberRow,
+  type TenantRoleRow,
+  type TenantRow,
 } from "./tables.ts";
+
+export { AUTH_TENANT_TABLES } from "./tenant-tables.ts";
+
+export {
+  AUTH_TENANTS_RESOURCE,
+  DEFAULT_TENANT_ROLE,
+  TenantError,
+  addMember,
+  createTenant,
+  createTenantStore,
+  deleteTenant,
+  getMember,
+  isMember,
+  listMembers,
+  listTenantIds,
+  listTenantsForUser,
+  removeMember,
+  tenantRoleScopeFailure,
+  tenantScopesForMember,
+  upsertTenantRole,
+  type CreateTenantOptions,
+  type TenantPublicRow,
+  type TenantStore,
+  type TenantStoreHooks,
+  type UpsertTenantRoleOptions,
+} from "./tenants.ts";
+
+export {
+  resolveTenantAuth,
+  type ResolvedTenantAuth,
+  type TenantAuthOptions,
+  type TenantResolveContext,
+  type TenantSource,
+} from "./tenant-config.ts";

package/src/auth/plugin.ts

@@ -9,6 +9,7 @@ import { plugin, type PluginDef } from "../kernel/plugin.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import { AUTH_TABLES } from "./tables.ts";
+import { AUTH_TENANT_TABLES } from "./tenant-tables.ts";
 
 /** Session knobs beyond raw access/refresh TTLs. */
 export interface AuthSessionOptions {
@@ -83,7 +84,11 @@ export function auth(options: AuthPluginOptions = {}): PluginDef {
     /* principals resolved by session / API key middleware at runtime */
   });
 
-  for (const name of Object.values(AUTH_TABLES)) {
+  const tables: readonly string[] = [
+    ...Object.values(AUTH_TABLES),
+    ...Object.values(AUTH_TENANT_TABLES),
+  ];
+  for (const name of tables) {
     builder = builder.table(name, undefined, {
       plane: name.includes("operator")
         ? "operator"

package/src/auth/sessions.ts

@@ -43,6 +43,11 @@ export interface AccessClaims {
    * Validated when the verifier supplies {@link VerifyAccessOptions.audience}.
    */
   readonly aud?: string;
+  /**
+   * Active tenant for this access token (request-scoped).
+   * Never stored on the session row — switching issues a new token pair.
+   */
+  readonly tid?: string;
 }
 
 /** Options for {@link createSessionStore}. */
@@ -106,6 +111,8 @@ export async function issueSession(
     readonly id: string;
     readonly plane: AuthPlane;
     readonly scopes: Iterable<string>;
+    /** Optional tenant claim (not stored on the session row). */
+    readonly tenantId?: string | null;
   },
 ): Promise<IssuedSession> {
   const now = crypto.now ?? (() => Date.now());
@@ -136,6 +143,7 @@ export async function issueSession(
   store.sessions.set(sessionId, session);
 
   const refreshRaw = `rt_${cryptoRandomId()}`;
+  const tid = principal.tenantId ?? undefined;
   const refreshRow: RefreshTokenRow = {
     id: cryptoRandomId(),
     sessionId,
@@ -144,6 +152,7 @@ export async function issueSession(
     expiresAt: t + refreshTtl,
     usedAt: null,
     revokedAt: null,
+    ...(tid !== undefined && tid !== "" ? { tid } : {}),
   };
   store.refresh.set(refreshRow.id, refreshRow);
 
@@ -156,6 +165,7 @@ export async function issueSession(
     iat: t,
     exp: accessExpiresAt,
     ...(crypto.audience !== undefined ? { aud: crypto.audience } : {}),
+    ...(tid !== undefined && tid !== "" ? { tid } : {}),
   });
 
   return { session, accessToken, refreshToken: refreshRaw, accessExpiresAt };
@@ -211,6 +221,7 @@ export async function rotateRefresh(
   const refreshTtl = crypto.refreshTtlMs ?? REFRESH_TTL_MS;
 
   const newRefreshRaw = `rt_${cryptoRandomId()}`;
+  const rotatedTid = existing.tid;
   const newRefresh: RefreshTokenRow = {
     id: cryptoRandomId(),
     sessionId: session.id,
@@ -219,6 +230,9 @@ export async function rotateRefresh(
     expiresAt: t + refreshTtl,
     usedAt: null,
     revokedAt: null,
+    ...(rotatedTid !== undefined && rotatedTid !== null && rotatedTid !== ""
+      ? { tid: rotatedTid }
+      : {}),
   };
   store.refresh.set(newRefresh.id, newRefresh);
 
@@ -231,6 +245,9 @@ export async function rotateRefresh(
     iat: t,
     exp: accessExpiresAt,
     ...(session.audience !== undefined ? { aud: session.audience } : {}),
+    ...(rotatedTid !== undefined && rotatedTid !== null && rotatedTid !== ""
+      ? { tid: rotatedTid }
+      : {}),
   });
 
   return {
@@ -291,6 +308,7 @@ export async function issueSessionWithScopes(
     readonly id: string;
     readonly plane: AuthPlane;
     readonly scopes: Iterable<string>;
+    readonly tenantId?: string | null;
   },
 ): Promise<IssuedSession> {
   return issueSession(store, crypto, principal);

package/src/auth/tables.ts

@@ -98,6 +98,8 @@ export interface ApiKeyRow {
   lastUsedAt: number | null;
   /** Epoch-ms when revoked; `null` while active. */
   revokedAt: number | null;
+  /** Optional tenant claim (tier-1 API-key tenancy). */
+  tenantId?: string | null;
 }
 
 /** Pending operator invitation (invite-only plane). */
@@ -136,4 +138,34 @@ export interface RefreshTokenRow {
   expiresAt: number;
   usedAt: number | null;
   revokedAt: number | null;
+  /** Tenant id stamped on this refresh row (request-scoped; not on the session). */
+  tid?: string | null;
+}
+
+/** Tenant registry row. */
+export interface TenantRow {
+  id: string;
+  name: string;
+  slug: string | null;
+  createdAt: number;
+  createdBy: string;
+}
+
+/** N:N membership — one user, many tenants; one tenant, many users. */
+export interface TenantMemberRow {
+  id: string;
+  tenantId: string;
+  userId: string;
+  /** Tenant role name (expanded via {@link TenantRoleRow}). */
+  role: string;
+  createdAt: number;
+}
+
+/** Tenant-scoped role → application scope names. */
+export interface TenantRoleRow {
+  tenantId: string;
+  roleName: string;
+  scopes: string[];
+  createdAt: number;
+  updatedAt: number;
 }

package/src/auth/tenant-config.ts

@@ -0,0 +1,74 @@
+/**
+ * `gate.auth.tenant` config — identity dimension opt-in.
+ */
+
+/** How the request names a tenant. */
+export type TenantSource = "claim" | "header" | "subdomain" | "resolve";
+
+/** Public `gate.auth.tenant` bag (boolean shorthand or options). */
+export interface TenantAuthOptions {
+  /**
+   * Pure B2B: every user-plane request needs a tenant.
+   * Default `false` (B2C+B2B coexistence).
+   */
+  readonly required?: boolean;
+  /** Resolution source. Default `"claim"`. */
+  readonly source?: TenantSource;
+  /** Header name for `source: "header"`. Default `x-oke-tenant`. */
+  readonly header?: string;
+  /**
+   * Tier-3 escape hatch. When it returns an id, membership is still
+   * checked unless {@link TenantAuthOptions.authoritative} is true.
+   */
+  readonly resolve?: (ctx: TenantResolveContext) => string | null | undefined;
+  /**
+   * When true, {@link TenantAuthOptions.resolve} is trusted without a
+   * membership query. Default false (fail-safe).
+   */
+  readonly authoritative?: boolean;
+}
+
+/** Context passed to {@link TenantAuthOptions.resolve}. */
+export interface TenantResolveContext {
+  readonly auth: {
+    readonly userId: string | null;
+    readonly tenantId?: string | null;
+  };
+  readonly request?: Request;
+  readonly claimTenantId: string | null;
+}
+
+/** Fully resolved tenant auth config. */
+export interface ResolvedTenantAuth {
+  readonly enabled: true;
+  readonly required: boolean;
+  readonly source: TenantSource;
+  readonly header: string;
+  readonly resolve?: TenantAuthOptions["resolve"];
+  readonly authoritative: boolean;
+}
+
+/**
+ * Normalize `gate.auth.tenant`.
+ *
+ * @param input - `true` or options bag
+ */
+export function resolveTenantAuth(input: true | TenantAuthOptions): ResolvedTenantAuth {
+  if (input === true) {
+    return {
+      enabled: true,
+      required: false,
+      source: "claim",
+      header: "x-oke-tenant",
+      authoritative: false,
+    };
+  }
+  return {
+    enabled: true,
+    required: input.required === true,
+    source: input.source ?? "claim",
+    header: input.header ?? "x-oke-tenant",
+    ...(input.resolve !== undefined ? { resolve: input.resolve } : {}),
+    authoritative: input.authoritative === true,
+  };
+}