@robelest/convex-auth 0.0.3-preview → 0.0.3-preview.3

package/src/server/implementation/passkey.ts

@@ -11,7 +11,6 @@
  * `@oslojs/crypto` for signature verification.
  */
 
-import { GenericId } from "convex/values";
 import {
   parseAttestationObject,
   parseClientDataJSON,
@@ -22,9 +21,7 @@ import {
   coseAlgorithmRS256,
   COSEKeyType,
 } from "@oslojs/webauthn";
-import type { AuthenticatorData } from "@oslojs/webauthn";
 import {
-  ECDSAPublicKey,
   p256,
   verifyECDSASignature,
   decodeSEC1PublicKey,
@@ -44,10 +41,22 @@ import {
   PasskeyProviderConfig,
   GenericActionCtxWithAuthConfig,
 } from "../types.js";
-import { AuthDataModel, SessionInfo } from "./types.js";
+import {
+  AuthDataModel,
+  SessionInfo,
+  queryUserById,
+  queryUserByVerifiedEmail,
+  queryPasskeysByUserId,
+  queryPasskeyByCredentialId,
+  queryVerifierById,
+  mutatePasskeyInsert,
+  mutatePasskeyUpdateCounter,
+  mutateVerifierDelete,
+} from "./types.js";
 import { callSignIn, callVerifier } from "./mutations/index.js";
-import { callVerifierSignature } from "./mutations/verifierSignature.js";
+import { callVerifierSignature } from "./mutations/signature.js";
 import { authDb } from "./db.js";
+import { throwAuthError } from "../errors.js";
 
 
 type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
@@ -64,7 +73,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 +134,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("|");
 
@@ -143,25 +150,16 @@ async function handleRegisterOptions(
   });
 
   // Get the user's profile for credential metadata
-  const user = await ctx.runQuery(
-    ctx.auth.config.component.public.userGetById,
-    { userId: userId! },
-  );
-  const userName = params.userName ?? (user as any)?.email ?? "user";
-  const userDisplayName = params.userDisplayName ?? (user as any)?.name ?? userName;
+  const user = await queryUserById(ctx, userId!);
+  const userName = params.userName ?? user?.email ?? "user";
+  const userDisplayName = params.userDisplayName ?? user?.name ?? userName;
 
   // Collect existing credentials to prevent re-registration
-  let excludeCredentials: Array<{ id: string; transports?: string[] }> = [];
-  const existing = await ctx.runQuery(
-    ctx.auth.config.component.public.passkeyListByUserId,
-    { userId: userId! },
-  );
-  if (existing) {
-    excludeCredentials = (existing as any[]).map((pk: any) => ({
-      id: pk.credentialId,
-      transports: pk.transports,
-    }));
-  }
+  const existing = await queryPasskeysByUserId(ctx, userId!);
+  const excludeCredentials = existing.map((pk) => ({
+    id: pk.credentialId,
+    transports: pk.transports,
+  }));
 
   // User handle is derived from the Convex userId
   const userHandle = encodeBase64urlNoPadding(
@@ -215,17 +213,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 +229,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(", ")}`,
     );
   }
@@ -249,19 +245,13 @@ async function handleRegisterVerify(
   const challengeHash = encodeBase64urlNoPadding(
     new Uint8Array(sha256(clientData.challenge)),
   );
-  const verifierDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.verifierGetById,
-    { verifierId: verifierValue },
-  );
-  if (!verifierDoc || (verifierDoc as any).signature !== challengeHash) {
-    throw new Error("Invalid or expired challenge");
+  const verifierDoc = await queryVerifierById(ctx, verifierValue);
+  if (!verifierDoc || verifierDoc.signature !== challengeHash) {
+    throwAuthError("PASSKEY_INVALID_CHALLENGE");
   }
 
   // Clean up the verifier
-  await ctx.runMutation(
-    ctx.auth.config.component.public.verifierDelete,
-    { verifierId: verifierValue },
-  );
+  await mutateVerifierDelete(ctx, verifierValue);
 
   // Parse attestation object
   const attestationObjectBytes = decodeBase64urlIgnorePadding(params.attestationObject);
@@ -270,21 +260,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 +310,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";
@@ -337,24 +327,21 @@ async function handleRegisterVerify(
   });
 
   // Store the passkey credential
-  await ctx.runMutation(
-    ctx.auth.config.component.public.passkeyInsert,
-    {
-      userId: userId!,
-      credentialId,
-      publicKey: publicKeyBytes.buffer.slice(
-        publicKeyBytes.byteOffset,
-        publicKeyBytes.byteOffset + publicKeyBytes.byteLength,
-      ),
-      algorithm,
-      counter: authenticatorData.signatureCounter,
-      transports: params.transports,
-      deviceType,
-      backedUp,
-      name: params.passkeyName,
-      createdAt: Date.now(),
-    },
-  );
+  await mutatePasskeyInsert(ctx, {
+    userId: userId!,
+    credentialId,
+    publicKey: publicKeyBytes.buffer.slice(
+      publicKeyBytes.byteOffset,
+      publicKeyBytes.byteOffset + publicKeyBytes.byteLength,
+    ),
+    algorithm,
+    counter: authenticatorData.signatureCounter,
+    transports: params.transports,
+    deviceType,
+    backedUp,
+    name: params.passkeyName,
+    createdAt: Date.now(),
+  });
 
   // Return tokens for the existing session
   const signInResult = await callSignIn(ctx, {
@@ -399,17 +386,11 @@ async function handleAuthOptions(
   let allowCredentials: Array<{ type: string; id: string; transports?: string[] }> | undefined;
   if (params.email) {
     // Look up user by email, then find their passkeys
-    const user = await ctx.runQuery(
-      ctx.auth.config.component.public.userFindByVerifiedEmail,
-      { email: params.email },
-    );
+    const user = await queryUserByVerifiedEmail(ctx, params.email);
     if (user) {
-      const passkeys = await ctx.runQuery(
-        ctx.auth.config.component.public.passkeyListByUserId,
-        { userId: (user as any)._id },
-      );
-      if (passkeys && (passkeys as any[]).length > 0) {
-        allowCredentials = (passkeys as any[]).map((pk: any) => ({
+      const passkeys = await queryPasskeysByUserId(ctx, user._id);
+      if (passkeys.length > 0) {
+        allowCredentials = passkeys.map((pk) => ({
           type: "public-key",
           id: pk.credentialId,
           transports: pk.transports,
@@ -447,7 +428,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 +437,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(", ")}`,
     );
   }
