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

package/src/server/implementation/signIn.ts

@@ -4,7 +4,9 @@ import {
   ConvexCredentialsConfig,
   EmailConfig,
   GenericActionCtxWithAuthConfig,
+  PasskeyProviderConfig,
   PhoneConfig,
+  TotpProviderConfig,
 } from "../types.js";
 import {
   AuthDataModel,
@@ -17,12 +19,15 @@ import {
   callRefreshSession,
   callSignIn,
   callVerifier,
+  callVerifierSignature,
   callVerifyCodeAndSignIn,
 } from "./mutations/index.js";
 import { redirectAbsoluteUrl, setURLSearchParam } from "./redirects.js";
 import { requireEnv } from "../utils.js";
 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";
 
 const DEFAULT_EMAIL_VERIFICATION_CODE_DURATION_S = 60 * 60 * 24; // 24 hours
 
@@ -50,6 +55,12 @@ export async function signInImpl(
   | { kind: "started"; started: true }
   // OAuth2 and OIDC flows
   | { kind: "redirect"; redirect: string; verifier: string }
+  // Passkey options (challenge + credential options)
+  | { kind: "passkeyOptions"; options: Record<string, any>; verifier: string }
+  // TOTP 2FA required after credentials sign-in
+  | { kind: "totpRequired"; verifier: string }
+  // TOTP setup response (enrollment)
+  | { kind: "totpSetup"; uri: string; secret: string; verifier: string; totpId: string }
 > {
   if (provider === null && args.refreshToken) {
     const tokens: Tokens = (await callRefreshSession(ctx, {
@@ -84,6 +95,12 @@ export async function signInImpl(
   if (provider.type === "oauth" || provider.type === "oidc") {
     return handleOAuthProvider(ctx, provider, args, options);
   }
+  if (provider.type === "passkey") {
+    return handlePasskey(ctx, provider, args);
+  }
+  if (provider.type === "totp") {
+    return handleTotp(ctx, provider, args);
+  }
   const _typecheck: never = provider;
   throw new Error(
     `Provider type ${(provider as any).type} is not supported yet`,
@@ -153,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") {
@@ -187,11 +194,32 @@ async function handleCredentials(
   options: {
     generateTokens: boolean;
   },
-): Promise<{ kind: "signedIn"; signedIn: SessionInfo | null }> {
+): Promise<
+  | { kind: "signedIn"; signedIn: SessionInfo | null }
+  | { kind: "totpRequired"; verifier: string }
+> {
   const result = await provider.authorize(args.params ?? {}, ctx);
   if (result === null) {
     return { kind: "signedIn", signedIn: null };
   }
+  // Check if user has TOTP 2FA enrolled before issuing tokens
+  const hasTotpEnrolled = await checkTotpRequired(ctx, result.userId);
+  if (hasTotpEnrolled) {
+    // Create session but withhold tokens — TOTP verification needed
+    const idsWithoutTokens = await callSignIn(ctx, {
+      userId: result.userId,
+      sessionId: result.sessionId,
+      generateTokens: false,
+    });
+    // Store userId in verifier so the TOTP verify flow can complete sign-in
+    const verifier = await callVerifier(ctx);
+    await callVerifierSignature(ctx, {
+      verifier,
+      signature: JSON.stringify({ userId: result.userId }),
+    });
+    return { kind: "totpRequired", verifier };
+  }
+
   const idsAndTokens = await callSignIn(ctx, {
     userId: result.userId,
     sessionId: result.sessionId,

package/src/server/implementation/totp.ts

@@ -0,0 +1,366 @@
+/**
+ * Server-side TOTP ceremony logic for two-factor authentication.
+ *
+ * Handles the three phases of the TOTP flow:
+ * 1. setup   — generate a TOTP secret and `otpauth://` URI for enrollment
+ * 2. confirm — verify the first code from the authenticator app and mark
+ *              the enrollment as verified
+ * 3. verify  — verify a TOTP code during sign-in (2FA challenge)
+ *
+ * Uses `@oslojs/otp` for TOTP generation / verification and
+ * `@oslojs/encoding` for base-32 secret encoding.
+ */
+
+import { GenericId } from "convex/values";
+import {
+  generateTOTP,
+  verifyTOTPWithGracePeriod,
+  createTOTPKeyURI,
+} from "@oslojs/otp";
+import { encodeBase32LowerCaseNoPadding } from "@oslojs/encoding";
+import {
+  TotpProviderConfig,
+  GenericActionCtxWithAuthConfig,
+} from "../types.js";
+import { AuthDataModel, SessionInfo } from "./types.js";
+import { callSignIn, callVerifier } from "./mutations/index.js";
+import { callVerifierSignature } from "./mutations/verifierSignature.js";
+
+type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
+
+// ============================================================================
+// Setup flow
+// ============================================================================
+
+/**
+ * Phase 1: Generate a TOTP secret and enrollment URI.
+ *
+ * Requires an authenticated user — TOTP enrollment always adds a second
+ * factor to an existing account.  The userId is taken from the current
+ * session identity.
+ */
+async function handleSetup(
+  ctx: EnrichedActionCtx,
+  provider: TotpProviderConfig,
+  params: Record<string, any>,
+): Promise<{
+  kind: "totpSetup";
+  uri: string;
+  secret: string;
+  verifier: string;
+  totpId: string;
+}> {
+  // 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.",
+    );
+  }
+  const [userId] = identity.subject.split("|");
+
+  // Generate a 20-byte random secret (160 bits, per RFC 4226 recommendation)
+  const secret = new Uint8Array(20);
+  crypto.getRandomValues(secret);
+
+  // 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";
+  }
+
+  // Build the otpauth:// URI for QR code scanning
+  const uri = createTOTPKeyURI(
+    provider.options.issuer,
+    accountName,
+    secret,
+    provider.options.period,
+    provider.options.digits,
+  );
+
+  // Encode the secret as base-32 for manual entry
+  const base32Secret = encodeBase32LowerCaseNoPadding(secret);
+
+  // Store enrolment metadata in a verifier so we can correlate the confirm step
+  const verifier = await callVerifier(ctx);
+  await callVerifierSignature(ctx, {
+    verifier,
+    signature: JSON.stringify({
+      secret: Array.from(secret),
+      userId,
+      digits: provider.options.digits,
+      period: provider.options.period,
+    }),
+  });
+
+  // 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(),
+    },
+  );
+
+  return {
+    kind: "totpSetup" as const,
+    uri,
+    secret: base32Secret,
+    verifier,
+    totpId: totpId as string,
+  };
+}
+
+// ============================================================================
+// Confirm flow
+// ============================================================================
+
+/**
+ * Phase 2: Verify the first code from the authenticator app.
+ *
+ * Requires an authenticated user.  Marks the TOTP enrollment as verified
+ * after confirming the code is correct.
+ */
+async function handleConfirm(
+  ctx: EnrichedActionCtx,
+  provider: TotpProviderConfig,
+  params: Record<string, any>,
+  verifierValue: string | undefined,
+): Promise<{ kind: "signedIn"; signedIn: SessionInfo | null }> {
+  // 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.",
+    );
+  }
+  const [userId] = identity.subject.split("|");
+
+  if (!verifierValue) {
+    throw new Error("Missing verifier");
+  }
+  if (!params.code) {
+    throw new Error("Missing `code` parameter");
+  }
+  if (!params.totpId) {
+    throw new Error("Missing `totpId` parameter");
+  }
+
+  // Look up the TOTP record
+  const totpDoc = await ctx.runQuery(
+    ctx.auth.config.component.public.totpGetById,
+    { totpId: params.totpId },
+  );
+  if (!totpDoc) {
+    throw new Error("TOTP enrollment not found");
+  }
+  if ((totpDoc as any).verified) {
+    throw new Error("TOTP enrollment is already verified");
+  }
+
+  // Extract the secret from the TOTP record
+  const secret = new Uint8Array((totpDoc as any).secret);
+
+  // Verify the code with a 30-second grace period
+  const valid = verifyTOTPWithGracePeriod(
+    secret,
+    provider.options.period,
+    provider.options.digits,
+    params.code,
+    30,
+  );
+  if (!valid) {
+    throw new Error("Invalid TOTP code");
+  }
+
+  // Mark the enrollment as verified
+  await ctx.runMutation(
+    ctx.auth.config.component.public.totpMarkVerified,
+    { totpId: params.totpId as any, lastUsedAt: Date.now() },
+  );
+
+  // Clean up the verifier
+  await ctx.runMutation(
+    ctx.auth.config.component.public.verifierDelete,
+    { verifierId: verifierValue },
+  );
+
+  // Return tokens for the existing session
+  const signInResult = await callSignIn(ctx, {
+    userId: userId!,
+    generateTokens: true,
+  });
+
+  return { kind: "signedIn", signedIn: signInResult };
+}
+
+// ============================================================================
+// Verify flow (2FA during sign-in)
+// ============================================================================
+
+/**
+ * Phase 3: Verify a TOTP code during sign-in.
+ *
+ * Does NOT require an authenticated user — this runs mid-sign-in as a
+ * second-factor challenge.  The userId is retrieved from the stored verifier.
+ */
+async function handleVerify(
+  ctx: EnrichedActionCtx,
+  provider: TotpProviderConfig,
+  params: Record<string, any>,
+  verifierValue: string | undefined,
+): Promise<{ kind: "signedIn"; signedIn: SessionInfo | null }> {
+  if (!verifierValue) {
+    throw new Error("Missing verifier");
+  }
+  if (!params.code) {
+    throw new Error("Missing `code` parameter");
+  }
+
+  // Look up the verifier to retrieve the stored userId
+  const verifierDoc = await ctx.runQuery(
+    ctx.auth.config.component.public.verifierGetById,
+    { verifierId: verifierValue },
+  );
+  if (!verifierDoc) {
+    throw new Error("Invalid or expired verifier");
+  }
+
+  // Parse the signature to extract userId
+  const signatureData = JSON.parse((verifierDoc as any).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 },
+  );
+  if (!totpDoc) {
+    throw new Error("No TOTP enrollment found");
+  }
+
+  // Extract the secret from the TOTP record
+  const secret = new Uint8Array((totpDoc as any).secret);
+
+  // Verify the code with a 30-second grace period
+  const valid = verifyTOTPWithGracePeriod(
+    secret,
+    (totpDoc as any).period,
+    (totpDoc as any).digits,
+    params.code,
+    30,
+  );
+  if (!valid) {
+    throw new Error("Invalid TOTP code");
+  }
+
+  // Update last used timestamp
+  await ctx.runMutation(
+    ctx.auth.config.component.public.totpUpdateLastUsed,
+    { totpId: (totpDoc as any)._id, lastUsedAt: Date.now() },
+  );
+
+  // Clean up the verifier
+  await ctx.runMutation(
+    ctx.auth.config.component.public.verifierDelete,
+    { verifierId: verifierValue },
+  );
+
+  // Sign in the user with tokens
+  const signInResult = await callSignIn(ctx, {
+    userId,
+    generateTokens: true,
+  });
+
+  return { kind: "signedIn", signedIn: signInResult };
+}
+
+// ============================================================================
+// Main dispatch
+// ============================================================================
+
+/**
+ * Main TOTP handler dispatched from signIn.ts.
+ *
+ * Routes to the appropriate phase based on `params.flow`.
+ */
+export async function handleTotp(
+  ctx: EnrichedActionCtx,
+  provider: TotpProviderConfig,
+  args: {
+    params?: Record<string, any>;
+    verifier?: string;
+  },
+): Promise<
+  | { kind: "signedIn"; signedIn: SessionInfo | null }
+  | {
+      kind: "totpSetup";
+      uri: string;
+      secret: string;
+      verifier: string;
+      totpId: string;
+    }
+> {
+  const flow = args.params?.flow;
+  if (!flow) {
+    throw new Error(
+      "Missing `flow` parameter. Expected one of: setup, confirm, verify",
+    );
+  }
+
+  switch (flow) {
+    case "setup":
+      return handleSetup(ctx, provider, args.params ?? {});
+    case "confirm":
+      return handleConfirm(
+        ctx,
+        provider,
+        args.params ?? {},
+        args.verifier,
+      );
+    case "verify":
+      return handleVerify(
+        ctx,
+        provider,
+        args.params ?? {},
+        args.verifier,
+      );
+    default:
+      throw new Error(
+        `Unknown TOTP flow: ${flow}. Expected one of: setup, confirm, verify`,
+      );
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Check if a user has a verified TOTP enrollment.
+ * Called after credentials sign-in to determine if 2FA is needed.
+ */
+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 },
+  );
+  return totpDoc !== null;
+}

package/src/server/index.ts

@@ -17,6 +17,20 @@ export type AuthCookies = {
   verifier: string | null;
 };
 
+/** A structured cookie ready to be set via any framework's cookie API. */
+export type AuthCookie = {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge?: number;
+    expires?: Date;
+  };
+};
+
 export type ServerOptions = {
   /** Convex deployment URL. */
   url: string;
@@ -27,8 +41,12 @@ export type ServerOptions = {
 };
 
 export type RefreshResult = {
-  response?: Response;
-  cookies?: string[];
+  /** Structured cookies to set on the response. */
+  cookies: AuthCookie[];
+  /** URL to redirect to (set after OAuth code exchange). */
+  redirect?: string;
+  /** JWT for SSR hydration, or `null` if not authenticated. */
+  token: string | null;
 };
 
 export function authCookieNames(host?: string) {
@@ -86,6 +104,57 @@ export function serializeAuthCookies(
   ];
 }
 
+/**
+ * Build structured cookie objects for any SSR framework.
+ *
+ * Use with SvelteKit's `event.cookies.set()`, TanStack Start's `setCookie()`,
+ * Next.js's `cookies().set()`, or any other framework cookie API.
+ */
+export function structuredAuthCookies(
+  cookies: AuthCookies,
+  host?: string,
+  config: AuthCookieConfig = { maxAge: null },
+): AuthCookie[] {
+  const names = authCookieNames(host);
+  const secure = !isLocalHost(host);
+  const base = {
+    path: "/" as const,
+    httpOnly: true as const,
+    secure,
+    sameSite: "lax" as const,
+  };
+  const maxAge = config.maxAge ?? undefined;
+  return [
+    {
+      name: names.token,
+      value: cookies.token ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.token === null ? 0 : maxAge,
+        expires: cookies.token === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.refreshToken,
+      value: cookies.refreshToken ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.refreshToken === null ? 0 : maxAge,
+        expires: cookies.refreshToken === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.verifier,
+      value: cookies.verifier ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.verifier === null ? 0 : maxAge,
+        expires: cookies.verifier === null ? new Date(0) : undefined,
+      },
+    },
+  ];
+}
+
 export function shouldProxyAuthAction(pathname: string, apiRoute: string) {
   if (apiRoute.endsWith("/")) {
     return pathname === apiRoute || pathname === apiRoute.slice(0, -1);
@@ -348,21 +417,21 @@ export function server(options: ServerOptions) {
 
     async refresh(request: Request): Promise<RefreshResult> {
       const host = cookieHost(request);
+      const currentToken = parseRequestCookies(request).token;
 
+      // CORS request — clear all auth cookies.
       if (isCorsRequest(request)) {
         return {
-          cookies: serializeAuthCookies(
-            {
-              token: null,
-              refreshToken: null,
-              verifier: null,
-            },
+          cookies: structuredAuthCookies(
+            { token: null, refreshToken: null, verifier: null },
             host,
             cookieConfig,
           ),
+          token: null,
         };
       }
 
+      // OAuth code exchange — exchange code for tokens and redirect.
       const requestUrl = new URL(request.url);
       const code = requestUrl.searchParams.get("code");
       const shouldHandleCode =
@@ -392,47 +461,41 @@ export function server(options: ServerOptions) {
           if (result.tokens === undefined) {
             throw new Error("Invalid `auth:signIn` result for code exchange");
           }
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: result.tokens?.token ?? null,
-                  refreshToken: result.tokens?.refreshToken ?? null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              {
+                token: result.tokens?.token ?? null,
+                refreshToken: result.tokens?.refreshToken ?? null,
+                verifier: null,
+              },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: result.tokens?.token ?? null,
           };
         } catch (error) {
           console.error(error);
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: null,
-                  refreshToken: null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              { token: null, refreshToken: null, verifier: null },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: null,
           };
         }
       }
 
+      // Normal page load — refresh tokens if needed.
       const tokens = await refreshTokens(request);
       if (tokens === undefined) {
-        return {};
+        // No refresh needed — return current token for hydration.
+        return { cookies: [], token: currentToken };
       }
       return {
-        cookies: serializeAuthCookies(
+        cookies: structuredAuthCookies(
           {
             token: tokens?.token ?? null,
             refreshToken: tokens?.refreshToken ?? null,
@@ -441,6 +504,7 @@ export function server(options: ServerOptions) {
           host,
           cookieConfig,
         ),
+        token: tokens?.token ?? null,
       };
     },
   };