okengine 0.18.4 → 0.19.0

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

@@ -1,436 +0,0 @@
----
-title: "Gate"
-description: "Permission to act — policies, rate limits, and built-in auth on the HTTP trigger, evaluated before any effect runs."
-icon: "ShieldCheck"
-source: "docs/spec/unified-theory.md"
----
-
-Gate answers **"may this happen?"** before it happens: is this a verified member? has this IP
-burned its minute quota? Attach gates to the HTTP trigger — the pipeline checks them before a
-store write, emit, or channel send runs.
-
-> **Same Semantics Across Planes:** OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes: users via sessions, operators via Console policies, and agents via `mcp.tool()` + OAuth 2.1 AS.
-
-<Callout title="The one rule">
-  Every HTTP trigger declares posture: attach a real gate, or attach `.public()`. Omitting both
-  fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Declare policies
-
-Policies are named predicates; rate limits are declarative budgets. Import the module before
-`oke()` — they auto-register. `oke({ gate: { policies } })` is still valid and additive.
-
-```typescript title="src/gates.ts"
-import { gate } from "okengine";
-
-export const member = gate.policy("member", ({ auth }) => !!auth.verified);
-
-export const canBook = gate.scope("booking:create");
-
-export const fair = gate.rate({
-  max: 60,
-  per: "1m",
-  keyBy: "ip",
-});
-```
-
-`gate.scope(name)` is sugar for
-`gate.policy(name, ({ auth }) => auth.scopes.has(name))` — one string is both the policy id and
-the scope checked.
-
-```typescript title="src/app.ts"
-import "./gates";
-import { oke } from "okengine";
-
-export const app = oke({ name: "shop", env: "dev" });
-```
-
-</Step>
-
-<Step>
-### Attach them to triggers
-
-`.gate(...)` composes left to right — first denial wins. Public routes must say so explicitly. Path and name can come from the file tree — see [Project structure](/docs/get-started/project-structure).
-
-```typescript title="src/flows/links/shorten.ts"
-import { on, flow, http, gate } from "okengine";
-import { member, canBook, fair } from "../../gates";
-
-export const health = on(
-  http.get("/health").public(),
-  flow("health.check", {
-    do: () => ({ ok: true }),
-  }),
-);
-
-export const write = gate.all(member, canBook, fair);
-
-export const shorten = on(
-  http.post("/links").gate(write),
-  flow("links.shorten", {
-    in: NewLink,
-    out: LinkCode,
-    errors: { Taken },
-    do: async ({ url, code }, fx) => {
-      /* runs only if every gate passed */
-    },
-  }),
-);
-```
-
-A single gate stays `.gate(member)`. Reuse two or more with `gate.all` — `.gate(write)`
-flattens. `http.resource(path, ops).gate(...)` stamps every verb. Public routes use
-`.public()` — do **not** put `gate.public` in `gate.policies`.
-
-</Step>
-
-<Step>
-### See typed denials
-
-A denied request never reaches `do`. It returns one of three typed failures:
-
-| Gate result                      | Typed failure                         |
-| -------------------------------- | ------------------------------------- |
-| Policy denied, not authenticated | `Unauthorized`                        |
-| Policy denied, authenticated     | `Forbidden` (with gate name + reason) |
-| Rate limit exceeded              | `RateLimited` (with `retryAfterMs`)   |
-
-</Step>
-
-</Steps>
-
-## First denial wins
-
-<GatePipeline />
-
-`.gate(member, canBook, fair)` and `.gate(write)` (from `gate.all`) evaluate left
-to right — first denial wins (`Unauthorized` · `Forbidden` · `RateLimited`); later
-gates are skipped. `do` runs only when every gate passed.
-
-## `oke({ gate })` bag
-
-| Option          | Type                    | Default  | Meaning                                                         |
-| --------------- | ----------------------- | -------- | --------------------------------------------------------------- |
-| `policies`      | `GateDecl[]`            | `[]`     | Policy / rate decls — `gate.all` handles flatten to members     |
-| `auth`          | `GateAuthOptions`       | —        | Builtin hybrid sessions + `/auth/*` Flows (see below)           |
-| `rateLimit`     | `{ enabled?: boolean }` | see note | When auth is on, defaults `true` — stricter rates on auth paths |
-| `unguardedHttp` | `"deny"` \| `"allow"`   | `"deny"` | `"allow"` skips posture audit **only** when `env === "test"`    |
-
-## Declarations
-
-| Declaration                           | Question it answers                         | Evaluated against                  |
-| ------------------------------------- | ------------------------------------------- | ---------------------------------- |
-| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)           | auth / operator / request metadata |
-| `gate.scope(name)`                    | Does `auth.scopes` contain this exact name? | `auth.scopes`                      |
-| `gate.public` / `.public()`           | Intentionally unauthenticated surface       | always allows                      |
-| `gate.rate(options)`                  | Is there budget left for this subject?      | an atomic counter on the kv driver |
-| `gate.all(...members)`                | Reuse this chain on many triggers           | flattens; each member is evaluated |
-
-Pass `{ check, description }` on `gate.policy` when you want a human title in the Console (falls
-back to the policy name). The name `"public"` is reserved — mark the trigger with
-`.public()`, not `gate.policy("public", …)`.
-
-`gate.all()` with no members throws. Nested `all` handles flatten.
-Members auto-register when declared; `oke({ gate: { policies: [write] } })` is additive.
-
-### Policy context
-
-| Field      | Contents                                                 |
-| ---------- | -------------------------------------------------------- |
-| `auth`     | User principal: `userId`, `scopes` (a `Set`), `verified` |
-| `operator` | Operator principal (Console plane): `id`                 |
-| `meta`     | Request metadata for keying: `ip`, `userId`, …           |
-
-A policy name containing `:` is also a `Module:Action` permission for Console role reviews.
-Fine-grained authorization (`gate.scope`, roles) stays opt-in — attach it only where you need it.
-
-### Rate options
-
-| Option        | Type         | Default                    | Meaning                                                  |
-| ------------- | ------------ | -------------------------- | -------------------------------------------------------- |
-| `max`         | number       | — (**required**)           | Takes allowed within `per`                               |
-| `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)              |
-| `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)                  |
-| `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                                        |
-| `overridable` | boolean      | `false`                    | Catalog flag in Console (rate edit UI not shipped)       |
-| `description` | string       | —                          | Human title in the Console (falls back to the rate name) |
-
-| Strategy                 | Behavior                                               |
-| ------------------------ | ------------------------------------------------------ |
-| `sliding-window-counter` | Near-exact, two keys, no boundary bursts — the default |
-| `fixed-window`           | Cheapest; allows bursts at window boundaries           |
-| `sliding-log`            | Exact; stores one timestamp per take                   |
-| `token-bucket`           | Steady refill; permits saved-up bursts                 |
-| `leaky-bucket`           | Smooths output to a constant rate                      |
-
-All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory
-driver in tests. Boot opens a dedicated `oke:gates` namespace on **`drivers.store.kv`**
-(`memory` in test · `redis` in `dev`/`prod`) so multi-instance rate limits share counters.
-
-## Auth posture at boot
-
-Every HTTP trigger must carry a gate or `.public()`. Omitting both fails boot with
-`GateBootError` — message starts with `gate boot failed —` and lists every gap.
-
-```typescript
-on(http.get("/health").public(), flow("health.check", {/* … */}));
-on(http.post("/bookings").gate(member, canBook), flow("bookings.create", {/* … */}));
-```
-
-**Consequence:** first `fetch` / `execute` auto-boots (`autoBoot` defaults to `true`).
-`oke({ autoBoot: false })` is a unit-test escape hatch only. A rate-only chain is declared
-posture but does **not** authenticate.
-
-`gate: { unguardedHttp: "allow" }` skips the audit **only** when `env === "test"`.
-In `dev` / `prod` migrate with per-trigger `.public()`.
-
-## Built-in auth (`gate.auth`)
-
-Enable hybrid sessions (Bearer access + revocable refresh). Auth HTTP surfaces are ordinary
-Bindings under `/auth` — same posture audit and pipeline as your app Flows:
-
-```typescript title="src/app.ts"
-import { oke } from "okengine";
-import { member, canBook } from "./gates";
-
-export const app = oke({
-  name: "shop",
-  env: "dev",
-  gate: {
-    auth: {
-      emailAndPassword: { enabled: true },
-      session: { freshAgeMs: 24 * 60 * 60_000 },
-    },
-    policies: [member, canBook],
-  },
-});
-```
-
-| Surface                    | When                                   |
-| -------------------------- | -------------------------------------- |
-| `POST /auth/sign-up/email` | `emailAndPassword.enabled`             |
-| `POST /auth/sign-in/email` | `emailAndPassword.enabled`             |
-| `POST /auth/refresh`       | when `gate.auth` is set                |
-| `POST /auth/revoke`        | when `gate.auth` is set                |
-| `GET /auth/me`             | Bearer session (`auth.session` policy) |
-
-| Auth option                                 | Default   | Meaning                                                                                                                    |
-| ------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `secret`                                    | minted\*  | HMAC for access tokens (\*`prod` requires you set it)                                                                      |
-| `basePath`                                  | `"/auth"` | HTTP prefix for auth Flows                                                                                                 |
-| `http`                                      | `true`    | `false` = secret/tables only (no `/auth/*` Bindings)                                                                       |
-| `audience`                                  | `oke-app` | Audience stamped on access tokens                                                                                          |
-| `emailAndPassword.enabled`                  | `false`   | Sign-up / sign-in email Flows                                                                                              |
-| `emailAndPassword.requireEmailVerification` | `false`   | Block sign-in until email is verified                                                                                      |
-| `passwordPolicy`                            | secure\*  | `\*` minLength 8, letter + number + upper + lower + special (`requireSpecial`); sign-up → `AuthFailed` / `password_policy` |
-| `breachCheck`                               | unset     | `(password) => Promise<boolean>` — `true` rejects as `password_breached`                                                   |
-| `session.freshAgeMs`                        | 24h       | Window for step-up `auth.fresh` policy                                                                                     |
-| `session.accessTtlMs` / `refreshTtlMs`      | 14m / 30d | Access / refresh lifetimes                                                                                                 |
-| `session.idleTtlMs`                         | unset     | Opt-in: reject refresh when idle too long                                                                                  |
-| `session.absoluteTtlMs`                     | unset     | Opt-in: hard cap from session creation                                                                                     |
-| `session.singleSessionPerUser`              | `false`   | Opt-in: issuing a session revokes other families for that user                                                             |
-| `cookies.enabled`                           | `false`   | Opt-in HttpOnly cookie mirror (Bearer stays default)                                                                       |
-| `secondaryStorage.enabled`                  | `false`   | Hot auth data in `store.kv` when configured                                                                                |
-| `tenant`                                    | unset     | Opt-in identity dimension — `true` or `{ required, source, header, resolve, authoritative }`                               |
-| `user` / `session` / …                      | defaults  | `modelName` / `fields` / `additionalFields`                                                                                |
-
-HIBP via `createHibpBreachCheck` from `okengine/auth` (k-anonymity range API; requires
-`userAgent`; `onError` defaults to `"reject"` — fail closed while the check is enabled):
-
-```typescript
-import { createHibpBreachCheck } from "okengine/auth";
-
-gate: {
-  auth: {
-    emailAndPassword: { enabled: true },
-    breachCheck: createHibpBreachCheck({ userAgent: "shop/1.0" }),
-  },
-}
-```
-
-Customize tables, then `oke schema generate` (`.oke/schema/oke.ts`; `--check` in CI). Extra
-sign-in shapes: [Plugins](/docs/plugins). Call auth from
-[createClient](/docs/reference/client) — helpers in `okengine/client/auth`.
-
-## Tenants (identity dimension)
-
-`gate.auth.tenant: true` (or an options bag) is **not** a second authorization system and not an
-organizations product. Tenant is a dimension of identity, like `fx.auth` / `fx.operator`.
-
-```typescript
-export const app = oke({
-  name: "shop",
-  gate: { auth: { tenant: true } },
-});
-```
-
-| Option          | Default        | Meaning                                                                                          |
-| --------------- | -------------- | ------------------------------------------------------------------------------------------------ |
-| `required`      | `false`        | Pure B2B: authenticated user-plane requests without a tenant are `Forbidden` / `tenant_required` |
-| `source`        | `"claim"`      | `"claim"` · `"header"` · `"subdomain"` · `"resolve"`                                             |
-| `header`        | `x-oke-tenant` | Header name when `source` is `"header"`                                                          |
-| `resolve`       | unset          | Callback that returns an id; membership is still checked unless `authoritative`                  |
-| `authoritative` | `false`        | Trust `resolve` without a membership query                                                       |
-
-Three tiers, fail-safe:
-
-1. **Claim** — signed JWT `tid` or API-key `tenantId`. The id is trusted; no membership query.
-2. **Header / subdomain** — never trust a client-supplied id without membership.
-3. **`resolve`** — still membership-checked unless `authoritative: true`.
-
-`required: false` (default) is B2C+B2B: `fx.tenant.id` may be `null`. Internal / cron / `fx.call`
-have no HTTP request — header and subdomain sources keep the stamped claim.
-
-`fx.auth.switchTenant(id)` issues a **new** access+refresh pair and a **new** family (so tab A
-rotation cannot reuse-detect tab B). It never Set-Cookies.
-
-Refresh copies that row's `tid`; tenant-role scopes never melt into the JWT.
-
-`fx.auth.listTenants` / `createTenant` / `addMember` / `upsertTenantRole` are session-only
-(`auth:tenants`). Tenant roles may grant application scopes only — `console:*` fails like an
-unknown name.
-
-Live `fx.auth.scopes` unions those grants only when `fx.tenant.id` is set, the flow is
-tenant-scoped (default on; `flow({ tenantScoped: false })` opts out), and user-plane.
-`gate.scope()` still reads `auth.scopes.has(name)`.
-
-SQL stamps `oke.tenant()` when tenancy is on — [Store](/docs/elements/store) and
-built-in [Vault](/docs/elements/vault#tenant-isolation-built-in-store) ciphertext.
-
-## API keys
-
-A key is the **issuer with fewer gates** — not a second permission system.
-Bearer secrets authenticate as the creator; `fx.auth.scopes` shrink to the key.
-
-| Field                               | Session        | API key                 |
-| ----------------------------------- | -------------- | ----------------------- |
-| `fx.auth.userId` / `fx.operator.id` | subject        | creator (`creatorId`)   |
-| `fx.auth.scopes`                    | session scopes | key scopes (attenuated) |
-| `fx.auth.apiKeyId`                  | `null`         | key id                  |
-| WideEvent `principal`               | subject        | issuer                  |
-| `dimensions.api_key`                | absent         | key id                  |
-
-`gate.auth` always creates a shared key store (HMAC-SHA-256 with `gate.auth.secret`).
-Do not pass `apiKeyStore` unless you are injecting a test Map.
-
-<Callout title="Keys live on the app database">
-  With `store.sql()`, boot hydrates public `oke_api_keys` on that connection (`DATABASE_URL`) and
-  write-through persists create / rotate / revoke. Console **Access** attaches this host store — it
-  does not keep a second key database.
-</Callout>
-
-Session Flows manage keys via [fx](/docs/reference/fx) (`createApiKey`, `listApiKeys`,
-`revokeApiKey`, `rotateApiKey`, `updateApiKey`). A key-authenticated caller cannot.
-
-Declare `effects.reads: ["auth:api-keys"]` / `effects.writes: ["auth:api-keys"]` — never
-`sql:oke_api_keys`. Console **Access** (`:6533` → `/access`) mints operator keys as the
-operator, and user-plane keys only as a picked issuer (`creatorUserId`).
-
-Verify rejects expired, revoked, allowlist-miss, and over-rate secrets with `401`
-and no `api_key` dimension.
-
-## Identity and decisions
-
-Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
-`fx.auth` (Console: `fx.operator`). Audit across `fx.call` uses read-only `fx.principal`
-(see [fx](/docs/reference/fx)).
-
-Pass **and** deny land on the run's `gates` dimension. Console (`:6533` → `/flows`) shows the
-chain on the flow contract. Rate `overridable` is a catalog flag only — Clock schedules are what the Console can
-edit live today.
-
-<Callout title="RLS reads the stamped principal">
-  After HTTP Gate passes, user-plane `fx.store` stamps `oke.gate()`, `oke.user()`, and
-  `oke.has_scope()`. With `gate.auth.tenant` on, a fourth GUC `oke.tenant()` is set. Rate, cron,
-  CDC, and signal stay unstamped. Helpers: [Store](/docs/elements/store).
-</Callout>
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="Boot: gate boot failed — N HTTP trigger(s) missing auth posture">
-
-Empty `.gate(...)` chain. Attach a policy/rate gate, or `.public()`. First `fetch`
-auto-boots — do not rely on `gate.unguardedHttp: "allow"` outside `env: "test"`.
-
-</Accordion>
-<Accordion title="Can a policy read the request body?">
-
-No. Gates run before the flow, so they see only `auth`, `operator`, and `meta`. Body-dependent
-decisions belong inside `do` as typed `errors`.
-
-</Accordion>
-<Accordion title="Logged-in users still get Forbidden">
-
-`Forbidden` means authenticated but a policy said no. Check `verified` or a missing scope —
-the failure includes the gate name and reason.
-
-</Accordion>
-<Accordion title="Forbidden tenant_required / not_member">
-
-`required: true` and no resolved tenant → `tenant_required`. Header/subdomain id that is not a
-membership → `not_member`. Call `fx.auth.switchTenant(id)` or send a signed `tid`.
-
-</Accordion>
-<Accordion title="Prod boot: gate.auth: secret is required">
-
-Set `gate.auth.secret` (or provide it before boot). Non-prod may mint a development secret.
-
-</Accordion>
-<Accordion title="Sign-up returns AuthFailed password_policy">
-
-Default policy: length ≥ 8 plus upper, lower, number, and special (`"123"` is rejected).
-Tighten via `gate.auth.passwordPolicy`. Console claim uses min length 12 with the same
-character classes.
-
-</Accordion>
-<Accordion title="Which keyBy should I use?">
-
-`"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
-Keying an authenticated endpoint by IP punishes shared NAT.
-
-</Accordion>
-<Accordion title="API key Bearer returns 401">
-
-Expired, revoked, allowlist miss, or over `rateLimit`. `ipAllowlist` uses the
-same X-Forwarded-For hop as `ip-allowlist` (IP or hostname; lookup failure is closed).
-Rotate if the secret was shown once and then lost.
-
-</Accordion>
-<Accordion title="Keys vanish after an app restart">
-
-No SQL store, or a new `gate.auth.secret`. Declare `store.sql()`, keep
-`DATABASE_URL` (or the same PGlite datadir) and the auth secret stable.
-Console does not persist keys in `oke_console`.
-
-</Accordion>
-<Accordion title="Key can call a route the issuer cannot">
-
-That is a bug in the mint. `createApiKey` / `fx.auth.createApiKey` re-run
-`assertAttenuated` against the issuer's live scopes. Custom `gate.policy`
-predicates that ignore scopes still see `verified: true`.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Project structure](/docs/get-started/project-structure) — `http.get()` and `flow({…})` fill path and name from the file tree
-- [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
-- [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`, `fx.tenant`
-- [Client](/docs/reference/client) — Bearer `createClient` + `okengine/client/auth`
-- [Plugins](/docs/plugins) — username, magic link, OTP, TOTP, passkeys
-- [Vault](/docs/elements/vault) — credentials your policies protect
-
-## Next
-
-<Cards>
-  <Card title="Vault" description="Continue to Vault." href="/docs/elements/vault" />
-  <Card title="Plugins" description="Sign-in method plugins under /auth." href="/docs/plugins" />
-</Cards>