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

package/src/server/implementation/totp.ts

@@ -11,9 +11,7 @@
  * `@oslojs/encoding` for base-32 secret encoding.
  */
 
-import { GenericId } from "convex/values";
 import {
-  generateTOTP,
   verifyTOTPWithGracePeriod,
   createTOTPKeyURI,
 } from "@oslojs/otp";
@@ -22,9 +20,21 @@ import {
   TotpProviderConfig,
   GenericActionCtxWithAuthConfig,
 } from "../types.js";
-import { AuthDataModel, SessionInfo } from "./types.js";
+import {
+  AuthDataModel,
+  SessionInfo,
+  queryUserById,
+  queryTotpById,
+  queryTotpVerifiedByUserId,
+  queryVerifierById,
+  mutateTotpInsert,
+  mutateTotpMarkVerified,
+  mutateTotpUpdateLastUsed,
+  mutateVerifierDelete,
+} from "./types.js";
 import { callSignIn, callVerifier } from "./mutations/index.js";
-import { callVerifierSignature } from "./mutations/verifierSignature.js";
+import { callVerifierSignature } from "./mutations/signature.js";
+import { throwAuthError } from "../errors.js";
 
 type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
 
@@ -53,10 +63,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("|");
 
@@ -67,11 +74,8 @@ async function handleSetup(
   // Resolve the account name for the otpauth:// URI
   let accountName: string = params.accountName as string;
   if (!accountName) {
-    const user = await ctx.runQuery(
-      ctx.auth.config.component.public.userGetById,
-      { userId: userId! },
-    );
-    accountName = (user as any)?.email ?? "user";
+    const user = await queryUserById(ctx, userId!);
+    accountName = user?.email ?? "user";
   }
 
   // Build the otpauth:// URI for QR code scanning
@@ -99,28 +103,25 @@ async function handleSetup(
   });
 
   // Insert an UNVERIFIED TOTP record in the DB
-  const totpId = await ctx.runMutation(
-    ctx.auth.config.component.public.totpInsert,
-    {
-      userId: userId as any,
-      secret: secret.buffer.slice(
-        secret.byteOffset,
-        secret.byteOffset + secret.byteLength,
-      ),
-      digits: provider.options.digits,
-      period: provider.options.period,
-      verified: false,
-      name: params.name,
-      createdAt: Date.now(),
-    },
-  );
+  const totpId = await mutateTotpInsert(ctx, {
+    userId: userId!,
+    secret: secret.buffer.slice(
+      secret.byteOffset,
+      secret.byteOffset + secret.byteLength,
+    ),
+    digits: provider.options.digits,
+    period: provider.options.period,
+    verified: false,
+    name: params.name,
+    createdAt: Date.now(),
+  });
 
   return {
     kind: "totpSetup" as const,
     uri,
     secret: base32Secret,
     verifier,
-    totpId: totpId as string,
+    totpId,
   };
 }
 
