okengine 0.7.0 → 0.9.0

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

@@ -0,0 +1,172 @@
+/**
+ * Real Taqnyat end-to-end: otp({ tier: 1 }) 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
+ *      (`OKE_SMS_LIVE=1` / `OKE_EMAIL_LIVE=1`), and
+ *   2. the matching real credentials are present in the environment.
+ *
+ * Credential presence alone is NEVER enough — this mirrors sently's own
+ * opt-in live suite and prevents burning provider quota on a routine
+ * `bun test` run with stray credentials in the shell. The flags are
+ * provider-agnostic: any future SMS or email provider live suite gates on
+ * the same medium flag plus its own credentials.
+ *
+ * Skip is always visible (`console.log("skip: …")` + `test.skip`), never a
+ * silent pass.
+ *
+ * Setup:
+ *   # SMS OTP — sends exactly ONE real SMS (the plugin's own send; its
+ *   # provider response is captured for the code-5 assertion)
+ *   export OKE_SMS_LIVE=1
+ *   export TAQNYAT_TOKEN=…            (or TAQNYAT_BEARER_TOKEN)
+ *   export TAQNYAT_SENDER=YourBrand
+ *   export OKE_TEST_TAQNYAT_PHONE=+9665xxxxxxxx   (or TAQNYAT_TO)
+ *   # Mail
+ *   export OKE_EMAIL_LIVE=1
+ *   export TAQNYAT_MAIL_TOKEN=…
+ *   export TAQNYAT_CAMPAIGN=auth
+ *   export OKE_TEST_TAQNYAT_MAIL=you@example.com  (or TAQNYAT_MAIL_TO)
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { resetFlowSeq } from "../kernel/flow.ts";
+import { resetBindings } from "../kernel/on.ts";
+import { magicLink } from "./magic-link.ts";
+import { otp } from "./otp.ts";
+
+const SECRET = "test-secret-at-least-16";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function jsonPost(path: string, body: unknown): Request {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+const WANT_SMS = process.env.OKE_SMS_LIVE === "1";
+const WANT_MAIL = process.env.OKE_EMAIL_LIVE === "1";
+
+const SMS_TOKEN = process.env.TAQNYAT_TOKEN ?? process.env.TAQNYAT_BEARER_TOKEN;
+const SMS_CREDS = Boolean(SMS_TOKEN) && Boolean(process.env.TAQNYAT_SENDER);
+// OKE_TEST_TAQNYAT_PHONE wins; TAQNYAT_TO (sently's convention) is the alias.
+const SMS_PHONE = process.env.OKE_TEST_TAQNYAT_PHONE ?? process.env.TAQNYAT_TO;
+const LIVE_SMS = WANT_SMS && SMS_CREDS && Boolean(SMS_PHONE);
+
+const MAIL_CREDS = Boolean(process.env.TAQNYAT_MAIL_TOKEN) && Boolean(process.env.TAQNYAT_CAMPAIGN);
+const MAIL_TO = process.env.OKE_TEST_TAQNYAT_MAIL ?? process.env.TAQNYAT_MAIL_TO;
+const LIVE_MAIL = WANT_MAIL && MAIL_CREDS && Boolean(MAIL_TO);
+
+if (!LIVE_SMS) {
+  console.log(
+    WANT_SMS
+      ? "skip: taqnyat SMS OTP live (missing TAQNYAT_TOKEN/TAQNYAT_SENDER or OKE_TEST_TAQNYAT_PHONE)"
+      : "skip: taqnyat SMS OTP live (OKE_SMS_LIVE≠1)",
+  );
+}
+if (!LIVE_MAIL) {
+  console.log(
+    WANT_MAIL
+      ? "skip: taqnyat mail live (missing TAQNYAT_MAIL_TOKEN/TAQNYAT_CAMPAIGN or OKE_TEST_TAQNYAT_MAIL)"
+      : "skip: taqnyat mail live (OKE_EMAIL_LIVE≠1)",
+  );
+}
+
+const liveSms = LIVE_SMS ? test : test.skip;
+const liveMail = LIVE_MAIL ? test : test.skip;
+
+describe("taqnyat live — provider-managed OTP (Taqnyat Verify)", () => {
+  liveSms(
+    "phone OTP request → real sendOtp → Taqnyat success code 5",
+    async () => {
+      const app = oke({
+        name: `taqnyat-live-${crypto.randomUUID()}`,
+        env: "test",
+        registry: "ignore",
+        gate: { auth: { secret: SECRET } },
+        config: {
+          drivers: { channel: { sms: { test: "taqnyat" } } },
+        },
+      }).plug(otp({ tier: 1 }));
+      await app.boot({ env: "test" });
+
+      // Wrap the live transport so the plugin's single real send also proves
+      // the provider accepted it (success code 5) — exactly one SMS, never two.
+      const sms = app.bootResult?.channel?.drivers.find((d) => d.id === "taqnyat")?.smsTransport as
+        | {
+            sendOtp(o: {
+              to: string;
+              requestId: string;
+              lang?: "en" | "ar";
+            }): Promise<{ code: number }>;
+          }
+        | undefined;
+      expect(sms).toBeDefined();
+      const realSendOtp = sms!.sendOtp.bind(sms);
+      let providerCode: number | undefined;
+      sms!.sendOtp = async (opts) => {
+        const result = await realSendOtp(opts);
+        providerCode = result.code;
+        return result;
+      };
+
+      const res = await app.fetch(jsonPost("/auth/otp/request", { phone: SMS_PHONE, lang: "en" }));
+      const body = (await res.json()) as { data?: { ok: true }; error?: { message?: string } };
+      if (res.status !== 200) {
+        console.log("taqnyat sendOtp response", res.status, body);
+      }
+      expect(res.status).toBe(200);
+      expect(body.data?.ok).toBe(true);
+      // Local dev leak must stay off in the provider path.
+      expect((body.data as { devOtp?: string }).devOtp).toBeUndefined();
+      // Taqnyat Verify documented success code — from the plugin's own send.
+      expect(providerCode).toBe(5);
+
+      await app.stop();
+    },
+    30_000,
+  );
+});
+
+describe("taqnyat live — magic-link via Taqnyat Mail", () => {
+  liveMail(
+    "magic-link request → real TaqnyatMailTransport send",
+    async () => {
+      const app = oke({
+        name: `taqnyat-mail-live-${crypto.randomUUID()}`,
+        env: "test",
+        registry: "ignore",
+        gate: { auth: { secret: SECRET } },
+        config: {
+          drivers: { channel: { email: { test: "taqnyat-mail" } } },
+        },
+      }).plug(magicLink({ baseUrl: "http://app.test:6530" }));
+      await app.boot({ env: "test" });
+
+      const res = await app.fetch(jsonPost("/auth/magic-link/request", { email: MAIL_TO }));
+      const body = (await res.json()) as { data?: { ok: true }; error?: { message?: string } };
+      if (res.status !== 200) {
+        console.log("taqnyat mail send response", res.status, body);
+      }
+      expect(res.status).toBe(200);
+      expect(body.data?.ok).toBe(true);
+      expect((body.data as { devToken?: string }).devToken).toBeUndefined();
+
+      // A successful send is recorded in the Channel receipt ledger.
+      const receipts = app.bootResult?.channel?.receipts.all() ?? [];
+      const sent = receipts.find((r) => r.to === MAIL_TO);
+      expect(sent?.status === "sent" || sent?.status === "fallback").toBe(true);
+      expect(sent?.driverId).toContain("taqnyat");
+
+      await app.stop();
+    },
+    30_000,
+  );
+});

package/src/release/official-plugins.ts

@@ -33,8 +33,7 @@ export const OFFICIAL_PLUGIN_BUDGETS: readonly OfficialPluginBudget[] = [
   { name: "username", file: "username.ts", category: "auth" },
   { name: "anonymous", file: "anonymous.ts", category: "auth" },
   { name: "magicLink", file: "magic-link.ts", category: "auth" },
-  { name: "emailOtp", file: "email-otp.ts", category: "auth" },
-  { name: "phoneNumber", file: "phone-number.ts", category: "auth" },
+  { name: "otp", file: "otp.ts", category: "auth" },
   { name: "twoFactor", file: "two-factor.ts", category: "auth" },
   { name: "passkey", file: "passkey.ts", category: "auth" },
   { name: "headers", file: "headers.ts", category: "security" },

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,111 +0,0 @@
----
-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/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;
-}