okengine 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -71,6 +71,7 @@
     "@duckdb/node-api": "^1.5.5-r.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "intl-messageformat": "^11.2.13",
     "oxc-parser": "^0.142.0",
     "sently": "^0.8.0"
   },

package/site/content/docs/elements/ai.mdx

@@ -88,6 +88,17 @@ export const triage = smart.prompt("ticket-triage", {
 
 <AiGuardrails />
 
+## Tools are flows (same `fx.call` path)
+
+Offer flows as tools on a one-shot ask — each model-initiated call goes through the host flow’s `fx.call`, so capability, Manifest `calls`, and Runs stay honest. No silent extra authority for the model:
+
+```typescript
+const result = await fx.ask(triage, input, {
+  tools: [getBooking, refundBooking],
+  maxSteps: 6,
+});
+```
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:
@@ -101,7 +112,25 @@ export const support = ai.agent("support", {
 });
 ```
 
-`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise.
+`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
+
+## Rate limits via Gate
+
+AI calls are expensive — reuse `gate.rate`, don’t invent a parallel budget. Presets: `aiRateGate("ask" | "agent" | "embed")` (defaults 20 / 10 / 60 per minute, `keyBy: "user"`). Attach on the HTTP trigger:
+
+```typescript
+on(http.post("/triage").gate(member, aiRateGate("ask")), triageFlow);
+```
+
+Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/agent `budget` decls.
+
+## Secrets stay out of prompts
+
+`Redacted` values (e.g. from `fx.vault`) stringify to `[redacted]` in provider-facing messages — the same placeholder as logs. Never cleartext to a model.
+
+## Streaming
+
+`fx.stream(model, { prompt })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
 
 ## PII cannot leak by accident
 
@@ -130,6 +159,53 @@ Because `fx.ask` is nondeterministic, the runtime adjusts around it: journaling
 
 There is deliberately **no production default**: `prod` must name a driver, which keeps the model choice visible in `oke.config.ts` where review can see it.
 
+### Local Ollama
+
+`ollama` is a local-model driver — any model you have pulled works. Pin it in `drivers.ai`; optionally pin `images.ai` for compose.
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    ai: { local: "ollama", docker: "ollama", prod: "anthropic" },
+  },
+  images: {
+    ai: "ollama/ollama:latest",
+  },
+});
+```
+
+```typescript title="src/ai.ts"
+export const smart = ai.model("smart", {
+  provider: "ollama",
+  model: "qwen3.5:9b", // balanced local-dev starting point — override freely
+});
+```
+
+- **Model:** set on `ai.model(…, { model })` or `OKE_AI_MODEL`. `qwen3.5:9b` ([Ollama library](https://ollama.com/library/qwen3.5); same as `qwen3.5:latest`) is a reasonable balanced starting point for local dev — not the only option. On Apple Silicon, prefer `qwen3.5:9b-mlx` for the MLX build.
+- **URL:** default `http://127.0.0.1:11434`. Override with `OKE_AI_URL` or `OLLAMA_HOST` (bare `host:port` is fine).
+- **Docker:** the image recipe pulls the configured model and writes `OKE_AI_URL` into `docker/.env.docker`.
+- **Fail-loud:** unreachable or unhealthy Ollama throws `OllamaUnavailableError` — never a silent mock fallback.
+- **PII:** `ollama` counts as on-premise for the build-time egress check (same as `mock`).
+
+### OpenAI-compatible endpoints (one driver)
+
+`openai-compatible` is the shared chat/completions client — OpenAI, Groq, Together, OpenRouter, vLLM, LM Studio, and Ollama’s `/v1` shim. You do **not** get a separate driver per vendor; only `baseUrl`, `apiKey`, `model`, and optional `headers` change.
+
+| Target             | Typical `baseUrl`                     | Key                                                         |
+| ------------------ | ------------------------------------- | ----------------------------------------------------------- |
+| OpenAI             | `https://api.openai.com/v1` (default) | required (`OPENAI_API_KEY`)                                 |
+| Groq               | `https://api.groq.com/openai/v1`      | required                                                    |
+| Together           | `https://api.together.xyz/v1`         | required                                                    |
+| OpenRouter         | `https://openrouter.ai/api/v1`        | required; optional `HTTP-Referer` / `X-Title` via `headers` |
+| LM Studio / local  | e.g. `http://127.0.0.1:1234/v1`       | optional                                                    |
+| Ollama OpenAI shim | `http://127.0.0.1:11434/v1`           | optional                                                    |
+
+Prefer the native `ollama` driver for local Ollama (`/api/chat`). Point `openai-compatible` at Ollama `/v1` only when you need the OpenAI wire shape.
+
+**Consequence:** a missing key against the default OpenAI cloud base fails at open; a custom `baseUrl` may omit the key. HTTP errors always throw — never a silent mock fallback.
+
 ## Troubleshooting
 
 <Accordions>
