@supa-media/convex 1.7.1 → 1.9.0

package/README.md

@@ -339,6 +339,29 @@ not own. That is a nuisance, not a hole: the library's own generator produces
 attacker gets is the ability to invalidate somebody's pending code — which
 `signIn("email", { email })` could always do too.
 
+### Phone sign-in through Twilio Verify (`phoneVerify`, opt-in)
+
+For people who already have an account. The app texts the code itself with
+`sendTwilioVerification`, after deciding who may be texted, and the client
+signs in with `signIn(PHONE_VERIFY_PROVIDER_ID, { phone, code })`:
+
+```ts
+createSupaAuth({
+  methods: ["email"],
+  phoneVerify: {
+    findUserByPhone: (ctx, phone) => ctx.runQuery(internal.phones.holder, { phone }),
+    mayCheck: (ctx, phone) => ctx.runMutation(internal.phones.spendCheck, { phone }),
+  },
+});
+```
+
+Twilio holds the code, so nothing secret is stored. Only `approved` signs
+anybody in, and a phone `findUserByPhone` does not know is refused: the
+provider never creates an account, so it never reaches `admission`. A
+credentials provider is not rate-limited by `@convex-dev/auth`; the limits are
+Twilio's (five checks per code, ten minutes) and `mayCheck`, which fails closed.
+This is separate from the bridge-based `"phone"` method.
+
 ### Auth helpers
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-media/convex",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Backend package for the Supa framework — OTP auth, schema helpers, and backend utilities for Convex",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/auth/index.ts

@@ -1,6 +1,7 @@
 export {
   createSupaAuth,
   MAGIC_LINK_PROVIDER_ID,
+  PHONE_VERIFY_PROVIDER_ID,
   NOT_ADMITTED_MESSAGE,
   TEST_EMAIL_PROVIDER_ID,
 } from "./setup";
