okengine 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

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

@@ -152,15 +152,18 @@ Email fallback uses ordered email transports; SMS with multiple SMS drivers uses
 the same failover path. Credentials for boot-opened drivers are listed under
 [Environment Variables](/docs/reference/environment-variables).
 
-### Provider-managed OTP
+### Provider OTP (`fx.sendOtp` / `fx.verifyOtp`)
 
-Flows can also send a provider-generated SMS code with `fx.sendOtp({ to, requestId, lang? })`
+Flows can send a provider-generated SMS code with `fx.sendOtp({ to, requestId, lang? })`
 and check it with `fx.verifyOtp({ to, requestId, code })` — Taqnyat's Verify API. Both are
-capability-gated `send` effects and dry-run safe.
+capability-gated `send` effects and dry-run safe. No `.plug()` required.
 
 They dispatch only when the bound SMS driver supports Verify (`taqnyat`); any other SMS
-driver fails loudly instead of silently falling back to a self-generated code. The
-[OTP](/docs/plugins/otp) Tier 1 uses this path automatically.
+driver fails loudly instead of silently falling back to a self-generated code.
+
+[OTP](/docs/plugins/otp) in provider mode is the full auth feature built on this same
+path (routes, sessions, rates). Custom shape? Call `fx.sendOtp` / `fx.verifyOtp` in
+your own flow — skipping the plugin does not drop the provider connection.
 
 `webpush` needs VAPID keys — open it yourself and include it in
 `BootOptions.channel.drivers` (boot does not open push from env):

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

@@ -1,18 +1,30 @@
 ---
 title: "OTP"
-description: "Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit Tier 1 or Tier 2 delivery."
+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 `tier` — there is no
-auto-detect. Tier 1 is provider-owned SMS Verify; Tier 2 is app-owned delivery
-across the channels you declare.
+`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({ tier: 1 }))` or
-  `.plug(otp({ tier: 2, channels: [...] }))`. Never omit `tier`. Never log raw
-  OTPs.
+  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
@@ -20,7 +32,7 @@ across the channels you declare.
 <Steps>
 
 <Step>