@@ -471,34 +453,24 @@ async function handleAuthVerify(
   const challengeHash = encodeBase64urlNoPadding(
     new Uint8Array(sha256(clientData.challenge)),
   );
-  const verifierDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.verifierGetById,
-    { verifierId: verifierValue },
-  );
-  if (!verifierDoc || (verifierDoc as any).signature !== challengeHash) {
-    throw new Error("Invalid or expired challenge");
+  const verifierDoc = await queryVerifierById(ctx, verifierValue);
+  if (!verifierDoc || verifierDoc.signature !== challengeHash) {
+    throwAuthError("PASSKEY_INVALID_CHALLENGE");
   }
 
   // Clean up the verifier
-  await ctx.runMutation(
-    ctx.auth.config.component.public.verifierDelete,
-    { verifierId: verifierValue },
-  );
+  await mutateVerifierDelete(ctx, verifierValue);
 
   // 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(
-    ctx.auth.config.component.public.passkeyGetByCredentialId,
-    { credentialId },
-  );
-  if (!passkeyDoc) {
-    throw new Error("Unknown credential");
+  const passkey = await queryPasskeyByCredentialId(ctx, credentialId);
+  if (!passkey) {
+    throwAuthError("PASSKEY_UNKNOWN_CREDENTIAL", "Unknown credential");
   }
-  const passkey = passkeyDoc as any;
 
   // Parse authenticator data
   const authenticatorDataBytes = decodeBase64urlIgnorePadding(params.authenticatorData);
@@ -506,15 +478,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 +510,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 +524,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,19 +537,15 @@ 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
-  await ctx.runMutation(
-    ctx.auth.config.component.public.passkeyUpdateCounter,
-    {
-      passkeyId: passkey._id,
-      counter: authenticatorData.signatureCounter,
-      lastUsedAt: Date.now(),
-    },
+  await mutatePasskeyUpdateCounter(
+    ctx,
+    passkey._id,
+    authenticatorData.signatureCounter,
+    Date.now(),
   );
 
   // Sign in the user
@@ -611,7 +579,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 +595,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 → refresh.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/sessions.ts

@@ -14,7 +14,7 @@ import {
   createRefreshToken,
   formatRefreshToken,
   deleteAllRefreshTokens,
-} from "./refreshTokens.js";
+} from "./refresh.js";
 import { authDb } from "./db.js";
 
 const DEFAULT_SESSION_TOTAL_DURATION_MS = 1000 * 60 * 60 * 24 * 30; // 30 days

package/src/server/implementation/{signIn.ts → signin.ts}

@@ -4,9 +4,7 @@ import {
   ConvexCredentialsConfig,
   EmailConfig,
   GenericActionCtxWithAuthConfig,
-  PasskeyProviderConfig,
   PhoneConfig,
-  TotpProviderConfig,
 } from "../types.js";
 import {
   AuthDataModel,
@@ -28,6 +26,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
 
@@ -63,9 +62,12 @@ export async function signInImpl(
   | { kind: "totpSetup"; uri: string; secret: string; verifier: string; totpId: string }
 > {
   if (provider === null && args.refreshToken) {
-    const tokens: Tokens = (await callRefreshSession(ctx, {
+    const tokens = await callRefreshSession(ctx, {
       refreshToken: args.refreshToken,
-    }))!;
+    });
+    if (tokens === null) {
+      return { kind: "signedIn", signedIn: null };
+    }
     return { kind: "refreshTokens", signedIn: { tokens } };
   }
   if (provider === null && args.params?.code !== undefined) {
@@ -82,9 +84,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 +102,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 +131,7 @@ async function handleEmailAndPhoneProvider(
       allowExtraProviders: options.allowExtraProviders,
     });
     if (result === null) {
-      throw new Error("Could not verify code");
+      throwAuthError("INVALID_VERIFICATION_CODE");
     }
     return {
       kind: "signedIn",
@@ -206,7 +207,7 @@ async function handleCredentials(
   const hasTotpEnrolled = await checkTotpRequired(ctx, result.userId);
   if (hasTotpEnrolled) {
     // Create session but withhold tokens — TOTP verification needed
-    const idsWithoutTokens = await callSignIn(ctx, {
+    await callSignIn(ctx, {
       userId: result.userId,
       sessionId: result.sessionId,
       generateTokens: false,
@@ -271,7 +272,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}`,
       );
     }