@supa-media/convex 1.7.0 → 1.8.0

package/package.json

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

@@ -12,6 +12,7 @@ export type {
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
   SupaAuthUserCreated,
+  SupaAuthFindUserByEmail,
 } from "./setup";
 export {
   checkTwilioVerification,

package/src/auth/setup.ts

@@ -28,10 +28,10 @@ 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 { 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 {
   createTestEmailOtp,
@@ -135,6 +135,15 @@ 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;
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -425,6 +434,8 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
 
   return convexAuth({
     providers,
-    callbacks: { createOrUpdateUser: userCallback(config.admission, config.onUserCreated) },
+    callbacks: {
+      createOrUpdateUser: userCallback(config.admission, config.onUserCreated, config.findUserByEmail),
+    },
   });
 }

package/src/auth/twilioVerify.ts

@@ -8,14 +8,20 @@
  * 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`. With any missing, `twilioVerifyKeys` answers
- * `null`, and the app decides what that means. It should never mean "verified".
+ * `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 =
@@ -34,15 +40,19 @@ export function twilioVerifyKeys(
   const accountSid = env.TWILIO_ACCOUNT_SID?.trim();
   const authToken = env.TWILIO_AUTH_TOKEN?.trim();
   const serviceSid = env.TWILIO_VERIFY_SERVICE_SID?.trim();
-  if (!accountSid || !authToken || !serviceSid) return null;
-  return { accountSid, authToken, serviceSid };
+  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.accountSid}:${keys.authToken}`)}`,
+      Authorization: `Basic ${btoa(`${keys.apiKeySid ?? keys.accountSid}:${keys.authToken}`)}`,
       "Content-Type": "application/x-www-form-urlencoded",
     },
     body: new URLSearchParams(body),

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))