okengine 0.18.4 → 0.19.0

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

@@ -0,0 +1,418 @@
+---
+title: "Overview"
+description: "Permission to act — policy and rate gates on the trigger, left to right, first denial wins."
+icon: "ShieldCheck"
+source: "docs/spec/unified-theory.md"
+---
+
+Gate is how your backend **decides whether a caller may run a Flow**. Policies and rate limits
+attach to the trigger with `.gate(...)`. Identity comes from `oke({ gate: { auth } })` into
+`fx.auth`; Gate policies read that principal — they do not invent a separate middleware layer.
+
+For developers protecting APIs on okengine — declare the check, chain it on the trigger, keep
+`do` behind the first denial.
+
+<Callout title="The one rule">
+  **First denial wins.** Gates on a trigger evaluate left to right. The first reject stops the chain
+  — later gates are skipped, and `do` never runs.
+</Callout>
+
+<GatePipeline />
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a policy and attach it
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", {
+  description: "Signed-in workspace member",
+  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>
+### Call with and without a session
+
+```bash
+# Anonymous → 401 Unauthorized (policy denied, no userId)
+curl -X GET http://localhost:6530/profile -H "accept: application/json"
+
+# Signed-in → 200 with principal
+curl -X GET http://localhost:6530/profile \
+  -H "accept: application/json" \
+  -H "authorization: Bearer …"
+```
+
+Anonymous denial envelope:
+
+```json
+{
+  "data": null,
+  "error": { "code": "Unauthorized", "message": "Authentication required.", "data": {} }
+}
+```
+
+</Step>
+
+</Steps>
+
+<Callout title="Auth posture is required">
+  Every HTTP (and MCP tool) trigger must declare a gate chain **or** `.public()`. Omitting both
+  fails boot with `GateBootError`. See [Boot Posture](#boot-posture).
+</Callout>
+
+## Progressive Patterns
+
+From a single policy to scopes, rates, and reusable chains:
+
+<Tabs items={["Policy", "Scope", "Rate", "Compose"]}>
+
+<Tab value="Policy">
+
+Named ABAC check over `auth` / `operator` / optional `meta`:
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+
+export const adminOnly = gate.policy("adminOnly", {
+  description: "Admin scope required",
+  check: ({ auth }) => auth.scopes.has("admin"),
+});
+```
+
+Both forms are valid: a bare predicate, or `{ check, description? }`.
+
+</Tab>
+
+<Tab value="Scope">
+
+`gate.scope(name)` is shorthand for
+`gate.policy(name, ({ auth }) => auth.scopes.has(name))` with `scopes: [name]` recorded:
+
+```typescript
+export const notesWrite = gate.scope("notes:write");
+```
+
+**Consequence:** the scope string is the policy id — one source of truth for Manifest and Console.
+
+</Tab>
+
+<Tab value="Rate">
+
+KV-backed throttle. Pass one options object — there is no `gate.rate(name, { limit })` form:
+
+```typescript
+export const notesWriteRate = gate.rate({
+  max: 60,
+  per: "1m",
+  keyBy: "user",
+  description: "Note write throttle",
+});
+```
+
+Default strategy is `sliding-window-counter`. See [Rate Limits](/docs/elements/gate/rate-limits).
+
+</Tab>
+
+<Tab value="Compose">
+
+`gate.all` builds a reusable chain. Nested `all` handles flatten at `.gate(...)`:
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const notesWrite = gate.scope("notes:write");
+export const notesWriteRate = gate.rate({ max: 60, per: "1m", keyBy: "user" });
+
+export const notesMutate = gate.all(member, notesWrite, notesWriteRate);
+```
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http } from "okengine";
+import { notesMutate } from "@/core/gate";
+
+export const create = on(
+  http.post().gate(notesMutate),
+  // or: .gate(member, notesWrite, notesWriteRate)
+  flow({
+    do: async (input, fx) => fx.json.create({ id: fx.id(), ...input }),
+  }),
+);
+```
+
+</Tab>
+
+</Tabs>
+
+## Declaration Reference
+
+| Declaration   | Signature                                             | Purpose                                |
+| ------------- | ----------------------------------------------------- | -------------------------------------- |
+| `gate.policy` | `gate.policy(name, check \| { check, description? })` | Named ABAC / auth predicate            |
+| `gate.scope`  | `gate.scope(name)`                                    | Require `auth.scopes.has(name)`        |
+| `gate.public` | `gate.public` (handle)                                | Intentionally unauthenticated sentinel |
+| `gate.rate`   | `gate.rate({ max, per, keyBy?, … })`                  | KV-backed throttle                     |
+| `gate.all`    | `gate.all(...members)`                                | Reusable left-to-right chain           |
+
+| `oke({ gate })` option | Type                  | Default             | Meaning                                                                           |
+| ---------------------- | --------------------- | ------------------- | --------------------------------------------------------------------------------- |
+| `auth`                 | bag / omitted         | off                 | Sessions, keys, optional tenancy — see [Authentication](/docs/elements/gate/auth) |
+| `policies`             | decls / `all` handles | auto from registry  | Explicit bag; usually unnecessary                                                 |
+| `rateLimit.enabled`    | `boolean`             | `true` when auth on | Stricter presets on auth Flows                                                    |
+| `unguardedHttp`        | `"deny"` \| `"allow"` | `"deny"`            | `"allow"` only when `env === "test"`                                              |
+
+## Attaching Gates
+
+Gates chain on the **trigger**, not on a `gates: [...]` field inside `flow()`:
+
+```typescript
+http.post().gate(member, gate.scope("editor"), gate.rate({ max: 100, per: "1m", keyBy: "user" }));
+```
+
+**Public** — open the route without authentication:
+
+```typescript
+http.get().public();
+// equivalent: http.get().gate(gate.public)
+```
+
+Resource mounts accept `.gate(...)` / `.public()` once — every CRUD verb (and live, when
+present) gets the same chain. See [HTTP · Resources](/docs/elements/flow/http#resources).
+
+## Evaluation Order
+
+<Callout title="Detailed section">
+  If you only need “attach and go”, the Smallest Example is enough. This section is the walk the
+  runtime takes before `do`.
+</Callout>
+
+On each request the pipeline:
+
+1. Resolves identity into `fx.auth` (Bearer / cookie / API key when `gate.auth` is on).
+2. Resolves `fx.tenant.id` when `gate.auth.tenant` is enabled.
+3. Evaluates the trigger’s gate names **in declaration order**.
+4. Stops on the first denial — maps to a typed envelope; later gates never run.
+5. Invokes `do` only when every gate allowed.
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http, gate } from "okengine";
+
+const member = gate.policy("member", ({ auth }) => !!auth.verified);
+const write = gate.scope("notes:write");
+const throttle = gate.rate({ max: 60, per: "1m", keyBy: "user" });
+
+// Order matters: identity → capability → quota
+export const create = on(
+  http.post().gate(member, write, throttle),
+  flow({
+    do: async (input, fx) => fx.json.create({ id: fx.id(), ...input }),
+  }),
+);
+```
+
+| Caller                          | First denial               | Later gates                  |
+| ------------------------------- | -------------------------- | ---------------------------- |
+| Anonymous                       | `member` → `Unauthorized`  | `write` / `throttle` skipped |
+| Signed-in, no `notes:write`     | `write` → `Forbidden`      | `throttle` skipped           |
+| Signed-in + scope, quota burned | `throttle` → `RateLimited` | —                            |
+| All pass                        | —                          | `do` runs                    |
+
+**Consequence:** put identity policies **before** rates so anonymous traffic 401s instead of
+burning a shared `"anon"` quota under `keyBy: "user"`.
+
+<Accordions>
+
+<Accordion title="What policies may read">
+  Predicates receive `GatePolicyContext` only — `auth`, `operator`, optional `meta` (`ip`, `userId`,
+  …). They must not touch Store, Vault, or the network. World access stays in `do` via `fx`. See
+  [Authorization](/docs/elements/gate/authorization).
+</Accordion>
+
+<Accordion title="Rate evaluation fields">
+  A rate take records `remaining` and `retryAfterMs` on the evaluation. A burn maps to
+  `RateLimited` with `{ retryAfterMs }` in `error.data`.
+
+Missing KV still uses kind `rate` → typed `RateLimited` (often `retryAfterMs: 0`);
+telemetry reason is `"rate gate requires kv"`.
+
+</Accordion>
+
+<Accordion title="Unknown gate names">
+  A name that is not registered denies with reason `unknown gate: …`. Prefer attaching the declared
+  handle (`member`) rather than a raw string so the registry always knows the predicate.
+</Accordion>
+
+</Accordions>
+
+## Denial Mapping
+
+Denials are typed error values — never thrown stacks mid-pipeline:
+
+| Situation                        | Code           | Status | Typical `error.data`               |
+| -------------------------------- | -------------- | ------ | ---------------------------------- |
+| Policy denied, no `auth.userId`  | `Unauthorized` | 401    | `{}`                               |
+| Policy denied, principal present | `Forbidden`    | 403    | `{ gate, reason }`                 |
+| Rate gate burned / no KV         | `RateLimited`  | 429    | `{ retryAfterMs }`                 |
+| Tenant required / not a member   | `Forbidden`    | 403    | `{ gate: "auth:tenants", reason }` |
+
+Authenticated policy denial:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "Forbidden",
+    "message": "You are not allowed to perform this action.",
+    "data": { "gate": "notes:write", "reason": "policy denied" }
+  }
+}
+```
+
+Rate burn:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "RateLimited",
+    "message": "Too many requests. Try again later.",
+    "data": { "retryAfterMs": 42000 }
+  }
+}
+```
+
+## Boot Posture
+
+Every HTTP and MCP-tool trigger must carry at least one gate (including `gate.public`) or
+`.public()`. Missing posture throws `GateBootError` listing every gap:
+
+```text
+gate boot failed — 2 trigger(s) missing auth posture (attach a gate or .public()):
+  - notes.list GET /notes
+  - notes.create POST /notes
+```
+
+`unguardedHttp: "allow"` skips the audit **only** when `env === "test"`. Outside test it has no
+effect — migrate real apps with per-trigger `.public()`.
+
+MCP tools follow the same rule: a tool trigger with an empty gate list fails the same boot
+audit (listed as `mcp` + tool name).
+
+## The Capabilities of Gate
+
+<Cards>
+  <Card
+    title="Authentication"
+    description="Enable gate.auth, populate fx.auth, then protect Flows with policies."
+    href="/docs/elements/gate/auth"
+  />
+  <Card
+    title="Authorization Policies"
+    description="gate.policy and gate.scope for RBAC / ABAC; compose with gate.all."
+    href="/docs/elements/gate/authorization"
+  />
+  <Card
+    title="RLS"
+    description="Stamp Gate identity into SQL — store.schema.policy helpers filter rows."
+    href="/docs/elements/gate/rls"
+  />
+  <Card
+    title="Rate Limits"
+    description="gate.rate with five KV strategies — sliding-window-counter by default."
+    href="/docs/elements/gate/rate-limits"
+  />
+  <Card
+    title="Tenancy"
+    description="Opt into gate.auth.tenant and read fx.tenant.id for isolation."
+    href="/docs/elements/gate/tenancy"
+  />
+</Cards>
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="GateBootError — missing auth posture">
+  Cause: `gate boot failed — N trigger(s) missing auth posture (attach a gate or .public()):`. Every
+  listed HTTP/MCP trigger needs `.gate(...)` or `.public()`. `unguardedHttp: "allow"` only works
+  when `env === "test"`.
+</Accordion>
+
+<Accordion title="401 Unauthorized on a gated route">
+  A policy denied and `auth.userId` is null — or Bearer forge / expiry mapped to `Unauthorized`
+  before gates. Send a valid Bearer (or cookie when enabled), or mark the route `.public()` if it
+  should be open.
+</Accordion>
+
+<Accordion title="403 Forbidden with gate + reason">
+  The principal is authenticated but failed a later policy (`error.data.gate` names it). Check
+  scopes on the session / API key, or the predicate in that policy.
+</Accordion>
+
+<Accordion title="429 RateLimited with retryAfterMs">
+  A `gate.rate` burned its quota (or ran without KV). Wait `retryAfterMs`, raise `max` / widen
+  `per`, or configure a KV driver when reason telemetry shows `"rate gate requires kv"`.
+</Accordion>
+
+<Accordion title='TypeError: gate.policy name "public" is reserved'>
+  Use `gate.public` or `.public()` for open surfaces. Do not declare `gate.policy("public", …)` or
+  `gate.scope("public")`.
+</Accordion>
+
+<Accordion title="TypeError: gate.all: at least one member is required">
+  `gate.all()` with zero members is invalid. Pass one or more policy / rate / nested `all` handles.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Authentication](/docs/elements/gate/auth) — `gate.auth`, `fx.auth`, sessions and keys
+- [Authorization](/docs/elements/gate/authorization) — policies, scopes, `gate.all`
+- [RLS](/docs/elements/gate/rls) — Gate identity stamped into SQL row policies
+- [Rate Limits](/docs/elements/gate/rate-limits) — strategies, `keyBy`, KV
+- [Tenancy](/docs/elements/gate/tenancy) — `fx.tenant.id` and isolation
+- [HTTP](/docs/elements/flow/http) — `.gate(...)` / `.public()` on triggers
+- [Errors](/docs/reference/errors) — `Unauthorized` · `Forbidden` · `RateLimited`
+
+## Next
+
+<Cards>
+  <Card
+    title="Authentication"
+    description="Configure gate.auth and session identity."
+    href="/docs/elements/gate/auth"
+  />
+  <Card
+    title="HTTP triggers"
+    description="Attach .gate(...) and .public() on REST routes."
+    href="/docs/elements/flow/http"
+  />
+  <Card
+    title="Vault Element"
+    description="Declare secrets and protected configuration."
+    href="/docs/elements/vault"
+  />
+</Cards>

package/site/content/docs/elements/gate/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Gate",
+  "icon": "ShieldCheck",
+  "pages": ["index", "auth", "authorization", "rls", "rate-limits", "tenancy"]
+}