okengine 0.18.4 → 0.19.0

package/site/content/docs/elements/gate/rate-limits.mdx

@@ -0,0 +1,365 @@
+---
+title: "Rate Limits"
+description: "gate.rate — KV-backed throttles with max, per, and keyBy; five strategies, sliding-window-counter by default."
+icon: "Gauge"
+source: "docs/spec/unified-theory.md"
+---
+
+`gate.rate` protects Flows from abuse and runaway clients. Limits run as atomic takes on the KV
+driver before `do`. Compose rates with policies via `gate.all` or list them on `.gate(...)`.
+
+For developers throttling login, writes, and expensive reads on okengine — declare the window,
+key the subject, attach on the trigger.
+
+<Callout title="The one rule">
+  Pass options as one object: `{ max, per, keyBy? }`. There is no `gate.rate(name, { limit, window })`
+  form — the runtime names the gate from strategy and window.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a rate gate
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const loginThrottle = gate.rate({
+  strategy: "sliding-window-counter", // default when omitted
+  max: 5,
+  per: "1m",
+  keyBy: "ip",
+  description: "Login attempts per IP",
+});
+```
+
+The runtime name is `rate:sliding-window-counter:5/1m` (strategy · max · per).
+
+</Step>
+
+<Step>
+### Attach on the trigger
+
+```typescript title="src/flows/auth/login.ts"
+import { on, flow, http, gate } from "okengine";
+import { loginThrottle } from "@/core/gate";
+
+export const login = on(
+  http.post("/auth/sign-in/email").gate(gate.public, loginThrottle),
+  flow({
+    do: async (input, fx) => {
+      // At most 5 takes per IP per minute
+      return input;
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### See a burned quota
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "RateLimited",
+    "message": "Too many requests. Try again later.",
+    "data": { "retryAfterMs": 42000 }
+  }
+}
+```
+
+Status is `429 Too Many Requests`. Clients should wait `retryAfterMs` before retrying.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From the default counter to bursty buckets and subject keys:
+
+<Tabs items={["Default", "Token bucket", "keyBy", "Compose"]}>
+
+<Tab value="Default">
+
+Omit `strategy` for `sliding-window-counter` — best accuracy-to-cost ratio (two KV keys, no
+boundary bursts):
+
+```typescript
+export const fair = gate.rate({ max: 60, per: "1m", keyBy: "user" });
+```
+
+</Tab>
+
+<Tab value="Token bucket">
+
+Allow short bursts that refill over `per`:
+
+```typescript
+export const bursty = gate.rate({
+  strategy: "token-bucket",
+  max: 20,
+  per: "1m",
+  keyBy: "user",
+});
+```
+
+Use `leaky-bucket` when you need a smooth outbound rate instead of burst capacity.
+
+</Tab>
+
+<Tab value="keyBy">
+
+Subject dimension for the take key:
+
+| `keyBy`              | Subject                                           |
+| -------------------- | ------------------------------------------------- |
+| `"user"`             | `auth.userId` (else `meta.userId`, else `"anon"`) |
+| `"ip"`               | `meta.ip` (else `"0.0.0.0"`)                      |
+| `"operator"`         | `operator.id` (else `"anon"`)                     |
+| `"global"` / omitted | Shared `"global"` bucket                          |
+| other string         | `meta[keyBy]` when present, else the literal      |
+
+```typescript
+gate.rate({ max: 100, per: "1h", keyBy: "ip" });
+gate.rate({ max: 10, per: "1s" }); // global
+```
+
+</Tab>
+
+<Tab value="Compose">
+
+Rates sit on the same chain as policies — first denial wins:
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http, gate } from "okengine";
+
+export const notesMutate = gate.all(
+  gate.policy("member", ({ auth }) => !!auth.verified),
+  gate.scope("notes:write"),
+  gate.rate({ max: 60, per: "1m", keyBy: "user" }),
+);
+
+export const create = on(
+  http.post().gate(notesMutate),
+  flow({
+    do: async (input, fx) => fx.json.create({ id: fx.id(), ...input }),
+  }),
+);
+```
+
+Put identity policies **before** rates when anonymous traffic should 401 instead of burning
+quota under `"anon"`.
+
+</Tab>
+
+</Tabs>
+
+## Strategies
+
+| Strategy                 | Best for                   | Cost shape                  |
+| ------------------------ | -------------------------- | --------------------------- |
+| `sliding-window-counter` | Default — accuracy vs cost | Two keys, weighted estimate |
+| `token-bucket`           | Bursty traffic with refill | One hash (`tokens`, `ts`)   |
+| `leaky-bucket`           | Smooth outbound rate       | One hash (`level`, `ts`)    |
+| `fixed-window`           | Simple reset intervals     | One counter per bucket      |
+| `sliding-log`            | Strict precision           | ZSET of event timestamps    |
+
+All five run as atomic Lua on the KV driver (memory / redis EVAL).
+
+<Callout title="Detailed section">
+  Pick the strategy from product physics, not fashion. The default covers most HTTP write paths;
+  switch only when you need bursts, smooth leak, or exact event logs.
+</Callout>
+
+<Tabs items={["sliding-window-counter", "token-bucket", "leaky-bucket", "fixed-window", "sliding-log"]}>
+
+<Tab value="sliding-window-counter">
+
+Near-exact rolling window without boundary spikes of a naive fixed window:
+
+```typescript
+gate.rate({
+  strategy: "sliding-window-counter", // or omit — this is the default
+  max: 100,
+  per: "1m",
+  keyBy: "user",
+});
+```
+
+Uses current + previous window counters with a time-weighted estimate.
+
+</Tab>
+
+<Tab value="token-bucket">
+
+Burst up to `max`, then refill smoothly across `per`:
+
+```typescript
+gate.rate({
+  strategy: "token-bucket",
+  max: 20,
+  per: "1m",
+  keyBy: "ip",
+});
+```
+
+**Consequence:** a quiet client can spend its full burst immediately after idle time.
+
+</Tab>
+
+<Tab value="leaky-bucket">
+
+Smooth outbound rate — rejects when the “bucket level” would exceed `max`:
+
+```typescript
+gate.rate({
+  strategy: "leaky-bucket",
+  max: 50,
+  per: "1m",
+  keyBy: "user",
+});
+```
+
+Prefer this for upstream APIs that punish spikes more than averages.
+
+</Tab>
+
+<Tab value="fixed-window">
+
+Simple counter that resets each `per` bucket:
+
+```typescript
+gate.rate({
+  strategy: "fixed-window",
+  max: 1000,
+  per: "1h",
+  keyBy: "global",
+});
+```
+
+Cheapest layout; allows a double-burst at the bucket boundary.
+
+</Tab>
+
+<Tab value="sliding-log">
+
+Exact event log (ZSET of timestamps) — strict precision at higher cost:
+
+```typescript
+gate.rate({
+  strategy: "sliding-log",
+  max: 10,
+  per: "1m",
+  keyBy: "ip",
+});
+```
+
+Use for sensitive endpoints where approximate counters are not enough.
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option        | Type           | Default                  | Meaning                                      |
+| ------------- | -------------- | ------------------------ | -------------------------------------------- |
+| `max`         | `number`       | required                 | Takes allowed within `per` (`> 0`)           |
+| `per`         | `string`       | required                 | Window / refill (`"1m"`, `"60s"`, `"1h"`, …) |
+| `strategy`    | `RateStrategy` | `sliding-window-counter` | Algorithm id                                 |
+| `keyBy`       | `string`       | global                   | Subject dim (`"ip"`, `"user"`, …)            |
+| `overridable` | `boolean`      | `false`                  | Console may override `max` / `per` in Store  |
+| `description` | `string`       | —                        | Human label for Console / docs               |
+
+**Consequence:** rate gates need a KV driver in the app. Without KV, evaluation denies with
+telemetry reason `"rate gate requires kv"` and the typed code is still `RateLimited`.
+
+Declare-time guards:
+
+- `gate.rate: max must be a positive number`
+- `gate.rate: per is required`
+
+Invalid `per` at evaluation → deny with `reason: "invalid per: …"`.
+
+## Naming & Overrides
+
+The runtime name is always `rate:{strategy}:{max}/{per}`:
+
+```text
+rate:sliding-window-counter:60/1m
+rate:token-bucket:20/1m
+```
+
+When `overridable: true`, Console may tune `max` / `per` in Store without a code deploy. Leave
+it `false` (default) for hard product limits.
+
+`oke({ gate: { rateLimit: { enabled } } })` controls whether **auth path** Flows attach
+stricter presets. Default is `true` when `gate.auth` is on, `false` otherwise — it does not
+replace your own `gate.rate` declarations.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="429 RateLimited immediately">
+  Quota burned for that subject. Inspect `retryAfterMs`, widen `per`, raise `max`, or change `keyBy`
+  so clients do not share one global bucket unintentionally.
+</Accordion>
+
+<Accordion title='Denial reason "rate gate requires kv"'>
+  Configure a KV driver (`memory` for local, `redis` for multi-instance). Policy-only apps can omit
+  KV; any `gate.rate` on a hot path cannot. The HTTP envelope is still `RateLimited`.
+</Accordion>
+
+<Accordion title="Anonymous traffic burns user quotas">
+  With `keyBy: "user"`, missing `userId` maps to `"anon"` — shared. Put a member policy before the
+  rate, or key by `"ip"` for public endpoints.
+</Accordion>
+
+<Accordion title="TypeError: gate.rate: max must be a positive number">
+  `max` must be `> 0`. Zero and negatives fail at declare.
+</Accordion>
+
+<Accordion title="TypeError: gate.rate: per is required">
+  Pass a duration string (`"1m"`, `"30s"`, …). Empty / missing `per` fails at declare.
+</Accordion>
+
+<Accordion title='Denial reason "invalid per: …"'>
+  The duration string did not parse to a positive window. Use `ms|s|m|h|d` style values the Clock
+  duration parser accepts (`"1m"`, `"60s"`, `"1h"`).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Gate Overview](/docs/elements/gate) — chain order and denial mapping
+- [Authorization](/docs/elements/gate/authorization) — policies on the same `.gate(...)`
+- [Store · KV](/docs/elements/store/kv) — KV facet drivers
+- [HTTP](/docs/elements/flow/http) — attach rates on REST routes
+
+## Next
+
+<Cards>
+  <Card
+    title="Tenancy"
+    description="Resolve fx.tenant.id for B2B isolation."
+    href="/docs/elements/gate/tenancy"
+  />
+  <Card
+    title="RLS"
+    description="Stamp Gate identity into SQL row policies."
+    href="/docs/elements/gate/rls"
+  />
+  <Card
+    title="Vault Element"
+    description="Secrets and protected configuration."
+    href="/docs/elements/vault"
+  />
+</Cards>

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

@@ -0,0 +1,303 @@
+---
+title: "RLS"
+description: "Row-level security — Gate identity stamped into SQL so store.schema.policy helpers filter every fx.store query."
+icon: "Rows3"
+source: "docs/spec/unified-theory.md"
+---
+
+Gate decides whether a caller may run a Flow. **RLS** decides which SQL rows that
+caller may see or change.
+
+After `.gate(...)` passes, `fx.store` stamps the principal into Postgres session GUCs
+(`oke.gate` · `oke.user` · `oke.scopes` · `oke.tenant`) so table policies enforce the
+same identity.
+
+For developers shipping multi-user SQL on okengine — declare Gate policies, attach them
+on the trigger, and mirror them on the table with `store.schema.policy.*`.
+
+<Callout title="The one rule">
+  Put row predicates on the **table** (`store.schema.policy.gate` / `owner` / `scope` / `tenant`).
+  Put permission to **act** on the **trigger** (`.gate(...)`). Never invent a separate middleware
+  layer — the stamp rides every `fx.store` call.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare a Gate policy and an RLS table
+
+```typescript title="src/core/gate.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+```
+
+```typescript title="src/db/schema.decl.ts"
+import { store, field } from "okengine";
+
+export const tasks = store.schema.table(
+  "tasks",
+  {
+    id: field.id().primaryKey(),
+    owner: field.text().notNull(),
+    title: field.text().notNull(),
+  },
+  [
+    store.schema.policy.gate("member", { for: "select" }),
+    store.schema.policy.owner("owner", { for: "all" }),
+  ],
+);
+```
+
+</Step>
+
+<Step>
+### Gate the route and query through `fx.store`
+
+```typescript title="src/flows/tasks/list.ts"
+import { on, flow, http } from "okengine";
+import { member } from "@/core/gate";
+import { db, tasks } from "@/schema";
+
+export const list = on(
+  http.get().gate(member),
+  flow({
+    do: async (_, fx) => fx.store(db).select().from(tasks),
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### What the caller sees
+
+Alice’s session stamps `oke.gate = 'member'` and `oke.user = '<alice>'`. SELECT
+policies that require `oke.gate() = 'member'` and `owner = oke.user()` return only
+Alice’s rows — even if the Flow’s `where` clause is empty.
+
+Use an RLS-capable SQL driver (`postgres` / `pglite`). The `memory` SQL driver does
+not enforce row policies.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a gate-name check to owner columns, scopes, and tenants:
+
+<Tabs items={["Gate", "Owner", "Scope", "Tenant"]}>
+
+<Tab value="Gate">
+
+`store.schema.policy.gate(name)` stamps `oke.gate() = '…'` (default `for: "select"`).
+The name must match a Gate policy on the trigger (rate gates are skipped when picking
+the stamp):
+
+```typescript
+store.schema.policy.gate("member", { for: "select" });
+```
+
+**Consequence:** the first non-rate gate on `.gate(...)` becomes `oke.gate` for that
+request. Put the policy you want stamped **first** when the chain mixes policies and
+rates.
+
+</Tab>
+
+<Tab value="Owner">
+
+`store.schema.policy.owner(column)` stamps `column = oke.user()` (default `for: "all"`):
+
+```typescript
+store.schema.policy.owner("owner", { for: "all" });
+```
+
+`oke.user()` is the stamped `fx.auth.userId` (empty string when anonymous / public).
+
+</Tab>
+
+<Tab value="Scope">
+
+`store.schema.policy.scope(scope)` stamps `oke.has_scope('…')` (default `for: "insert"`).
+Pass a string or a `gate.scope(...)` handle so the scope stays single-sourced:
+
+```typescript
+import { gate } from "okengine";
+
+export const bookingCreate = gate.scope("booking:create");
+
+// On the table:
+store.schema.policy.scope(bookingCreate, { for: "insert" });
+// or: store.schema.policy.scope("booking:create", { for: "insert" });
+```
+
+</Tab>
+
+<Tab value="Tenant">
+
+When `gate.auth.tenant` is on, every table needs a tenant policy or an explicit opt-out:
+
+```typescript
+store.schema.policy.tenant("tenantId"); // default for: "all" → tenantId = oke.tenant()
+// or shared catalog tables:
+store.schema.unscoped();
+```
+
+See [Tenancy](/docs/elements/gate/tenancy). Extract fails without one:
+
+```text
+extract: table "{store}.{table}" needs store.schema.policy.tenant(...) or store.schema.unscoped() when gate.auth.tenant is on
+```
+
+</Tab>
+
+</Tabs>
+
+## Identity Stamp
+
+After Gate allows, the SQL session prelude sets:
+
+| GUC / helper       | Source                             | Used by         |
+| ------------------ | ---------------------------------- | --------------- |
+| `oke.gate()`       | First non-rate gate on the trigger | `policy.gate`   |
+| `oke.user()`       | `fx.auth.userId`                   | `policy.owner`  |
+| `oke.has_scope(…)` | `fx.auth.scopes` (JSON)            | `policy.scope`  |
+| `oke.tenant()`     | `fx.tenant.id` when tenancy is on  | `policy.tenant` |
+
+The stamp `SET LOCAL ROLE oke_app` and turns `row_security` on so table owners cannot
+bypass policies on the hot path.
+
+| Plane / mode                | Stamp?                     |
+| --------------------------- | -------------------------- |
+| User-plane Flow, gated      | Yes                        |
+| `plane: "operator"`         | No — operator bypasses RLS |
+| Console / Call API `bypass` | No                         |
+
+## Policy Helpers
+
+Extras are the **third argument** of `store.schema.table(name, cols, extras)`:
+
+| Helper                             | Default `for` | Predicate                               |
+| ---------------------------------- | ------------- | --------------------------------------- |
+| `store.schema.policy.gate(name)`   | `select`      | `oke.gate() = '…'`                      |
+| `store.schema.policy.owner(col)`   | `all`         | `col = oke.user()`                      |
+| `store.schema.policy.scope(scope)` | `insert`      | `oke.has_scope('…')`                    |
+| `store.schema.policy.tenant(col)`  | `all`         | `col = oke.tenant()`                    |
+| `store.schema.rls()`               | —             | Enable RLS with no policies yet         |
+| `store.schema.unscoped()`          | —             | Opt out of tenant requirement           |
+| `store.schema.policy(name, opts)`  | —             | Raw `using` / `withCheck` / `as` / `to` |
+
+`for` accepts `select` · `insert` · `update` · `delete` · `all`. Optional `as`:
+`"permissive"` (default) or `"restrictive"`. Optional `to` limits Postgres roles.
+
+```typescript title="src/db/schema.decl.ts"
+import { store, field } from "okengine";
+import { member, bookingCreate } from "@/core/gate";
+
+export const bookings = store.schema.table(
+  "bookings",
+  {
+    id: field.id().primaryKey(),
+    owner: field.text().notNull(),
+    tenantId: field.text().notNull(),
+  },
+  [
+    store.schema.policy.gate("member", { for: "select" }),
+    store.schema.policy.owner("owner", { for: "all" }),
+    store.schema.policy.scope(bookingCreate, { for: "insert" }),
+    store.schema.policy.tenant("tenantId"),
+  ],
+);
+```
+
+<Callout title="Detailed section">
+  Schema extras, relations, and emit live under [Store · SQL · Schema Extras &
+  RLS](/docs/elements/store/sql#schema-extras--rls). This page is the Gate ↔ row identity contract.
+</Callout>
+
+## Composition
+
+Multiple **PERMISSIVE** policies for the same command OR together — a row is visible if
+any permissive policy passes. **RESTRICTIVE** policies AND with the rest (`as: "restrictive"`).
+
+```typescript
+[
+  store.schema.policy.gate("member", { for: "select" }),
+  store.schema.policy.owner("owner", { for: "select" }),
+];
+```
+
+A `member` principal sees rows that pass the gate predicate **or** the owner predicate
+(for SELECT). Tighten with restrictive policies or a single compound raw `using`.
+
+## Live Queries & Resources
+
+Resource live (`store.resource({ live: true })`) and handwritten `liveQuery` classify
+CDC events through the same RLS stamp. Needs `postgres` / `pglite` and a gated identity.
+
+See [HTTP · Resource Live](/docs/elements/flow/http#resources) and
+[Store · SQL](/docs/elements/store/sql).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Every query returns zero rows">
+  Stamp or policies are wrong. Confirm `.gate(member)` (or matching name), that `owner` / `tenantId`
+  columns match `oke.user()` / `oke.tenant()`, and that the driver is `postgres` or `pglite` — not
+  `memory`.
+</Accordion>
+
+<Accordion title="Extract: needs store.schema.policy.tenant or unscoped">
+  Cause: `extract: table "{store}.{table}" needs store.schema.policy.tenant(...) or
+  store.schema.unscoped() when gate.auth.tenant is on`. Add a tenant column policy or mark the table
+  shared.
+</Accordion>
+
+<Accordion title="live query requires an RLS-capable SQL driver">
+  Cause: `live query for "…" requires an RLS-capable SQL driver (postgres / pglite)`. Switch the SQL
+  driver and attach a Gate chain so the stamp has a principal.
+</Accordion>
+
+<Accordion title="Operator / Console sees all rows">
+  `plane: "operator"` and Call API `bypass` skip the RLS stamp by design. User-plane Flows always
+  stamp when gated.
+</Accordion>
+
+<Accordion title="Wrong gate stamped on a long chain">
+  The first non-rate gate name wins for `oke.gate()`. Reorder `.gate(member, write, rate)` so the
+  policy you want in SQL predicates comes before rates and secondary scopes when those scopes use
+  `oke.has_scope` instead of `oke.gate`.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Authorization](/docs/elements/gate/authorization) — `gate.policy` / `gate.scope` on triggers
+- [Tenancy](/docs/elements/gate/tenancy) — `fx.tenant.id` and `policy.tenant`
+- [Store · SQL](/docs/elements/store/sql) — schema extras, session handle, drivers
+- [HTTP](/docs/elements/flow/http) — resource live + RLS
+
+## Next
+
+<Cards>
+  <Card
+    title="Rate Limits"
+    description="Throttle with gate.rate on the same chain."
+    href="/docs/elements/gate/rate-limits"
+  />
+  <Card
+    title="Tenancy"
+    description="Resolve fx.tenant.id and policy.tenant."
+    href="/docs/elements/gate/tenancy"
+  />
+  <Card
+    title="Store · SQL"
+    description="Schema extras, fx.store, and RLS-capable drivers."
+    href="/docs/elements/store/sql"
+  />
+</Cards>