@robelest/convex-auth 0.0.2 → 0.0.3-preview.1

package/src/server/implementation/passkey.ts

@@ -48,6 +48,7 @@ import { AuthDataModel, SessionInfo } from "./types.js";
 import { callSignIn, callVerifier } from "./mutations/index.js";
 import { callVerifierSignature } from "./mutations/verifierSignature.js";
 import { authDb } from "./db.js";
+import { throwAuthError } from "../errors.js";
 
 
 type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
@@ -64,7 +65,8 @@ function resolveRpOptions(provider: PasskeyProviderConfig) {
   // because the RP ID wouldn't match the page origin.
   const siteUrl = process.env.SITE_URL;
   if (!siteUrl && !provider.options.rpId) {
-    throw new Error(
+    throwAuthError(
+      "PASSKEY_MISSING_CONFIG",
       "Passkey provider requires SITE_URL env var (your frontend URL) " +
       "or explicit rpId / origin in the provider config. " +
       "CONVEX_SITE_URL cannot be used because WebAuthn RP ID must match the frontend domain.",
@@ -124,10 +126,7 @@ async function handleRegisterOptions(
   // Passkey registration requires an authenticated user
   const identity = await ctx.auth.getUserIdentity();
   if (identity === null) {
-    throw new Error(
-      "Passkey registration requires an authenticated user. " +
-      "Sign in first, then add a passkey to your account.",
-    );
+    throwAuthError("PASSKEY_AUTH_REQUIRED");
   }
   const [userId] = identity.subject.split("|");
 
@@ -215,17 +214,14 @@ async function handleRegisterVerify(
   // Passkey registration requires an authenticated user
   const identity = await ctx.auth.getUserIdentity();
   if (identity === null) {
-    throw new Error(
-      "Passkey registration requires an authenticated user. " +
-      "Sign in first, then add a passkey to your account.",
-    );
+    throwAuthError("PASSKEY_AUTH_REQUIRED");
   }
   const [userId] = identity.subject.split("|");
 
   const rp = resolveRpOptions(provider);
 
   if (!verifierValue) {
-    throw new Error("Missing verifier for passkey registration");
+    throwAuthError("PASSKEY_MISSING_VERIFIER");
   }
 
   // Decode client data
@@ -234,13 +230,14 @@ async function handleRegisterVerify(
 
   // Verify client data type is "webauthn.create"
   if (clientData.type !== ClientDataType.Create) {
-    throw new Error("Invalid client data type: expected webauthn.create");
+    throwAuthError("PASSKEY_INVALID_CLIENT_DATA", "Invalid client data type: expected webauthn.create");
   }
 
   // Verify origin
   const allowedOrigins = Array.isArray(rp.origin) ? rp.origin : [rp.origin];
   if (!allowedOrigins.includes(clientData.origin)) {
-    throw new Error(
+    throwAuthError(
+      "PASSKEY_INVALID_ORIGIN",
       `Invalid origin: ${clientData.origin}, expected one of: ${allowedOrigins.join(", ")}`,
     );
   }
@@ -254,7 +251,7 @@ async function handleRegisterVerify(
     { verifierId: verifierValue },
   );
   if (!verifierDoc || (verifierDoc as any).signature !== challengeHash) {
-    throw new Error("Invalid or expired challenge");
+    throwAuthError("PASSKEY_INVALID_CHALLENGE");
   }
 
   // Clean up the verifier
@@ -270,21 +267,21 @@ async function handleRegisterVerify(
 
   // Verify RP ID hash
   if (!authenticatorData.verifyRelyingPartyIdHash(rp.rpId)) {
-    throw new Error("Relying party ID mismatch");
+    throwAuthError("PASSKEY_RP_MISMATCH");
   }
 
   // Verify user presence and verification flags
   if (!authenticatorData.userPresent) {
-    throw new Error("User presence flag not set");
+    throwAuthError("PASSKEY_USER_PRESENCE");
   }
   if (rp.userVerification === "required" && !authenticatorData.userVerified) {
-    throw new Error("User verification required but not performed");
+    throwAuthError("PASSKEY_USER_VERIFICATION");
   }
 
   // Extract credential
   const credential = authenticatorData.credential;
   if (!credential) {
-    throw new Error("No credential in attestation");
+    throwAuthError("PASSKEY_NO_CREDENTIAL");
   }
 
   const credentialId = encodeBase64urlNoPadding(credential.id);
@@ -320,7 +317,7 @@ async function handleRegisterVerify(
     const rsaPubKey = new RSAPublicKey(rsa.n, rsa.e);
     publicKeyBytes = rsaPubKey.encodePKCS1();
   } else {
-    throw new Error(`Unsupported algorithm: ${algorithm}`);
+    throwAuthError("PASSKEY_UNSUPPORTED_ALGORITHM", `Unsupported algorithm: ${algorithm}`);
   }
 
   const deviceType = params.deviceType ?? "single-device";
@@ -447,7 +444,7 @@ async function handleAuthVerify(
   const rp = resolveRpOptions(provider);
 
   if (!verifierValue) {
-    throw new Error("Missing verifier for passkey authentication");
+    throwAuthError("PASSKEY_MISSING_VERIFIER");
   }
 
   // Decode client data
@@ -456,13 +453,14 @@ async function handleAuthVerify(
 
   // Verify client data type is "webauthn.get"
   if (clientData.type !== ClientDataType.Get) {
-    throw new Error("Invalid client data type: expected webauthn.get");
+    throwAuthError("PASSKEY_INVALID_CLIENT_DATA", "Invalid client data type: expected webauthn.get");
   }
 
   // Verify origin
   const allowedOrigins = Array.isArray(rp.origin) ? rp.origin : [rp.origin];
   if (!allowedOrigins.includes(clientData.origin)) {
-    throw new Error(
+    throwAuthError(
+      "PASSKEY_INVALID_ORIGIN",
       `Invalid origin: ${clientData.origin}, expected one of: ${allowedOrigins.join(", ")}`,
     );
   }
@@ -476,7 +474,7 @@ async function handleAuthVerify(
     { verifierId: verifierValue },
   );
   if (!verifierDoc || (verifierDoc as any).signature !== challengeHash) {
-    throw new Error("Invalid or expired challenge");
+    throwAuthError("PASSKEY_INVALID_CHALLENGE");
   }
 
   // Clean up the verifier
@@ -488,7 +486,7 @@ async function handleAuthVerify(
   // Look up the credential
   const credentialId = params.credentialId;
   if (!credentialId) {
-    throw new Error("Missing credential ID");
+    throwAuthError("PASSKEY_UNKNOWN_CREDENTIAL", "Missing credential ID");
   }
 
   const passkeyDoc = await ctx.runQuery(
@@ -496,7 +494,7 @@ async function handleAuthVerify(
     { credentialId },
   );
   if (!passkeyDoc) {
-    throw new Error("Unknown credential");
+    throwAuthError("PASSKEY_UNKNOWN_CREDENTIAL", "Unknown credential");
   }
   const passkey = passkeyDoc as any;
 
@@ -506,15 +504,15 @@ async function handleAuthVerify(
 
   // Verify RP ID hash
   if (!authenticatorData.verifyRelyingPartyIdHash(rp.rpId)) {
-    throw new Error("Relying party ID mismatch");
+    throwAuthError("PASSKEY_RP_MISMATCH");
   }
 
   // Verify user presence
   if (!authenticatorData.userPresent) {
-    throw new Error("User presence flag not set");
+    throwAuthError("PASSKEY_USER_PRESENCE");
   }
   if (rp.userVerification === "required" && !authenticatorData.userVerified) {
-    throw new Error("User verification required but not performed");
+    throwAuthError("PASSKEY_USER_VERIFICATION");
   }
 
   // Verify signature
@@ -538,7 +536,7 @@ async function handleAuthVerify(
       ecdsaSignature,
     );
     if (!valid) {
-      throw new Error("Invalid signature");
+      throwAuthError("PASSKEY_INVALID_SIGNATURE");
     }
   } else if (passkey.algorithm === coseAlgorithmRS256) {
     // RSA PKCS#1 v1.5 with SHA-256 verification
@@ -552,10 +550,10 @@ async function handleAuthVerify(
       signature,
     );
     if (!valid) {
-      throw new Error("Invalid signature");
+      throwAuthError("PASSKEY_INVALID_SIGNATURE");
     }
   } else {
-    throw new Error(`Unsupported algorithm: ${passkey.algorithm}`);
+    throwAuthError("PASSKEY_UNSUPPORTED_ALGORITHM", `Unsupported algorithm: ${passkey.algorithm}`);
   }
 
   // Verify counter (clone detection)
@@ -565,9 +563,7 @@ async function handleAuthVerify(
     authenticatorData.signatureCounter !== 0 &&
     authenticatorData.signatureCounter <= passkey.counter
   ) {
-    throw new Error(
-      "Authenticator counter did not increase — possible credential cloning detected",
-    );
+    throwAuthError("PASSKEY_COUNTER_ERROR");
   }
 
   // Update counter and last used timestamp
@@ -611,7 +607,8 @@ export async function handlePasskey(
 > {
   const flow = args.params?.flow;
   if (!flow) {
-    throw new Error(
+    throwAuthError(
+      "PASSKEY_MISSING_FLOW",
       "Missing `flow` parameter. Expected one of: register-options, register-verify, auth-options, auth-verify",
     );
   }
@@ -626,7 +623,8 @@ export async function handlePasskey(
     case "auth-verify":
       return handleAuthVerify(ctx, provider, args.params ?? {}, args.verifier);
     default:
-      throw new Error(
+      throwAuthError(
+        "PASSKEY_UNKNOWN_FLOW",
         `Unknown passkey flow: ${flow}. Expected one of: register-options, register-verify, auth-options, auth-verify`,
       );
   }

package/src/server/implementation/provider.ts

@@ -1,15 +1,14 @@
 import { AuthProviderMaterializedConfig } from "../types.js";
 import { ConvexAuthMaterializedConfig } from "../types.js";
+import { throwAuthError } from "../errors.js";
 
 export async function hash(provider: any, secret: string) {
   if (provider.type !== "credentials") {
-    throw new Error(`Provider ${provider.id} is not a credentials provider`);
+    throwAuthError("INVALID_CREDENTIALS_PROVIDER", `Provider ${provider.id} is not a credentials provider`, { provider: provider.id });
   }
   const hashSecretFn = provider.crypto?.hashSecret;
   if (hashSecretFn === undefined) {
-    throw new Error(
-      `Provider ${provider.id} does not have a \`crypto.hashSecret\` function`,
-    );
+    throwAuthError("MISSING_CRYPTO_FUNCTION", `Provider ${provider.id} does not have a \`crypto.hashSecret\` function`, { provider: provider.id });
   }
   return await hashSecretFn(secret);
 }
@@ -20,13 +19,11 @@ export async function verify(
   hash: string,
 ) {
   if (provider.type !== "credentials") {
-    throw new Error(`Provider ${provider.id} is not a credentials provider`);
+    throwAuthError("INVALID_CREDENTIALS_PROVIDER", `Provider ${provider.id} is not a credentials provider`, { provider: provider.id });
   }
   const verifySecretFn = provider.crypto?.verifySecret;
   if (verifySecretFn === undefined) {
-    throw new Error(
-      `Provider ${provider.id} does not have a \`crypto.verifySecret\` function`,
-    );
+    throwAuthError("MISSING_CRYPTO_FUNCTION", `Provider ${provider.id} does not have a \`crypto.verifySecret\` function`, { provider: provider.id });
   }
   return await verifySecretFn(secret, hash);
 }

package/src/server/implementation/redirects.ts

@@ -1,5 +1,6 @@
 import { ConvexAuthMaterializedConfig } from "../types.js";
 import { requireEnv } from "../utils.js";
+import { throwAuthError } from "../errors.js";
 
 export async function redirectAbsoluteUrl(
   config: ConvexAuthMaterializedConfig,
@@ -7,9 +8,7 @@ export async function redirectAbsoluteUrl(
 ) {
   if (params.redirectTo !== undefined) {
     if (typeof params.redirectTo !== "string") {
-      throw new Error(
-        `Expected \`redirectTo\` to be a string, got ${params.redirectTo as any}`,
-      );
+      throwAuthError("INVALID_REDIRECT", `Expected \`redirectTo\` to be a string, got ${params.redirectTo as any}`);
     }
     const redirectCallback =
       config.callbacks?.redirect ?? defaultRedirectCallback;

package/src/server/implementation/refreshTokens.ts

@@ -1,5 +1,6 @@
 import { GenericId } from "convex/values";
 import { ConvexAuthConfig } from "../types.js";
+import { throwAuthError } from "../errors.js";
 import { Doc, MutationCtx } from "./types.js";
 import {
   LOG_LEVELS,
@@ -47,7 +48,7 @@ export const parseRefreshToken = (
 } => {
   const [refreshTokenId, sessionId] = refreshToken.split(REFRESH_TOKEN_DIVIDER);
   if (!refreshTokenId || !sessionId) {
-    throw new Error(`Can't parse refresh token: ${maybeRedact(refreshToken)}`);
+    throwAuthError("INVALID_REFRESH_TOKEN", `Can't parse refresh token: ${maybeRedact(refreshToken)}`);
   }
   return {
     refreshTokenId: refreshTokenId as GenericId<"token">,

package/src/server/implementation/signIn.ts

@@ -28,6 +28,7 @@ import { OAuth2Config, OIDCConfig } from "@auth/core/providers/oauth.js";
 import { generateRandomString } from "./utils.js";
 import { handlePasskey } from "./passkey.js";
 import { handleTotp, checkTotpRequired } from "./totp.js";
+import { throwAuthError } from "../errors.js";
 
 const DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours
 
@@ -82,9 +83,7 @@ export async function signInImpl(
   }
 
   if (provider === null) {
-    throw new Error(
-      "Cannot sign in: Missing `provider`, `params.code` or `refreshToken`",
-    );
+    throwAuthError("SIGN_IN_MISSING_PARAMS");
   }
   if (provider.type === "email" || provider.type === "phone") {
     return handleEmailAndPhoneProvider(ctx, provider, args, options);
@@ -102,7 +101,8 @@ export async function signInImpl(
     return handleTotp(ctx, provider, args);
   }
   const _typecheck: never = provider;
-  throw new Error(
+  throwAuthError(
+    "UNSUPPORTED_PROVIDER_TYPE",
     `Provider type ${(provider as any).type} is not supported yet`,
   );
 }
@@ -130,7 +130,7 @@ async function handleEmailAndPhoneProvider(
       allowExtraProviders: options.allowExtraProviders,
     });
     if (result === null) {
-      throw new Error("Could not verify code");
+      throwAuthError("INVALID_VERIFICATION_CODE");
     }
     return {
       kind: "signedIn",
@@ -170,20 +170,10 @@ async function handleEmailAndPhoneProvider(
     await provider.sendVerificationRequest(
       {
         ...verificationArgs,
-        provider: {
-          ...provider,
-          from:
-            // Simplifies demo configuration of Resend
-            provider.from === "Auth.js <no-reply@authjs.dev>" &&
-            provider.id === "resend"
-              ? "My App <onboarding@resend.dev>"
-              : provider.from,
-        },
-        request: new Request("http://localhost"), // TODO: Document
+        provider,
+        request: new Request("http://localhost"),
         theme: ctx.auth.config.theme,
       },
-      // @ts-expect-error Figure out typing for email providers so they can
-      // access ctx.
       ctx,
     );
   } else if (provider.type === "phone") {
@@ -281,7 +271,8 @@ async function handleOAuthProvider(
   redirect.searchParams.set("code", verifier);
   if (args.params?.redirectTo !== undefined) {
     if (typeof args.params.redirectTo !== "string") {
-      throw new Error(
+      throwAuthError(
+        "INVALID_REDIRECT",
         `Expected \`redirectTo\` to be a string, got ${args.params.redirectTo}`,
       );
     }

package/src/server/implementation/totp.ts

@@ -25,6 +25,7 @@ import {
 import { AuthDataModel, SessionInfo } from "./types.js";
 import { callSignIn, callVerifier } from "./mutations/index.js";
 import { callVerifierSignature } from "./mutations/verifierSignature.js";
+import { throwAuthError } from "../errors.js";
 
 type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
 
@@ -53,10 +54,7 @@ async function handleSetup(
   // TOTP enrollment requires an authenticated user
   const identity = await ctx.auth.getUserIdentity();
   if (identity === null) {
-    throw new Error(
-      "TOTP enrollment requires an authenticated user. " +
-        "Sign in first, then add TOTP to your account.",
-    );
+    throwAuthError("TOTP_AUTH_REQUIRED");
   }
   const [userId] = identity.subject.split("|");
 
@@ -143,21 +141,18 @@ async function handleConfirm(
   // TOTP confirmation requires an authenticated user
   const identity = await ctx.auth.getUserIdentity();
   if (identity === null) {
-    throw new Error(
-      "TOTP confirmation requires an authenticated user. " +
-        "Sign in first, then confirm your TOTP enrollment.",
-    );
+    throwAuthError("TOTP_AUTH_REQUIRED");
   }
   const [userId] = identity.subject.split("|");
 
   if (!verifierValue) {
-    throw new Error("Missing verifier");
+    throwAuthError("TOTP_MISSING_VERIFIER");
   }
   if (!params.code) {
-    throw new Error("Missing `code` parameter");
+    throwAuthError("TOTP_MISSING_CODE");
   }
   if (!params.totpId) {
-    throw new Error("Missing `totpId` parameter");
+    throwAuthError("TOTP_MISSING_ID");
   }
 
   // Look up the TOTP record
@@ -166,10 +161,10 @@ async function handleConfirm(
     { totpId: params.totpId },
   );
   if (!totpDoc) {
-    throw new Error("TOTP enrollment not found");
+    throwAuthError("TOTP_NOT_FOUND");
   }
   if ((totpDoc as any).verified) {
-    throw new Error("TOTP enrollment is already verified");
+    throwAuthError("TOTP_ALREADY_VERIFIED");
   }
 
   // Extract the secret from the TOTP record
@@ -184,7 +179,7 @@ async function handleConfirm(
     30,
   );
   if (!valid) {
-    throw new Error("Invalid TOTP code");
+    throwAuthError("TOTP_INVALID_CODE");
   }
 
   // Mark the enrollment as verified
@@ -225,10 +220,10 @@ async function handleVerify(
   verifierValue: string | undefined,
 ): Promise<{ kind: "signedIn"; signedIn: SessionInfo | null }> {
   if (!verifierValue) {
-    throw new Error("Missing verifier");
+    throwAuthError("TOTP_MISSING_VERIFIER");
   }
   if (!params.code) {
-    throw new Error("Missing `code` parameter");
+    throwAuthError("TOTP_MISSING_CODE");
   }
 
   // Look up the verifier to retrieve the stored userId
@@ -237,7 +232,7 @@ async function handleVerify(
     { verifierId: verifierValue },
   );
   if (!verifierDoc) {
-    throw new Error("Invalid or expired verifier");
+    throwAuthError("TOTP_INVALID_VERIFIER");
   }
 
   // Parse the signature to extract userId
@@ -250,7 +245,7 @@ async function handleVerify(
     { userId: userId as any },
   );
   if (!totpDoc) {
-    throw new Error("No TOTP enrollment found");
+    throwAuthError("TOTP_NO_ENROLLMENT");
   }
 
   // Extract the secret from the TOTP record
@@ -265,7 +260,7 @@ async function handleVerify(
     30,
   );
   if (!valid) {
-    throw new Error("Invalid TOTP code");
+    throwAuthError("TOTP_INVALID_CODE");
   }
 
   // Update last used timestamp
@@ -317,7 +312,8 @@ export async function handleTotp(
 > {
   const flow = args.params?.flow;
   if (!flow) {
-    throw new Error(
+    throwAuthError(
+      "TOTP_MISSING_FLOW",
       "Missing `flow` parameter. Expected one of: setup, confirm, verify",
     );
   }
@@ -340,7 +336,8 @@ export async function handleTotp(
         args.verifier,
       );
     default:
-      throw new Error(
+      throwAuthError(
+        "TOTP_UNKNOWN_FLOW",
         `Unknown TOTP flow: ${flow}. Expected one of: setup, confirm, verify`,
       );
   }

package/src/server/implementation/users.ts

@@ -3,6 +3,7 @@ import { Doc, MutationCtx } from "./types.js";
 import { AuthProviderMaterializedConfig, ConvexAuthConfig } from "../types.js";
 import { LOG_LEVELS, logWithLevel } from "./utils.js";
 import { authDb } from "./db.js";
+import { throwAuthError } from "../errors.js";
 
 type CreateOrUpdateUserArgs = {
   type: "oauth" | "credentials" | "email" | "phone" | "verification";
@@ -137,12 +138,10 @@ async function defaultCreateOrUpdateUser(
     try {
       await db.users.patch(userId, userData);
     } catch (error) {
-      throw new Error(
-        `Could not update user document with ID \`${userId}\`, ` +
+      throwAuthError("USER_UPDATE_FAILED", `Could not update user document with ID \`${userId}\`, ` +
           `either the user has been deleted but their account has not, ` +
           `or the profile data doesn't match the \`users\` table schema: ` +
-          `${(error as Error).message}`,
-      );
+          `${(error as Error).message}`);
     }
   } else {
     userId = (await db.users.insert(userData)) as GenericId<"user">;
@@ -231,9 +230,7 @@ export async function getAccountOrThrow(
 ) {
   const existingAccount = await authDb(ctx, config).accounts.getById(existingAccountId);
   if (existingAccount === null) {
-    throw new Error(
-      `Expected an account to exist for ID "${existingAccountId}"`,
-    );
+    throwAuthError("ACCOUNT_NOT_FOUND", `Expected an account to exist for ID "${existingAccountId}"`);
   }
   return existingAccount;
 }