@supa-media/convex 1.4.0 → 1.6.0

package/README.md

@@ -193,6 +193,8 @@ function createSupaAuth(config?: {
   appName?: string;
   methods?: Array<"email" | "phone">;      // default ["email", "phone"]
   magicLink?: SupaAuthMagicLinkConfig;     // off unless present
+  admission?: SupaAuthAdmission;           // invite-only; open sign-up unless present
+  onUserCreated?: SupaAuthUserCreated;     // once per brand-new user, same transaction
   resend?: { fromAddress: string; emailSubject?: (code) => string;
              renderHtml?: (p: { code, email }) => string };
   twilio?: { tokenBridgePath?: string };   // default "/api/internal/phone-token"
@@ -244,6 +246,42 @@ production login code.
 > `PHONE_TOKEN_BRIDGE_SECRET` is unset, the provider logs the raw token to the
 > console and returns, so local dev degrades rather than breaks.
 
+
+### Invite-only sign-in (`admission`)
+
+```ts
+createSupaAuth({
+  admission: {
+    canReceiveEmailCode: (ctx, email) => ctx.runQuery(internal.waitlist.isAdmitted, { email }),
+    canCreateUser: (ctx, { email }) => isAdmitted(ctx.db, email),
+  },
+});
+```
+
+`canReceiveEmailCode` runs before a sign-in code is mailed; refusing means no
+mail goes out and `signIn` throws. `canCreateUser` runs before a user row is
+created for somebody with no account, whichever provider they came through, and
+is never asked for an account that already exists. Both fail closed: a hook
+that throws refuses. Ask your own "is this address let in?" before calling
+`signIn` and draw the answer yourself; the error message is redacted in
+production.
+
+### New accounts (`onUserCreated`)
+
+```ts
+createSupaAuth({
+  onUserCreated: async (ctx, { userId, email }) => {
+    await ctx.scheduler.runAfter(0, internal.alerts.newAccount, { userId });
+  },
+});
+```
+
+Runs once for each brand-new user row, after the insert and inside the same
+mutation, so whatever it writes or schedules commits only with the account. A
+returning account, or a new sign-in method linked to an existing user, never
+calls it. A hook that throws fails the sign-in, so keep it to quick writes and
+`ctx.scheduler`.
+
 ### Magic link (opt-in)
 
 Set `magicLink: {}` and a **second** email provider is registered under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-media/convex",
-  "version": "1.4.0",
+  "version": "1.6.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/admission.ts

@@ -0,0 +1,90 @@
+/**
+ * Who may sign in at all: the hooks an invite-only or waitlisted app uses.
+ *
+ * Without `admission`, anybody who can read their inbox can make an account —
+ * the default, and unchanged. With it, an app answers two questions:
+ *
+ *  - **May this address be mailed a code?** Asked before the email OTP
+ *    provider sends anything. Refusing means no mail goes out and `signIn`
+ *    throws, so a person who has not been let in never holds a code.
+ *  - **May this person get a brand-new account?** Asked in
+ *    `createOrUpdateUser`, only when no user exists yet. This is the backstop,
+ *    and it is the one that covers every provider — the magic link, the
+ *    fixed-code test accounts, a phone number — not only the email OTP.
+ *    Returning users never reach it, so turning an app invite-only can never
+ *    lock out an account that already exists.
+ *
+ * Both hooks fail closed: one that throws, or a send that arrives with no ctx
+ * to ask with, refuses.
+ *
+ * The refusal is one fixed message, `NOT_ADMITTED_MESSAGE`. A client should
+ * not rely on reading it — Convex redacts action errors in production — and
+ * should instead ask the app whether an address is let in *before* calling
+ * `signIn`, drawing its own "you're on the list" for the answer. These hooks
+ * are what makes that answer binding rather than advisory.
+ */
+import type {
+  AnyDataModel,
+  GenericActionCtx,
+  GenericMutationCtx,
+} from "convex/server";
+
+export interface SupaAuthAdmission {
+  /**
+   * Before a sign-in code is mailed. `email` is the address as the provider
+   * received it; normalize it the same way the app stores addresses.
+   */
+  canReceiveEmailCode?: (
+    ctx: GenericActionCtx<AnyDataModel>,
+    email: string,
+  ) => Promise<boolean>;
+  /**
+   * Before a user row is created for somebody with no account. `provider` is
+   * the auth provider's id (`"email"`, `"magic-link"`, `"test-email"`, …).
+   */
+  canCreateUser?: (
+    ctx: GenericMutationCtx<AnyDataModel>,
+    who: { provider: string; email?: string; phone?: string },
+  ) => Promise<boolean>;
+}
+
+export const NOT_ADMITTED_MESSAGE = "This address has not been let in yet.";
+
+async function allowed(check: () => Promise<boolean>): Promise<boolean> {
+  try {
+    return (await check()) === true;
+  } catch (error) {
+    console.error("[supa-auth] admission check failed, refusing:", error);
+    return false;
+  }
+}
+
+/** Throws unless `admission` lets `email` be mailed a code. */
+export async function assertMayReceiveEmailCode(
+  admission: SupaAuthAdmission | undefined,
+  ctx: unknown,
+  email: string,
+): Promise<void> {
+  const check = admission?.canReceiveEmailCode;
+  if (check === undefined) return;
+  const ok =
+    ctx !== undefined &&
+    ctx !== null &&
+    (await allowed(() =>
+      check(ctx as GenericActionCtx<AnyDataModel>, email),
+    ));
+  if (!ok) throw new Error(NOT_ADMITTED_MESSAGE);
+}
+
+/** Throws unless `admission` lets this person have a new account. */
+export async function assertMayCreateUser(
+  admission: SupaAuthAdmission | undefined,
+  ctx: GenericMutationCtx<AnyDataModel>,
+  who: { provider: string; email?: string; phone?: string },
+): Promise<void> {
+  const check = admission?.canCreateUser;
+  if (check === undefined) return;
+  if (!(await allowed(() => check(ctx, who)))) {
+    throw new Error(NOT_ADMITTED_MESSAGE);
+  }
+}

package/src/auth/index.ts

@@ -1,14 +1,17 @@
 export {
   createSupaAuth,
   MAGIC_LINK_PROVIDER_ID,
+  NOT_ADMITTED_MESSAGE,
   TEST_EMAIL_PROVIDER_ID,
 } from "./setup";
 export type {
+  SupaAuthAdmission,
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
   SupaAuthResendConfig,
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
+  SupaAuthUserCreated,
 } from "./setup";
 export {
   requireAuth,

package/src/auth/setup.ts

@@ -25,9 +25,12 @@
 import { convexAuth } from "@convex-dev/auth/server";
 import { Email } from "@convex-dev/auth/providers/Email";
 import { Phone } from "@convex-dev/auth/providers/Phone";
-import type { GenericId } from "convex/values";
-
+import { assertMayReceiveEmailCode, type SupaAuthAdmission } from "./admission";
 import { createTestEmailOtps, type SupaAuthTestEmailConfig } from "./testEmail";
+import { userCallback, type SupaAuthUserCreated } from "./users";
+
+export { NOT_ADMITTED_MESSAGE, type SupaAuthAdmission } from "./admission";
+export type { SupaAuthUserCreated } from "./users";
 
 export {
   createTestEmailOtp,
@@ -117,6 +120,20 @@ export interface SupaAuthConfig {
    * other email address is refused by a distinct provider.
    */
   testEmail?: SupaAuthTestEmailConfig | SupaAuthTestEmailConfig[];
+  /**
+   * Make the app invite-only: who may be mailed a sign-in code, and who may
+   * get a brand-new account. Omitted, anybody may sign up. See `admission.ts`.
+   */
+  admission?: SupaAuthAdmission;
+  /**
+   * Called once for each brand-new user row, never for a returning account or
+   * a new sign-in method linked to an existing one. Runs inside the sign-in
+   * mutation, after the insert: what it writes or schedules commits only with
+   * the account, and a hook that throws fails the sign-in. Keep it to quick
+   * writes and `ctx.scheduler` — a welcome email or a staff alert belongs in a
+   * scheduled action, not here.
+   */
+  onUserCreated?: SupaAuthUserCreated;
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -165,7 +182,10 @@ function createEmailOtp(config: SupaAuthConfig) {
   return Email({
     maxAge: 10 * 60, // 10 minutes
     generateVerificationToken: createOtpGenerator(config.productionIdentifier),
-    sendVerificationRequest: async ({ identifier: email, token }) => {
+    // `@convex-dev/auth` passes its action ctx as a second argument that the
+    // Auth.js type does not declare; the admission check needs it to ask.
+    sendVerificationRequest: async ({ identifier: email, token }, ctx?: unknown) => {
+      await assertMayReceiveEmailCode(config.admission, ctx, email);
       // Dynamic import of resend — only loaded when RESEND_API_KEY is set
       const apiKey = process.env.RESEND_API_KEY;
 
@@ -430,86 +450,6 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
 
   return convexAuth({
     providers,
-    callbacks: {
-      async createOrUpdateUser(ctx, { existingUserId, type, profile }) {
-        // Returning user — auth account already exists
-        if (existingUserId !== null) {
-          const existingUser = await ctx.db.get(existingUserId);
-          if (existingUser) {
-            const updateData: Record<string, unknown> = {};
-            if (type === "phone" || type === "verification") {
-              updateData.phoneVerificationTime = Date.now();
-            }
-            if (type === "email" || type === "verification") {
-              updateData.emailVerificationTime = Date.now();
-            }
-            if (profile.phone) updateData.phone = profile.phone;
-            if (profile.email) updateData.email = profile.email;
-            if (profile.name) updateData.name = profile.name;
-
-            if (Object.keys(updateData).length > 0) {
-              await ctx.db.patch(existingUserId, updateData);
-            }
-            return existingUserId;
-          }
-        }
-
-        // New auth account — try to link to existing user by phone
-        if (type === "phone" && typeof profile.phone === "string") {
-          const phone = profile.phone;
-          const existingUser = await ctx.db
-            .query("users")
-            .filter((q) => q.eq(q.field("phone"), phone))
-            .first();
-
-          if (existingUser) {
-            await ctx.db.patch(existingUser._id, {
-              phoneVerificationTime: Date.now(),
-            });
-            return existingUser._id;
-          }
-        }
-
-        // New auth account — try to link to existing user by email
-        if (type === "email" && typeof profile.email === "string") {
-          const email = profile.email;
-          const existingUser = await ctx.db
-            .query("users")
-            .filter((q) => q.eq(q.field("email"), email))
-            .first();
-
-          if (existingUser) {
-            await ctx.db.patch(existingUser._id, {
-              emailVerificationTime: Date.now(),
-            });
-            return existingUser._id;
-          }
-        }
-
-        // No existing user — create a new one
-        const userData: Record<string, unknown> = {};
-        if (profile.email) userData.email = profile.email;
-        if (profile.phone) userData.phone = profile.phone;
-        if (profile.name) userData.name = profile.name;
-        if (profile.image) userData.image = profile.image;
-        if (profile.emailVerified || type === "email") {
-          userData.emailVerificationTime = Date.now();
-        }
-        if (profile.phoneVerified || type === "phone") {
-          userData.phoneVerificationTime = Date.now();
-        }
-        userData.isActive = true;
-        userData.createdAt = Date.now();
-
-        const userId = await ctx.db.insert(
-          "users",
-          userData as Record<string, unknown> & {
-            email?: string;
-            phone?: string;
-          },
-        );
-        return userId as GenericId<"users">;
-      },
-    },
+    callbacks: { createOrUpdateUser: userCallback(config.admission, config.onUserCreated) },
   });
 }

package/src/auth/users.ts

@@ -0,0 +1,134 @@
+/**
+ * The `createOrUpdateUser` callback `createSupaAuth` hands `convexAuth`.
+ *
+ * A returning account keeps its user. A new account is linked to an existing
+ * user with the same phone or email before anything is created, so one person
+ * who signs in two ways is one user. Only when nobody matches is a user row
+ * created — and that is the one place `admission.canCreateUser` is asked, so
+ * an invite-only app can refuse a stranger without ever locking out somebody
+ * who already has an account. It is also the one place `onUserCreated` runs,
+ * so an app hears about each brand-new account exactly once.
+ */
+import type { AnyDataModel, GenericMutationCtx } from "convex/server";
+import type { GenericId } from "convex/values";
+import type { convexAuth } from "@convex-dev/auth/server";
+
+import { assertMayCreateUser, type SupaAuthAdmission } from "./admission";
+
+/** See `SupaAuthConfig.onUserCreated`. */
+export type SupaAuthUserCreated = (
+  ctx: GenericMutationCtx<AnyDataModel>,
+  created: { userId: GenericId<"users">; provider: string; email?: string; phone?: string },
+) => Promise<void>;
+
+type Handler = NonNullable<
+  NonNullable<Parameters<typeof convexAuth>[0]["callbacks"]>["createOrUpdateUser"]
+>;
+
+export function userCallback(
+  admission: SupaAuthAdmission | undefined,
+  onUserCreated?: SupaAuthUserCreated,
+): Handler {
+  async function createOrUpdateUser(
+    ctx: Parameters<Handler>[0],
+    { existingUserId, type, provider, profile }: Parameters<Handler>[1],
+  ): Promise<GenericId<"users">> {
+    // Returning user — auth account already exists
+    if (existingUserId !== null) {
+      const existingUser = await ctx.db.get(existingUserId);
+      if (existingUser) {
+        const updateData: Record<string, unknown> = {};
+        if (type === "phone" || type === "verification") {
+          updateData.phoneVerificationTime = Date.now();
+        }
+        if (type === "email" || type === "verification") {
+          updateData.emailVerificationTime = Date.now();
+        }
+        if (profile.phone) updateData.phone = profile.phone;
+        if (profile.email) updateData.email = profile.email;
+        if (profile.name) updateData.name = profile.name;
+
+        if (Object.keys(updateData).length > 0) {
+          await ctx.db.patch(existingUserId, updateData);
+        }
+        return existingUserId;
+      }
+    }
+
+    // New auth account — try to link to existing user by phone
+    if (type === "phone" && typeof profile.phone === "string") {
+      const phone = profile.phone;
+      const existingUser = await ctx.db
+        .query("users")
+        .filter((q) => q.eq(q.field("phone"), phone))
+        .first();
+
+      if (existingUser) {
+        await ctx.db.patch(existingUser._id, {
+          phoneVerificationTime: Date.now(),
+        });
+        return existingUser._id;
+      }
+    }
+
+    // New auth account — try to link to existing user by email
+    if (type === "email" && typeof profile.email === "string") {
+      const email = profile.email;
+      const existingUser = await ctx.db
+        .query("users")
+        .filter((q) => q.eq(q.field("email"), email))
+        .first();
+
+      if (existingUser) {
+        await ctx.db.patch(existingUser._id, {
+          emailVerificationTime: Date.now(),
+        });
+        return existingUser._id;
+      }
+    }
+
+    // No existing user. Ask the app first: this is the backstop that holds
+    // for every provider, not only the email OTP. See `admission.ts`.
+    await assertMayCreateUser(admission, ctx, {
+      provider: provider.id,
+      ...(typeof profile.email === "string" ? { email: profile.email } : {}),
+      ...(typeof profile.phone === "string" ? { phone: profile.phone } : {}),
+    });
+
+    // No existing user — create a new one
+    const userData: Record<string, unknown> = {};
+    if (profile.email) userData.email = profile.email;
+    if (profile.phone) userData.phone = profile.phone;
+    if (profile.name) userData.name = profile.name;
+    if (profile.image) userData.image = profile.image;
+    if (profile.emailVerified || type === "email") {
+      userData.emailVerificationTime = Date.now();
+    }
+    if (profile.phoneVerified || type === "phone") {
+      userData.phoneVerificationTime = Date.now();
+    }
+    userData.isActive = true;
+    userData.createdAt = Date.now();
+
+    const userId = await ctx.db.insert(
+      "users",
+      userData as Record<string, unknown> & {
+        email?: string;
+        phone?: string;
+      },
+    );
+    // Same transaction as the insert: a hook that throws undoes the account,
+    // and anything it writes or schedules lands only if the account does.
+    if (onUserCreated !== undefined) {
+      await onUserCreated(ctx, {
+        userId: userId as GenericId<"users">,
+        provider: provider.id,
+        ...(typeof profile.email === "string" ? { email: profile.email } : {}),
+        ...(typeof profile.phone === "string" ? { phone: profile.phone } : {}),
+      });
+    }
+    return userId as GenericId<"users">;
+  }
+
+  return createOrUpdateUser;
+}