@supa-media/convex 1.3.0 → 1.5.0

package/README.md

@@ -193,6 +193,7 @@ 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
   resend?: { fromAddress: string; emailSubject?: (code) => string;
              renderHtml?: (p: { code, email }) => string };
   twilio?: { tokenBridgePath?: string };   // default "/api/internal/phone-token"
@@ -244,6 +245,26 @@ 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.
+
 ### 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.3.0",
+  "version": "1.5.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,9 +1,11 @@
 export {
   createSupaAuth,
   MAGIC_LINK_PROVIDER_ID,
+  NOT_ADMITTED_MESSAGE,
   TEST_EMAIL_PROVIDER_ID,
 } from "./setup";
 export type {
+  SupaAuthAdmission,
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
   SupaAuthResendConfig,

package/src/auth/setup.ts

@@ -25,7 +25,18 @@
 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 } from "./users";
+
+export { NOT_ADMITTED_MESSAGE, type SupaAuthAdmission } from "./admission";
+
+export {
+  createTestEmailOtp,
+  createTestEmailOtps,
+  TEST_EMAIL_PROVIDER_ID,
+  type SupaAuthTestEmailConfig,
+} from "./testEmail";
 
 export interface SupaAuthResendConfig {
   /** The "from" address for OTP emails. */
@@ -57,16 +68,6 @@ export interface SupaAuthTwilioConfig {
  */
 export const MAGIC_LINK_PROVIDER_ID = "magic-link";
 
-/** Provider id for an explicitly scoped production test account. */
-export const TEST_EMAIL_PROVIDER_ID = "test-email";
-
-export interface SupaAuthTestEmailConfig {
-  /** The only email address allowed to use the fixed test code. */
-  email: string;
-  /** Fixed verification code. Defaults to `000000`. */
-  code?: string;
-}
-
 export interface SupaAuthMagicLinkConfig {
   /**
    * How long a link stays live, in seconds. Defaults to one hour.
@@ -111,11 +112,18 @@ export interface SupaAuthConfig {
    */
   magicLink?: SupaAuthMagicLinkConfig;
   /**
-   * Register a fixed-code provider for one exact test account.
+   * Register a fixed-code provider for one exact test account, or one
+   * provider per account when given a list (each with its own `id` and code;
+   * an app store or connector-directory reviewer is the usual second one).
    * Unlike `DEV_OTP_BYPASS`, this may be used in production because every
    * other email address is refused by a distinct provider.
    */
-  testEmail?: SupaAuthTestEmailConfig;
+  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;
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -164,7 +172,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;
 
@@ -209,41 +220,6 @@ function createEmailOtp(config: SupaAuthConfig) {
   });
 }
 
-/** Build the fixed-code provider separately so its security boundary is testable. */
-export function createTestEmailOtp(config: SupaAuthTestEmailConfig) {
-  const email = config.email.trim().toLowerCase();
-  const code = config.code ?? DEV_BYPASS_CODE;
-  if (!/^\d{6}$/.test(code)) {
-    throw new Error("testEmail.code must be exactly six digits");
-  }
-  if (email.length === 0) {
-    throw new Error("testEmail.email must not be empty");
-  }
-
-  const provider = Email({
-    maxAge: 10 * 60,
-    generateVerificationToken: () => code,
-    sendVerificationRequest: async ({ identifier }) => {
-      if (identifier.trim().toLowerCase() !== email) {
-        throw new Error("This test sign-in provider is not available for that email.");
-      }
-    },
-  });
-  return {
-    ...provider,
-    id: TEST_EMAIL_PROVIDER_ID,
-    authorize: async (params: Record<string, unknown>, account: { providerAccountId: string }) => {
-      if (
-        typeof params.email !== "string" ||
-        params.email.trim().toLowerCase() !== email ||
-        account.providerAccountId.trim().toLowerCase() !== email
-      ) {
-        throw new Error("This test sign-in provider is not available for that email.");
-      }
-    },
-  };
-}
-
 /**
  * The link-only email provider.
  *
@@ -458,94 +434,12 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
     ...(methods.includes("email") && config.magicLink !== undefined
       ? [createMagicLink(config)]
       : []),
-    ...(methods.includes("email") && config.testEmail !== undefined
-      ? [createTestEmailOtp(config.testEmail)]
-      : []),
+    ...(methods.includes("email") ? createTestEmailOtps(config.testEmail) : []),
     ...(methods.includes("phone") ? [createPhoneOtp(config)] : []),
   ];
 
   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) },
   });
 }

package/src/auth/testEmail.ts

@@ -0,0 +1,87 @@
+/**
+ * Fixed-code sign-in for named test accounts (the CUJ account, a reviewer).
+ *
+ * Each account gets a provider of its own that refuses every other address,
+ * which is what makes a fixed code safe to register in production.
+ */
+
+import { Email } from "@convex-dev/auth/providers/Email";
+
+/** The code a test account uses when its config names none. */
+const DEFAULT_TEST_CODE = "000000";
+
+/** Provider id for an explicitly scoped production test account. */
+export const TEST_EMAIL_PROVIDER_ID = "test-email";
+
+export interface SupaAuthTestEmailConfig {
+  /** The only email address allowed to use the fixed test code. */
+  email: string;
+  /** Fixed verification code. Defaults to `000000`. */
+  code?: string;
+  /**
+   * Provider id the client signs in with. Defaults to `TEST_EMAIL_PROVIDER_ID`.
+   *
+   * Needed only when an app has more than one fixed-code account, because
+   * `@convex-dev/auth` mints a provider's code without knowing the address,
+   * so each account needs a provider, and so an id, of its own. Must start
+   * with `TEST_EMAIL_PROVIDER_ID`, which keeps it clear of the customer
+   * `email` provider whose `authorize` it must never share.
+   */
+  id?: string;
+}
+
+/** Build the fixed-code provider separately so its security boundary is testable. */
+export function createTestEmailOtp(config: SupaAuthTestEmailConfig) {
+  const email = config.email.trim().toLowerCase();
+  const code = config.code ?? DEFAULT_TEST_CODE;
+  const id = config.id ?? TEST_EMAIL_PROVIDER_ID;
+  if (!/^test-email(-[a-z0-9]+)*$/.test(id)) {
+    throw new Error(`testEmail.id must be "${TEST_EMAIL_PROVIDER_ID}" or start with "${TEST_EMAIL_PROVIDER_ID}-"`);
+  }
+  if (!/^\d{6}$/.test(code)) {
+    throw new Error("testEmail.code must be exactly six digits");
+  }
+  if (email.length === 0) {
+    throw new Error("testEmail.email must not be empty");
+  }
+
+  const provider = Email({
+    maxAge: 10 * 60,
+    generateVerificationToken: () => code,
+    sendVerificationRequest: async ({ identifier }) => {
+      if (identifier.trim().toLowerCase() !== email) {
+        throw new Error("This test sign-in provider is not available for that email.");
+      }
+    },
+  });
+  return {
+    ...provider,
+    id,
+    authorize: async (params: Record<string, unknown>, account: { providerAccountId: string }) => {
+      if (
+        typeof params.email !== "string" ||
+        params.email.trim().toLowerCase() !== email ||
+        account.providerAccountId.trim().toLowerCase() !== email
+      ) {
+        throw new Error("This test sign-in provider is not available for that email.");
+      }
+    },
+  };
+}
+
+/** One fixed-code provider per configured account, refusing a repeated id or address. */
+export function createTestEmailOtps(
+  config: SupaAuthTestEmailConfig | SupaAuthTestEmailConfig[] | undefined,
+) {
+  const configs = config === undefined ? [] : Array.isArray(config) ? config : [config];
+  const providers = configs.map(createTestEmailOtp);
+  const ids = new Set(providers.map((provider) => provider.id));
+  const emails = new Set(configs.map((entry) => entry.email.trim().toLowerCase()));
+  if (ids.size !== providers.length) {
+    throw new Error("testEmail entries must each have their own id");
+  }
+  if (emails.size !== configs.length) {
+    throw new Error("testEmail entries must each have their own email");
+  }
+  return providers;
+}

package/src/auth/users.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+import type { GenericId } from "convex/values";
+import type { convexAuth } from "@convex-dev/auth/server";
+
+import { assertMayCreateUser, type SupaAuthAdmission } from "./admission";
+
+type Handler = NonNullable<
+  NonNullable<Parameters<typeof convexAuth>[0]["callbacks"]>["createOrUpdateUser"]
+>;
+
+export function userCallback(admission: SupaAuthAdmission | undefined): 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;
+      },
+    );
+    return userId as GenericId<"users">;
+  }
+
+  return createOrUpdateUser;
+}