okengine 0.4.3 → 0.5.0

package/site/content/docs/get-started/index.mdx

@@ -0,0 +1,33 @@
+---
+title: "Get Started"
+description: "From the one law to a running app — introduction, why OKE, install, and first flows."
+icon: "Rocket"
+source: "docs/spec/unified-theory.md"
+---
+
+Learn the shape once, install on Bun, then write your first Flow from the standard starter.
+
+## Pages
+
+<Cards>
+  <Card
+    title="Introduction"
+    description="One law, eight elements, ten exports."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Why OKE"
+    description="Six seams every backend maintains by hand."
+    href="/docs/get-started/why"
+  />
+  <Card
+    title="Installation"
+    description="Scaffold with create-oke and open the Console."
+    href="/docs/get-started/installation"
+  />
+  <Card
+    title="Basic Usage"
+    description="Health Flow, typed client, Console proof."
+    href="/docs/get-started/basic-usage"
+  />
+</Cards>

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

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

package/site/content/docs/index.mdx

@@ -23,41 +23,19 @@ on(orderPlaced, sendReceipt);
   <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"
+    href="/docs/get-started"
   />
+  <Card title="Elements" description="Flow → AI reference, one page each." href="/docs/elements" />
   <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"
+    description="Official extensions — security, ops, performance."
+    href="/docs/plugins"
   />
+  <Card title="Console" description="Manifest-derived operator panels." href="/docs/console" />
   <Card
-    title="AI Resources"
-    description="AGENTS.md, MCP `:6535`, `/llms.txt`."
-    href="/docs/ai/mcp"
+    title="Reference"
+    description="Config, fx, env, errors, CLI, security."
+    href="/docs/reference"
   />
+  <Card title="AI Resources" description="MCP, skills, /llms.txt." href="/docs/ai" />
 </Cards>

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

@@ -0,0 +1,95 @@
+---
+title: "Anonymous"
+description: "Official plugin — issue a user-plane session with a random id and no password."
+icon: "UserRoundMinus"
+source: "docs/spec/unified-theory.md"
+---
+
+`anonymous()` creates a throwaway principal: one public Flow returns hybrid session tokens for a
+new random `userId`. Use it for guest carts or try-before-account flows.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(anonymous())`. Treat the session like any other Bearer principal —
+  gates still decide what it may do.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { anonymous } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(anonymous());
+```
+
+</Step>
+
+<Step>
+### Sign in anonymously
+
+```typescript
+const { data } = await api.auth.signInAnonymous();
+// data.userId is a fresh UUID; store tokens like any other session
+```
+
+`POST /auth/sign-in/anonymous` — no body.
+
+</Step>
+
+<Step>
+### Gate what guests can do
+
+Attach real policies to guest-capable Flows (`gate.scope`, custom policies). Anonymous only
+issues a session — it does not grant scopes.
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option        | Type           | Default    | Meaning                                                     |
+| ------------- | -------------- | ---------- | ----------------------------------------------------------- |
+| `secret`      | `string`       | active\*   | HMAC secret (\*from `gate.auth` when plugged after `oke()`) |
+| `sessions`    | `SessionStore` | active\*   | Session store shared with Gate auth                         |
+| `now`         | `() => number` | `Date.now` | Injectable clock                                            |
+| `emailDomain` | `string`       | —          | Reserved; unused in v1                                      |
+
+## Surfaces
+
+| Flow                   | Path                           | Gate                         |
+| ---------------------- | ------------------------------ | ---------------------------- |
+| `auth.signInAnonymous` | `POST /auth/sign-in/anonymous` | `gate.public` + sign-in rate |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="plugin boot failed — needs &quot;auth&quot;">
+
+Set `oke({ gate: { auth: { … } } })` before `.plug(anonymous())`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — policies on the new principal
+- [Username](/docs/plugins/username) — upgrade path to a real credential
+- [Plugins](/docs/plugins) — all auth method plugins
+
+## Next
+
+<Cards>
+  <Card title="Username" description="Username + password." href="/docs/plugins/username" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+</Cards>

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

@@ -47,9 +47,9 @@ Thresholds and matchers can follow the database like every other official plugin
 
 <Cards>
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card
     title="IP Allowlist"

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

@@ -86,9 +86,9 @@ See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configur
     href="/docs/plugins/csrf"
   />
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card
     title="Plugin API"

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

@@ -89,8 +89,8 @@ See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configur
     href="/docs/elements/gate"
   />
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
 </Cards>

package/site/content/docs/plugins/email-otp.mdx

