@supa-media/convex 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-media/convex",
-  "version": "1.2.1",
+  "version": "1.4.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,8 +1,13 @@
-export { createSupaAuth, MAGIC_LINK_PROVIDER_ID } from "./setup";
+export {
+  createSupaAuth,
+  MAGIC_LINK_PROVIDER_ID,
+  TEST_EMAIL_PROVIDER_ID,
+} from "./setup";
 export type {
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
   SupaAuthResendConfig,
+  SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
 } from "./setup";
 export {

package/src/auth/setup.ts

@@ -27,6 +27,15 @@ import { Email } from "@convex-dev/auth/providers/Email";
 import { Phone } from "@convex-dev/auth/providers/Phone";
 import type { GenericId } from "convex/values";
 
+import { createTestEmailOtps, type SupaAuthTestEmailConfig } from "./testEmail";
+
+export {
+  createTestEmailOtp,
+  createTestEmailOtps,
+  TEST_EMAIL_PROVIDER_ID,
+  type SupaAuthTestEmailConfig,
+} from "./testEmail";
+
 export interface SupaAuthResendConfig {
   /** The "from" address for OTP emails. */
   fromAddress: string;
@@ -100,6 +109,14 @@ export interface SupaAuthConfig {
    * `MAGIC_LINK_PROVIDER_ID` for what it does and does not change.
    */
   magicLink?: SupaAuthMagicLinkConfig;
+  /**
+   * 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 | SupaAuthTestEmailConfig[];
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -407,6 +424,7 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
     ...(methods.includes("email") && config.magicLink !== undefined
       ? [createMagicLink(config)]
       : []),
+    ...(methods.includes("email") ? createTestEmailOtps(config.testEmail) : []),
     ...(methods.includes("phone") ? [createPhoneOtp(config)] : []),
   ];
 

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/index.ts

@@ -9,6 +9,7 @@
 export {
   createSupaAuth,
   MAGIC_LINK_PROVIDER_ID,
+  TEST_EMAIL_PROVIDER_ID,
   requireAuth,
   requireAuthId,
   getOptionalAuth,
@@ -18,6 +19,7 @@ export type {
   SupaAuthConfig,
   SupaAuthMagicLinkConfig,
   SupaAuthResendConfig,
+  SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
 } from "./auth";