@@ -8,10 +9,12 @@ export type {
   SupaAuthAdmission,
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
+  SupaAuthPhoneVerifyConfig,
   SupaAuthResendConfig,
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
   SupaAuthUserCreated,
+  SupaAuthFindUserByEmail,
 } from "./setup";
 export {
   checkTwilioVerification,

package/src/auth/phoneVerify.ts

@@ -0,0 +1,86 @@
+/**
+ * Sign in with a phone whose code Twilio Verify holds.
+ *
+ * An app texts the code itself (`sendTwilioVerification`), deciding first who
+ * may be texted at all, then the client calls
+ * `signIn(PHONE_VERIFY_PROVIDER_ID, { phone, code })`. This provider asks
+ * Twilio whether that code is approved for that phone, and only then asks the
+ * app which user holds the phone. Nothing secret is stored: Twilio keeps the
+ * code, and the app keeps only which phone is whose.
+ *
+ * ## It signs people in, it never makes them
+ *
+ * `findUserByPhone` answering `null` refuses the sign-in. A new person comes
+ * in another way (an email code, an invitation link) and adds the phone once
+ * signed in. That keeps the provider out of `createOrUpdateUser`, and out of
+ * `admission`, entirely: there is no row it could create.
+ *
+ * ## Guessing a code
+ *
+ * `@convex-dev/auth` does not rate-limit a credentials provider, so the limits
+ * are Twilio's — five checks per texted code, and a code lives ten minutes —
+ * and the app's own `mayCheck`, asked before every check. It fails closed: a
+ * hook that throws refuses. Only `approved` from Twilio signs anybody in.
+ */
+
+import { ConvexCredentials } from "@convex-dev/auth/providers/ConvexCredentials";
+import type { AnyDataModel, GenericActionCtx } from "convex/server";
+import type { GenericId } from "convex/values";
+
+import { checkTwilioVerification, twilioVerifyKeys, type TwilioCheckResult } from "./twilioVerify";
+
+/** Provider id the client signs in with. */
+export const PHONE_VERIFY_PROVIDER_ID = "phone-verify";
+
+/** E.164: a plus, a non-zero country digit, 7 to 15 digits in all. */
+const E164 = /^\+[1-9]\d{6,14}$/;
+
+export interface SupaAuthPhoneVerifyConfig {
+  /**
+   * The user who holds `phone` (E.164), or `null`. Only return a user the
+   * phone was confirmed for: whoever holds that phone signs in as them.
+   */
+  findUserByPhone: (ctx: GenericActionCtx<AnyDataModel>, phone: string) => Promise<GenericId<"users"> | null>;
+  /** Spend one check for `phone`; `false` refuses before Twilio is asked. */
+  mayCheck?: (ctx: GenericActionCtx<AnyDataModel>, phone: string) => Promise<boolean>;
+  /** Overridable for tests. */
+  check?: (phone: string, code: string) => Promise<TwilioCheckResult>;
+}
+
+async function twilioCheck(phone: string, code: string): Promise<TwilioCheckResult> {
+  const keys = twilioVerifyKeys();
+  if (keys === null) return "failed";
+  return await checkTwilioVerification(keys, phone, code);
+}
+
+/** The `authorize` step, on its own so its boundary is testable without a deployment. */
+export function phoneVerifyAuthorize(config: SupaAuthPhoneVerifyConfig) {
+  const check = config.check ?? twilioCheck;
+  return async (
+    credentials: Partial<Record<string, unknown>>,
+    ctx: GenericActionCtx<AnyDataModel>,
+  ): Promise<{ userId: GenericId<"users"> } | null> => {
+    const phone = typeof credentials.phone === "string" ? credentials.phone.trim() : "";
+    const code = typeof credentials.code === "string" ? credentials.code.replace(/\s/g, "") : "";
+    if (!E164.test(phone) || !/^\d{4,10}$/.test(code)) return null;
+    if (config.mayCheck !== undefined) {
+      let ok = false;
+      try {
+        ok = (await config.mayCheck(ctx, phone)) === true;
+      } catch (error) {
+        console.error("[supa-auth] phone check limit failed, refusing:", error);
+      }
+      if (!ok) return null;
+    }
+    if ((await check(phone, code)) !== "approved") return null;
+    const userId = await config.findUserByPhone(ctx, phone);
+    return userId === null ? null : { userId };
+  };
+}
+
+export function createPhoneVerifySignIn(config: SupaAuthPhoneVerifyConfig) {
+  return ConvexCredentials({
+    id: PHONE_VERIFY_PROVIDER_ID,
+    authorize: phoneVerifyAuthorize(config) as never,
+  });
+}

package/src/auth/setup.ts

@@ -28,10 +28,18 @@ import { Email } from "@convex-dev/auth/providers/Email";
 import { Phone } from "@convex-dev/auth/providers/Phone";
 import { assertMayReceiveEmailCode, type SupaAuthAdmission } from "./admission";
 import { createTestEmailOtps, type SupaAuthTestEmailConfig } from "./testEmail";
-import { userCallback, type SupaAuthUserCreated } from "./users";
+import { createPhoneVerifySignIn, type SupaAuthPhoneVerifyConfig } from "./phoneVerify";
+import { userCallback, type SupaAuthFindUserByEmail, type SupaAuthUserCreated } from "./users";
 
 export { NOT_ADMITTED_MESSAGE, type SupaAuthAdmission } from "./admission";
-export type { SupaAuthUserCreated } from "./users";
+export type { SupaAuthFindUserByEmail, SupaAuthUserCreated } from "./users";
+
+export {
+  createPhoneVerifySignIn,
+  phoneVerifyAuthorize,
+  PHONE_VERIFY_PROVIDER_ID,
+  type SupaAuthPhoneVerifyConfig,
+} from "./phoneVerify";
 
 export {
   createTestEmailOtp,
@@ -135,6 +143,22 @@ export interface SupaAuthConfig {
    * scheduled action, not here.
    */
   onUserCreated?: SupaAuthUserCreated;
+  /**
+   * For an app that lets one person sign in with several emails: the user an
+   * address belongs to, or `null`. Asked when an email sign-in has no auth
+   * account yet, before the `users.email` match, so a sign-in through an
+   * attached address reaches its user rather than making a new one. Only
+   * return a user the address was confirmed for: whoever holds that mailbox
+   * signs in as them.
+   */
+  findUserByEmail?: SupaAuthFindUserByEmail;
+  /**
+   * Sign in with a phone through Twilio Verify, for people who already have
+   * an account: the app texts the code, this checks it. Independent of
+   * `methods`, which governs the older bridge-based phone provider. See
+   * `phoneVerify.ts`.
+   */
+  phoneVerify?: SupaAuthPhoneVerifyConfig;
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -421,10 +445,13 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
       : []),
     ...(methods.includes("email") ? createTestEmailOtps(config.testEmail) : []),
     ...(methods.includes("phone") ? [createPhoneOtp(config)] : []),
+    ...(config.phoneVerify !== undefined ? [createPhoneVerifySignIn(config.phoneVerify)] : []),
   ];
 
   return convexAuth({
     providers,
-    callbacks: { createOrUpdateUser: userCallback(config.admission, config.onUserCreated) },
+    callbacks: {
+      createOrUpdateUser: userCallback(config.admission, config.onUserCreated, config.findUserByEmail),
+    },
   });
 }

