okengine 0.8.0 → 0.9.1

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

@@ -1,117 +0,0 @@
----
-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). Request sends the
-code via Channel (`auth-email-otp`); verify creates the user on first success and returns hybrid
-session tokens.
-
-<Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(emailOtp())`. Never log raw OTPs. Delivery goes through `fx.send`;
-  use `exposeDevOtp` only for local DX without SMTP.
-</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());
-```
-
-</Step>
-
-<Step>
-### Request a code
-
-```typescript
-const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
-// Channel delivers auth-email-otp; data.devOtp only 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,
-});
-```
-
-`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                      |
-| `from`          | `string`            | `OKE <no-reply@oke.local>` | Template From address                   |
-| `exposeDevOtp`  | `boolean`           | `false`                    | Include raw OTP in the request response |
-| `identities`    | `IdentityStore`     | new                        | Email → user map                        |
-| `verifications` | `VerificationStore` | new                        | Challenge store                         |
-
-## Surfaces
-
-| 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 |
-
-**Consequence:** the plugin contributes the `auth-email-otp` Channel template and EN/AR
-catalog bodies (`{{otp}}`). Override copy by merging your own catalog at boot.
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="No email with the code">
-
-In `local` / `test` the `console` driver captures mail — open the inbox, or run
-`oke dev --docker` and check Mailpit. For unit tests without SMTP, set `exposeDevOtp: true`.
-
-</Accordion>
-<Accordion title="AuthFailed after a few tries">
-
-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; delivery deferred)
-- [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
-- [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="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
-</Cards>

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

@@ -1,172 +0,0 @@
----
-title: "Phone number"
-description: "Official plugin — E.164 phone OTP request and verify under /auth, with provider-managed delivery via Taqnyat Verify."
-icon: "Smartphone"
-source: "docs/spec/unified-theory.md"
----
-
-`phoneNumber()` signs people in with a phone number in E.164 form (`+15551234567`). Delivery
-has two shapes: provider-managed OTP through Taqnyat Verify when an SMS driver is bound, or a
-local hashed code (10 minutes, 5 attempts) you deliver yourself.
-
-<Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(phoneNumber())`. For real SMS set `drivers.channel.sms` to
-  `taqnyat` — the plugin uses Taqnyat's Verify API, never a self-generated code. Use `exposeDevOtp`
-  only when no SMS driver is bound.
-</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`. Optional `lang:
-"en" | "ar"` picks the OTP message language on the Taqnyat path.
-
-</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>
-
-## Delivery
-
-| Bound SMS driver     | Request behavior                                           | Verify behavior                |
-| -------------------- | ---------------------------------------------------------- | ------------------------------ |
-| `taqnyat`            | Taqnyat Verify `sendOtp` (provider generates the code)     | Taqnyat Verify `verifyOtp`     |
-| none                 | Local 6-digit code, hashed at rest (`exposeDevOtp` for DX) | Local hash compare, 5 attempts |
-| any other SMS driver | Fails loudly — provider-managed OTP unsupported            | —                              |
-
-**Consequence:** the request response never contains `devOtp` on the Taqnyat path — the code
-exists only inside the SMS Taqnyat sends.
-
-### Taqnyat Verify
-
-```typescript title="oke.config.ts"
-export default {
-  drivers: {
-    channel: {
-      sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
-    },
-  },
-};
-```
-
-| Env                    | Meaning                                      |
-| ---------------------- | -------------------------------------------- |
-| `TAQNYAT_BEARER_TOKEN` | Taqnyat bearer token (`TAQNYAT_TOKEN` alias) |
-| `TAQNYAT_SENDER`       | Pre-approved sender id                       |
-
-Request stores a provider challenge (`taqnyat:<requestId>`, 10m TTL, 5 attempts) and calls
-`fx.sendOtp`; verify replays the same `requestId` with the code through `fx.verifyOtp`. Both
-are capability-gated `send` effects — dry-run records them without contacting Taqnyat.
-
-An SMS driver without Verify support (for example a generic SMS sender) makes the request fail
-with a clear error: use `exposeDevOtp` locally or switch `drivers.channel.sms` to `taqnyat`.
-
-## 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 (local path only) |
-| `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}$`.
-
-## Live tests (opt-in)
-
-The Taqnyat live suite sends real SMS and burns real quota, so it is double-gated: it runs only when
-`OKE_SMS_LIVE=1` **and** the real credentials (`TAQNYAT_TOKEN`, `TAQNYAT_SENDER`, plus
-`OKE_TEST_TAQNYAT_PHONE` — `TAQNYAT_TO` also accepted) are all present. Credentials alone never send.
-
-The suite sends exactly one SMS and never asks for the code.
-
-```bash
-OKE_SMS_LIVE=1 TAQNYAT_TOKEN=… TAQNYAT_SENDER=YourBrand \
-  OKE_TEST_TAQNYAT_PHONE=+9665xxxxxxxx bun test src/plugins
-```
-
-Without the flag the suite skips visibly — never a silent pass.
-
-## 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="SMS driver does not support provider-managed OTP">
-
-The configured `drivers.channel.sms` driver has no Verify API. Either switch to `taqnyat` or
-remove the SMS driver so the local hashed path (`exposeDevOtp`) is used.
-
-</Accordion>
-<Accordion title="No SMS arrived">
-
-On the local path no SMS is sent by design — use `exposeDevOtp`, or bind `taqnyat` with valid
-`TAQNYAT_*` credentials. On the Taqnyat path check the sender id is pre-approved and the
-number is E.164.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [Email OTP](/docs/plugins/email-otp) — email variant of the same OTP rules
-- [Magic link](/docs/plugins/magic-link) — one-time email link sign-in
-- [Channel](/docs/elements/channel) — SMS / email drivers and delivery
-
-## 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/src/plugins/email-otp.ts

@@ -1,214 +0,0 @@
-/**
- * Email OTP Gate auth method plugin.
- *
- * Delivers the one-time code via Channel (`fx.send` + `auth-email-otp`
- * template). {@link EmailOtpOptions.exposeDevOtp} remains available for
- * local DX without Mailpit / SMTP.
- */
-
-import {
-  createIdentityStore,
-  normalizeEmail,
-  type IdentityStore,
-  type UserIdentityRow,
-} from "../auth/identity.ts";
-import { issueSessionWithScopes } from "../auth/sessions.ts";
-import {
-  createVerificationStore,
-  findActiveVerification,
-  generateOtp,
-  hashChallenge,
-  putVerification,
-  type VerificationStore,
-} from "../auth/verification.ts";
-import { channel } from "../elements/channel.ts";
-import { plugin, type PluginDef } from "../kernel/plugin.ts";
-import {
-  AuthFailed,
-  AuthRateLimited,
-  SessionTokensOut,
-  bindPublicAuth,
-  createMethodRuntime,
-  fail,
-  flow,
-  z,
-  type AuthMethodOptions,
-} from "./auth/shared.ts";
-
-const DEFAULT_TTL_MS = 10 * 60 * 1000;
-const MAX_ATTEMPTS = 5;
-const DEFAULT_FROM = "OKE <no-reply@oke.local>";
-
-/** Channel template for email OTP delivery. */
-export const emailOtpTemplate = channel.email({ from: DEFAULT_FROM }).template("auth-email-otp", {
-  description: "Email OTP sign-in code",
-  schema: z.object({
-    email: z.string(),
-    otp: z.string(),
-  }),
-  locales: ["en", "ar"],
-});
-
-/** Default EN/AR bodies for {@link emailOtpTemplate}. */
-export const emailOtpCatalog = {
-  "auth-email-otp": {
-    en: {
-      subject: "Your sign-in code",
-      text: "Your one-time sign-in code is: {{otp}}\n",
-      html: "<p>Your one-time sign-in code is:</p><p><strong>{{otp}}</strong></p>",
-    },
-    ar: {
-      subject: "رمز تسجيل الدخول",
-      text: "رمز تسجيل الدخول لمرة واحدة هو: {{otp}}\n",
-      html: '<p dir="rtl">رمز تسجيل الدخول لمرة واحدة هو:</p><p dir="rtl"><strong>{{otp}}</strong></p>',
-    },
-  },
-} as const;
-
-/** Options for {@link emailOtp}. */
-export interface EmailOtpOptions extends AuthMethodOptions {
-  /** Challenge TTL (default 10m). */
-  readonly ttlMs?: number;
-  readonly identities?: IdentityStore;
-  readonly verifications?: VerificationStore;
-  /** Return raw OTP in the request response (test / local). */
-  readonly exposeDevOtp?: boolean;
-  /** Override the template `from` address. */
-  readonly from?: string;
-}
-
-/**
- * Email OTP request + verify (6-digit, hashed, 5 attempts).
- *
- * @param opts - TTL / stores / dev OTP
- */
-export function emailOtp(opts: EmailOtpOptions = {}): PluginDef {
-  const runtime = createMethodRuntime(opts);
-  const identities = opts.identities ?? createIdentityStore();
-  const verifications = opts.verifications ?? createVerificationStore();
-  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const tmpl =
-    opts.from !== undefined
-      ? channel.email({ from: opts.from }).template("auth-email-otp", {
-          description: "Email OTP sign-in code",
-          schema: z.object({
-            email: z.string(),
-            otp: z.string(),
-          }),
-          locales: ["en", "ar"],
-        })
-      : emailOtpTemplate;
-
-  const request = flow({
-    name: "auth.requestEmailOtp",
-    unit: "auth",
-    plane: "user",
-    in: z.object({ email: z.string().min(3) }),
-    out: z.object({
-      ok: z.literal(true),
-      devOtp: z.string().optional(),
-    }),
-    errors: { AuthFailed, AuthRateLimited },
-    effects: { sends: ["auth-email-otp"] },
-    do: async (input, fx) => {
-      const email = normalizeEmail(input.email);
-      if (!email.includes("@")) return fail("AuthFailed", { reason: "invalid_email" });
-      const otp = generateOtp(6);
-      const now = runtime.now();
-      // Invalidate prior active challenges for this email.
-      for (const row of verifications.rows.values()) {
-        if (row.identifier === `email-otp:${email}` && row.consumedAt === null) {
-          row.consumedAt = now;
-        }
-      }
-      putVerification(verifications, {
-        id: crypto.randomUUID(),
-        identifier: `email-otp:${email}`,
-        value: await hashChallenge(otp),
-        expiresAt: now + ttlMs,
-        createdAt: now,
-        consumedAt: null,
-        attempts: 0,
-      });
-      await fx.send(tmpl, {
-        to: email,
-        data: { email, otp },
-      });
-      return {
-        ok: true as const,
-        ...(opts.exposeDevOtp ? { devOtp: otp } : {}),
-      };
-    },
-  });
-
-  const verify = flow({
-    name: "auth.verifyEmailOtp",
-    unit: "auth",
-    plane: "user",
-    in: z.object({
-      email: z.string().min(3),
-      otp: z.string().min(4).max(8),
-    }),
-    out: SessionTokensOut,
-    errors: { AuthFailed, AuthRateLimited },
-    do: async (input) => {
-      const email = normalizeEmail(input.email);
-      const now = runtime.now();
-      const row = findActiveVerification(verifications, `email-otp:${email}`, now);
-      if (!row) return fail("AuthFailed", { reason: "invalid_credentials" });
-      if (row.attempts >= MAX_ATTEMPTS) {
-        row.consumedAt = now;
-        return fail("AuthFailed", { reason: "invalid_credentials" });
-      }
-      const hash = await hashChallenge(input.otp.trim());
-      if (hash !== row.value) {
-        row.attempts += 1;
-        if (row.attempts >= MAX_ATTEMPTS) row.consumedAt = now;
-        return fail("AuthFailed", { reason: "invalid_credentials" });
-      }
-      row.consumedAt = now;
-      const user = ensureUserByEmail(identities, email, now);
-      const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
-        id: user.id,
-        plane: "user",
-        scopes: [],
-      });
-      return {
-        accessToken: issued.accessToken,
-        refreshToken: issued.refreshToken,
-        accessExpiresAt: issued.accessExpiresAt,
-        userId: user.id,
-      };
-    },
-  });
-
-  return plugin("emailOtp", { version: "0.0.1", config: { method: "email-otp" } })
-    .needs("auth")
-    .needs("channel")
-    .channelTemplate(tmpl)
-    .channelCatalog(emailOtpCatalog)
-    .binding(bindPublicAuth("/email-otp/request", request, "otp"))
-    .binding(bindPublicAuth("/email-otp/verify", verify, "otp"));
-}
-
-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;
-}