@supa-media/convex 1.6.0 → 1.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-media/convex",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "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

@@ -13,6 +13,12 @@ export type {
   SupaAuthTwilioConfig,
   SupaAuthUserCreated,
 } from "./setup";
+export {
+  checkTwilioVerification,
+  sendTwilioVerification,
+  twilioVerifyKeys,
+} from "./twilioVerify";
+export type { TwilioCheckResult, TwilioSendResult, TwilioVerifyKeys } from "./twilioVerify";
 export {
   requireAuth,
   requireAuthId,

package/src/auth/setup.ts

@@ -22,6 +22,7 @@
  * ```
  */
 
+import { sendTwilioVerification } from "./twilioVerify";
 import { convexAuth } from "@convex-dev/auth/server";
 import { Email } from "@convex-dev/auth/providers/Email";
 import { Phone } from "@convex-dev/auth/providers/Phone";
@@ -388,39 +389,13 @@ function createPhoneOtp(config: SupaAuthConfig) {
         return;
       }
 
-      const response = await fetch(
-        `https://verify.twilio.com/v2/Services/${verifyServiceSid}/Verifications`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Basic ${btoa(`${accountSid}:${authToken}`)}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-          },
-          body: new URLSearchParams({
-            To: phone,
-            Channel: "sms",
-          }),
-        },
+      const sent = await sendTwilioVerification(
+        { accountSid, authToken, serviceSid: verifyServiceSid },
+        phone,
       );
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        let errorData: { code?: number; message?: string };
-        try {
-          errorData = JSON.parse(errorText);
-        } catch {
-          errorData = { message: errorText };
-        }
-
-        console.error("Twilio Verify send error:", {
-          status: response.status,
-          errorCode: errorData?.code,
-          errorMessage: errorData?.message,
-          phone,
-        });
-
+      if (!sent.ok) {
         throw new Error(
-          errorData?.message?.includes("Invalid phone number")
+          sent.reason === "invalid_phone"
             ? "Invalid phone number. Please check and try again."
             : "Failed to send verification code. Please try again.",
         );

package/src/auth/twilioVerify.ts

@@ -0,0 +1,108 @@
+/**
+ * Twilio Verify, on its own: send a code to a phone, then check one.
+ *
+ * `createSupaAuth`'s phone provider uses Twilio Verify to *sign in* with a
+ * phone. An app that signs in with email can still want to know a person holds
+ * a phone: proof of a real person, or one identity across several sign-in
+ * emails. These two calls are that, without a sign-in provider: Twilio keeps
+ * the code, so the app stores no secret and only records the result.
+ *
+ * The keys are the provider's: `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`,
+ * `TWILIO_VERIFY_SERVICE_SID`. An API key works in place of the auth token:
+ * `TWILIO_API_KEY_SID` with `TWILIO_API_KEY_SECRET`, which Twilio recommends
+ * because it can be revoked on its own. With no usable pair, `twilioVerifyKeys`
+ * answers `null`, and the app decides what that means. It should never mean
+ * "verified".
+ */
+
+export interface TwilioVerifyKeys {
+  accountSid: string;
+  /** The account's auth token, or the API key's secret when `apiKeySid` is set. */
+  authToken: string;
+  serviceSid: string;
+  /** Set when signing requests with an API key rather than the auth token. */
+  apiKeySid?: string;
+}
+
+export type TwilioSendResult =
+  | { ok: true }
+  | { ok: false; reason: "invalid_phone" | "too_many" | "failed" };
+
+/** `wrong` covers an expired or unknown code too: Twilio answers both with 404. */
+export type TwilioCheckResult = "approved" | "wrong" | "too_many" | "failed";
+
+type Fetch = typeof fetch;
+
+/** The keys from the environment, or `null` when any is unset. */
+export function twilioVerifyKeys(
+  env: Record<string, string | undefined> = process.env,
+): TwilioVerifyKeys | null {
+  const accountSid = env.TWILIO_ACCOUNT_SID?.trim();
+  const authToken = env.TWILIO_AUTH_TOKEN?.trim();
+  const serviceSid = env.TWILIO_VERIFY_SERVICE_SID?.trim();
+  if (!accountSid || !serviceSid) return null;
+  if (authToken) return { accountSid, authToken, serviceSid };
+  const apiKeySid = env.TWILIO_API_KEY_SID?.trim();
+  const apiKeySecret = env.TWILIO_API_KEY_SECRET?.trim();
+  if (!apiKeySid || !apiKeySecret) return null;
+  return { accountSid, authToken: apiKeySecret, serviceSid, apiKeySid };
+}
+
+function request(keys: TwilioVerifyKeys, path: string, body: Record<string, string>, fetchImpl: Fetch) {
+  return fetchImpl(`https://verify.twilio.com/v2/Services/${keys.serviceSid}/${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${btoa(`${keys.apiKeySid ?? keys.accountSid}:${keys.authToken}`)}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams(body),
+  });
+}
+
+async function errorOf(response: Response): Promise<{ code?: number; message?: string }> {
+  const text = await response.text();
+  try {
+    return JSON.parse(text) as { code?: number; message?: string };
+  } catch {
+    return { message: text };
+  }
+}
+
+/** Twilio's "Max send attempts reached" and "Max check attempts reached". */
+const TOO_MANY = new Set([60203, 60202]);
+
+/** Text a code to `phone` (E.164). */
+export async function sendTwilioVerification(
+  keys: TwilioVerifyKeys,
+  phone: string,
+  fetchImpl: Fetch = fetch,
+): Promise<TwilioSendResult> {
+  const response = await request(keys, "Verifications", { To: phone, Channel: "sms" }, fetchImpl);
+  if (response.ok) return { ok: true };
+  const error = await errorOf(response);
+  // Logged without the number: a phone number is personal data.
+  console.error("Twilio Verify send failed", { status: response.status, code: error.code });
+  if (error.code !== undefined && TOO_MANY.has(error.code)) return { ok: false, reason: "too_many" };
+  if (error.code === 60200 || /invalid.*phone/i.test(error.message ?? "")) {
+    return { ok: false, reason: "invalid_phone" };
+  }
+  return { ok: false, reason: "failed" };
+}
+
+/** Check a code typed for `phone`. Only `approved` means the person holds it. */
+export async function checkTwilioVerification(
+  keys: TwilioVerifyKeys,
+  phone: string,
+  code: string,
+  fetchImpl: Fetch = fetch,
+): Promise<TwilioCheckResult> {
+  const response = await request(keys, "VerificationCheck", { To: phone, Code: code }, fetchImpl);
+  if (response.status === 404) return "wrong";
+  if (!response.ok) {
+    const error = await errorOf(response);
+    console.error("Twilio Verify check failed", { status: response.status, code: error.code });
+    return error.code !== undefined && TOO_MANY.has(error.code) ? "too_many" : "failed";
+  }
+  const body = (await response.json()) as { status?: string; valid?: boolean };
+  return body.status === "approved" && body.valid !== false ? "approved" : "wrong";
+}