okengine 0.8.0 → 0.9.1

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

@@ -0,0 +1,214 @@
+---
+title: "OTP"
+description: "Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit provider or app mode."
+icon: "KeyRound"
+source: "docs/spec/unified-theory.md"
+---
+
+`otp()` signs people in with a one-time code. You must set `mode` — there is no
+auto-detect. Provider mode is SMS Verify via the bound driver; app mode is
+app-owned delivery across the channels you declare.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(otp({ mode: "provider" }))` or
+  `.plug(otp({ mode: "app", channels: [...] }))`. Never omit `mode`. Never log
+  raw OTPs.
+</Callout>
+
+<Callout type="info" title="One otp() per app">
+  Provider and app mode cannot both be active — they claim the same fixed `/auth/otp/*` routes. Need
+  two OTP-like mechanisms? Combine `otp()` with a different plugin (e.g. `magicLink()`), not a
+  second `otp()`.
+</Callout>
+
+<Callout type="info" title="fx.sendOtp vs otp()">
+  `fx.sendOtp` / `fx.verifyOtp` are raw Channel capabilities — no `.plug()`. Direct use means you
+  build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path; skip
+  it and call the raw methods in your own flow without losing the provider connection.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug app mode (multi-channel)
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { otp } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(
+  otp({
+    mode: "app",
+    channels: ["sms", "whatsapp", "email"],
+    exposeDevOtp: true, // local DX only
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Request a code
+
+```typescript
+const { data } = await api.auth.requestOtp({
+  phone: "+15551234567",
+  email: "ali@example.com",
+});
+```
+
+`POST /auth/otp/request`. Prior active challenges for that principal are
+invalidated. Delivery follows `channels` order for addresses you pass.
+
+</Step>
+
+<Step>
+### Resend on another channel (app mode only)
+
+```typescript
+const { data } = await api.auth.resendOtp({
+  phone: "+15551234567",
+  email: "ali@example.com",
+  channel: "email",
+});
+```
+
+Same code, same TTL. Default cooldown is 60 seconds. Provider mode has no
+resend surface — the provider owns the code.
+
+</Step>
+
+<Step>
+### Verify
+
+```typescript
+const { data } = await api.auth.verifyOtp({
+  phone: "+15551234567",
+  otp,
+});
+```
+
+`POST /auth/otp/verify` — five failed attempts consume the challenge.
+
+</Step>
+
+</Steps>
+
+## Modes
+
+|                      | Provider mode                 | App mode                                      |
+| -------------------- | ----------------------------- | --------------------------------------------- |
+| Config               | `otp({ mode: "provider" })`   | `otp({ mode: "app", channels: [...] })`       |
+| Who owns the code    | Provider (Verify API)         | Your app                                      |
+| Delivery             | `fx.sendOtp` / `fx.verifyOtp` | `fx.deliverOtp` (Channel templates)           |
+| Channels             | SMS only                      | `sms` · `whatsapp` · `email` (declared order) |
+| Resend other channel | Impossible                    | `POST /auth/otp/resend`                       |
+| `exposeDevOtp`       | Forbidden                     | Optional (default off)                        |
+
+<Callout type="warn" title="Provider mode limitation">
+  Resend-via-different-channel is impossible in provider mode — the code value is never visible to
+  OKE. Use app mode when you need SMS → email fallback for the same code.
+</Callout>
+
+### Provider mode setup
+
+```typescript title="oke.config.ts"
+export default {
+  drivers: {
+    channel: {
+      sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
+    },
+  },
+};
+```
+
+Boot fails loudly if no SMS driver exposes `sendOtp` / `verifyOtp`. Switch to
+app mode, or bind a Verify-capable driver (for example `taqnyat`).
+
+### App mode delivery
+
+| Concern         | Behavior                                                                                                                    |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Storage         | SHA-256 hash for verify + sealed AES-GCM copy (HKDF `oke-otp-seal-v1`) for redelivery                                       |
+| Seal lifetime   | Wiped on verify, lockout, or TTL expiry — never left after the challenge dies                                               |
+| Challenge TTL   | Default 10 minutes (`ttlMs`)                                                                                                |
+| Resend cooldown | Default 60 seconds (`resendCooldownMs`) — separate from TTL                                                                 |
+| Auto failover   | On real provider send errors, sently `FallbackTransport` walks remaining media; Taqnyat WhatsApp may use `sendWithFailover` |
+| User resend     | Explicit `resend` with `channel` — not automatic                                                                            |
+
+Templates: `auth-otp-email`, `auth-otp-sms`, `auth-otp-whatsapp` (EN/AR,
+`{{otp}}`). SMS here is a plain message — not Taqnyat Verify.
+
+## Options
+
+| Option             | Type                             | Default                    | Meaning                             |
+| ------------------ | -------------------------------- | -------------------------- | ----------------------------------- |
+| `mode`             | `"provider" \| "app"`            | required                   | Delivery mechanism — no auto        |
+| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required in app mode       | Build-time preferred order          |
+| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                  |
+| `resendCooldownMs` | `number`                         | 60s                        | App-mode resend spacing             |
+| `exposeDevOtp`     | `boolean`                        | `false`                    | App mode only — raw OTP in response |
+| `from`             | `string`                         | `OKE <no-reply@oke.local>` | Email template From                 |
+| `secret`           | `string`                         | active\*                   | Auth secret (\*from `gate.auth`)    |
+| `sessions`         | `SessionStore`                   | active\*                   | Session store                       |
+| `identities`       | `IdentityStore`                  | new                        | Email → user                        |
+| `phones`           | `PhoneStore`                     | new                        | Phone → user                        |
+| `verifications`    | `VerificationStore`              | new                        | Challenge store                     |
+
+## Surfaces
+
+| Flow              | Path                     | Gate                     | Mode          |
+| ----------------- | ------------------------ | ------------------------ | ------------- |
+| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | both          |
+| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | both          |
+| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | app mode only |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title='otp(): mode is required'>
+
+You omitted `mode`. Set `mode: "provider"` or `mode: "app"` explicitly — OKE
+never infers which mechanism you meant.
+
+</Accordion>
+<Accordion title="Boot fails in provider mode">
+
+No Verify-capable SMS driver is bound. Set `drivers.channel.sms` to `taqnyat`
+(or another driver with `sendOtp`/`verifyOtp`), or switch to
+`otp({ mode: "app", channels: [...] })`.
+
+</Accordion>
+<Accordion title="resend_cooldown">
+
+Wait for `resendCooldownMs` (default 60s). The challenge TTL is unchanged —
+only delivery is rate-limited.
+
+</Accordion>
+<Accordion title="No email / SMS with the code (app mode)">
+
+In `local` / `test` the `console` driver captures messages. Use
+`exposeDevOtp: true` for unit tests without a real provider.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Magic link](/docs/plugins/magic-link) — link instead of a code
+- [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+  <Card title="Two-factor" description="TOTP second factor." href="/docs/plugins/two-factor" />
+  <Card title="Channel" description="Delivery drivers and Mailpit." href="/docs/elements/channel" />
+</Cards>

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

@@ -107,12 +107,12 @@ enable. A recovery code works once, then is consumed.
 - [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against
-- OTP over SMS or email instead of TOTP? See [Phone number](/docs/plugins/phone-number) / [Magic link](/docs/plugins/magic-link)
+- OTP over SMS or email instead of TOTP? See [OTP](/docs/plugins/otp) / [Magic link](/docs/plugins/magic-link)
 
 ## 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" />
+  <Card title="OTP" description="SMS, WhatsApp, or email codes." href="/docs/plugins/otp" />
 </Cards>

package/site/content/docs/reference/cli.md

@@ -33,8 +33,9 @@ oke db seed --env prod --force   # CI: skip docker/prod confirmation prompt
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
-oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
+oke docker                       # docker/Dockerfile + compose.yml + compose.<role>.yml + compose.all.yml · …
+                                 # opt-in images.proxy → Caddyfile (caddy) or Traefik labels + socket-proxy
+oke docker --prod                # + compose.prod.yml (HEALTHCHECK /_/ready, deploy, limits); folded into compose.all.yml
 oke docker clean                 # TTY: pick oke-dev-* stacks → down -v (containers, networks, volumes)
 oke docker clean --yes           # non-TTY: current project stack only
 oke docker clean --all --yes     # non-TTY: every oke-dev-* stack on this machine

package/site/content/docs/reference/configuration.mdx

@@ -75,16 +75,32 @@ Container image pins keyed by element role — vendor choice lives here, never i
 ```typescript
 images: {
   "store.sql": "postgres:18",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
   "store.kv": "redis:8",
+  // or: "valkey/valkey:8-alpine"
+  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
   "store.files": "rustfs/rustfs:1.0.0-beta.11",
   "channel.email": "axllent/mailpit:v1.22.3",
   vault: "openbao/openbao:2.6.1",
   ai: "ollama/ollama:latest",
+  // opt-in TLS edge — omit for the default (app publishes 6530):
+  // proxy: "caddy:2-alpine",   // simplest automatic HTTPS
+  // proxy: "traefik:v3.3",     // label auto-discovery for --scale app=N
 },
 ```
 
+When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog
+(`6432`) — wire-protocol transparent to Bun.SQL / Drizzle. See
+[Store · Multiple environments](/docs/elements/store#multiple-environments).
+
+For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays
+`redis`, same `REDIS_URL`. Image table + licenses: [Store · KV](/docs/elements/store#kv).
+
 For `ai`, the Ollama recipe pulls `OKE_AI_MODEL` (default `qwen3.5:9b` — a balanced local-dev starting point; override freely; on Apple Silicon prefer `qwen3.5:9b-mlx`) and writes `OKE_AI_URL`.
 
+For `proxy`, pin **either** Caddy or Traefik — never both. Opt-in only; see
+[Reverse proxy](/docs/deployment/reverse-proxy).
+
 ## i18n
 
 | Option    | Type       | Default | Meaning                                     |

package/site/content/docs/reference/environment-variables.mdx

@@ -13,14 +13,15 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## SQL store
 
-| Variable            | Used for                                                                      | Default when unset              |
-| ------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
-| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal drivers, drizzle-kit) | `postgres://localhost:5432/oke` |
-| `OKE_STORE_SQL_URL` | Explicit SQL URL override                                                     | —                               |
-| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                                            | `.oke/app.sqlite`               |
-| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)                                     | `.oke/app.libsql`               |
-| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)                              | `.oke/pgdata`                   |
-| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                               | config map                      |
+| Variable            | Used for                                                                                                                                        | Default when unset              |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal drivers, drizzle-kit). When PgDog is in the stack, this points at the pooler (`:6432`). | `postgres://localhost:5432/oke` |
+| `OKE_STORE_SQL_URL` | Direct SQL URL (Postgres host, even when PgDog fronts the app)                                                                                  | —                               |
+| `OKE_PGDOG_URL`     | PgDog pooler URL (same value as `DATABASE_URL` when both are present)                                                                           | —                               |
+| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                                                                                                              | `.oke/app.sqlite`               |
+| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)                                                                                                       | `.oke/app.libsql`               |
+| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)                                                                                                | `.oke/pgdata`                   |
+| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                                                                                                 | config map                      |
 
 ## Index store
 

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

@@ -243,7 +243,7 @@ Extending an existing **app-owned** table with plugin columns is not supported i
 
 ## Learn more
 
-- [Plugins](/docs/plugins) — [username](/docs/plugins/username) · [anonymous](/docs/plugins/anonymous) · [magic link](/docs/plugins/magic-link) · [email OTP](/docs/plugins/email-otp) · [phone](/docs/plugins/phone-number) · [two-factor](/docs/plugins/two-factor) · [passkey](/docs/plugins/passkey) · [Headers](/docs/plugins/headers) · [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) · [Compression](/docs/plugins/compression) · [Maintenance Mode](/docs/plugins/maintenance-mode) · [IP Allowlist](/docs/plugins/ip-allowlist)
+- [Plugins](/docs/plugins) — [username](/docs/plugins/username) · [anonymous](/docs/plugins/anonymous) · [magic link](/docs/plugins/magic-link) · [OTP](/docs/plugins/otp) · [two-factor](/docs/plugins/two-factor) · [passkey](/docs/plugins/passkey) · [Headers](/docs/plugins/headers) · [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) · [Compression](/docs/plugins/compression) · [Maintenance Mode](/docs/plugins/maintenance-mode) · [IP Allowlist](/docs/plugins/ip-allowlist)
 - [Flow](/docs/elements/flow) — what plugin flows and hooks plug into
 - [Store](/docs/elements/store) — `field.*` builders and schema sync
 - [Configuration](/docs/reference/configuration) — where plugin config is declared

package/src/auth/auth.test.ts

@@ -231,6 +231,42 @@ describe("hybrid sessions", () => {
       SessionError,
     );
   });
+
+  test("scopes and audience survive on the session row across store instances", async () => {
+    const store = createSessionStore();
+    let now = 2_000_000;
+    const crypto = {
+      secret: "test-secret",
+      now: () => now,
+      audience: "oke-app",
+    };
+    const issued = await issueSessionWithScopes(store, crypto, {
+      id: "user-2",
+      plane: "user",
+      scopes: ["notes:write", "notes:read"],
+    });
+    expect(issued.session.scopes).toEqual(["notes:write", "notes:read"]);
+    expect(issued.session.audience).toBe("oke-app");
+
+    // Simulate process restart: copy rows into a fresh SessionStore (no module Maps).
+    const restored = createSessionStore();
+    for (const [id, row] of store.sessions) {
+      restored.sessions.set(id, { ...row, scopes: [...row.scopes] });
+    }
+    for (const [id, row] of store.refresh) {
+      restored.refresh.set(id, { ...row });
+    }
+
+    now += 1_000;
+    const rotated = await rotateRefresh(restored, crypto, issued.refreshToken);
+    const { verifyAccess } = await import("./sessions.ts");
+    const claims = await verifyAccess(restored, crypto.secret, rotated.accessToken, {
+      now: () => now,
+      audience: "oke-app",
+    });
+    expect(claims.scopes).toEqual(["notes:write", "notes:read"]);
+    expect(claims.aud).toBe("oke-app");
+  });
 });
 
 describe("operator plane", () => {

package/src/auth/bindings.ts

@@ -32,7 +32,7 @@ import {
   type SessionCrypto,
   type SessionStore,
 } from "./sessions.ts";
-import { touchRateLimit, type LoginAttemptBag, createLoginAttemptBag } from "./rate.ts";
+import { type LoginAttemptBag, createLoginAttemptBag } from "./rate.ts";
 
 /** Built-in policy: verified user session (for `/auth/me` and step-up surfaces). */
 export const AUTH_SESSION_GATE: PolicyGateDecl = gate.policy(
@@ -297,17 +297,8 @@ export function createAuthHttpBindings(
       out: SessionTokensOut,
       errors: { AuthFailed, AuthRateLimited },
       do: async (input) => {
-        const key = input.email.trim().toLowerCase();
-        let bag = loginAttempts.get(key);
-        if (!bag) {
-          bag = [];
-          loginAttempts.set(key, bag);
-        }
-        if (touchRateLimit(bag, ctx.now()) === "rate_limited") {
-          return fail("AuthRateLimited", {
-            reason: "rate_limited",
-          });
-        }
+        // Rate limit is Gate KV (`signInRate` on the binding) — shared across
+        // instances when `drivers.store.kv` is redis. No process-local email bag.
         const user = await authenticateUser(identities, input.email, input.password);
         // Enumeration hygiene: identical failure for unknown email / bad password.
         if (!user) return fail("AuthFailed", { reason: "invalid_credentials" });

package/src/auth/identity.ts

@@ -77,6 +77,39 @@ export function normalizeEmail(email: string): string {
   return email.trim().toLowerCase();
 }
 
+/**
+ * Find or create a user row keyed by email (magic-link / OTP sign-in).
+ *
+ * @param store - Identity store
+ * @param email - Normalized email
+ * @param now - Clock
+ */
+export function ensureUserByEmail(
+  store: IdentityStore,
+  email: string,
+  now: number,
+): UserIdentityRow {
+  const existingId = store.byEmail.get(email);
+  if (existingId) {
+    const existing = store.users.get(existingId);
+    if (existing) return existing;
+  }
+  const id = crypto.randomUUID();
+  const user: UserIdentityRow = {
+    id,
+    email,
+    name: email.split("@")[0] || "user",
+    emailVerified: true,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    extra: {},
+  };
+  store.users.set(id, user);
+  store.byEmail.set(email, id);
+  return user;
+}
+
 /**
  * Create a user with a credential account (provider `credential`).
  *

package/src/auth/index.ts

@@ -69,10 +69,14 @@ export {
   createVerificationStore,
   putVerification,
   findActiveVerification,
+  consumeVerification,
+  invalidateVerifications,
+  wipeSealedOtp,
   hashChallenge,
   generateOtp,
   type VerificationStore,
   type VerificationRow,
+  type OtpChannel,
 } from "./verification.ts";
 
 export { constantTimeEqual } from "./constant-time.ts";
@@ -83,6 +87,7 @@ export {
   authenticateUser,
   getUserById,
   normalizeEmail,
+  ensureUserByEmail,
   IdentityError,
   type IdentityStore,
   type UserIdentityRow,

package/src/auth/otp-capability.ts

@@ -0,0 +1,119 @@
+/**
+ * Fail-loud capability checks for the otp() plugin (provider / app mode).
+ */
+
+import type { ChannelDriver, SmsOtpTransport } from "../drivers/channel-types.ts";
+import type { OtpChannel } from "./verification.ts";
+
+/** Config snapshot stored on the otp plugin for boot-time assertion. */
+export interface OtpPluginConfig {
+  readonly method: "otp";
+  readonly mode: "provider" | "app";
+  readonly channels?: readonly OtpChannel[];
+}
+
+/**
+ * Whether an SMS transport exposes provider OTP via Verify (structural).
+ *
+ * @param t - Candidate transport
+ */
+export function isSmsOtpTransport(t: unknown): t is SmsOtpTransport {
+  if (!t || typeof t !== "object") return false;
+  const o = t as Partial<SmsOtpTransport>;
+  return typeof o.sendOtp === "function" && typeof o.verifyOtp === "function";
+}
+
+/**
+ * Find a bound SMS driver with real sendOtp/verifyOtp, or undefined.
+ *
+ * @param drivers - Bound channel drivers
+ */
+export function findOtpSmsDriver(
+  drivers: readonly ChannelDriver[],
+): { readonly driver: ChannelDriver; readonly otp: SmsOtpTransport } | undefined {
+  for (const d of drivers) {
+    if (isSmsOtpTransport(d.smsTransport)) {
+      return { driver: d, otp: d.smsTransport };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether any bound driver can deliver on `medium`.
+ *
+ * @param drivers - Bound channel drivers
+ * @param medium - OTP channel
+ */
+export function driverCoversMedium(drivers: readonly ChannelDriver[], medium: OtpChannel): boolean {
+  for (const d of drivers) {
+    if (medium === "email" && d.transport) return true;
+    if (medium === "sms" && (d.smsTransport || d.channel?.mediums.includes("sms"))) return true;
+    if (medium === "whatsapp" && (d.whatsappTransport || d.channel?.mediums.includes("whatsapp"))) {
+      return true;
+    }
+    if (d.channel?.mediums.includes(medium) || d.channel?.mediums.includes("any")) return true;
+  }
+  return false;
+}
+
+/**
+ * Assert provider mode: a Verify-capable SMS driver must be bound.
+ *
+ * @param drivers - Bound channel drivers
+ */
+export function assertOtpProviderModeCapability(drivers: readonly ChannelDriver[]): void {
+  if (findOtpSmsDriver(drivers)) return;
+  const sms = drivers.filter((d) => d.smsTransport);
+  if (sms.length === 0) {
+    throw new Error(
+      'otp({ mode: "provider" }): no SMS driver with sendOtp/verifyOtp bound — set drivers.channel.sms to a Verify-capable driver (e.g. "taqnyat"), or switch to otp({ mode: "app", channels: [...] })',
+    );
+  }
+  const id = sms[0]?.id ?? "unknown";
+  throw new Error(
+    `otp({ mode: "provider" }): SMS driver "${id}" does not support provider OTP — bind a Verify-capable driver (e.g. taqnyat), or switch to otp({ mode: "app", channels: [...] })`,
+  );
+}
+
+/**
+ * Assert app mode: every declared channel has a deliverable driver.
+ *
+ * @param drivers - Bound channel drivers
+ * @param channels - Declared channel order
+ */
+export function assertOtpAppModeChannels(
+  drivers: readonly ChannelDriver[],
+  channels: readonly OtpChannel[],
+): void {
+  for (const ch of channels) {
+    if (!driverCoversMedium(drivers, ch)) {
+      throw new Error(
+        `otp({ mode: "app" }): no channel driver covers "${ch}" — configure drivers.channel.${ch === "email" ? "email" : ch === "sms" ? "sms" : "whatsapp"}`,
+      );
+    }
+  }
+}
+
+/**
+ * Run the matching boot assertion for an otp plugin config snapshot.
+ *
+ * @param config - Plugin configSnapshot
+ * @param drivers - Bound channel drivers
+ */
+export function assertOtpPluginCapability(
+  config: unknown,
+  drivers: readonly ChannelDriver[],
+): void {
+  if (!config || typeof config !== "object") return;
+  const c = config as Partial<OtpPluginConfig>;
+  if (c.method !== "otp") return;
+  if (c.mode === "provider") {
+    assertOtpProviderModeCapability(drivers);
+    return;
+  }
+  if (c.mode === "app") {
+    const channels = c.channels ?? [];
+    assertOtpAppModeChannels(drivers, channels);
+  }
+}

package/src/auth/otp-seal.test.ts

@@ -0,0 +1,61 @@
+/**
+ * OTP seal — HKDF domain separation + AES-GCM round-trip.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { deriveOtpSealKey, OTP_SEAL_HKDF_INFO, sealOtp, unsealOtp } from "./otp-seal.ts";
+
+describe("otp-seal", () => {
+  test("info constant is the literal oke-otp-seal-v1", () => {
+    expect(OTP_SEAL_HKDF_INFO).toBe("oke-otp-seal-v1");
+  });
+
+  test("round-trip seal / unseal", async () => {
+    const secret = "test-secret-at-least-16";
+    const otp = "482913";
+    const blob = await sealOtp(secret, otp);
+    expect(blob).not.toContain(otp);
+    expect(await unsealOtp(secret, blob)).toBe(otp);
+  });
+
+  test("secret A cannot unseal secret B", async () => {
+    const blob = await sealOtp("secret-aaaaaaaaaaaa", "123456");
+    await expect(unsealOtp("secret-bbbbbbbbbbbb", blob)).rejects.toThrow();
+  });
+
+  test("deriveOtpSealKey produces an AES-GCM key (not raw secret)", async () => {
+    const key = await deriveOtpSealKey("test-secret-at-least-16");
+    expect(key.type).toBe("secret");
+    expect(key.algorithm).toMatchObject({ name: "AES-GCM" });
+    // Non-extractable — raw secret bytes never leave HKDF as exportable AES material.
+    expect(key.extractable).toBe(false);
+  });
+
+  test("HKDF info bytes pin domain separation (known key length)", async () => {
+    const ikm = new TextEncoder().encode("fixed-secret-for-vector");
+    const baseKey = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+    const bits = await crypto.subtle.deriveBits(
+      {
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(0),
+        info: new TextEncoder().encode(OTP_SEAL_HKDF_INFO),
+      },
+      baseKey,
+      256,
+    );
+    expect(new Uint8Array(bits).byteLength).toBe(32);
+    // Different info → different bits
+    const other = await crypto.subtle.deriveBits(
+      {
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(0),
+        info: new TextEncoder().encode("session-hmac-v1"),
+      },
+      baseKey,
+      256,
+    );
+    expect(Buffer.from(bits).equals(Buffer.from(other))).toBe(false);
+  });
+});