okengine 0.4.3 → 0.5.1

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

@@ -0,0 +1,140 @@
+---
+title: "Passkey"
+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 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. Post the full ceremony fields — presence of a stored credential alone never issues a
+  session.
+</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({ origins: ["http://localhost", "https://localhost"] }));
+```
+
+</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: "...", // 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)
+});
+```
+
+Paths: `POST /auth/passkey/register/options`, `POST /auth/passkey/register`.
+
+</Step>
+
+<Step>
+### Authenticate
+
+```typescript
+const opts = await api.auth.passkeyAuthenticateOptions({});
+const { data } = await api.auth.passkeyAuthenticate({
+  credentialId: "...",
+  challenge: opts.data!.challenge,
+  clientDataJSON: "...",
+  authenticatorData: "...",
+  signature: "...",
+});
+```
+
+Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
+Challenges are single-use; wrong origin → `invalid_origin`; bad signature → `invalid_credentials`.
+
+</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                 |
+| `origins`    | `string[]`          | `["http://localhost","https://localhost"]` | Allowed `clientDataJSON.origin`  |
+
+## 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:** a stolen `credentialId` without the private key cannot mint a session. Set
+`origins` to your real app origins before production.
+
+## 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_origin">
+
+`clientDataJSON.origin` must be in `passkey({ origins })`. Default allows only localhost HTTP/S.
+
+</Accordion>
+<Accordion title="authenticate returns invalid_credentials">
+
+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>
+
+## 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>

package/site/content/docs/plugins/two-factor.mdx

@@ -0,0 +1,117 @@
+---
+title: "Two-factor"
+description: "Official plugin — TOTP enable, verify, and disable for an authenticated session."
+icon: "LockKeyhole"
+source: "docs/spec/unified-theory.md"
+---
+
+`twoFactor()` adds RFC 6238 TOTP (HMAC-SHA1, 6 digits, 30s) after someone already has a session.
+Enable returns a secret, `otpauth://` URL, and recovery codes; verify mints a new session.
+TOTP codes are compared in constant time (±1 step window).
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(twoFactor())`. Enable and disable need a Bearer session —
+  verify is public and takes `{ userId, code }` after password (or other) sign-in.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { twoFactor } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(twoFactor());
+```
+
+</Step>
+
+<Step>
+### Enable (session required)
+
+Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take input only.
+
+```typescript
+const { data } = await api.auth.twoFactorEnable({});
+// data.secret, data.otpauthUrl, data.recoveryCodes
+```
+
+`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once; they are
+shown only here.
+
+</Step>
+
+<Step>
+### Verify a code
+
+```typescript
+const { data } = await api.auth.twoFactorVerify({ userId, code: "123456" });
+// hybrid session tokens — recovery codes also accepted once each
+```
+
+`POST /auth/two-factor/verify`. Missing / disabled factor or bad code → `AuthFailed` /
+`invalid_credentials`. Disable: `api.auth.twoFactorDisable` (Bearer via `auth.getToken`).
+
+</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                 |
+| `factors`  | `TwoFactorStore` | new        | Per-user TOTP + recovery hashes  |
+| `issuer`   | `string`         | `"oke"`    | Label in `otpauth://` URLs       |
+
+## Surfaces
+
+| Flow                    | Path                            | Gate                     |
+| ----------------------- | ------------------------------- | ------------------------ |
+| `auth.twoFactorEnable`  | `POST /auth/two-factor/enable`  | session + bearer         |
+| `auth.twoFactorVerify`  | `POST /auth/two-factor/verify`  | `gate.public` + otp rate |
+| `auth.twoFactorDisable` | `POST /auth/two-factor/disable` | session + bearer         |
+
+**Consequence:** verify issues a full session for `userId` — use it as the step after first-factor
+sign-in when the account has 2FA enabled.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="twoFactorEnable returns AuthFailed unauthenticated">
+
+Wire a session into `createClient` (`auth.getToken` / `memorySession`) from email/password
+(or another method) first — enable is gated on Bearer.
+
+</Accordion>
+<Accordion title="verify always fails">
+
+Code must be six digits. Check clock skew (±1 window), and that you enrolled the `secret` from
+enable. A recovery code works once, then is consumed.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
+- [Gate](/docs/elements/gate) — session + policies
+- [Username](/docs/plugins/username) — first factor to enroll against
+
+## Next
+
+<Cards>
+  <Card title="Passkey" description="WebAuthn register and assert." href="/docs/plugins/passkey" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Email OTP" description="Passwordless email codes." href="/docs/plugins/email-otp" />
+</Cards>

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

@@ -0,0 +1,117 @@
+---
+title: "Username"
+description: "Official plugin — username + password sign-up and sign-in under /auth, plugged onto gate.auth."
+icon: "UserRound"
+source: "docs/spec/unified-theory.md"
+---
+
+`username()` lets people register and sign in with a username instead of email. It adds two public
+Flows under `/auth` and contributes the `oke_usernames` table.
+
+<Callout title="The one rule">
+  Enable `gate.auth` first, then `.plug(username())`. The plugin `.needs("auth")` and joins the HTTP
+  router via Bindings — not registry metadata alone.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { username } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(username());
+```
+
+</Step>
+
+<Step>
+### Sign up
+
+```typescript
+const { data, error } = await api.auth.signUpUsername({
+  username: "ali",
+  password: "CorrectHorse1",
+});
+```
+
+`POST /auth/sign-up/username` — usernames are normalized to lowercase; allowed pattern
+`[a-z0-9._-]{3,64}`.
+
+</Step>
+
+<Step>
+### Sign in
+
+```typescript
+const { data } = await api.auth.signInUsername({
+  username: "ali",
+  password: "CorrectHorse1",
+});
+// data: accessToken, refreshToken, accessExpiresAt, userId
+```
+
+Unknown username and bad password both return `AuthFailed` with
+`reason: "invalid_credentials"` (enumeration-safe).
+
+</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                                            |
+| `usernames` | `UsernameStore` | new map    | Shared in-memory credential store                           |
+
+## Surfaces
+
+| Flow                  | Path                          | Gate                         |
+| --------------------- | ----------------------------- | ---------------------------- |
+| `auth.signUpUsername` | `POST /auth/sign-up/username` | `gate.public` + sign-up rate |
+| `auth.signInUsername` | `POST /auth/sign-in/username` | `gate.public` + sign-in rate |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="plugin boot failed — needs &quot;auth&quot;">
+
+Set `oke({ gate: { auth: { … } } })` before `.plug(username())`.
+
+</Accordion>
+<Accordion title="AuthFailed invalid_credentials on sign-up">
+
+Username taken, or it fails the `[a-z0-9._-]{3,64}` pattern after lowercasing. Same error shape
+on purpose — do not treat it as "exists" in the UI.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — `gate.auth` and posture
+- [Plugins](/docs/plugins) — all auth method plugins
+- [Client](/docs/reference/client) — `createClient` + `memorySession`
+
+## Next
+
+<Cards>
+  <Card
+    title="Anonymous"
+    description="Session without a password."
+    href="/docs/plugins/anonymous"
+  />
+  <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>