@supa-media/convex 1.8.0 → 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.8.0",
+  "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,6 +9,7 @@ export type {
   SupaAuthAdmission,
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
+  SupaAuthPhoneVerifyConfig,
   SupaAuthResendConfig,
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,

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,11 +28,19 @@ 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 { createPhoneVerifySignIn, type SupaAuthPhoneVerifyConfig } from "./phoneVerify";
 import { userCallback, type SupaAuthFindUserByEmail, type SupaAuthUserCreated } from "./users";
 
 export { NOT_ADMITTED_MESSAGE, type SupaAuthAdmission } from "./admission";
 export type { SupaAuthFindUserByEmail, SupaAuthUserCreated } from "./users";
 
+export {
+  createPhoneVerifySignIn,
+  phoneVerifyAuthorize,
+  PHONE_VERIFY_PROVIDER_ID,
+  type SupaAuthPhoneVerifyConfig,
+} from "./phoneVerify";
+
 export {
   createTestEmailOtp,
   createTestEmailOtps,
@@ -144,6 +152,13 @@ export interface SupaAuthConfig {
    * 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. */
@@ -430,6 +445,7 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
       : []),
     ...(methods.includes("email") ? createTestEmailOtps(config.testEmail) : []),
     ...(methods.includes("phone") ? [createPhoneOtp(config)] : []),
+    ...(config.phoneVerify !== undefined ? [createPhoneVerifySignIn(config.phoneVerify)] : []),
   ];
 
   return convexAuth({