@@ -143,37 +144,31 @@ 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
-  const totpDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.totpGetById,
-    { totpId: params.totpId },
-  );
+  const totpDoc = await queryTotpById(ctx, 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");
+  if (totpDoc.verified) {
+    throwAuthError("TOTP_ALREADY_VERIFIED");
   }
 
   // Extract the secret from the TOTP record
-  const secret = new Uint8Array((totpDoc as any).secret);
+  const secret = new Uint8Array(totpDoc.secret);
 
   // Verify the code with a 30-second grace period
   const valid = verifyTOTPWithGracePeriod(
@@ -184,20 +179,14 @@ async function handleConfirm(
     30,
   );
   if (!valid) {
-    throw new Error("Invalid TOTP code");
+    throwAuthError("TOTP_INVALID_CODE");
   }
 
   // Mark the enrollment as verified
-  await ctx.runMutation(
-    ctx.auth.config.component.public.totpMarkVerified,
-    { totpId: params.totpId as any, lastUsedAt: Date.now() },
-  );
+  await mutateTotpMarkVerified(ctx, params.totpId, Date.now());
 
   // Clean up the verifier
-  await ctx.runMutation(
-    ctx.auth.config.component.public.verifierDelete,
-    { verifierId: verifierValue },
-  );
+  await mutateVerifierDelete(ctx, verifierValue);
 
   // Return tokens for the existing session
   const signInResult = await callSignIn(ctx, {
@@ -225,60 +214,48 @@ 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
-  const verifierDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.verifierGetById,
-    { verifierId: verifierValue },
-  );
+  const verifierDoc = await queryVerifierById(ctx, verifierValue);
   if (!verifierDoc) {
-    throw new Error("Invalid or expired verifier");
+    throwAuthError("TOTP_INVALID_VERIFIER");
   }
 
   // Parse the signature to extract userId
-  const signatureData = JSON.parse((verifierDoc as any).signature);
+  const signatureData = JSON.parse(verifierDoc.signature!);
   const userId = signatureData.userId as string;
 
   // Look up the user's verified TOTP enrollment
-  const totpDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.totpGetVerifiedByUserId,
-    { userId: userId as any },
-  );
+  const totpDoc = await queryTotpVerifiedByUserId(ctx, userId);
   if (!totpDoc) {
-    throw new Error("No TOTP enrollment found");
+    throwAuthError("TOTP_NO_ENROLLMENT");
   }
 
   // Extract the secret from the TOTP record
-  const secret = new Uint8Array((totpDoc as any).secret);
+  const secret = new Uint8Array(totpDoc.secret);
 
   // Verify the code with a 30-second grace period
   const valid = verifyTOTPWithGracePeriod(
     secret,
-    (totpDoc as any).period,
-    (totpDoc as any).digits,
+    totpDoc.period,
+    totpDoc.digits,
     params.code,
     30,
   );
   if (!valid) {
-    throw new Error("Invalid TOTP code");
+    throwAuthError("TOTP_INVALID_CODE");
   }
 
   // Update last used timestamp
-  await ctx.runMutation(
-    ctx.auth.config.component.public.totpUpdateLastUsed,
-    { totpId: (totpDoc as any)._id, lastUsedAt: Date.now() },
-  );
+  await mutateTotpUpdateLastUsed(ctx, totpDoc._id, Date.now());
 
   // Clean up the verifier
-  await ctx.runMutation(
-    ctx.auth.config.component.public.verifierDelete,
-    { verifierId: verifierValue },
-  );
+  await mutateVerifierDelete(ctx, verifierValue);
 
   // Sign in the user with tokens
   const signInResult = await callSignIn(ctx, {
@@ -317,7 +294,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 +318,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`,
       );
   }
@@ -358,9 +337,6 @@ export async function checkTotpRequired(
   ctx: EnrichedActionCtx,
   userId: string,
 ): Promise<boolean> {
-  const totpDoc = await ctx.runQuery(
-    ctx.auth.config.component.public.totpGetVerifiedByUserId,
-    { userId: userId as any },
-  );
+  const totpDoc = await queryTotpVerifiedByUserId(ctx, userId);
   return totpDoc !== null;
 }

package/src/server/implementation/types.ts

@@ -6,8 +6,9 @@ import {
   TableNamesInDataModel,
 } from "convex/server";
 import { GenericId } from "convex/values";
-import { GenericDoc } from "../convex_types.js";
+import { GenericDoc } from "../types.js";
 import schema from "../../component/schema.js";
+import { AuthComponentApi } from "../types.js";
 
 /** Data model derived from the component schema. */
 export type AuthDataModel = DataModelFromSchemaDefinition<typeof schema>;
@@ -43,3 +44,317 @@ export type SessionInfoWithTokens = {
   sessionId: GenericId<"session">;
   tokens: Tokens;
 };
+
+// ---------------------------------------------------------------------------
+// Cross-component document shapes
+// ---------------------------------------------------------------------------
+// These mirror the component schema tables. They exist so that server-side
+// code can work with typed results from cross-component queries/mutations
+// instead of casting to `any` at every field access.
+
+export interface TotpDoc {
+  _id: string;
+  _creationTime: number;
+  userId: string;
+  secret: ArrayBuffer;
+  digits: number;
+  period: number;
+  verified: boolean;
+  name?: string;
+  createdAt: number;
+  lastUsedAt?: number;
+}
+
+export interface PasskeyDoc {
+  _id: string;
+  _creationTime: number;
+  userId: string;
+  credentialId: string;
+  publicKey: ArrayBuffer;
+  algorithm: number;
+  counter: number;
+  transports?: string[];
+  deviceType: string;
+  backedUp: boolean;
+  name?: string;
+  createdAt: number;
+  lastUsedAt?: number;
+}
+
+export interface VerifierDoc {
+  _id: string;
+  _creationTime: number;
+  signature?: string;
+  sessionId?: string;
+}
+
+export interface UserDoc {
+  _id: string;
+  _creationTime: number;
+  email?: string;
+  emailVerificationTime?: number;
+  phone?: string;
+  phoneVerificationTime?: number;
+  name?: string;
+  image?: string;
+  isAnonymous?: boolean;
+}
+
+export interface KeyDoc {
+  _id: string;
+  _creationTime: number;
+  userId: string;
+  prefix: string;
+  hashedKey: string;
+  name: string;
+  scopes: Array<{ resource: string; actions: string[] }>;
+  rateLimit?: { maxRequests: number; windowMs: number };
+  rateLimitState?: { attemptsLeft: number; lastAttemptTime: number };
+  expiresAt?: number;
+  lastUsedAt?: number;
+  createdAt: number;
+  revoked: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Cross-component wrapper context
+// ---------------------------------------------------------------------------
+// Structural type accepted by all wrappers below.  Works for both action and
+// mutation contexts — the only capabilities we need are runQuery / runMutation
+// and access to the component API via `auth.config.component`.
+
+/** @internal */
+export type ComponentCallCtx = {
+  runQuery: GenericActionCtx<AuthDataModel>["runQuery"];
+  runMutation: GenericActionCtx<AuthDataModel>["runMutation"];
+  auth: { config: { component: AuthComponentApi } };
+};
+
+// ---------------------------------------------------------------------------
+// Typed wrappers for cross-component calls
+// ---------------------------------------------------------------------------
+// Each wrapper encapsulates the single `as any` cast at the component
+// boundary so that callers get full type safety on both args and return
+// values.
+
+// -- User queries --
+
+export async function queryUserById(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<UserDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.userGetById,
+    { userId },
+  )) as UserDoc | null;
+}
+
+export async function queryUserByVerifiedEmail(
+  ctx: ComponentCallCtx,
+  email: string,
+): Promise<UserDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.userFindByVerifiedEmail,
+    { email },
+  )) as UserDoc | null;
+}
+
+// -- Verifier queries / mutations --
+
+export async function queryVerifierById(
+  ctx: ComponentCallCtx,
+  verifierId: string,
+): Promise<VerifierDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.verifierGetById,
+    { verifierId },
+  )) as VerifierDoc | null;
+}
+
+export async function mutateVerifierDelete(
+  ctx: ComponentCallCtx,
+  verifierId: string,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.verifierDelete,
+    { verifierId },
+  );
+}
+
+// -- TOTP queries / mutations --
+
+export async function queryTotpById(
+  ctx: ComponentCallCtx,
+  totpId: string,
+): Promise<TotpDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.totpGetById,
+    { totpId },
+  )) as TotpDoc | null;
+}
+
+export async function queryTotpVerifiedByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<TotpDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.totpGetVerifiedByUserId,
+    { userId },
+  )) as TotpDoc | null;
+}
+
+export async function mutateTotpInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    secret: ArrayBuffer;
+    digits: number;
+    period: number;
+    verified: boolean;
+    name?: string;
+    createdAt: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.totpInsert,
+    args,
+  )) as string;
+}
+
+export async function mutateTotpMarkVerified(
+  ctx: ComponentCallCtx,
+  totpId: string,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.totpMarkVerified,
+    { totpId, lastUsedAt },
+  );
+}
+
+export async function mutateTotpUpdateLastUsed(
+  ctx: ComponentCallCtx,
+  totpId: string,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.totpUpdateLastUsed,
+    { totpId, lastUsedAt },
+  );
+}
+
+// -- Passkey queries / mutations --
+
+export async function queryPasskeysByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<PasskeyDoc[]> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.passkeyListByUserId,
+    { userId },
+  )) as PasskeyDoc[];
+}
+
+export async function queryPasskeyByCredentialId(
+  ctx: ComponentCallCtx,
+  credentialId: string,
+): Promise<PasskeyDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.passkeyGetByCredentialId,
+    { credentialId },
+  )) as PasskeyDoc | null;
+}
+
+export async function mutatePasskeyInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    credentialId: string;
+    publicKey: ArrayBuffer | ArrayBufferLike;
+    algorithm: number;
+    counter: number;
+    transports?: string[];
+    deviceType: string;
+    backedUp: boolean;
+    name?: string;
+    createdAt: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.passkeyInsert,
+    args,
+  )) as string;
+}
+
+export async function mutatePasskeyUpdateCounter(
+  ctx: ComponentCallCtx,
+  passkeyId: string,
+  counter: number,
+  lastUsedAt: number,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.passkeyUpdateCounter,
+    { passkeyId, counter, lastUsedAt },
+  );
+}
+
+// -- Key queries / mutations --
+
+export async function mutateKeyInsert(
+  ctx: ComponentCallCtx,
+  args: {
+    userId: string;
+    prefix: string;
+    hashedKey: string;
+    name: string;
+    scopes: Array<{ resource: string; actions: string[] }>;
+    rateLimit?: { maxRequests: number; windowMs: number };
+    expiresAt?: number;
+  },
+): Promise<string> {
+  return (await ctx.runMutation(
+    ctx.auth.config.component.public.keyInsert,
+    args,
+  )) as string;
+}
+
+export async function queryKeysByUserId(
+  ctx: ComponentCallCtx,
+  userId: string,
+): Promise<KeyDoc[]> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.keyListByUserId,
+    { userId },
+  )) as KeyDoc[];
+}
+
+export async function queryKeyById(
+  ctx: ComponentCallCtx,
+  keyId: string,
+): Promise<KeyDoc | null> {
+  return (await ctx.runQuery(
+    ctx.auth.config.component.public.keyGetById,
+    { keyId },
+  )) as KeyDoc | null;
+}
+
+export async function mutateKeyPatch(
+  ctx: ComponentCallCtx,
+  keyId: string,
+  data: Record<string, unknown>,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.keyPatch,
+    { keyId, data },
+  );
+}
+
+export async function mutateKeyDelete(
+  ctx: ComponentCallCtx,
+  keyId: string,
+): Promise<void> {
+  await ctx.runMutation(
+    ctx.auth.config.component.public.keyDelete,
+    { keyId },
+  );
+}

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;
 }