@@ -0,0 +1,111 @@
+---
+title: "Email OTP"
+description: "Official plugin — six-digit email one-time codes to sign in under /auth."
+icon: "MailCheck"
+source: "docs/spec/unified-theory.md"
+---
+
+`emailOtp()` stores a hashed 6-digit code (default 10 minutes, 5 attempts). Verify creates the
+user on first success and returns hybrid session tokens.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(emailOtp())`. Never log raw OTPs. Channel email delivery is not
+  wired yet — use `exposeDevOtp` locally.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { emailOtp } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(emailOtp({ exposeDevOtp: true }));
+```
+
+</Step>
+
+<Step>
+### Request a code
+
+```typescript
+const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
+// data.devOtp when exposeDevOtp
+```
+
+`POST /auth/email-otp/request` — prior active codes for that email are invalidated.
+
+</Step>
+
+<Step>
+### Verify
+
+```typescript
+const { data } = await api.auth.verifyEmailOtp({
+  email: "ali@example.com",
+  otp: data!.devOtp!,
+});
+```
+
+`POST /auth/email-otp/verify`. Wrong code increments attempts; after 5 →
+`invalid_credentials`.
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option          | Type                | Default  | Meaning                                 |
+| --------------- | ------------------- | -------- | --------------------------------------- |
+| `secret`        | `string`            | active\* | HMAC secret (\*from `gate.auth`)        |
+| `sessions`      | `SessionStore`      | active\* | Session store                           |
+| `ttlMs`         | `number`            | 10m      | Challenge lifetime                      |
+| `exposeDevOtp`  | `boolean`           | `false`  | Include raw OTP in the request response |
+| `identities`    | `IdentityStore`     | new      | Email → user map                        |
+| `verifications` | `VerificationStore` | new      | Challenge store                         |
+
+## Surfaces
+
+| Flow                   | Path                           | Gate                     |
+| ---------------------- | ------------------------------ | ------------------------ |
+| `auth.requestEmailOtp` | `POST /auth/email-otp/request` | `gate.public` + otp rate |
+| `auth.verifyEmailOtp`  | `POST /auth/email-otp/verify`  | `gate.public` + otp rate |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="No email with the code">
+
+v1 does not send mail. Use `exposeDevOtp` in local/test, or send the code via your own Channel
+Flow.
+
+</Accordion>
+<Accordion title="AuthFailed after a few tries">
+
+Five failed attempts consume the challenge. Request a new OTP.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Magic link](/docs/plugins/magic-link) — link instead of a code
+- [Phone number](/docs/plugins/phone-number) — SMS OTP (E.164)
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card title="Phone number" description="E.164 SMS OTP." href="/docs/plugins/phone-number" />
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+  <Card title="Two-factor" description="TOTP step-up." href="/docs/plugins/two-factor" />
+</Cards>

package/site/content/docs/plugins/{security-headers.mdx → headers.mdx}

@@ -1,5 +1,5 @@
 ---
-title: "Security Headers"
+title: "Headers"
 description: "Official plugin — the complete secure-headers set on every HTTP response, failures included. Full helmet.js parity with API-first defaults, a CSP builder with report-only mode, and live DB-driven config."
 icon: "ShieldCheck"
 source: "src/plugins/security-headers.ts"

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

@@ -0,0 +1,69 @@
+---
+title: "Plugins"
+description: "Official okengine/plugins extensions — authentication, security, operations, and performance."
+icon: "Puzzle"
+source: "docs/spec/unified-theory.md"
+---
+
+First-party plugins you `.plug()` onto an app. Each page is one export from `okengine/plugins`.
+
+## Authentication
+
+<Cards>
+  <Card title="Username" description="Username + password." href="/docs/plugins/username" />
+  <Card
+    title="Anonymous"
+    description="Guest session, no password."
+    href="/docs/plugins/anonymous"
+  />
+  <Card title="Magic link" description="One-time email link." href="/docs/plugins/magic-link" />
+  <Card title="Email OTP" description="Six-digit email codes." href="/docs/plugins/email-otp" />
+  <Card title="Phone number" description="E.164 SMS OTP." href="/docs/plugins/phone-number" />
+  <Card title="Two-factor" description="TOTP enable / verify." href="/docs/plugins/two-factor" />
+  <Card title="Passkey" description="WebAuthn-shaped passkeys." href="/docs/plugins/passkey" />
+</Cards>
+
+## Security
+
+<Cards>
+  <Card
+    title="Headers"
+    description="Secure headers on every HTTP response."
+    href="/docs/plugins/headers"
+  />
+  <Card
+    title="CORS"
+    description="Cross-origin rules; closed by default."
+    href="/docs/plugins/cors"
+  />
+  <Card
+    title="CSRF"
+    description="Fetch-metadata forgery defense, no tokens."
+    href="/docs/plugins/csrf"
+  />
+  <Card
+    title="IP Allowlist"
+    description="Allow/deny by client IP at the edge."
+    href="/docs/plugins/ip-allowlist"
+  />
+</Cards>
+
+## Operations
+
+<Cards>
+  <Card
+    title="Maintenance Mode"
+    description="Drain HTTP with 503 and Retry-After."
+    href="/docs/plugins/maintenance-mode"
+  />
+</Cards>
+
+## Performance
+
+<Cards>
+  <Card
+    title="Compression"
+    description="gzip responses when the client accepts it."
+    href="/docs/plugins/compression"
+  />
+</Cards>

