okengine 0.18.5 → 0.19.0

package/site/content/docs/elements/gate/tenancy.mdx

@@ -0,0 +1,372 @@
+---
+title: "Tenancy"
+description: "Opt into gate.auth.tenant so requests resolve fx.tenant.id from claim, header, or subdomain."
+icon: "Building2"
+source: "docs/spec/unified-theory.md"
+---
+
+Tenancy is an identity **dimension** under `gate.auth.tenant`, not a separate gate you attach with
+`.gate(...)`. When enabled, the runtime resolves a tenant for the request and exposes it as
+`fx.tenant.id`. Your SQL / KV / files code (and optional RLS) use that id for isolation.
+
+For developers shipping B2B or mixed B2C+B2B apps on okengine — enable the dimension, filter every
+store access by `fx.tenant.id`.
+
+<Callout title="The one rule">
+  Enable `gate.auth.tenant`, keep membership checks on — then filter every store access by
+  `fx.tenant.id`. Do not invent a `gate.auth.tenant` trigger handle.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Turn tenancy on
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: {
+    auth: {
+      tenant: true, // claim source · header x-oke-tenant · required: false
+    },
+  },
+});
+```
+
+Or pass options:
+
+```typescript
+tenant: {
+  required: true, // every user-plane request needs a tenant
+  source: "header", // "claim" | "header" | "subdomain" | "resolve"
+  header: "x-oke-tenant",
+}
+```
+
+</Step>
+
+<Step>
+### Protect the route and scope data
+
+```typescript title="src/flows/invoices/list.ts"
+import { on, flow, http } from "okengine";
+import { eq } from "drizzle-orm";
+import { member } from "@/core/gate";
+import { db, invoices } from "@/schema";
+
+export const list = on(
+  http.get().gate(member),
+  flow({
+    do: async (_, fx) => {
+      const tenantId = fx.tenant.id;
+      if (!tenantId) return fx.fail("Forbidden", { reason: "tenant_required" });
+      return await fx.store(db).select().from(invoices).where(eq(invoices.tenantId, tenantId));
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Switch tenant (session)
+
+```typescript
+// Session-only
+const session = await fx.auth.switchTenant("ten_acme");
+// New access token carries tid; subsequent requests resolve fx.tenant.id
+```
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From claim-based B2C+B2B to pure B2B, custom resolve, and Flow opt-out:
+
+<Tabs items={["Claim", "Required", "Resolve", "Opt-out"]}>
+
+<Tab value="Claim">
+
+Default when `tenant: true`: `source: "claim"`, `required: false`, header name `x-oke-tenant`
+(unused until you switch source).
+
+The signed session / key claim supplies `tid`. Membership is still checked unless
+`authoritative: true` on a custom `resolve`.
+
+</Tab>
+
+<Tab value="Required">
+
+Pure B2B — every user-plane request must resolve a tenant:
+
+```typescript
+tenant: {
+  required: true,
+  source: "header",
+  header: "x-oke-tenant",
+}
+```
+
+**Consequence:** missing tenant fails before `do` with
+`Forbidden` · `reason: "tenant_required"`. Operator-plane Flows are not forced through the
+same required path.
+
+</Tab>
+
+<Tab value="Resolve">
+
+Custom resolver (tier-3 escape hatch). Membership is still checked unless `authoritative`:
+
+```typescript
+tenant: {
+  source: "resolve",
+  resolve: ({ auth, request, claimTenantId }) => {
+    if (claimTenantId) return claimTenantId;
+    return request?.headers.get("x-workspace") ?? null;
+  },
+  // authoritative: true  // trust resolve without membership query (fail-open — rare)
+}
+```
+
+</Tab>
+
+<Tab value="Opt-out">
+
+When tenancy is on, Flows default to tenant-scoped (role scopes may union into `fx.auth.scopes`).
+Opt a Flow out with `tenantScoped: false`:
+
+```typescript
+flow("billing.globalReport", {
+  plane: "operator",
+  tenantScoped: false,
+  do: async (_, fx) => {
+    // No tenant-role scope union; fx.tenant.id may still be set from the request
+  },
+});
+```
+
+</Tab>
+
+</Tabs>
+
+## Resolution Sources
+
+<Callout title="Detailed section">
+  Three tiers: signed claim (no membership query), client-supplied header/subdomain (membership
+  required), and custom `resolve` (membership unless `authoritative`).
+</Callout>
+
+<Tabs items={["claim", "header", "subdomain", "resolve"]}>
+
+<Tab value="claim">
+
+Signed `tid` on the session / API key. Fast path — no membership query:
+
+```typescript
+tenant: true;
+// expands to source: "claim", required: false, header: "x-oke-tenant"
+```
+
+After `fx.auth.switchTenant(id)`, new access tokens carry `tid` for this source.
+
+</Tab>
+
+<Tab value="header">
+
+Client sends the configured header; membership is required:
+
+```typescript
+tenant: {
+  source: "header",
+  header: "x-oke-tenant", // default name
+}
+```
+
+```bash
+curl -X GET http://localhost:6530/invoices \
+  -H "authorization: Bearer …" \
+  -H "x-oke-tenant: ten_acme"
+```
+
+Not a member → `Forbidden` · `reason: "not_member"`. Anonymous with a header →
+`Unauthorized`.
+
+</Tab>
+
+<Tab value="subdomain">
+
+First Host label is the tenant id (`acme.example.com` → `acme`). Needs at least three
+labels; membership is required:
+
+```typescript
+tenant: {
+  source: "subdomain";
+}
+```
+
+Internal / cron calls without an HTTP request keep the stamped claim when present.
+
+</Tab>
+
+<Tab value="resolve">
+
+Callback receives `{ auth, request, claimTenantId }`. Membership still runs unless
+`authoritative: true`:
+
+```typescript
+tenant: {
+  source: "resolve",
+  resolve: ({ claimTenantId, request }) =>
+    claimTenantId ?? request?.headers.get("x-workspace") ?? null,
+}
+```
+
+**Consequence:** `authoritative: true` is fail-open — use only when you own the resolver’s
+trust boundary.
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option          | Type                                                    | Default        | Meaning                                     |
+| --------------- | ------------------------------------------------------- | -------------- | ------------------------------------------- |
+| `required`      | `boolean`                                               | `false`        | Reject user-plane requests without a tenant |
+| `source`        | `"claim"` \| `"header"` \| `"subdomain"` \| `"resolve"` | `"claim"`      | Where the tenant id comes from              |
+| `header`        | `string`                                                | `x-oke-tenant` | Header name when `source: "header"`         |
+| `resolve`       | `(ctx) => string \| null \| undefined`                  | —              | Custom resolver; membership still checked   |
+| `authoritative` | `boolean`                                               | `false`        | Trust `resolve` without a membership query  |
+
+`tenant: true` expands to `{ required: false, source: "claim", header: "x-oke-tenant", authoritative: false }`.
+
+## `fx.auth` tenant methods
+
+Session-only. API keys get `Forbidden` with `reason: "session_only"`:
+
+| Method                                             | Meaning                              |
+| -------------------------------------------------- | ------------------------------------ |
+| `listTenants()`                                    | Tenants the user belongs to          |
+| `switchTenant(id)`                                 | Mint a new session family with `tid` |
+| `createTenant({ name, slug?, id? })`               | Create + add caller as member        |
+| `deleteTenant(id)`                                 | Remove tenant                        |
+| `addMember` / `removeMember`                       | Membership                           |
+| `listMembers(tenantId)`                            | Members of a tenant                  |
+| `upsertTenantRole({ tenantId, roleName, scopes })` | Role → scopes (unioned when scoped)  |
+
+```typescript title="src/flows/tenants/switch.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { member } from "@/core/gate";
+
+export const switchTenant = on(
+  http.post().gate(member),
+  flow({
+    in: z.object({ tenantId: z.string() }),
+    do: async ({ tenantId }, fx) => fx.auth.switchTenant(tenantId),
+  }),
+);
+```
+
+## Store isolation
+
+| Facet | Pattern                                                                  |
+| ----- | ------------------------------------------------------------------------ |
+| SQL   | Filter / RLS by `fx.tenant.id` (and table tenant policies when declared) |
+| KV    | Optional `{tenantId}:` key prefix when the namespace is tenant-scoped    |
+| Files | Path / ACL under the active tenant                                       |
+
+RLS helper for a tenant column:
+
+```typescript
+import { store, field } from "okengine";
+
+export const invoices = store.schema.table(
+  "invoices",
+  {
+    id: field.text().primaryKey(),
+    tenantId: field.text(),
+    total: field.integer(),
+  },
+  [store.schema.policy.tenant("tenantId"), store.schema.rls()],
+);
+```
+
+Globally shared tables when tenancy is on need an explicit opt-out:
+
+```typescript
+store.schema.table("plans", { id: field.text().primaryKey() }, [store.schema.unscoped()]);
+```
+
+**Consequence:** Gate resolves identity; your Flow still owns the filter. A missing `where
+tenant_id = …` is a data leak, not a Gate bug.
+
+## Denial Mapping
+
+| Situation                                  | Code           | `error.data.reason` |
+| ------------------------------------------ | -------------- | ------------------- |
+| `required: true`, authenticated, no tenant | `Forbidden`    | `tenant_required`   |
+| Header / subdomain / resolve, not a member | `Forbidden`    | `not_member`        |
+| Header / subdomain without session         | `Unauthorized` | —                   |
+| Tenant admin from API key                  | `Forbidden`    | `session_only`      |
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="fx.tenant.id is null on every request">
+  Tenancy off, `required: false` with no claim/header, or membership failed. Enable
+  `gate.auth.tenant`, send the claim / header, and confirm the user is a member.
+</Accordion>
+
+<Accordion title="Forbidden · session_only on listTenants / switchTenant">
+  Tenant admin methods refuse API-key principals. Use a user session.
+</Accordion>
+
+<Accordion title="Tenant-granted scope does not authorize a route">
+  The Flow set `tenantScoped: false`, or the role was never upserted. Tenant-role union only applies
+  when the Flow is tenant-scoped (default when tenancy is on).
+</Accordion>
+
+<Accordion title="required: true rejects browser calls">
+  Pure B2B needs a tenant on every user-plane request — send `tid` (claim) or the configured header
+  before calling gated APIs.
+</Accordion>
+
+<Accordion title="Forbidden · not_member on header / subdomain">
+  The supplied tenant id is not in the user’s membership set. Add the member, or switch to `source:
+  "claim"` after `switchTenant` so the signed `tid` is trusted.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Authentication](/docs/elements/gate/auth) — `gate.auth` and `fx.auth`
+- [Authorization](/docs/elements/gate/authorization) — scopes after tenant-role union
+- [RLS](/docs/elements/gate/rls) — `policy.tenant` and the SQL stamp
+- [Store](/docs/elements/store) — SQL / KV / files facets
+- [HTTP](/docs/elements/flow/http) — gated routes that read `fx.tenant`
+
+## Next
+
+<Cards>
+  <Card
+    title="RLS"
+    description="policy.tenant and the SQL identity stamp."
+    href="/docs/elements/gate/rls"
+  />
+  <Card
+    title="Vault Element"
+    description="Secrets and protected configuration."
+    href="/docs/elements/vault"
+  />
+  <Card title="Gate Overview" description="Return to Gate overview." href="/docs/elements/gate" />
+</Cards>

package/site/content/docs/elements/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Elements"
-description: "The eight closed semantic primitives of the OKEngine backend model."
+description: "The closed set of eight semantic primitives forming the entire OKEngine backend model."
 icon: "Boxes"
 source: "docs/spec/unified-theory.md"
 ---
@@ -8,8 +8,8 @@ source: "docs/spec/unified-theory.md"
 Forty backend concerns collapse into eight semantic primitives. An element earns its place only with **irreducible physics**.
 
 <Callout title="Closed primitive set">
-  There is no ninth element. New infrastructure creates a protocol driver or plugin, preserving a
-  small mental model.
+  There is no ninth element. Every backend capability belongs to one of the eight elements. New
+  infrastructure creates a protocol driver or plugin, preserving a small mental model.
 </Callout>
 
 ```text
@@ -19,37 +19,47 @@ Drivers connect the model to infrastructure.
 Providers and Recipes choose where that infrastructure runs.
 ```
 
+## The Structural Anatomy
+
+Every backend concern is mapped across three conceptual tiers:
+
+| Tier             | Question Answered                   | Definition & Scope                                                          |
+| ---------------- | ----------------------------------- | --------------------------------------------------------------------------- |
+| **Elements**     | _What is the thing?_                | The 8 closed primitives representing irreducible backend physics.           |
+| **Capabilities** | _What can it do?_                   | Explicit facets, triggers, and execution mechanics within each element.     |
+| **Composition**  | _What happens when they cooperate?_ | Emergent system properties (Realtime, Live Queries, Multi-Tenancy, Agents). |
+
 ## The Eight Primitives
 
 <Cards>
   <Card
     title="Flow"
-    description="Behavior — on(Trigger) → Effects via fx."
+    description="Behavior — on(Trigger) → Effects via fx. Unified endpoints, jobs, consumers, and durable sagas."
     href="/docs/elements/flow"
   />
   <Card
     title="Signal"
-    description="Data in motion — delivery physics as a property (once, broadcast, live)."
+    description="Data in motion — once, broadcast, and live with mandatory delivery physics."
     href="/docs/elements/signal"
   />
   <Card
     title="Store"
-    description="Data at rest — SQL, KV, files with image transforms, and search."
+    description="Data at rest — SQL, KV, files with image transforms, and search behind one handle."
     href="/docs/elements/store"
   />
   <Card
     title="Clock"
-    description="Time — schedules, intervals, durable sleeps, and time travel."
+    description="Time — schedules, intervals, durable sleep, and deterministic time travel."
     href="/docs/elements/clock"
   />
   <Card
     title="Gate"
-    description="Permission to act — auth, tenancy, ABAC, and rate limits at the trigger."
+    description="Permission to act — auth, tenancy, ABAC/RBAC, and rate limits at the trigger."
     href="/docs/elements/gate"
   />
   <Card
     title="Vault"
-    description="Protected knowledge — fail-loud secret contracts and redacted values."
+    description="Protected knowledge — fail-loud secret contracts, dynamic config, and redacted values."
     href="/docs/elements/vault"
   />
   <Card
@@ -59,7 +69,7 @@ Providers and Recipes choose where that infrastructure runs.
   />
   <Card
     title="AI"
-    description="Reaching machine intelligence — models, prompts, agents, and RAG."
+    description="Reaching machine intelligence — models, prompts, agents, and MCP tool boundaries."
     href="/docs/elements/ai"
   />
 </Cards>