-### Plug Tier 2 (multi-channel)
+### Plug app mode (multi-channel)
 
 ```typescript title="src/app.ts"
 import { oke } from "okengine";
@@ -32,7 +44,7 @@ export const app = oke({
   gate: { auth: {} },
 }).plug(
   otp({
-    tier: 2,
+    mode: "app",
     channels: ["sms", "whatsapp", "email"],
     exposeDevOtp: true, // local DX only
   }),
@@ -57,7 +69,7 @@ invalidated. Delivery follows `channels` order for addresses you pass.
 </Step>
 
 <Step>
-### Resend on another channel (Tier 2 only)
+### Resend on another channel (app mode only)
 
 ```typescript
 const { data } = await api.auth.resendOtp({
@@ -67,8 +79,8 @@ const { data } = await api.auth.resendOtp({
 });
 ```
 
-Same code, same TTL. Default cooldown is 60 seconds. Tier 1 has no resend
-surface — the provider owns the code.
+Same code, same TTL. Default cooldown is 60 seconds. Provider mode has no
+resend surface — the provider owns the code.
 
 </Step>
 
@@ -88,23 +100,23 @@ const { data } = await api.auth.verifyOtp({
 
 </Steps>
 
-## Tiers
+## Modes
 
-|                      | Tier 1                        | Tier 2                                        |
+|                      | Provider mode                 | App mode                                      |
 | -------------------- | ----------------------------- | --------------------------------------------- |
-| Config               | `otp({ tier: 1 })`            | `otp({ tier: 2, channels: [...] })`           |
+| 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="Tier 1 limitation">
-  Resend-via-different-channel is impossible on Tier 1 — the code value is never visible to OKE. Use
-  Tier 2 when you need SMS → email fallback for the same code.
+<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>
 
-### Tier 1 setup
+### Provider mode setup
 
 ```typescript title="oke.config.ts"
 export default {
@@ -117,9 +129,9 @@ export default {
 ```
 
 Boot fails loudly if no SMS driver exposes `sendOtp` / `verifyOtp`. Switch to
-Tier 2, or bind a Verify-capable driver (for example `taqnyat`).
+app mode, or bind a Verify-capable driver (for example `taqnyat`).
 
-### Tier 2 delivery
+### App mode delivery
 
 | Concern         | Behavior                                                                                                                    |
 | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -135,42 +147,42 @@ Templates: `auth-otp-email`, `auth-otp-sms`, `auth-otp-whatsapp` (EN/AR,
 
 ## Options
 
-| Option             | Type                             | Default                    | Meaning                           |
-| ------------------ | -------------------------------- | -------------------------- | --------------------------------- |
-| `tier`             | `1 \| 2`                         | required                   | Delivery mechanism — no auto      |
-| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required on Tier 2         | Build-time preferred order        |
-| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                |
-| `resendCooldownMs` | `number`                         | 60s                        | Tier 2 resend spacing             |
-| `exposeDevOtp`     | `boolean`                        | `false`                    | Tier 2 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                   |
+| 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                     | Tier   |
-| ----------------- | ------------------------ | ------------------------ | ------ |
-| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | 1 + 2  |
-| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | 1 + 2  |
-| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | 2 only |
+| 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(): tier is required'>
+<Accordion title='otp(): mode is required'>
 
-You omitted `tier`. Set `tier: 1` or `tier: 2` explicitly — OKE never infers
-which mechanism you meant.
+You omitted `mode`. Set `mode: "provider"` or `mode: "app"` explicitly — OKE
+never infers which mechanism you meant.
 
 </Accordion>
-<Accordion title="Boot fails on Tier 1">
+<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({ tier: 2, channels: [...] })`.
+`otp({ mode: "app", channels: [...] })`.
 
 </Accordion>
 <Accordion title="resend_cooldown">
@@ -179,7 +191,7 @@ Wait for `resendCooldownMs` (default 60s). The challenge TTL is unchanged —
 only delivery is rate-limited.
 
 </Accordion>
-<Accordion title="No email / SMS with the code (Tier 2)">
+<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.
@@ -190,7 +202,7 @@ In `local` / `test` the `console` driver captures messages. Use
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
-- [Channel](/docs/elements/channel) — `fx.send`, drivers, Mailpit
+- [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
 - [Gate](/docs/elements/gate) — `gate.auth`
 
 ## Next

package/src/auth/otp-capability.ts

@@ -1,5 +1,5 @@
 /**
- * Fail-loud capability checks for the otp() plugin (Tier 1 / Tier 2).
+ * Fail-loud capability checks for the otp() plugin (provider / app mode).
  */
 
 import type { ChannelDriver, SmsOtpTransport } from "../drivers/channel-types.ts";
@@ -8,12 +8,12 @@ import type { OtpChannel } from "./verification.ts";
 /** Config snapshot stored on the otp plugin for boot-time assertion. */
 export interface OtpPluginConfig {
   readonly method: "otp";
-  readonly tier: 1 | 2;
+  readonly mode: "provider" | "app";
   readonly channels?: readonly OtpChannel[];
 }
 
 /**
- * Whether an SMS transport exposes provider-managed OTP (structural).
+ * Whether an SMS transport exposes provider OTP via Verify (structural).
  *
  * @param t - Candidate transport
  */
@@ -58,38 +58,38 @@ export function driverCoversMedium(drivers: readonly ChannelDriver[], medium: Ot
 }
 
 /**
- * Assert Tier 1: a Verify-capable SMS driver must be bound.
+ * Assert provider mode: a Verify-capable SMS driver must be bound.
  *
  * @param drivers - Bound channel drivers
  */
-export function assertOtpTier1Capability(drivers: readonly ChannelDriver[]): void {
+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({ tier: 1 }): no SMS driver with sendOtp/verifyOtp bound — set drivers.channel.sms to a Verify-capable driver (e.g. "taqnyat"), or switch to otp({ tier: 2, channels: [...] })',
+      '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({ tier: 1 }): SMS driver "${id}" does not support provider-managed OTP — bind a Verify-capable driver (e.g. taqnyat), or switch to otp({ tier: 2, channels: [...] })`,
+    `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 Tier 2: every declared channel has a deliverable driver.
+ * Assert app mode: every declared channel has a deliverable driver.
  *
  * @param drivers - Bound channel drivers
  * @param channels - Declared channel order
  */
-export function assertOtpTier2Channels(
+export function assertOtpAppModeChannels(
   drivers: readonly ChannelDriver[],
   channels: readonly OtpChannel[],
 ): void {
   for (const ch of channels) {
     if (!driverCoversMedium(drivers, ch)) {
       throw new Error(
-        `otp({ tier: 2 }): no channel driver covers "${ch}" — configure drivers.channel.${ch === "email" ? "email" : ch === "sms" ? "sms" : "whatsapp"}`,
+        `otp({ mode: "app" }): no channel driver covers "${ch}" — configure drivers.channel.${ch === "email" ? "email" : ch === "sms" ? "sms" : "whatsapp"}`,
       );
     }
   }
@@ -108,12 +108,12 @@ export function assertOtpPluginCapability(
   if (!config || typeof config !== "object") return;
   const c = config as Partial<OtpPluginConfig>;
   if (c.method !== "otp") return;
-  if (c.tier === 1) {
-    assertOtpTier1Capability(drivers);
+  if (c.mode === "provider") {
+    assertOtpProviderModeCapability(drivers);
     return;
   }
-  if (c.tier === 2) {
+  if (c.mode === "app") {
     const channels = c.channels ?? [];
-    assertOtpTier2Channels(drivers, channels);
+    assertOtpAppModeChannels(drivers, channels);
   }
 }

package/src/kernel/app.ts

@@ -844,7 +844,7 @@ export function oke(options: OkeOptions): OkeApp {
     };
     const result = await bootApplication(merged);
     bootResult = result;
-    // otp() Tier 1 / Tier 2 capability — fail loud at boot, never silent downgrade.
+    // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
       for (const entry of pluginRegistry.installed) {

package/src/plugins/auth-delivery.mailpit.integration.test.ts

@@ -290,7 +290,7 @@ describe("auth delivery — Mailpit integration", () => {
           config: {
             drivers: { channel: { email: { test: "smtp" } } },
           },
-        }).plug(otp({ tier: 2, channels: ["email"], exposeDevOtp: true }));
+        }).plug(otp({ mode: "app", channels: ["email"], exposeDevOtp: true }));
         await app.boot({ env: "test" });
 
         const res = await app.fetch(jsonPost("/auth/otp/request", { email }));

package/src/plugins/auth-methods.security.test.ts

@@ -50,7 +50,7 @@ function fullAuthApp() {
     .plug(username())
     .plug(anonymous())
     .plug(magicLink({ exposeDevToken: true }))
-    .plug(otp({ tier: 2, channels: ["email", "sms"], exposeDevOtp: true }))
+    .plug(otp({ mode: "app", channels: ["email", "sms"], exposeDevOtp: true }))
     .plug(twoFactor())
     .plug(passkey({ origins: ["http://localhost"] }));
 }
@@ -418,7 +418,7 @@ describe("auth methods — anonymous non-escalation", () => {
 });
 
 describe("auth methods — channel delivery", () => {
-  test("magic uses fx.send; otp Tier 2 uses fx.deliverOtp; exposeDev* stays off by default", async () => {
+  test("magic uses fx.send; otp app mode uses fx.deliverOtp; exposeDev* stays off by default", async () => {
     resetBindings();
     resetFlowSeq();
     const app = oke({
@@ -428,7 +428,7 @@ describe("auth methods — channel delivery", () => {
       gate: { auth: { secret: SECRET, emailAndPassword: { enabled: true } } },
     })
       .plug(magicLink())
-      .plug(otp({ tier: 2, channels: ["email", "sms"] }));
+      .plug(otp({ mode: "app", channels: ["email", "sms"] }));
     await app.boot({ env: "test" });
 
     const ml = await app.fetch(jsonPost("/auth/magic-link/request", { email: "x@example.com" }));

package/src/plugins/auth-methods.test.ts

@@ -31,7 +31,7 @@ function authApp() {
     .plug(username())
     .plug(anonymous())
     .plug(magicLink({ exposeDevToken: true }))
-    .plug(otp({ tier: 2, channels: ["email"], exposeDevOtp: true }));
+    .plug(otp({ mode: "app", channels: ["email"], exposeDevOtp: true }));
 }
 
 describe("auth method plugins", () => {

package/src/plugins/index.ts

@@ -30,9 +30,9 @@ export {
   otpEmailTemplate,
   otpSmsTemplate,
   otpWhatsappTemplate,
+  type OtpAppModeOptions,
   type OtpOptions,
-  type OtpTier1Options,
-  type OtpTier2Options,
+  type OtpProviderModeOptions,
   type PhoneStore,
 } from "./otp.ts";
 export {

package/src/plugins/otp.test.ts

@@ -1,5 +1,5 @@
 /**
- * otp() plugin — plug-time fail-loud, Tier 2 resend / sealed lifetime, Tier 1 boot.
+ * otp() plugin — plug-time fail-loud, app-mode resend / sealed lifetime, provider-mode boot.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -71,44 +71,46 @@ function mockOtpSmsDriver(): ChannelDriver {
 }
 
 describe("otp() plug-time fail-loud", () => {
-  test("missing tier throws", () => {
-    expect(() => otp({} as never)).toThrow(/tier is required/);
+  test("missing mode throws", () => {
+    expect(() => otp({} as never)).toThrow(/mode is required/);
   });
 
-  test("tier 1 with channels throws", () => {
-    expect(() => otp({ tier: 1, channels: ["sms"] } as never)).toThrow(/channels are forbidden/);
+  test('mode "provider" with channels throws', () => {
+    expect(() => otp({ mode: "provider", channels: ["sms"] } as never)).toThrow(
+      /channels are forbidden/,
+    );
   });
 
-  test("tier 1 with exposeDevOtp throws", () => {
-    expect(() => otp({ tier: 1, exposeDevOtp: true } as never)).toThrow(
+  test('mode "provider" with exposeDevOtp throws', () => {
+    expect(() => otp({ mode: "provider", exposeDevOtp: true } as never)).toThrow(
       /exposeDevOtp is forbidden/,
     );
   });
 
-  test("tier 2 without channels throws", () => {
-    expect(() => otp({ tier: 2 } as never)).toThrow(/channels is required/);
+  test('mode "app" without channels throws', () => {
+    expect(() => otp({ mode: "app" } as never)).toThrow(/channels is required/);
   });
 });
 
-describe("otp() Tier 1 boot", () => {
+describe("otp() provider mode boot", () => {
   test("fails loud without Verify-capable SMS driver", async () => {
     const app = oke({
-      name: `otp-t1-${crypto.randomUUID()}`,
+      name: `otp-provider-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
-    }).plug(otp({ tier: 1 }));
-    await expect(app.boot({ env: "test" })).rejects.toThrow(/tier: 1/);
+    }).plug(otp({ mode: "provider" }));
+    await expect(app.boot({ env: "test" })).rejects.toThrow(/mode: "provider"/);
   });
 
   test("boots when Verify-capable SMS driver is bound", async () => {
     const app = oke({
-      name: `otp-t1-ok-${crypto.randomUUID()}`,
+      name: `otp-provider-ok-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
       channel: { drivers: [mockOtpSmsDriver()] },
-    }).plug(otp({ tier: 1 }));
+    }).plug(otp({ mode: "provider" }));
     await app.boot({ env: "test" });
     const res = await app.fetch(jsonPost("/auth/otp/request", { phone: "+15551234567" }));
     expect(res.status).toBe(200);
@@ -120,12 +122,12 @@ describe("otp() Tier 1 boot", () => {
   });
 });
 
-describe("otp() Tier 2 resend + sealed lifetime", () => {
+describe("otp() app mode resend + sealed lifetime", () => {
   test("cross-channel resend keeps same code; cooldown then verify wipes seal", async () => {
     let now = 1_000_000;
     const verifications: VerificationStore = createVerificationStore();
     const app = oke({
-      name: `otp-t2-${crypto.randomUUID()}`,
+      name: `otp-app-${crypto.randomUUID()}`,
       env: "test",
       registry: "ignore",
       gate: { auth: { secret: SECRET } },
@@ -133,7 +135,7 @@ describe("otp() Tier 2 resend + sealed lifetime", () => {
       fx: { now: () => now },
     }).plug(
       otp({
-        tier: 2,
+        mode: "app",
         channels: ["sms", "email"],
         exposeDevOtp: true,
         resendCooldownMs: 60_000,
@@ -209,7 +211,7 @@ describe("otp() Tier 2 resend + sealed lifetime", () => {
       fx: { now: () => now },
     }).plug(
       otp({
-        tier: 2,
+        mode: "app",
         channels: ["email"],
         exposeDevOtp: true,
         ttlMs: 1_000,

package/src/plugins/otp.ts

@@ -1,6 +1,6 @@
 /**
- * Unified OTP Gate auth method plugin — Tier 1 (provider-owned) or Tier 2
- * (app-owned multi-channel). Replaces emailOtp() + phoneNumber().
+ * Unified OTP Gate auth method plugin — provider mode (Verify) or app mode
+ * (multi-channel). Replaces emailOtp() + phoneNumber().
  */
 
 import { constantTimeEqual } from "../auth/constant-time.ts";
@@ -66,20 +66,20 @@ interface OtpBaseOptions extends AuthMethodOptions {
   readonly identities?: IdentityStore;
 }
 
-/** Tier 1 — provider-owned OTP via fx.sendOtp / fx.verifyOtp. */
-export interface OtpTier1Options extends OtpBaseOptions {
-  readonly tier: 1;
-  /** Forbidden on Tier 1 — fail loud if set. */
+/** Provider mode — provider-owned OTP via fx.sendOtp / fx.verifyOtp. */
+export interface OtpProviderModeOptions extends OtpBaseOptions {
+  readonly mode: "provider";
+  /** Forbidden in provider mode — fail loud if set. */
   readonly channels?: never;
-  /** Forbidden on Tier 1 — code never exists server-side. */
+  /** Forbidden in provider mode — code never exists server-side. */
   readonly exposeDevOtp?: never;
   readonly resendCooldownMs?: never;
   readonly from?: never;
 }
 
-/** Tier 2 — app-owned OTP with multi-channel delivery. */
-export interface OtpTier2Options extends OtpBaseOptions {
-  readonly tier: 2;
+/** App mode — app-owned OTP with multi-channel delivery. */
+export interface OtpAppModeOptions extends OtpBaseOptions {
+  readonly mode: "app";
   /** Build-time preferred channel order (required). */
   readonly channels: readonly OtpChannel[];
   readonly resendCooldownMs?: number;
@@ -87,24 +87,24 @@ export interface OtpTier2Options extends OtpBaseOptions {
   readonly from?: string;
 }
 
-/** Options for {@link otp}. `tier` is mandatory — no auto-detect. */
-export type OtpOptions = OtpTier1Options | OtpTier2Options;
+/** Options for {@link otp}. `mode` is mandatory — no auto-detect. */
+export type OtpOptions = OtpProviderModeOptions | OtpAppModeOptions;
 
-/** Email OTP template (Tier 2). */
+/** Email OTP template (app mode). */
 export const otpEmailTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-otp-email", {
   description: "OTP sign-in code (email)",
   schema: z.object({ email: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
 });
 
-/** SMS OTP template (Tier 2 — plain message, not provider Verify). */
+/** SMS OTP template (app mode — plain message, not provider Verify). */
 export const otpSmsTemplate = channel.sms().template("auth-otp-sms", {
   description: "OTP sign-in code (SMS)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
   locales: ["en", "ar"],
 });
 
-/** WhatsApp OTP template (Tier 2). */
+/** WhatsApp OTP template (app mode). */
 export const otpWhatsappTemplate = channel.whatsapp().template("auth-otp-whatsapp", {
   description: "OTP sign-in code (WhatsApp)",
   schema: z.object({ phone: z.string(), otp: z.string() }),
@@ -136,18 +136,20 @@ export const otpCatalog = {
 } as const;
 
 function assertOtpOptions(opts: OtpOptions): void {
-  if (opts.tier !== 1 && opts.tier !== 2) {
-    throw new Error("otp(): tier is required — set tier: 1 or tier: 2 (no auto-detect)");
+  if (opts.mode !== "provider" && opts.mode !== "app") {
+    throw new Error(
+      'otp(): mode is required — set mode: "provider" or mode: "app" (no auto-detect)',
+    );
   }
-  if (opts.tier === 1) {
+  if (opts.mode === "provider") {
     if ("channels" in opts && opts.channels !== undefined) {
       throw new Error(
-        "otp({ tier: 1 }): channels are forbidden — provider-owned OTP cannot resend via a different channel; use tier: 2 for multi-channel",
+        'otp({ mode: "provider" }): channels are forbidden — provider-owned OTP cannot resend via a different channel; use mode: "app" for multi-channel',
       );
     }
     if ("exposeDevOtp" in opts && (opts as { exposeDevOtp?: boolean }).exposeDevOtp === true) {
       throw new Error(
-        "otp({ tier: 1 }): exposeDevOtp is forbidden — the code never exists server-side",
+        'otp({ mode: "provider" }): exposeDevOtp is forbidden — the code never exists server-side',
       );
     }
     return;
@@ -155,12 +157,12 @@ function assertOtpOptions(opts: OtpOptions): void {
   const channels = opts.channels;
   if (!channels || channels.length === 0) {
     throw new Error(
-      'otp({ tier: 2 }): channels is required — declare at least one of "sms" | "whatsapp" | "email"',
+      'otp({ mode: "app" }): channels is required — declare at least one of "sms" | "whatsapp" | "email"',
     );
   }
   for (const ch of channels) {
     if (!(OTP_CHANNELS as readonly string[]).includes(ch)) {
-      throw new Error(`otp({ tier: 2 }): unknown channel "${String(ch)}"`);
+      throw new Error(`otp({ mode: "app" }): unknown channel "${String(ch)}"`);
     }
   }
 }
@@ -186,9 +188,9 @@ function pickRequestChannel(
 }
 
 /**
- * Unified OTP request + verify (+ Tier-2 resend).
+ * Unified OTP request + verify (+ app-mode resend).
  *
- * @param opts - Must include `tier: 1` or `tier: 2`
+ * @param opts - Must include `mode: "provider"` or `mode: "app"`
  */
 export function otp(opts: OtpOptions): PluginDef {
   assertOtpOptions(opts);
@@ -200,12 +202,12 @@ export function otp(opts: OtpOptions): PluginDef {
   const verifications = opts.verifications ?? createVerificationStore();
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
   const resendCooldownMs =
-    opts.tier === 2
+    opts.mode === "app"
       ? (opts.resendCooldownMs ?? DEFAULT_RESEND_COOLDOWN_MS)
       : DEFAULT_RESEND_COOLDOWN_MS;
-  const channels = opts.tier === 2 ? opts.channels : ([] as const);
-  const exposeDevOtp = opts.tier === 2 && opts.exposeDevOtp === true;
-  const from = opts.tier === 2 ? opts.from : undefined;
+  const channels = opts.mode === "app" ? opts.channels : ([] as const);
+  const exposeDevOtp = opts.mode === "app" && opts.exposeDevOtp === true;
+  const from = opts.mode === "app" ? opts.from : undefined;
 
   const emailTmpl =
     from !== undefined
@@ -223,9 +225,9 @@ export function otp(opts: OtpOptions): PluginDef {
   } as const;
 
   const configSnapshot: OtpPluginConfig =
-    opts.tier === 1
-      ? { method: "otp", tier: 1 }
-      : { method: "otp", tier: 2, channels: [...channels] };
+    opts.mode === "provider"
+      ? { method: "otp", mode: "provider" }
+      : { method: "otp", mode: "app", channels: [...channels] };
 
   const requestOut = z.object({
     ok: z.literal(true),
@@ -233,7 +235,7 @@ export function otp(opts: OtpOptions): PluginDef {
     channel: z.enum(["sms", "whatsapp", "email"]).optional(),
   });
 
-  if (opts.tier === 1) {
+  if (opts.mode === "provider") {
     const request = flow({
       name: "auth.requestOtp",
       unit: "auth",
@@ -270,7 +272,7 @@ export function otp(opts: OtpOptions): PluginDef {
           phone,
           sealedOtp: null,
         });
-        // Tier 1: resend-via-different-channel is impossible — provider owns the code.
+        // Provider mode: resend-via-different-channel is impossible — provider owns the code.
         return { ok: true as const, channel: "sms" as const };
       },
     });
@@ -344,7 +346,7 @@ export function otp(opts: OtpOptions): PluginDef {
       .binding(bindPublicAuth("/otp/verify", verify, "otp"));
   }
 
-  // ── Tier 2 ────────────────────────────────────────────────────────────
+  // ── App mode ───────────────────────────────────────────────────────────
   const request = flow({
     name: "auth.requestOtp",
     unit: "auth",

package/src/plugins/taqnyat.live.test.ts

@@ -1,5 +1,5 @@
 /**
- * Real Taqnyat end-to-end: otp({ tier: 1 }) via Verify API + magic-link via Taqnyat Mail.
+ * Real Taqnyat end-to-end: otp({ mode: "provider" }) via Verify API + magic-link via Taqnyat Mail.
  *
  * Double-gated — runs ONLY when BOTH:
  *   1. The global per-medium opt-in flag is set explicitly
@@ -82,7 +82,7 @@ if (!LIVE_MAIL) {
 const liveSms = LIVE_SMS ? test : test.skip;
 const liveMail = LIVE_MAIL ? test : test.skip;
 
-describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
+describe("taqnyat live — provider OTP (Taqnyat Verify)", () => {
   liveSms(
     "phone OTP request → real sendOtp → Taqnyat success code 5",
     async () => {
@@ -94,7 +94,7 @@ describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
         config: {
           drivers: { channel: { sms: { test: "taqnyat" } } },
         },
-      }).plug(otp({ tier: 1 }));
+      }).plug(otp({ mode: "provider" }));
       await app.boot({ env: "test" });
 
       // Wrap the live transport so the plugin's single real send also proves