okengine 0.3.6 → 0.5.0

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"
@@ -51,7 +51,7 @@ Every [helmet.js](https://helmet.js.org/) middleware maps to an option here —
 | `xPoweredBy`                    | `poweredBy`                                                                               | Yes — removed; a string sets a decoy value                                  |
 | `xXssProtection`                | `xssProtection`                                                                           | Yes — `0` (disables the legacy buggy auditor)                               |
 
-Beyond parity: headers land on **failures too** (helmet middleware ordering bugs are a classic Express footgun), app-set values win by default, and every option can be driven live from the database (below).
+Beyond parity: headers land on **failures too** (middleware that only wraps happy paths skips error responses), app-set values win by default, and every option can be driven live from the database (below).
 
 ## Options
 

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/ip-allowlist.mdx

@@ -46,8 +46,7 @@ A client whose IP is not on the list receives `403` with a typed denial:
 <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).
+  this to your real proxy count — wrong depth bypasses the allowlist.
 </Callout>
 
 ## Notes

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",

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

@@ -0,0 +1,128 @@
+---
+title: "Passkey"
+description: "Official plugin — simplified WebAuthn register and authenticate under /auth."
+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).
+
+<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.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { passkey } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(passkey());
+```
+
+</Step>
+
+<Step>
+### Register (session required)
+
+Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take input only.
+
+```typescript
+const opts = await api.auth.passkeyRegisterOptions({});
+// opts.data: { challenge, rpId, userId }
+
+await api.auth.passkeyRegister({
+  credentialId: "...",
+  publicKey: "...",
+  userId: opts.data!.userId,
+  challenge: opts.data!.challenge,
+});
+```
+
+Paths: `POST /auth/passkey/register/options`, `POST /auth/passkey/register`.
+
+</Step>
+
+<Step>
+### Authenticate
+
+```typescript
+await api.auth.passkeyAuthenticateOptions({});
+const { data } = await api.auth.passkeyAuthenticate({
+  credentialId: "...",
+  userId: "...",
+});
+```
+
+Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
+v1 issues a session when the stored credential matches `userId`.
+
+</Step>
+
+</Steps>
+
+## 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      |
+
+## Surfaces
+
+| Flow                              | Path                                      | Gate                     |
+| --------------------------------- | ----------------------------------------- | ------------------------ |
+| `auth.passkeyRegisterOptions`     | `POST /auth/passkey/register/options`     | session + bearer         |
+| `auth.passkeyRegister`            | `POST /auth/passkey/register`             | session + bearer         |
+| `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.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="register fails with unauthenticated">
+
+Sign in with another method first. `userId` in the body must match the Bearer session.
+
+</Accordion>
+<Accordion title="authenticate returns invalid_credentials">
+
+Unknown `credentialId`, or `userId` does not match the stored credential. Re-run registration
+after a successful session.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Two-factor](/docs/plugins/two-factor) — TOTP step-up
+- [Gate](/docs/elements/gate) — `gate.auth`
+- [Client](/docs/reference/client) — calling `/auth` from the browser
+
+## Next
+
+<Cards>
+  <Card title="Two-factor" description="TOTP enable / verify." href="/docs/plugins/two-factor" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Anonymous" description="Guest sessions." href="/docs/plugins/anonymous" />
+</Cards>

package/site/content/docs/plugins/phone-number.mdx

@@ -0,0 +1,111 @@
+---
+title: "Phone number"
+description: "Official plugin — E.164 phone OTP request and verify under /auth."
+icon: "Smartphone"
+source: "docs/spec/unified-theory.md"
+---
+
+`phoneNumber()` signs people in with a phone number in E.164 form (`+15551234567`). Codes are
+6 digits, hashed, 10 minutes, 5 attempts — same security shape as email OTP.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(phoneNumber())`. Reject non-E.164 numbers. SMS Channel delivery is
+  not wired yet — use `exposeDevOtp` locally. Prefer stronger methods when phone is the only factor.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { phoneNumber } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(phoneNumber({ exposeDevOtp: true }));
+```
+
+</Step>
+
+<Step>
+### Request a code
+
+```typescript
+const { data, error } = await api.auth.requestPhoneOtp({ phone: "+15551234567" });
+```
+
+`POST /auth/phone/request`. Invalid E.164 → `AuthFailed` / `invalid_phone`.
+
+</Step>
+
+<Step>
+### Verify
+
+```typescript
+const { data } = await api.auth.verifyPhoneOtp({
+  phone: "+15551234567",
+  otp: data!.devOtp!,
+});
+```
+
+`POST /auth/phone/verify` — first success creates a phone → `userId` mapping.
+
+</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 |
+| `phones`        | `PhoneStore`        | new      | Phone → userId map                      |
+| `verifications` | `VerificationStore` | new      | Challenge store                         |
+
+## Surfaces
+
+| Flow                   | Path                       | Gate                     |
+| ---------------------- | -------------------------- | ------------------------ |
+| `auth.requestPhoneOtp` | `POST /auth/phone/request` | `gate.public` + otp rate |
+| `auth.verifyPhoneOtp`  | `POST /auth/phone/verify`  | `gate.public` + otp rate |
+
+E.164 pattern: `^\+[1-9]\d{7,14}$`.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="invalid_phone">
+
+Number must start with `+` and a non-zero country digit, then 7–14 more digits. No spaces or
+dashes.
+
+</Accordion>
+<Accordion title="No SMS arrived">
+
+v1 does not send SMS. Use `exposeDevOtp` in local/test, or deliver via your own Channel Flow.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Email OTP](/docs/plugins/email-otp) — email variant of the same OTP rules
+- [Gate](/docs/elements/gate) — `gate.auth`
+- [Channel](/docs/elements/channel) — when you wire SMS yourself
+
+## Next
+
+<Cards>
+  <Card title="Email OTP" description="Six-digit email codes." href="/docs/plugins/email-otp" />
+  <Card title="Two-factor" description="TOTP step-up." href="/docs/plugins/two-factor" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+</Cards>