okengine 0.18.4 → 0.19.0

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

@@ -0,0 +1,371 @@
+---
+title: "Authentication"
+description: "Enable gate.auth so sessions and API keys fill fx.auth — then protect Flows with policy gates."
+icon: "Lock"
+source: "docs/spec/unified-theory.md"
+---
+
+Authentication is configured as `oke({ gate: { auth } })`. That bag issues `/auth/*` Flows
+(unless `http: false`), fills `fx.auth`, and leaves permission to policy gates — there is no
+`gate.auth` handle for `.gate(...)`.
+
+For developers shipping signed-in APIs on okengine — turn on auth, plug a method, attach policies.
+
+<Callout title="The one rule">
+  Turn on `gate.auth` for identity. Attach `gate.policy` / `gate.scope` (or `.public()`) for
+  permission. Boot fails if an HTTP trigger has neither.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Enable auth on the app
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { username } from "okengine/plugins";
+
+export const app = oke({
+  name: "notes",
+  env: "dev",
+  gate: {
+    auth: {
+      // secret required in prod; minted in dev when omitted
+      // basePath defaults to "/auth"
+    },
+  },
+}).plug(username());
+```
+
+</Step>
+
+<Step>
+### Declare a signed-in policy and attach it
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", {
+  description: "Signed-in user",
+  check: ({ auth }) => !!auth.verified,
+});
+```
+
+```typescript title="src/flows/profile/get.ts"
+import { on, flow, http } from "okengine";
+import { member } from "@/core/gate";
+
+export const get = on(
+  http.get().gate(member),
+  flow({
+    do: async (_, fx) => ({ userId: fx.auth.userId }),
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Sign in and call
+
+```bash
+# Method routes live under basePath (default /auth) — see your plugged method docs
+curl -X GET http://localhost:6530/profile \
+  -H "accept: application/json" \
+  -H "authorization: Bearer …"
+```
+
+Authenticated callers reach `do` with `fx.auth.userId` and `fx.auth.scopes` set. Anonymous
+callers fail the policy → typed `Unauthorized`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From Bearer-only identity to cookies, API keys, and method plugins:
+
+<Tabs items={["Bearer", "Cookies", "API keys", "Plugins"]}>
+
+<Tab value="Bearer">
+
+Default transport is `Authorization: Bearer <access>`. The pipeline verifies the token into
+`fx.auth` before gate evaluation:
+
+```typescript
+export const app = oke({
+  name: "notes",
+  env: "dev",
+  gate: { auth: {} },
+});
+```
+
+In production, set `gate.auth.secret` (or `OKE_AUTH_SECRET`). Omitting it in `prod` throws:
+`gate.auth: secret is required in production (set gate.auth.secret or OKE_AUTH_SECRET)`.
+
+Forged, expired, or revoked access tokens map to typed `Unauthorized` — they never become a
+principal.
+
+</Tab>
+
+<Tab value="Cookies">
+
+Opt-in HttpOnly cookie mirror (Bearer remains default). Enable under `gate.auth.cookies`:
+
+```typescript
+gate: {
+  auth: {
+    cookies: {
+      enabled: true,
+      prefix: "oke", // default
+      sameSite: "lax", // default
+      // secure defaults true; path defaults "/"
+    },
+  },
+}
+```
+
+**Consequence:** cookie sessions need the same CSRF / CORS posture as any cookie app — plug
+[`csrf`](/docs/plugins/csrf) and [`cors`](/docs/plugins/cors) when browsers call cross-origin.
+
+</Tab>
+
+<Tab value="API keys">
+
+Machine principals authenticate with a key secret. Inside `do`, `fx.auth.apiKeyId` is set;
+session-only methods (`fx.auth.createApiKey`, tenant admin, …) refuse keys.
+
+```typescript title="src/flows/keys/create.ts"
+import { on, flow, http } from "okengine";
+import { member } from "@/core/gate";
+
+export const create = on(
+  http.post().gate(member),
+  flow({
+    do: async (_, fx) => {
+      const { key, secret } = await fx.auth.createApiKey({
+        name: "ci",
+        scopes: ["notes:read"],
+        expiresIn: "90d",
+      });
+      return { id: key.id, secret }; // secret shown once
+    },
+  }),
+);
+```
+
+Key methods: `createApiKey` · `listApiKeys` · `revokeApiKey` · `rotateApiKey` · `updateApiKey`.
+
+</Tab>
+
+<Tab value="Plugins">
+
+`gate.auth` alone does not ship a login UI — plug a method from `okengine/plugins`:
+
+| Plugin              | Docs                                   |
+| ------------------- | -------------------------------------- |
+| `username`          | [Username](/docs/plugins/username)     |
+| `magicLink`         | [Magic link](/docs/plugins/magic-link) |
+| `passkey`           | [Passkey](/docs/plugins/passkey)       |
+| `oauth` / providers | [OAuth](/docs/plugins/oauth)           |
+| `anonymous`         | [Anonymous](/docs/plugins/anonymous)   |
+| `twoFactor`         | [Two-factor](/docs/plugins/two-factor) |
+| `otp`               | [OTP](/docs/plugins/otp)               |
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option                                      | Type          | Default            | Meaning                                                    |
+| ------------------------------------------- | ------------- | ------------------ | ---------------------------------------------------------- |
+| `secret`                                    | `string`      | minted in non-prod | HMAC for access tokens; required in prod                   |
+| `basePath`                                  | `string`      | `"/auth"`          | HTTP prefix for auth Flows                                 |
+| `http`                                      | `boolean`     | `true`             | `false` skips `/auth/*` bindings (secret + tables only)    |
+| `audience`                                  | `string`      | `"oke-app"`        | Access-token audience claim                                |
+| `emailAndPassword.enabled`                  | `boolean`     | `false`            | Credential method knobs                                    |
+| `emailAndPassword.requireEmailVerification` | `boolean`     | `false`            | Block sign-in until verified                               |
+| `session.accessTtlMs`                       | `number`      | `14m`              | Access token lifetime                                      |
+| `session.refreshTtlMs`                      | `number`      | `30d`              | Refresh token lifetime                                     |
+| `session.freshAgeMs`                        | `number`      | `24h`              | Max age for "fresh" step-up policies                       |
+| `session.idleTtlMs`                         | `number`      | off                | Idle timeout from last activity                            |
+| `session.absoluteTtlMs`                     | `number`      | off                | Absolute lifetime from creation                            |
+| `session.singleSessionPerUser`              | `boolean`     | `false`            | One live family per user                                   |
+| `cookies`                                   | bag           | off                | HttpOnly cookie mirror                                     |
+| `secondaryStorage`                          | bag           | off                | Hot-path KV cache (`prefix` default `"auth:"`)             |
+| `tenant`                                    | `true` \| bag | off                | Multi-tenancy — see [Tenancy](/docs/elements/gate/tenancy) |
+
+## What `fx.auth` carries
+
+| Field           | Meaning                                                                    |
+| --------------- | -------------------------------------------------------------------------- |
+| `userId`        | Principal id, or `null` when anonymous                                     |
+| `scopes`        | `ReadonlySet<string>` used by `gate.scope` (may include tenant-role union) |
+| `sessionScopes` | Session / JWT scopes before tenant-role union                              |
+| `verified`      | Session / credential passed verification                                   |
+| `apiKeyId`      | Present when the principal is an API key                                   |
+
+Inside `do`, read identity from `fx.auth` — not `fx.user`. World access stays on `fx`.
+
+## Sessions & Cookies
+
+<Callout title="Detailed section">
+  Defaults match a short-lived access token plus a long-lived refresh family. Override only what
+  your product needs.
+</Callout>
+
+```typescript title="src/app.ts"
+export const app = oke({
+  name: "notes",
+  env: "prod",
+  gate: {
+    auth: {
+      secret: process.env.OKE_AUTH_SECRET!,
+      session: {
+        accessTtlMs: 14 * 60 * 1000,
+        refreshTtlMs: 30 * 24 * 60 * 60 * 1000,
+        freshAgeMs: 24 * 60 * 60 * 1000,
+        // idleTtlMs / absoluteTtlMs / singleSessionPerUser when needed
+      },
+      cookies: {
+        enabled: true,
+        prefix: "oke",
+        sameSite: "lax",
+        secure: true,
+        path: "/",
+      },
+    },
+  },
+});
+```
+
+| Cookie option    | Default | Meaning                           |
+| ---------------- | ------- | --------------------------------- |
+| `enabled`        | `false` | Opt-in HttpOnly mirror            |
+| `prefix`         | `"oke"` | Cookie name prefix                |
+| `secure`         | `true`  | HTTPS-only                        |
+| `sameSite`       | `"lax"` | `"strict"` \| `"lax"` \| `"none"` |
+| `path`           | `"/"`   | Cookie path                       |
+| `crossSubdomain` | `false` | Share across subdomains           |
+| `domain`         | —       | Explicit cookie domain            |
+
+**Freshness:** policies that require a recent sign-in should compare session age against
+`session.freshAgeMs` (default 24h). Step-up plugins (e.g. [two-factor](/docs/plugins/two-factor))
+build on the same window.
+
+## API Keys
+
+<Accordions>
+
+<Accordion title="createApiKey options">
+
+| Field         | Type                   | Meaning                                    |
+| ------------- | ---------------------- | ------------------------------------------ |
+| `name`        | `string`               | Label for Console / list                   |
+| `scopes`      | `string[]`             | Cannot exceed the creator’s session scopes |
+| `expiresIn`   | duration string        | Optional (`"90d"`, `"1h"`, …)              |
+| `ipAllowlist` | `string[]`             | Optional source IP allowlist               |
+| `rateLimit`   | `{ max, per } \| null` | Optional per-key throttle                  |
+
+Return shape: `{ key, secret }` — the secret is shown once at create / rotate.
+
+</Accordion>
+
+<Accordion title="Session-only refusals">
+  Key management and tenant admin refuse API-key principals:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "Forbidden",
+    "message": "You are not allowed to perform this action.",
+    "data": { "gate": "auth:api-keys", "reason": "session_only" }
+  }
+}
+```
+
+Call those methods from a user session. Machine keys authenticate _into_ Flows; they do not
+mint more keys.
+
+</Accordion>
+
+</Accordions>
+
+## Public routes
+
+Health checks and login endpoints must declare open posture explicitly:
+
+```typescript
+http.get().public();
+// equivalent: http.get().gate(gate.public)
+```
+
+Auth method Flows under `basePath` register their own posture; your app routes still need
+`.gate(...)` or `.public()`.
+
+Set `gate.auth.http: false` when you want tables + Bearer verify without materializing
+`/auth/*` HTTP bindings (embedding / Console-style hosts).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="gate.auth: secret is required in production">
+  Cause: `gate.auth: secret is required in production (set gate.auth.secret or OKE_AUTH_SECRET)`.
+  Set an explicit secret before shipping — never rely on the minted dev secret in prod.
+</Accordion>
+
+<Accordion title="401 on every gated route after sign-in">
+  Token missing, expired, wrong audience, or cookies enabled without sending credentials. Check
+  `Authorization: Bearer`, `audience`, and cookie `SameSite` / CORS.
+</Accordion>
+
+<Accordion title="Forbidden · session_only on createApiKey / listTenants">
+  Those methods refuse API-key principals (`error.data.reason: "session_only"`). Call them from a
+  user session, not a machine key.
+</Accordion>
+
+<Accordion title="Forbidden · not_owner on revokeApiKey">
+  Keys are owned by the creator. A different session cannot revoke or rotate another user’s key
+  (`reason: "not_owner"`).
+</Accordion>
+
+<Accordion title="GateBootError after enabling auth">
+  Enabling `gate.auth` does not auto-gate your routes. Attach `member` (or `.public()`) on every
+  HTTP trigger — see [Boot Posture](/docs/elements/gate#boot-posture).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Username plugin](/docs/plugins/username) — email-free sign-up on `gate.auth`
+- [Authorization](/docs/elements/gate/authorization) — scopes and ABAC policies
+- [RLS](/docs/elements/gate/rls) — row policies from stamped identity
+- [Tenancy](/docs/elements/gate/tenancy) — `fx.tenant.id`
+- [HTTP](/docs/elements/flow/http) — `.gate` / `.public` on triggers
+
+## Next
+
+<Cards>
+  <Card
+    title="Authorization"
+    description="gate.policy and gate.scope for permission checks."
+    href="/docs/elements/gate/authorization"
+  />
+  <Card
+    title="RLS"
+    description="Stamp Gate identity into SQL row policies."
+    href="/docs/elements/gate/rls"
+  />
+  <Card
+    title="Tenancy"
+    description="Resolve fx.tenant.id from claims, headers, or subdomains."
+    href="/docs/elements/gate/tenancy"
+  />
+</Cards>

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

@@ -0,0 +1,298 @@
+---
+title: "Authorization"
+description: "gate.policy and gate.scope — reusable permission checks composed with gate.all and attached via .gate."
+icon: "ShieldAlert"
+source: "docs/spec/unified-theory.md"
+---
+
+Authorization answers “may this principal do this?” after identity is known. Declare reusable
+`gate.policy` / `gate.scope` handles, compose them with `gate.all`, and attach the chain on the
+trigger.
+
+For developers enforcing RBAC / ABAC on okengine — name the check once, reuse it on every route.
+
+<Callout title="The one rule">
+  Policies receive `GatePolicyContext` (`auth`, `operator`, optional `meta`) — never invent
+  `ctx.user` or `ctx.store`. World access stays inside `do` via `fx`.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare policies and scopes
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+/** Signed-in member. */
+export const member = gate.policy("member", {
+  check: ({ auth }) => !!auth.verified,
+});
+
+/** Holds the notes:write scope (name is the scope string). */
+export const notesWrite = gate.scope("notes:write");
+
+/** Admin-only ABAC example. */
+export const adminOnly = gate.policy("adminOnly", ({ auth }) => auth.scopes.has("admin"));
+```
+
+`gate.scope(name)` is shorthand for
+`gate.policy(name, ({ auth }) => auth.scopes.has(name))` with `scopes: [name]` recorded.
+
+</Step>
+
+<Step>
+### Compose and attach
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http, gate } from "okengine";
+import { member, notesWrite } from "@/core/gate";
+
+export const notesMutate = gate.all(member, notesWrite);
+
+export const create = on(
+  http.post().gate(notesMutate),
+  // or: .gate(member, notesWrite)
+  flow({
+    do: async ({ title }, fx) => fx.json.create({ id: fx.id(), title }),
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### See the denial
+
+Missing `notes:write` on an authenticated caller:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "Forbidden",
+    "message": "You are not allowed to perform this action.",
+    "data": { "gate": "notes:write", "reason": "policy denied" }
+  }
+}
+```
+
+Anonymous callers denied earlier in the chain get `Unauthorized` instead.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a single scope to Module:Action names, composition, and operator plane:
+
+<Tabs items={["Scope", "ABAC", "Compose", "Operator"]}>
+
+<Tab value="Scope">
+
+Prefer `gate.scope` when the check is exactly “has this scope string”:
+
+```typescript
+export const bookingCreate = gate.scope("booking:create");
+export const notesRead = gate.scope("notes:read");
+```
+
+Names containing `:` are Module:Action pairs — extracted into Manifest permissions for Console.
+
+</Tab>
+
+<Tab value="ABAC">
+
+Use `gate.policy` when the predicate needs more than a single scope membership:
+
+```typescript
+export const freshAdmin = gate.policy("freshAdmin", ({ auth, meta }) => {
+  if (!auth.scopes.has("admin")) return false;
+  // Example: combine scopes with request meta (ip allowlists live in plugins)
+  return !!auth.verified && meta?.ip !== undefined;
+});
+```
+
+Async predicates are allowed (`Promise<boolean>`).
+
+</Tab>
+
+<Tab value="Compose">
+
+`gate.all` is every-member-must-pass, left to right. Nesting flattens:
+
+```typescript
+const write = gate.all(member, notesWrite, gate.rate({ max: 60, per: "1m", keyBy: "user" }));
+const strictWrite = gate.all(write, gate.scope("notes:admin"));
+```
+
+Attach either the composed handle or list members on `.gate(...)` — order is declaration order;
+first denial wins.
+
+</Tab>
+
+<Tab value="Operator">
+
+Console / operator-plane Flows read `operator`, not `auth.userId`:
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const consoleOp = gate.policy("consoleOp", ({ operator }) => operator.id !== null);
+```
+
+```typescript title="src/flows/ops/cleanup.ts"
+import { on, flow, http } from "okengine";
+import { consoleOp } from "@/core/gate";
+
+export const cleanup = on(
+  http.post().gate(consoleOp),
+  flow({
+    plane: "operator",
+    do: async (_, fx) => ({ operatorId: fx.operator.id }),
+  }),
+);
+```
+
+Rate `keyBy: "operator"` keys on `operator.id`.
+
+</Tab>
+
+</Tabs>
+
+## Policy Context
+
+| Field                | Type                          | Meaning                                        |
+| -------------------- | ----------------------------- | ---------------------------------------------- |
+| `auth.userId`        | `string \| null`              | User-plane principal                           |
+| `auth.scopes`        | `ReadonlySet<string>`         | Granted scopes (may include tenant-role union) |
+| `auth.verified`      | `boolean \| undefined`        | Credential verified                            |
+| `auth.apiKeyId`      | `string \| null \| undefined` | API-key principal when present                 |
+| `operator.id`        | `string \| null`              | Operator-plane principal                       |
+| `meta.ip` / `userId` | optional                      | Subject dims for rate `keyBy`                  |
+
+Policies must not touch the store, vault, or network — those belong in `do` via `fx`.
+
+## Declaration Forms
+
+| Form            | Example                                                | Notes                             |
+| --------------- | ------------------------------------------------------ | --------------------------------- |
+| Predicate       | `gate.policy("member", ({ auth }) => !!auth.verified)` | Shortest                          |
+| Options         | `gate.policy("member", { check, description? })`       | Console / docs label              |
+| Scope shorthand | `gate.scope("notes:write")`                            | Records `scopes: ["notes:write"]` |
+| Public sentinel | `gate.public`                                          | Always allows; reserved name      |
+| Chain           | `gate.all(a, b, c)`                                    | Flattened at attach time          |
+
+Reserved: `gate.policy("public", …)` and `gate.scope("public")` throw — use `gate.public`.
+
+## Module:Action Permissions
+
+<Callout title="Detailed section">
+  Scopes with a colon (`notes:write`) are Module:Action pairs. Manifest + Console derive the
+  permission catalog from Flows, effects, and gate scopes — you do not hand-maintain a second list.
+</Callout>
+
+| Source                         | Example pair                     |
+| ------------------------------ | -------------------------------- |
+| Flow id `notes.create`         | `notes:create`                   |
+| `gate.scope("booking:create")` | `booking:create`                 |
+| Effect `reads: ["sql:notes"]`  | `store.sql:read`                 |
+| Operator-plane Flow            | also `console:…` when applicable |
+
+**Consequence:** prefer `gate.scope("notes:write")` over a one-off policy with the same string —
+the scope is recorded on the declaration for Manifest / Console.
+
+Tenant roles may grant **application** scopes only (`notes:write`), not `console:*`. See
+[Tenancy](/docs/elements/gate/tenancy).
+
+## Attaching on Resources & Live
+
+Chain once on the mount — every verb (and live, when present) inherits the same gates:
+
+```typescript title="src/flows/notes/index.ts"
+import { on, http } from "okengine";
+import { member, notesWrite } from "@/core/gate";
+import { notesResource } from "./resource";
+
+export const notes = on(http.resource("/notes", notesResource.all()).gate(member, notesWrite));
+```
+
+Live firehoses use the same `.gate(...)` fluent:
+
+```typescript
+on(http.live(orderStatus).gate(member));
+```
+
+See [HTTP · Resources](/docs/elements/flow/http#resources) and
+[HTTP · Live Streams](/docs/elements/flow/http#live-streams).
+
+## Denial Mapping
+
+| Situation                        | Code           | Status | `error.data`                |
+| -------------------------------- | -------------- | ------ | --------------------------- |
+| Policy denied, no `auth.userId`  | `Unauthorized` | 401    | `{}`                        |
+| Policy denied, principal present | `Forbidden`    | 403    | `{ gate, reason }`          |
+| Unknown gate name at runtime     | deny           | —      | `reason: "unknown gate: …"` |
+
+`reason` is `"policy denied"` for failed predicates (unless a rate gate burned earlier).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="403 Forbidden but the user looks signed in">
+  A later gate in the chain failed — read `error.data.gate`. Confirm the session / key actually
+  carries that scope (`fx.auth.scopes`), including tenant-role unions when tenancy is on.
+</Accordion>
+
+<Accordion title="Policy always fails with verified users">
+  Check for `!!auth.verified` vs `auth.userId !== null`. Some principals have a `userId` before
+  verification completes — pick the predicate that matches your product rule.
+</Accordion>
+
+<Accordion title='TypeError: name "public" is reserved'>
+  Cause: `gate.policy: name "public" is reserved — use gate.public for intentionally unauthenticated
+  surfaces` (or the `gate.scope` variant). Rename the policy or use `.public()`.
+</Accordion>
+
+<Accordion title="TypeError: gate.all: at least one member is required">
+  Pass one or more policy / rate / nested `all` handles — empty `gate.all()` is invalid.
+</Accordion>
+
+<Accordion title="Scope present in JWT but route still Forbidden">
+  Tenant-role scopes union into `fx.auth.scopes` only when the Flow is tenant-scoped (default when
+  tenancy is on). A Flow with `tenantScoped: false` keeps session scopes only.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Authentication](/docs/elements/gate/auth) — how `fx.auth` is filled
+- [RLS](/docs/elements/gate/rls) — row policies from the same Gate identity
+- [Rate Limits](/docs/elements/gate/rate-limits) — throttle on the same chain
+- [Tenancy](/docs/elements/gate/tenancy) — tenant-role scope union
+- [HTTP](/docs/elements/flow/http) — `.gate(...)` on triggers
+
+## Next
+
+<Cards>
+  <Card
+    title="RLS"
+    description="Stamp Gate identity into SQL row policies."
+    href="/docs/elements/gate/rls"
+  />
+  <Card
+    title="Rate Limits"
+    description="Throttle with gate.rate on the same chain."
+    href="/docs/elements/gate/rate-limits"
+  />
+  <Card
+    title="Tenancy"
+    description="fx.tenant.id and membership-scoped data."
+    href="/docs/elements/gate/tenancy"
+  />
+</Cards>