package/src/auth/users.ts

@@ -15,6 +15,12 @@ import type { convexAuth } from "@convex-dev/auth/server";
 
 import { assertMayCreateUser, type SupaAuthAdmission } from "./admission";
 
+/** See `SupaAuthConfig.findUserByEmail`. */
+export type SupaAuthFindUserByEmail = (
+  ctx: GenericMutationCtx<AnyDataModel>,
+  email: string,
+) => Promise<GenericId<"users"> | null>;
+
 /** See `SupaAuthConfig.onUserCreated`. */
 export type SupaAuthUserCreated = (
   ctx: GenericMutationCtx<AnyDataModel>,
@@ -28,6 +34,7 @@ type Handler = NonNullable<
 export function userCallback(
   admission: SupaAuthAdmission | undefined,
   onUserCreated?: SupaAuthUserCreated,
+  findUserByEmail?: SupaAuthFindUserByEmail,
 ): Handler {
   async function createOrUpdateUser(
     ctx: Parameters<Handler>[0],
@@ -44,8 +51,12 @@ export function userCallback(
         if (type === "email" || type === "verification") {
           updateData.emailVerificationTime = Date.now();
         }
-        if (profile.phone) updateData.phone = profile.phone;
-        if (profile.email) updateData.email = profile.email;
+        // Fill in a missing address, never replace one. A user may sign in
+        // through several auth accounts (an app that lets one person keep a
+        // work and a home email), and the address on the user row is the one
+        // they chose for mail, not whichever they signed in with last.
+        if (profile.phone && !existingUser.phone) updateData.phone = profile.phone;
+        if (profile.email && !existingUser.email) updateData.email = profile.email;
         if (profile.name) updateData.name = profile.name;
 
         if (Object.keys(updateData).length > 0) {
@@ -74,6 +85,13 @@ export function userCallback(
     // New auth account — try to link to existing user by email
     if (type === "email" && typeof profile.email === "string") {
       const email = profile.email;
+      // The app's own answer first: an address it has attached to a user as
+      // an extra sign-in email is that user, whatever the user row says.
+      const attached = findUserByEmail === undefined ? null : await findUserByEmail(ctx, email);
+      if (attached !== null) {
+        await ctx.db.patch(attached, { emailVerificationTime: Date.now() });
+        return attached;
+      }
       const existingUser = await ctx.db
         .query("users")
         .filter((q) => q.eq(q.field("email"), email))