@@ -142,6 +218,11 @@ A flow sends a classified PII field to a third-party model. Either stop sending
 
 The one you declared. There is no fallback or guess — if `prod` has no AI driver configured, that's a configuration gap to fix, not a silent default.
 
+</Accordion>
+<Accordion title="oke boot: ollama driver needs OKE_AI_URL">
+
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Locally, the default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers and that you have pulled the model you named (`ollama pull qwen3.5:9b`, or `qwen3.5:9b-mlx` on Apple Silicon, or your `OKE_AI_MODEL`).
+
 </Accordion>
 <Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">
 

package/site/content/docs/elements/channel.mdx

@@ -87,7 +87,12 @@ Opt-out is first-class: a subject who opted out of a medium is **suppressed**
 
 ### Locale resolves through a chain
 
-Templates render per recipient locale, falling back through your configured chain (`ar` → default `en`) instead of failing when a translation is missing. Locales and the default come from the `i18n` block in `oke.config.ts`.
+Templates render per recipient locale, falling back through your configured chain
+(`ar` → default `en`) instead of failing when a translation is missing.
+
+Locales come from `oke.config.ts` `i18n`. Catalog bodies use `{{field}}` — not
+ICU ([i18n](/docs/reference/i18n) / `fx.t` owns flow copy). Pass `locale` /
+`profileLocale` / `acceptLanguage` on `fx.send`, or omit them for `fx.locale`.
 
 ### Fallback chains are explicit
 

package/site/content/docs/elements/flow.mdx