package/site/content/docs/plugins/magic-link.mdx

@@ -0,0 +1,112 @@
+---
+title: "Magic link"
+description: "Official plugin — request and verify a one-time email link to sign in under /auth."
+icon: "Link2"
+source: "docs/spec/unified-theory.md"
+---
+
+`magicLink()` issues a hashed, single-use token (default 10 minutes). Verify exchanges it for a
+hybrid session and creates the user on first success.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(magicLink())`. Tokens are hashed at rest — never log the raw link.
+  Channel email delivery is not wired yet; use `exposeDevToken` locally.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { magicLink } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(magicLink({ exposeDevToken: true }));
+```
+
+</Step>
+
+<Step>
+### Request a link
+
+```typescript
+const { data } = await api.auth.requestMagicLink({ email: "ali@example.com" });
+// data.ok === true; data.devToken only when exposeDevToken
+```
+
+`POST /auth/magic-link/request`.
+
+</Step>
+
+<Step>
+### Verify
+
+```typescript
+const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
+// session tokens + userId
+```
+
+`POST /auth/magic-link/verify`. Bad or reused tokens → `AuthFailed` /
+`invalid_credentials`.
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option           | Type                | Default  | Meaning                                   |
+| ---------------- | ------------------- | -------- | ----------------------------------------- |
+| `secret`         | `string`            | active\* | HMAC secret (\*from `gate.auth`)          |
+| `sessions`       | `SessionStore`      | active\* | Session store                             |
+| `ttlMs`          | `number`            | 10m      | Challenge lifetime                        |
+| `exposeDevToken` | `boolean`           | `false`  | Include raw token in the request response |
+| `identities`     | `IdentityStore`     | new      | Email → user map                          |
+| `verifications`  | `VerificationStore` | new      | Challenge store                           |
+
+## Surfaces
+
+| Flow                    | Path                            | Gate                     |
+| ----------------------- | ------------------------------- | ------------------------ |
+| `auth.requestMagicLink` | `POST /auth/magic-link/request` | `gate.public` + otp rate |
+| `auth.verifyMagicLink`  | `POST /auth/magic-link/verify`  | `gate.public` + otp rate |
+
+**Consequence:** until Channel delivery ships, production apps must send the link themselves
+(or keep `exposeDevToken` off and never log tokens).
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="verify returns invalid_credentials">
+
+Token expired (default 10m), already used, or mistyped. Request a new link.
+
+</Accordion>
+<Accordion title="No email arrived">
+
+v1 does not send mail. Use `exposeDevToken` in local/test, or deliver `devToken` / your own
+link via a Channel Flow you own.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Email OTP](/docs/plugins/email-otp) — numeric code instead of a link
+- [Gate](/docs/elements/gate) — `gate.auth`
+- [Channel](/docs/elements/channel) — when you wire delivery yourself
+
+## Next
+
+<Cards>
+  <Card title="Email OTP" description="Six-digit email codes." href="/docs/plugins/email-otp" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Username" description="Password sign-in." href="/docs/plugins/username" />
+</Cards>

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

@@ -60,12 +60,12 @@ With `MAINTENANCE_MODE=1` in the environment, every HTTP flow answers:
 
 ## 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                                  |
+| Behavior          | Detail                                                                     |
+| ----------------- | -------------------------------------------------------------------------- |
+| Pipeline position | `onRequest` — flows never parse, authenticate, or execute                  |
+| Still shaped      | The 503 flows through `onResponse`, so 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
 
@@ -93,9 +93,9 @@ See [Plugins → Runtime configuration](/docs/reference/plugins#runtime-configur
     href="/docs/plugins/ip-allowlist"
   />
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card title="Plugin API" description="Build your own plugin." href="/docs/reference/plugins" />
 </Cards>

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

@@ -2,8 +2,17 @@
   "title": "Plugins",
   "icon": "Puzzle",
   "pages": [
+    "index",
+    "---Authentication---",
+    "username",
+    "anonymous",
+    "magic-link",
+    "email-otp",
+    "phone-number",
+    "two-factor",
+    "passkey",
     "---Security---",
-    "security-headers",
+    "headers",
     "cors",
     "csrf",
     "ip-allowlist",