okengine 0.2.8 → 0.3.4

package/site/content/docs/get-started/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Get Started",
+  "icon": "Rocket",
+  "pages": ["introduction", "comparison", "installation", "basic-usage"]
+}

package/site/content/docs/index.mdx

@@ -0,0 +1,63 @@
+---
+title: "Documentation"
+description: "One law. Eight elements. Ten exports."
+icon: "BookOpen"
+source: "docs/spec/unified-theory.md"
+---
+
+Welcome to the okengine handbook. Pick a section below — or start with Get Started if you are new.
+
+<Callout title="The one law">
+  Every backend behavior is a Flow: `on(Trigger) → Effects`. One species; triggers are typed values.
+</Callout>
+
+```ts
+on(http.post("/bookings"), createBooking);
+on(every("10m"), expireStale);
+on(orderPlaced, sendReceipt);
+```
+
+## Browse by section
+
+<Cards>
+  <Card
+    title="Get Started"
+    description="One law → install → first flows."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Basic Usage"
+    description="Build from the standard starter."
+    href="/docs/get-started/basic-usage"
+  />
+  <Card
+    title="Elements"
+    description="Flow → AI reference, one page each."
+    href="/docs/elements/flow"
+  />
+  <Card
+    title="Console"
+    description="Seventeen Manifest-derived panels."
+    href="/docs/console/overview"
+  />
+  <Card
+    title="Plugins"
+    description="Official extensions — security headers, CORS, CSRF, compression, maintenance, IP rules."
+    href="/docs/plugins/security-headers"
+  />
+  <Card
+    title="CLI Reference"
+    description="`oke` and `create-oke` everyday commands."
+    href="/docs/reference/cli"
+  />
+  <Card
+    title="Security"
+    description="Console security posture — Host, Origin, MCP."
+    href="/docs/reference/security"
+  />
+  <Card
+    title="AI Resources"
+    description="AGENTS.md, MCP `:6535`, `/llms.txt`."
+    href="/docs/ai/mcp"
+  />
+</Cards>

package/site/content/docs/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Documentation",
+  "icon": "BookOpen",
+  "pages": ["index", "get-started", "elements", "plugins", "console", "reference", "ai"]
+}

package/site/content/docs/plugins/compression.mdx