@@ -92,7 +92,9 @@ do: async (input, fx) => {
 };
 ```
 
-Every response follows one envelope — success `{ data, error: null }`, failure `{ data: null, error: { code, data } }` — so clients handle outcomes by `error.code`, not by parsing status text.
+Every response follows one envelope — success `{ data, error: null }`, failure
+`{ data: null, error: { code, data, message? } }` — clients switch on `error.code`.
+Built-in codes attach a localized `message` ([Errors](/docs/reference/errors)); custom codes stay message-less unless registered or `{ message }` is passed.
 
 ## The five triggers
 
@@ -178,22 +180,22 @@ const order = await fx.call(getOrder, { id: orderId }); // from any other flow
 
 Everything a flow may touch, on one object:
 
-| Surface                                 | Effect recorded | What it does                                 |
-| --------------------------------------- | --------------- | -------------------------------------------- |
-| `fx.store(db).select/insert/…`          | read / write    | SQL, KV, files, index sessions               |
-| `fx.emit(signal, payload)`              | emit            | Publish a signal (transactional with writes) |
-| `fx.send(template, opts)`               | send            | Reach a human (email · SMS · …)              |
-| `fx.ask(prompt, input)`                 | ask             | Call a versioned AI prompt                   |
-| `fx.run(agent, input)`                  | ask             | Run a bounded agent                          |
-| `fx.call(flow, input)`                  | call            | Invoke another flow                          |
-| `fx.vault(contract)`                    | read            | Read a secret (`Redacted`; logs masked)      |
-| `fx.clock.now()` / `.sleep(…)`          | —               | Injected time / durable sleep                |
-| `fx.cache.get/set`                      | —               | Shared cache with effect-aware invalidation  |
-| `fx.step(name, fn)`                     | —               | Named durable step — never re-runs on replay |
-| `fx.all` / `fx.race` / `fx.retry`       | —               | Structured concurrency + backoff retry       |
-| `fx.signal`                             | —               | Ambient `AbortSignal` for the current branch |
-| `fx.id()` · `fx.log` · `fx.t`           | —               | UUIDs, redacting logger, i18n                |
-| `fx.auth` · `fx.operator` · `fx.tenant` | —               | Who is calling (user / operator / tenant)    |
+| Surface                                     | Effect recorded | What it does                                 |
+| ------------------------------------------- | --------------- | -------------------------------------------- |
+| `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions               |
+| `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes) |
+| `fx.send(template, opts)`                   | send            | Reach a human (email · SMS · …)              |
+| `fx.ask(prompt, input)`                     | ask             | Call a versioned AI prompt                   |
+| `fx.run(agent, input)`                      | ask             | Run a bounded agent                          |
+| `fx.call(flow, input)`                      | call            | Invoke another flow                          |
+| `fx.vault(contract)`                        | read            | Read a secret (`Redacted`; logs masked)      |
+| `fx.clock.now()` / `.sleep(…)`              | —               | Injected time / durable sleep                |
+| `fx.cache.get/set`                          | —               | Shared cache with effect-aware invalidation  |
+| `fx.step(name, fn)`                         | —               | Named durable step — never re-runs on replay |
+| `fx.all` / `fx.race` / `fx.retry`           | —               | Structured concurrency + backoff retry       |
+| `fx.signal`                                 | —               | Ambient `AbortSignal` for the current branch |
+| `fx.id()` · `fx.log` · `fx.t` · `fx.locale` | —               | UUIDs, redacting logger, ICU i18n            |
+| `fx.auth` · `fx.operator` · `fx.tenant`     | —               | Who is calling (user / operator / tenant)    |
 
 <Callout title="Why this strictness pays off">
   Effects are inferred from `fx` usage, so the Manifest knows exactly which flows read `orders` or
@@ -275,6 +277,7 @@ Only that run fails — the schedule keeps firing and the process does not exit.
 
 ## Learn more
 
+- [fx](/docs/reference/fx) — full `fx` surface, including ICU `fx.t` / `fx.locale`
 - [Signal](/docs/elements/signal) — delivery physics (`once` · `broadcast` · `live`)
 - [Clock](/docs/elements/clock) — schedules and durable sleep
 - [Console · Flows](/docs/console/flows) — the Manifest-derived panel

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

@@ -93,16 +93,16 @@ ninth element — the set of eight is closed.
 
 ## Traditional vs OKE
 
-| Seam               | Maintained by hand                                        | Derived by OKE                                                                  |
-| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                                     |
-| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                                      |
-| HTTP glue          | Middleware copied per repo                                | Official plugins — `securityHeaders`, `cors`, `csrf`, compression, IP allowlist |
-| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                                       |
-| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                               |
-| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                                    |
-| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev --docker`                        |
-| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                           |
+| Seam               | Maintained by hand                                        | Derived by OKE                                                          |
+| ------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                             |
+| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                              |
+| HTTP glue          | Middleware copied per repo                                | Official plugins — `headers`, `cors`, `csrf`, compression, IP allowlist |
+| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                               |
+| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                       |
+| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                            |
+| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev --docker`                |
+| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                   |
 
 ## Ambition, stated plainly
 

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

@@ -5,12 +5,13 @@ 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.
+`emailOtp()` stores a hashed 6-digit code (default 10 minutes, 5 attempts). Request sends the
+code via Channel (`auth-email-otp`); 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.
+  Enable `gate.auth`, then `.plug(emailOtp())`. Never log raw OTPs. Delivery goes through `fx.send`;
+  use `exposeDevOtp` only for local DX without SMTP.
 </Callout>
 
 ## Quick start
@@ -28,7 +29,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(emailOtp({ exposeDevOtp: true }));
+}).plug(emailOtp());
 ```
 
 </Step>
@@ -38,7 +39,7 @@ export const app = oke({
 
 ```typescript
 const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
-// data.devOtp when exposeDevOtp
+// Channel delivers auth-email-otp; data.devOtp only when exposeDevOtp
 ```
 
 `POST /auth/email-otp/request` — prior active codes for that email are invalidated.
@@ -51,7 +52,7 @@ const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
 ```typescript
 const { data } = await api.auth.verifyEmailOtp({
   email: "ali@example.com",
-  otp: data!.devOtp!,
+  otp,
 });
 ```
 
@@ -64,14 +65,15 @@ const { data } = await api.auth.verifyEmailOtp({
 
 ## 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                         |
+| Option          | Type                | Default                    | Meaning                                 |
+| --------------- | ------------------- | -------------------------- | --------------------------------------- |
+| `secret`        | `string`            | active\*                   | HMAC secret (\*from `gate.auth`)        |
+| `sessions`      | `SessionStore`      | active\*                   | Session store                           |
+| `ttlMs`         | `number`            | 10m                        | Challenge lifetime                      |
+| `from`          | `string`            | `OKE <no-reply@oke.local>` | Template From address                   |
+| `exposeDevOtp`  | `boolean`           | `false`                    | Include raw OTP in the request response |
+| `identities`    | `IdentityStore`     | new                        | Email → user map                        |
+| `verifications` | `VerificationStore` | new                        | Challenge store                         |
 
 ## Surfaces
 
@@ -80,13 +82,16 @@ const { data } = await api.auth.verifyEmailOtp({
 | `auth.requestEmailOtp` | `POST /auth/email-otp/request` | `gate.public` + otp rate |
 | `auth.verifyEmailOtp`  | `POST /auth/email-otp/verify`  | `gate.public` + otp rate |
 
+**Consequence:** the plugin contributes the `auth-email-otp` Channel template and EN/AR
+catalog bodies (`{{otp}}`). Override copy by merging your own catalog at boot.
+
 ## 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.
+In `local` / `test` the `console` driver captures mail — open the inbox, or run
+`oke dev --docker` and check Mailpit. For unit tests without SMTP, set `exposeDevOtp: true`.
 
 </Accordion>
 <Accordion title="AuthFailed after a few tries">
@@ -99,7 +104,8 @@ Five failed attempts consume the challenge. Request a new OTP.
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
-- [Phone number](/docs/plugins/phone-number) — SMS OTP (E.164)
+- [Phone number](/docs/plugins/phone-number) — SMS OTP (E.164; delivery deferred)
+- [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
 - [Gate](/docs/elements/gate) — `gate.auth`
 
 ## Next
@@ -107,5 +113,5 @@ Five failed attempts consume the challenge. Request a new OTP.
 <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" />
+  <Card title="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -2,18 +2,18 @@
 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"
+source: "src/plugins/headers.ts"
 ---
 
-`securityHeaders()` stamps security headers on **every** HTTP flow response — successes, failures, and short-circuits alike, because it runs at `onResponse`, the last pipeline stage. An explicit value your app already set is never overridden unless you ask for it.
+`headers()` stamps security headers on **every** HTTP flow response — successes, failures, and short-circuits alike, because it runs at `onResponse`, the last pipeline stage. An explicit value your app already set is never overridden unless you ask for it.
 
 ## Quick start
 
 ```typescript title="src/app.ts"
 import { oke } from "okengine";
-import { securityHeaders } from "okengine/plugins";
+import { headers } from "okengine/plugins";
 
-export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders());
+export const app = oke({ name: "shop", env: "dev" }).plug(headers());
 ```
 
 Every HTTP response now carries:
@@ -75,7 +75,7 @@ Beyond parity: headers land on **failures too** (middleware that only wraps happ
 
 ```typescript
 .plug(
-  securityHeaders({
+  headers({
     contentSecurityPolicy: {
       directives: { scriptSrc: ["'self'", "https://cdn.example.com"] }, // merged over the defaults
       reportOnly: true, // Content-Security-Policy-Report-Only while you tune
@@ -97,18 +97,18 @@ Beyond parity: headers land on **failures too** (middleware that only wraps happ
 Header policy is exactly the config you want to flip without a redeploy — enable HSTS the day HTTPS lands, tighten the CSP after an audit. Pass a `configSource()` and options follow the database within one sync interval:
 
 ```typescript
-const headers = configSource({
-  plugin: "security-headers",
+const headerConfig = configSource({
+  plugin: "headers",
   code: { hsts: false }, // safe floor for local dev
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), headers.sync());
-export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders(headers));
+on(every("30s"), headerConfig.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(headers(headerConfig));
 ```
 
 ```sql
-INSERT INTO security_headers_config ("key", "value")
+INSERT INTO headers_config ("key", "value")
 VALUES ('config', '{"hsts": true}');
 ```
 

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

@@ -5,12 +5,13 @@ 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.
+`magicLink()` issues a hashed, single-use token (default 10 minutes). Request sends the link
+via Channel (`auth-magic-link`); 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.
+  Delivery goes through `fx.send`; use `exposeDevToken` only for local DX without SMTP.
 </Callout>
 
 ## Quick start
@@ -28,7 +29,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(magicLink({ exposeDevToken: true }));
+}).plug(magicLink({ baseUrl: "http://127.0.0.1:6530" }));
 ```
 
 </Step>
@@ -38,10 +39,12 @@ export const app = oke({
 
 ```typescript
 const { data } = await api.auth.requestMagicLink({ email: "ali@example.com" });
-// data.ok === true; data.devToken only when exposeDevToken
+// data.ok === true; Channel delivers auth-magic-link
+// data.devToken only when exposeDevToken
 ```
 
-`POST /auth/magic-link/request`.
+`POST /auth/magic-link/request`. Locally the `console` driver captures mail; with
+`oke dev --docker`, Mailpit receives the real SMTP message.
 
 </Step>
 
@@ -49,7 +52,7 @@ const { data } = await api.auth.requestMagicLink({ email: "ali@example.com" });
 ### Verify
 
 ```typescript
-const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
+const { data } = await api.auth.verifyMagicLink({ token });
 // session tokens + userId
 ```
 
@@ -62,14 +65,16 @@ const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
 
 ## 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                           |
+| Option           | Type                | Default                    | Meaning                                   |
+| ---------------- | ------------------- | -------------------------- | ----------------------------------------- |
+| `secret`         | `string`            | active\*                   | HMAC secret (\*from `gate.auth`)          |
+| `sessions`       | `SessionStore`      | active\*                   | Session store                             |
+| `ttlMs`          | `number`            | 10m                        | Challenge lifetime                        |
+| `baseUrl`        | `string`            | `OKE_APP_URL` or `:6530`   | Origin used to build the magic link       |
+| `from`           | `string`            | `OKE <no-reply@oke.local>` | Template From address                     |
+| `exposeDevToken` | `boolean`           | `false`                    | Include raw token in the request response |
+| `identities`     | `IdentityStore`     | new                        | Email → user map                          |
+| `verifications`  | `VerificationStore` | new                        | Challenge store                           |
 
 ## Surfaces
 
@@ -78,8 +83,8 @@ const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
 | `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).
+**Consequence:** the plugin contributes the `auth-magic-link` Channel template and EN/AR
+catalog bodies (`{{link}}`, `{{token}}`). Override copy by merging your own catalog at boot.
 
 ## Troubleshooting
 
@@ -91,8 +96,9 @@ 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.
+In `local` / `test` the `console` driver captures mail into the inbox — nothing hits a mailbox.
+Run `oke dev --docker` and open Mailpit (`MAILPIT_UI_URL`) to see the rendered message. For
+unit tests without SMTP, set `exposeDevToken: true`.
 
 </Accordion>
 </Accordions>
@@ -101,12 +107,12 @@ link via a Channel Flow you own.
 
 - [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
+- [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
 
 ## 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" />
+  <Card title="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -1,18 +1,18 @@
 ---
 title: "Passkey"
-description: "Official plugin — simplified WebAuthn register and authenticate under /auth."
+description: "Official plugin — WebAuthn register and authenticate under /auth with signature and origin checks."
 icon: "FingerprintPattern"
 source: "docs/spec/unified-theory.md"
 ---
 
-`passkey()` adds register and authenticate Flows for passkey-shaped credentials (`oke_passkeys`).
-v1 is a simplified ceremony — options return a challenge; register/authenticate accept the
-payload your client posts (not a full browser WebAuthn SDK).
+`passkey()` adds register and authenticate Flows for WebAuthn credentials (`oke_passkeys`).
+Options return a challenge; register and authenticate verify `clientDataJSON` origin + challenge,
+`authenticatorData` rpId hash, and an ECDSA P-256 signature against the stored SPKI public key.
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(passkey())`. Registration needs a Bearer session; authenticate is
-  public. Wire `navigator.credentials` (or tests) yourself — the plugin stores and verifies the
-  posted fields.
+  public. Post the full ceremony fields — presence of a stored credential alone never issues a
+  session.
 </Callout>
 
 ## Quick start
@@ -30,7 +30,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(passkey());
+}).plug(passkey({ origins: ["http://localhost", "https://localhost"] }));
 ```
 
 </Step>
@@ -45,10 +45,13 @@ const opts = await api.auth.passkeyRegisterOptions({});
 // opts.data: { challenge, rpId, userId }
 
 await api.auth.passkeyRegister({
-  credentialId: "...",
-  publicKey: "...",
+  credentialId: "...", // base64url
+  publicKey: "...", // base64url SPKI (ECDSA P-256)
   userId: opts.data!.userId,
   challenge: opts.data!.challenge,
+  clientDataJSON: "...", // base64url JSON { type, challenge, origin }
+  authenticatorData: "...", // base64url
+  signature: "...", // base64url ECDSA over authData || SHA-256(clientDataJSON)
 });
 ```
 
@@ -60,15 +63,18 @@ Paths: `POST /auth/passkey/register/options`, `POST /auth/passkey/register`.
 ### Authenticate
 
 ```typescript
-await api.auth.passkeyAuthenticateOptions({});
+const opts = await api.auth.passkeyAuthenticateOptions({});
 const { data } = await api.auth.passkeyAuthenticate({
   credentialId: "...",
-  userId: "...",
+  challenge: opts.data!.challenge,
+  clientDataJSON: "...",
+  authenticatorData: "...",
+  signature: "...",
 });
 ```
 
 Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
-v1 issues a session when the stored credential matches `userId`.
+Challenges are single-use; wrong origin → `invalid_origin`; bad signature → `invalid_credentials`.
 
 </Step>
 
@@ -76,14 +82,15 @@ v1 issues a session when the stored credential matches `userId`.
 
 ## Options
 
-| Option       | Type                | Default       | Meaning                          |
-| ------------ | ------------------- | ------------- | -------------------------------- |
-| `secret`     | `string`            | active\*      | HMAC secret (\*from `gate.auth`) |
-| `sessions`   | `SessionStore`      | active\*      | Session store                    |
-| `now`        | `() => number`      | `Date.now`    | Injectable clock                 |
-| `passkeys`   | `PasskeyStore`      | new           | Credential → user mapping        |
-| `challenges` | `VerificationStore` | new           | Registration / auth challenges   |
-| `rpId`       | `string`            | `"localhost"` | Relying party id in options      |
+| Option       | Type                | Default                                    | Meaning                          |
+| ------------ | ------------------- | ------------------------------------------ | -------------------------------- |
+| `secret`     | `string`            | active\*                                   | HMAC secret (\*from `gate.auth`) |
+| `sessions`   | `SessionStore`      | active\*                                   | Session store                    |
+| `now`        | `() => number`      | `Date.now`                                 | Injectable clock                 |
+| `passkeys`   | `PasskeyStore`      | new                                        | Credential → user mapping        |
+| `challenges` | `VerificationStore` | new                                        | Registration / auth challenges   |
+| `rpId`       | `string`            | `"localhost"`                              | Relying party id                 |
+| `origins`    | `string[]`          | `["http://localhost","https://localhost"]` | Allowed `clientDataJSON.origin`  |
 
 ## Surfaces
 
@@ -94,8 +101,8 @@ v1 issues a session when the stored credential matches `userId`.
 | `auth.passkeyAuthenticateOptions` | `POST /auth/passkey/authenticate/options` | `gate.public` + otp rate |
 | `auth.passkeyAuthenticate`        | `POST /auth/passkey/authenticate`         | `gate.public` + otp rate |
 
-**Consequence:** production apps should replace the simplified verify with a standards-compliant
-WebAuthn verifier when you leave local/test.
+**Consequence:** a stolen `credentialId` without the private key cannot mint a session. Set
+`origins` to your real app origins before production.
 
 ## Troubleshooting
 
@@ -104,11 +111,16 @@ WebAuthn verifier when you leave local/test.
 
 Sign in with another method first. `userId` in the body must match the Bearer session.
 
+</Accordion>
+<Accordion title="authenticate returns invalid_origin">
+
+`clientDataJSON.origin` must be in `passkey({ origins })`. Default allows only localhost HTTP/S.
+
 </Accordion>
 <Accordion title="authenticate returns invalid_credentials">
 
-Unknown `credentialId`, or `userId` does not match the stored credential. Re-run registration
-after a successful session.
+Unknown `credentialId`, consumed/expired challenge, bad signature, or rpId hash mismatch.
+Re-run authenticate options for a fresh challenge, then sign with the enrolled private key.
 
 </Accordion>
 </Accordions>