@@ -0,0 +1,60 @@
+---
+title: "Compression"
+description: "Official plugin — gzip response bodies for clients that send Accept-Encoding: gzip, with a size threshold and content-type matcher. Bun.serve does not compress on its own."
+icon: "Shrink"
+source: "src/plugins/compression.ts"
+---
+
+`compression()` gzips HTTP response bodies with the native `Bun.gzipSync` binding when the client advertises `Accept-Encoding: gzip`. `Bun.serve` never compresses on its own — without this plugin every byte goes over the wire raw, no matter how large the JSON.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { compression } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(compression());
+```
+
+A client sending `Accept-Encoding: gzip` now receives `Content-Encoding: gzip` with a `Vary: Accept-Encoding` marker; a client that does not ask gets the untouched body.
+
+## Options
+
+| Option    | Type     | Default                                      | Does                                                                    |
+| --------- | -------- | -------------------------------------------- | ----------------------------------------------------------------------- |
+| `minSize` | `number` | `1024`                                       | Bodies smaller than this pass through raw (gzip can grow tiny payloads) |
+| `match`   | `RegExp` | JSON · `+json` · javascript · xml · `text/*` | Which `Content-Type`s are compressible                                  |
+
+```typescript
+.plug(compression({ minSize: 0 })) // compress even tiny bodies (tests, debugging)
+```
+
+## Notes
+
+| Behavior          | Detail                                                                 |
+| ----------------- | ---------------------------------------------------------------------- |
+| Negotiation       | Runs only when `Accept-Encoding` allows gzip — `gzip;q=0` is respected |
+| Already encoded   | Skips responses that already carry `Content-Encoding`                  |
+| `no-transform`    | Skips responses whose `Cache-Control` forbids transformation           |
+| Content-Length    | Deleted after compression — stale lengths would corrupt the response   |
+| Non-HTTP triggers | No-op — nothing to compress outside HTTP                               |
+
+## Runtime configuration
+
+Thresholds and matchers can follow the database like every other official plugin — pass a `configSource()` as the options. See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Next
+
+<Cards>
+  <Card
+    title="Security Headers"
+    description="The full secure-headers set on every response."
+    href="/docs/plugins/security-headers"
+  />
+  <Card
+    title="IP Allowlist"
+    description="Allow/deny rules by client IP."
+    href="/docs/plugins/ip-allowlist"
+  />
+  <Card title="Plugin API" description="Build your own plugin." href="/docs/reference/plugins" />
+</Cards>

package/site/content/docs/plugins/cors.mdx

@@ -0,0 +1,98 @@
+---
+title: "CORS"
+description: "Official plugin — cross-origin rules at the edge: preflight OPTIONS answered even for paths bound to other methods, plus CORS headers on matched responses. Closed by default."
+icon: "Globe"
+source: "src/plugins/cors.ts"
+---
+
+`cors()` decides which websites may call your app from a browser. It answers preflight `OPTIONS` requests itself — even for paths bound to other methods, which would otherwise 404 before any middleware could run — and stamps `Access-Control-*` headers on matched responses.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { cors } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(
+  cors({ origin: "https://app.example.com" }),
+);
+```
+
+Browsers on `https://app.example.com` can now call every flow; every other origin gets a quiet `204` on preflight with **no** CORS headers, so the browser blocks it. Same-origin traffic never needs this plugin — browsers only enforce CORS across origins.
+
+<Callout title="Closed by default">
+  `cors()` with no `origin` opens nothing. Cross-origin access is a deliberate decision — pass
+  `"*"`, one origin, or an exact-match list when you mean it.
+</Callout>
+
+## Options
+
+| Option           | Type                          | Default                                                | Does                                                                      |
+| ---------------- | ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
+| `origin`         | `"*"` · `string` · `string[]` | none (closed)                                          | Origins allowed cross-origin; lists are exact matches                     |
+| `methods`        | `string[]`                    | GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS     | Methods answered on preflight                                             |
+| `allowedHeaders` | `string[]`                    | reflect the request's `Access-Control-Request-Headers` | `Access-Control-Allow-Headers` on preflight                               |
+| `exposedHeaders` | `string[]`                    | omit                                                   | `Access-Control-Expose-Headers` on actual responses                       |
+| `credentials`    | `boolean`                     | `false`                                                | Send `Access-Control-Allow-Credentials`; requires an explicit origin list |
+| `maxAge`         | `number`                      | omit                                                   | `Access-Control-Max-Age` seconds on preflight                             |
+
+```typescript
+.plug(cors({
+  origin: ["https://app.example.com", "https://admin.example.com"],
+  credentials: true,
+  maxAge: 600,
+}))
+```
+
+<Callout type="error">
+  `cors({ origin: "*", credentials: true })` throws at construction. Browsers reject that literal
+  pair; reflecting the request origin would grant **any** site credentialed access. List exact
+  origins for cookies/`Authorization` — no any-origin + credentials shortcut.
+</Callout>
+
+## Notes
+
+| Behavior          | Detail                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| Preflight         | Answered by the plugin's **edge handler** — runs even when no flow matches the path/method |
+| Denied preflight  | `204` with no CORS headers — the correct, quiet failure; the browser blocks it             |
+| Credentials + `*` | Construction throws — enumerate origins; never reflect `*` into credentialed access        |
+| `Vary`            | `Origin` (plus request-method/headers on preflight) is appended, never duplicated          |
+| Non-HTTP triggers | No-op                                                                                      |
+
+## Runtime configuration
+
+Origin lists belong to the class of config you want to change without a redeploy — an emergency integration, a partner cutover. Pass a `configSource()` instead of static options and the origin rule follows the database:
+
+```typescript
+const origins = configSource({
+  plugin: "cors",
+  code: { origin: "https://app.example.com" },
+  db: { store: db },
+  kv: cache,
+});
+on(every("30s"), origins.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(cors(origins));
+```
+
+See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Next
+
+<Cards>
+  <Card
+    title="CSRF"
+    description="Block cross-site state changes with fetch metadata."
+    href="/docs/plugins/csrf"
+  />
+  <Card
+    title="Security Headers"
+    description="The full secure-headers set on every response."
+    href="/docs/plugins/security-headers"
+  />
+  <Card
+    title="Plugin API"
+    description="Edge handlers and runtime configuration."
+    href="/docs/reference/plugins"
+  />
+</Cards>

package/site/content/docs/plugins/csrf.mdx

@@ -0,0 +1,96 @@
+---
+title: "CSRF"
+description: "Official plugin — cross-site request forgery defense using fetch metadata (Sec-Fetch-Site) with an Origin fallback. Stateless: no tokens, no cookies, no session reads."
+icon: "ShieldAlert"
+source: "src/plugins/csrf.ts"
+---
+
+`csrf()` blocks browsers on other sites from mutating your state. It runs at `onAuth` — before gate policies and the flow body — using the fetch-metadata headers every modern browser sends, with an `Origin` check as the fallback. No tokens to mint, no cookies to double-submit, no session reads: the defense is stateless.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { csrf } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(csrf());
+```
+
+`GET`/`HEAD`/`OPTIONS` always pass. A `POST` with `Sec-Fetch-Site: cross-site` now gets the gate element's typed `Forbidden` — unless its `Origin` is yours or allow-listed.
+
+## How it decides
+
+<Steps>
+
+<Step>
+### Fetch metadata first
+
+`Sec-Fetch-Site: same-origin` and `none` pass. `same-site` passes by default (your subdomains) — set `allowSameSite: false` when subdomains host untrusted content. `cross-site` falls through to the Origin check.
+
+</Step>
+
+<Step>
+### Origin fallback
+
+With `cross-site` (or no metadata at all — older browsers), the `Origin` header must be the app's own origin or an entry in `allowOrigins`; anything else is `Forbidden`.
+
+</Step>
+
+<Step>
+### Headerless clients
+
+Requests carrying neither header — curl, server-to-server calls, webhooks — are not browser CSRF vectors, so they pass by default. Set `allowNoHeader: false` to fail closed when your auth is purely cookie-based.
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option          | Type       | Default | Does                                                                           |
+| --------------- | ---------- | ------- | ------------------------------------------------------------------------------ |
+| `allowOrigins`  | `string[]` | none    | Absolute origins allowed to mutate cross-site (e.g. a separately-hosted admin) |
+| `allowSameSite` | `boolean`  | `true`  | Allow `Sec-Fetch-Site: same-site` (your subdomains)                            |
+| `allowNoHeader` | `boolean`  | `true`  | Allow mutating requests with neither metadata nor `Origin`                     |
+
+## Notes
+
+| Behavior          | Detail                                                                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| Denial shape      | The gate element's typed `Forbidden` (`error.data.reason: "csrf"`) — same as any gate denial               |
+| Legacy browsers   | No fetch metadata → the `Origin` check carries the defense                                                 |
+| Token patterns    | Double-submit tokens can layer on later for defense-in-depth; fetch metadata alone covers current browsers |
+| Non-HTTP triggers | No-op — clock and signal flows are never browser-driven                                                    |
+
+## Runtime configuration
+
+Allow-listed origins are exactly the config you want to change live. Pass a `configSource()` and the rules follow the database within one sync interval:
+
+```typescript
+const rules = configSource({
+  plugin: "csrf",
+  code: { allowOrigins: ["https://admin.example.com"] },
+  db: { store: db },
+  kv: cache,
+});
+on(every("30s"), rules.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(csrf(rules));
+```
+
+See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Next
+
+<Cards>
+  <Card title="CORS" description="Cross-origin rules at the edge." href="/docs/plugins/cors" />
+  <Card
+    title="Gate"
+    description="The element behind the typed denials."
+    href="/docs/elements/gate"
+  />
+  <Card
+    title="Security Headers"
+    description="The full secure-headers set on every response."
+    href="/docs/plugins/security-headers"
+  />
+</Cards>

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -0,0 +1,93 @@
+---
+title: "IP Allowlist"
+description: "Official plugin — allow/deny rules by client IP at the edge of the pipeline, with the same typed Forbidden denial the gate element produces."
+icon: "ListChecks"
+source: "src/plugins/ip-allowlist.ts"
+---
+
+`ipAllowlist()` enforces IP rules at `onAuth`, before any gate policy or flow body runs. Internal admin surfaces, staging environments, and webhook endpoints stop unknown clients at the edge with the same typed `Forbidden` denial the [gate element](/docs/elements/gate) produces.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { ipAllowlist } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(
+  ipAllowlist({ allow: ["203.0.113.7", "2001:db8::42"] }),
+);
+```
+
+A client whose IP is not on the list receives `403` with a typed denial:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "Forbidden",
+    "data": { "reason": "ip_not_allowed", "ip": "198.51.100.9" }
+  }
+}
+```
+
+## Options
+
+| Option              | Type       | Default             | Does                                                                   |
+| ------------------- | ---------- | ------------------- | ---------------------------------------------------------------------- |
+| `allow`             | `string[]` | — (everyone passes) | Exact IPs permitted — every other client is denied                     |
+| `deny`              | `string[]` | — (nobody blocked)  | Exact IPs blocked — checked first, so deny wins on overlap             |
+| `header`            | `string`   | `"x-forwarded-for"` | Header carrying the client IP                                          |
+| `trustedProxyDepth` | `number`   | `1`                 | Trusted proxies that append XFF; client IP is that many from the right |
+
+```typescript
+.plug(ipAllowlist({ deny: ["198.51.100.9"], trustedProxyDepth: 1 }))
+```
+
+<Callout type="error">
+  Standard reverse proxies **append** to `X-Forwarded-For` — left-side hops are attacker-controlled.
+  The plugin trusts the hop `trustedProxyDepth` from the **right** (default `1` = last hop). Set
+  this to your real proxy count; wrong depth bypasses the allowlist — topology-dependent, not
+  drop-in.
+</Callout>
+
+## Notes
+
+| Behavior          | Detail                                                                             |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| XFF parsing       | Last hop (depth `1`) is the client; left-side spoofed entries are ignored          |
+| Missing header    | Denied when `allow` is set (unknown is not allowed); permitted for deny-only rules |
+| Deny wins         | An IP in both lists is blocked                                                     |
+| Non-HTTP triggers | No-op — there is no client IP outside HTTP                                         |
+
+## Runtime configuration
+
+Block an abusive IP from the database and every instance picks it up on the next sync:
+
+```typescript
+const rules = configSource({
+  plugin: "ip-allowlist",
+  code: { deny: [] },
+  db: { store: db },
+  kv: cache,
+});
+on(every("30s"), rules.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(ipAllowlist(rules));
+```
+
+See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Next
+
+<Cards>
+  <Card
+    title="Maintenance Mode"
+    description="Drain traffic with one flag."
+    href="/docs/plugins/maintenance-mode"
+  />
+  <Card
+    title="Gate"
+    description="Policies and rate limits after the IP edge."
+    href="/docs/elements/gate"
+  />
+  <Card title="Plugin API" description="Build your own plugin." href="/docs/reference/plugins" />
+</Cards>

package/site/content/docs/plugins/maintenance-mode.mdx

@@ -0,0 +1,101 @@
+---
+title: "Maintenance Mode"
+description: "Official plugin — drain HTTP traffic with one flag: every flow returns a 503 ServiceUnavailable envelope with an optional Retry-After, while allow-listed paths and an operator bypass header stay alive."
+icon: "Construction"
+source: "src/plugins/maintenance-mode.ts"
+---
+
+`maintenanceMode()` short-circuits every HTTP invocation at `onRequest` — the earliest pipeline stage — with a typed `503 ServiceUnavailable` envelope. Deploys, migrations, and incidents stop traffic with one flag instead of a deploy-time firewall rule.
+
+## Quick start
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { maintenanceMode } from "okengine/plugins";
+
+export const app = oke({ name: "shop", env: "dev" }).plug(
+  maintenanceMode({ enabled: process.env.MAINTENANCE_MODE === "1" }),
+);
+```
+
+With `MAINTENANCE_MODE=1` in the environment, every HTTP flow answers:
+
+```json
+{
+  "data": null,
+  "error": {
+    "code": "ServiceUnavailable",
+    "data": { "retryAfter": 300 },
+    "message": "Service is under maintenance."
+  }
+}
+```
+
+## Options
+
+| Option         | Type       | Default                           | Does                                                 |
+| -------------- | ---------- | --------------------------------- | ---------------------------------------------------- |
+| `enabled`      | `boolean`  | `true`                            | Master switch — drive it from the environment        |
+| `retryAfter`   | `number`   | — (omitted)                       | `Retry-After` seconds on the 503                     |
+| `allowPaths`   | `string[]` | — (none)                          | Path prefixes that keep serving (e.g. `["/health"]`) |
+| `bypassHeader` | `string`   | — (none)                          | Header whose non-empty value lets a request through  |
+| `message`      | `string`   | `"Service is under maintenance."` | Failure message in the envelope                      |
+
+```typescript
+.plug(
+  maintenanceMode({
+    enabled: process.env.MAINTENANCE_MODE === "1",
+    retryAfter: 300,
+    allowPaths: ["/health"],       // load-balancer checks stay green
+    bypassHeader: "x-ops-token",   // operators keep working
+  }),
+)
+```
+
+<Callout type="info">
+  The bypass header is presence-based — an ops convenience, not authentication. Anyone who learns
+  the header name passes through, so treat its value as a light secret and never as a security
+  boundary.
+</Callout>
+
+## Notes
+
+| Behavior          | Detail                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| Pipeline position | `onRequest` — flows never parse, authenticate, or execute                           |
+| Still shaped      | The 503 flows through `onResponse`, so Security Headers and Compression apply to it |
+| Non-HTTP triggers | No-op — clock flows and signal subscribers keep running                             |
+| Infra routes      | `/_oke/*` bypass the pipeline entirely and stay up                                  |
+
+## Runtime configuration
+
+The flagship `configSource()` use case — flip `enabled` from the database and drain traffic without a redeploy:
+
+```typescript
+const maintenance = configSource({
+  plugin: "maintenance-mode",
+  code: { enabled: false },
+  db: { store: db },
+  kv: cache,
+});
+on(every("30s"), maintenance.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
+```
+
+See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configuration-code-or-db) for the full contract.
+
+## Next
+
+<Cards>
+  <Card
+    title="IP Allowlist"
+    description="Allow/deny rules by client IP."
+    href="/docs/plugins/ip-allowlist"
+  />
+  <Card
+    title="Security Headers"
+    description="The full secure-headers set on every response."
+    href="/docs/plugins/security-headers"
+  />
+  <Card title="Plugin API" description="Build your own plugin." href="/docs/reference/plugins" />
+</Cards>

package/site/content/docs/plugins/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Plugins",
+  "icon": "Puzzle",
+  "pages": [
+    "---Security---",
+    "security-headers",
+    "cors",
+    "csrf",
+    "ip-allowlist",
+    "---Operations---",
+    "maintenance-mode",
+    "---Performance---",
+    "compression"
+  ]
+}