@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/dist/server/sso/validators.js

@@ -0,0 +1,88 @@
+import { v } from "convex/values";
+
+//#region src/server/sso/validators.ts
+/** @internal Shared validator for mounted group connection status fields. */
+const groupConnectionStatusValidator = v.union(v.literal("draft"), v.literal("active"), v.literal("disabled"));
+/** @internal Structured validator for mounted group policy patch payloads. */
+const groupPolicyPatchValidator = v.object({
+	identity: v.optional(v.object({ accountLinking: v.optional(v.object({
+		oidc: v.optional(v.union(v.literal("verifiedEmail"), v.literal("none"))),
+		saml: v.optional(v.union(v.literal("verifiedEmail"), v.literal("none")))
+	})) })),
+	provisioning: v.optional(v.object({
+		user: v.optional(v.object({
+			createOnSignIn: v.optional(v.boolean()),
+			updateProfileOnLogin: v.optional(v.union(v.literal("never"), v.literal("missing"), v.literal("always"))),
+			updateProfileFromScim: v.optional(v.union(v.literal("never"), v.literal("missing"), v.literal("always"))),
+			authority: v.optional(v.union(v.literal("app"), v.literal("sso"), v.literal("scim")))
+		})),
+		scimReuse: v.optional(v.object({ user: v.optional(v.union(v.literal("externalId"), v.literal("none"))) })),
+		jit: v.optional(v.object({
+			mode: v.optional(v.union(v.literal("off"), v.literal("createUser"), v.literal("createUserAndMembership"))),
+			defaultRoleIds: v.optional(v.array(v.string()))
+		})),
+		deprovision: v.optional(v.object({ mode: v.optional(v.union(v.literal("soft"), v.literal("hard"))) })),
+		groups: v.optional(v.object({
+			mode: v.optional(v.union(v.literal("ignore"), v.literal("sync"))),
+			source: v.optional(v.literal("protocol")),
+			mapping: v.optional(v.record(v.string(), v.array(v.string())))
+		})),
+		roles: v.optional(v.object({
+			mode: v.optional(v.union(v.literal("ignore"), v.literal("map"))),
+			source: v.optional(v.literal("protocol")),
+			mapping: v.optional(v.record(v.string(), v.array(v.string())))
+		}))
+	}))
+});
+/** @internal Filter validator for mounted group connection list queries. */
+const groupConnectionWhereValidator = v.object({
+	groupId: v.optional(v.string()),
+	slug: v.optional(v.string()),
+	status: v.optional(groupConnectionStatusValidator)
+});
+/** @internal Domain replacement input validator for mounted connection APIs. */
+const groupConnectionDomainInputValidator = v.object({
+	domain: v.string(),
+	isPrimary: v.optional(v.boolean())
+});
+/** @internal Input validator for connection domain verification actions. */
+const groupConnectionDomainVerificationInputValidator = v.object({
+	connectionId: v.string(),
+	domain: v.string()
+});
+/** @internal SAML attribute mapping validator for mounted SSO admin APIs. */
+const ssoSamlAttributeMappingValidator = v.object({
+	subject: v.optional(v.string()),
+	email: v.optional(v.string()),
+	name: v.optional(v.string()),
+	firstName: v.optional(v.string()),
+	lastName: v.optional(v.string()),
+	image: v.optional(v.string()),
+	groups: v.optional(v.string()),
+	roles: v.optional(v.string())
+});
+/** @internal SAML service-provider override validator for mounted admin APIs. */
+const ssoSamlSpValidator = v.object({
+	entityId: v.optional(v.string()),
+	acsUrl: v.optional(v.string()),
+	sloUrl: v.optional(v.string()),
+	signingCert: v.optional(v.union(v.string(), v.array(v.string()))),
+	encryptCert: v.optional(v.union(v.string(), v.array(v.string()))),
+	privateKey: v.optional(v.string()),
+	privateKeyPass: v.optional(v.string()),
+	encPrivateKey: v.optional(v.string()),
+	encPrivateKeyPass: v.optional(v.string())
+});
+/** @internal SAML security validator for mounted admin APIs. */
+const ssoSamlSecurityValidator = v.object({
+	requireSignedAssertions: v.optional(v.boolean()),
+	requireTimestamps: v.optional(v.boolean()),
+	clockSkewSeconds: v.optional(v.number()),
+	weakAlgorithmHandling: v.optional(v.union(v.literal("warn"), v.literal("reject"))),
+	maxMetadataSize: v.optional(v.number()),
+	maxResponseSize: v.optional(v.number())
+});
+
+//#endregion
+export { groupConnectionDomainInputValidator, groupConnectionDomainVerificationInputValidator, groupConnectionStatusValidator, groupConnectionWhereValidator, groupPolicyPatchValidator, ssoSamlAttributeMappingValidator, ssoSamlSecurityValidator, ssoSamlSpValidator };
+//# sourceMappingURL=validators.js.map

package/dist/server/sso/webhook.js

@@ -0,0 +1,94 @@
+import { createWebhookEndpoint, getWebhookEndpoint, listReadyWebhookDeliveries, listWebhookDeliveries, listWebhookEndpoints, patchWebhookDelivery, updateWebhookEndpoint } from "../contract.js";
+import { ConvexError } from "convex/values";
+
+//#region src/server/sso/webhook.ts
+const convexError = (data) => new ConvexError(data);
+function createGroupWebhookDomain(deps) {
+	const { config, sha256, loadConnectionOrThrow, recordGroupAuditEvent, emitGroupWebhookDeliveries } = deps;
+	return {
+		endpoint: {
+			get: async (ctx, endpointId) => {
+				return await getWebhookEndpoint(ctx, config.component.public, endpointId);
+			},
+			create: async (ctx, data) => {
+				const connection = await loadConnectionOrThrow(ctx, data.connectionId);
+				if (connection === null) throw convexError({
+					code: "INVALID_PARAMETERS",
+					message: "Connection not found."
+				});
+				const secretHash = await sha256(data.secret);
+				const endpointId = await createWebhookEndpoint(ctx, config.component.public, {
+					connectionId: connection._id,
+					groupId: connection.groupId,
+					url: data.url,
+					secretHash,
+					subscriptions: data.subscriptions,
+					createdByUserId: data.createdByUserId
+				});
+				await recordGroupAuditEvent(ctx, {
+					connectionId: connection._id,
+					groupId: connection.groupId,
+					eventType: "group.sso.webhook.endpoint.created",
+					actorType: data.createdByUserId ? "user" : "system",
+					actorId: data.createdByUserId,
+					subjectType: "group_webhook_endpoint",
+					subjectId: endpointId,
+					ok: true
+				});
+				return { endpointId };
+			},
+			list: async (ctx, connectionId) => {
+				return await listWebhookEndpoints(ctx, config.component.public, connectionId);
+			},
+			disable: async (ctx, endpointId) => {
+				await updateWebhookEndpoint(ctx, config.component.public, {
+					endpointId,
+					data: { status: "disabled" }
+				});
+				return { endpointId };
+			}
+		},
+		emit: async (ctx, data) => {
+			await emitGroupWebhookDeliveries(ctx, data);
+		},
+		delivery: {
+			list: async (ctx, data) => {
+				return await listWebhookDeliveries(ctx, config.component.public, data);
+			},
+			listReady: async (ctx, limit) => {
+				return await listReadyWebhookDeliveries(ctx, config.component.public, {
+					now: Date.now(),
+					limit
+				});
+			},
+			markDelivered: async (ctx, deliveryId, responseStatus) => {
+				await patchWebhookDelivery(ctx, config.component.public, {
+					deliveryId,
+					data: {
+						status: "delivered",
+						attemptCount: 1,
+						lastAttemptAt: Date.now(),
+						lastResponseStatus: responseStatus
+					}
+				});
+			},
+			markFailed: async (ctx, deliveryId, data) => {
+				await patchWebhookDelivery(ctx, config.component.public, {
+					deliveryId,
+					data: {
+						status: data.retryAt ? "pending" : "failed",
+						attemptCount: data.attemptCount,
+						lastAttemptAt: Date.now(),
+						lastResponseStatus: data.responseStatus,
+						lastError: data.error,
+						nextAttemptAt: data.retryAt ?? Date.now()
+					}
+				});
+			}
+		}
+	};
+}
+
+//#endregion
+export { createGroupWebhookDomain };
+//# sourceMappingURL=webhook.js.map

package/dist/server/tokens.js

@@ -1,17 +1,29 @@
-import { TOKEN_SUB_CLAIM_DIVIDER, generateRandomString, requireEnv } from "./utils.js";
+import { generateRandomString } from "./random.js";
+import { requireEnv } from "./env.js";
 import { SignJWT, importPKCS8 } from "jose";
 
 //#region src/server/tokens.ts
+const TOKEN_SUB_CLAIM_DIVIDER = "|";
 const DEFAULT_JWT_DURATION_MS = 1e3 * 60 * 60;
 const TOKEN_JTI_LENGTH = 24;
 const TOKEN_JTI_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+let cachedPrivateKeyPromise = null;
+let cachedIssuer = null;
+const getPrivateKey = () => {
+	if (cachedPrivateKeyPromise === null) cachedPrivateKeyPromise = importPKCS8(requireEnv("JWT_PRIVATE_KEY"), "RS256");
+	return cachedPrivateKeyPromise;
+};
+const getIssuer = () => {
+	if (cachedIssuer === null) cachedIssuer = requireEnv("CONVEX_SITE_URL");
+	return cachedIssuer;
+};
 /** @internal */
 async function generateToken(args, config) {
-	const privateKey = await importPKCS8(requireEnv("JWT_PRIVATE_KEY"), "RS256");
+	const privateKey = await getPrivateKey();
 	const expirationTime = new Date(Date.now() + (config.jwt?.durationMs ?? DEFAULT_JWT_DURATION_MS));
-	return await new SignJWT({ sub: args.userId + TOKEN_SUB_CLAIM_DIVIDER + args.sessionId }).setProtectedHeader({ alg: "RS256" }).setIssuedAt().setJti(generateRandomString(TOKEN_JTI_LENGTH, TOKEN_JTI_ALPHABET)).setIssuer(requireEnv("CONVEX_SITE_URL")).setAudience("convex").setExpirationTime(expirationTime).sign(privateKey);
+	return await new SignJWT({ sub: args.userId + TOKEN_SUB_CLAIM_DIVIDER + args.sessionId }).setProtectedHeader({ alg: "RS256" }).setIssuedAt().setJti(generateRandomString(TOKEN_JTI_LENGTH, TOKEN_JTI_ALPHABET)).setIssuer(getIssuer()).setAudience("convex").setExpirationTime(expirationTime).sign(privateKey);
 }
 
 //#endregion
-export { generateToken };
+export { TOKEN_SUB_CLAIM_DIVIDER, generateToken };
 //# sourceMappingURL=tokens.js.map

package/dist/server/totp.js

@@ -1,10 +1,10 @@
 import { userIdFromIdentitySubject } from "./identity.js";
-import { callVerifierSignature } from "./mutations/signature.js";
 import { callSignIn } from "./mutations/signin.js";
 import { callVerifier } from "./mutations/verifier.js";
+import { authFlowError } from "../shared/errors.js";
+import { toConvexError } from "./errors.js";
 import { mutateTotpInsert, mutateTotpMarkVerified, mutateTotpUpdateLastUsed, mutateVerifierDelete, queryTotpById, queryTotpVerifiedByUserId, queryUserById, queryVerifierById } from "./types.js";
-import { Fx } from "@robelest/fx";
-import { Cv } from "@robelest/fx/convex";
+import { ConvexError } from "convex/values";
 import { encodeBase32LowerCaseNoPadding } from "@oslojs/encoding";
 import { createTOTPKeyURI, verifyTOTPWithGracePeriod } from "@oslojs/otp";
 
@@ -22,185 +22,176 @@ const TOTP_FLOWS = [
 	"confirm",
 	"verify"
 ];
-const resolveTotpFlowFx = (params) => {
+const convexError = (code, message) => toConvexError(authFlowError(code, message));
+const asConvexError = (error, code, message) => error instanceof ConvexError ? error : error instanceof Error ? toConvexError(authFlowError(code, error.message || message)) : convexError(code, message);
+function resolveTotpFlow(params) {
 	const flow = params.flow;
-	return typeof flow === "string" && TOTP_FLOWS.includes(flow) ? Fx.succeed(flow) : Cv.fail({
-		code: "TOTP_MISSING_FLOW",
-		message: "Missing `flow` parameter. Expected one of: setup, confirm, verify"
-	});
-};
-const requireTotpVerifierFx = (verifier) => verifier != null ? Fx.succeed(verifier) : Cv.fail({
-	code: "TOTP_MISSING_VERIFIER",
-	message: "Missing verifier for TOTP operation."
-});
-const requireTotpCodeFx = (params) => typeof params.code === "string" ? Fx.succeed(params.code) : Cv.fail({
-	code: "TOTP_MISSING_CODE",
-	message: "Missing TOTP code."
-});
-const requireTotpIdFx = (params) => typeof params.totpId === "string" ? Fx.succeed(params.totpId) : Cv.fail({
-	code: "TOTP_MISSING_ID",
-	message: "Missing TOTP enrollment ID."
-});
-const resolveTotpDispatchFx = (params, verifier) => resolveTotpFlowFx(params).pipe(Fx.chain((flow) => Fx.match({ flow }).on("flow", {
-	setup: () => Fx.succeed({
+	if (typeof flow === "string" && TOTP_FLOWS.includes(flow)) return flow;
+	throw convexError("TOTP_MISSING_FLOW", "Missing `flow` parameter. Expected one of: setup, confirm, verify");
+}
+function requireTotpVerifier(verifier) {
+	if (verifier != null) return verifier;
+	throw convexError("TOTP_MISSING_VERIFIER", "Missing verifier for TOTP operation.");
+}
+function requireTotpCode(params) {
+	if (typeof params.code === "string") return params.code;
+	throw convexError("TOTP_MISSING_CODE", "Missing TOTP code.");
+}
+function requireTotpId(params) {
+	if (typeof params.totpId === "string") return params.totpId;
+	throw convexError("TOTP_MISSING_ID", "Missing TOTP enrollment ID.");
+}
+function resolveTotpDispatch(params, verifier) {
+	const flow = resolveTotpFlow(params);
+	if (flow === "setup") return {
 		flow: "setup",
 		params
-	}),
-	confirm: () => Fx.gen(function* () {
-		const resolvedVerifier = yield* requireTotpVerifierFx(verifier);
+	};
+	if (flow === "confirm") {
+		const resolvedVerifier$1 = requireTotpVerifier(verifier);
 		return {
 			flow: "confirm",
-			code: yield* requireTotpCodeFx(params),
-			totpId: yield* requireTotpIdFx(params),
-			verifier: resolvedVerifier
-		};
-	}),
-	verify: () => Fx.gen(function* () {
-		const resolvedVerifier = yield* requireTotpVerifierFx(verifier);
-		return {
-			flow: "verify",
-			code: yield* requireTotpCodeFx(params),
-			verifier: resolvedVerifier
+			code: requireTotpCode(params),
+			totpId: requireTotpId(params),
+			verifier: resolvedVerifier$1
 		};
-	})
-})));
+	}
+	const resolvedVerifier = requireTotpVerifier(verifier);
+	return {
+		flow: "verify",
+		code: requireTotpCode(params),
+		verifier: resolvedVerifier
+	};
+}
+async function requireAuthenticatedUserId(ctx) {
+	let identity;
+	try {
+		identity = await ctx.auth.getUserIdentity();
+	} catch (error) {
+		throw asConvexError(error, "INTERNAL_ERROR", String(error));
+	}
+	if (identity === null) throw convexError("TOTP_AUTH_REQUIRED", "Sign in first, then set up two-factor authentication.");
+	return userIdFromIdentitySubject(identity.subject);
+}
 /** @internal */
-const handleTotp = (ctx, provider, args) => {
-	return resolveTotpDispatchFx(args.params ?? {}, args.verifier).pipe(Fx.chain((dispatch) => Fx.match(dispatch).on("flow", {
-		setup: ({ params }) => Fx.from({
-			ok: () => ctx.auth.getUserIdentity(),
-			err: (e) => Cv.error({
-				code: "INTERNAL_ERROR",
-				message: String(e)
-			})
-		}).pipe(Fx.chain((identity) => identity === null ? Cv.fail({
-			code: "TOTP_AUTH_REQUIRED",
-			message: "Sign in first, then set up two-factor authentication."
-		}) : Fx.succeed(userIdFromIdentitySubject(identity.subject))), Fx.chain((userId) => Fx.from({
-			ok: async () => {
-				const secret = new Uint8Array(20);
-				crypto.getRandomValues(secret);
-				let accountName = params.accountName;
-				if (!accountName) accountName = (await queryUserById(ctx, userId))?.email ?? "user";
-				const uri = createTOTPKeyURI(provider.options.issuer, accountName, secret, provider.options.period, provider.options.digits);
-				const base32Secret = encodeBase32LowerCaseNoPadding(secret);
-				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
-					})
+const handleTotp = async (ctx, provider, args) => {
+	const dispatch = resolveTotpDispatch(args.params ?? {}, args.verifier);
+	const handler = {
+		setup: async () => {
+			const { params: setupParams } = dispatch;
+			const userId = await requireAuthenticatedUserId(ctx);
+			const secret = new Uint8Array(20);
+			crypto.getRandomValues(secret);
+			let accountName = setupParams.accountName;
+			if (!accountName) {
+				let user;
+				try {
+					user = await queryUserById(ctx, userId);
+				} catch (error) {
+					throw asConvexError(error, "INTERNAL_ERROR", `TOTP setup failed: ${String(error)}`);
+				}
+				accountName = user?.email ?? "user";
+			}
+			const uri = createTOTPKeyURI(provider.options.issuer, accountName, secret, provider.options.period, provider.options.digits);
+			const base32Secret = encodeBase32LowerCaseNoPadding(secret);
+			let verifier;
+			try {
+				verifier = await callVerifier(ctx, JSON.stringify({
+					secret: Array.from(secret),
+					userId,
+					digits: provider.options.digits,
+					period: provider.options.period
+				}));
+			} catch (error) {
+				throw asConvexError(error, "INTERNAL_ERROR", `TOTP setup failed: ${String(error)}`);
+			}
+			let totpId;
+			try {
+				totpId = await mutateTotpInsert(ctx, {
+					userId,
+					secret: secret.buffer.slice(secret.byteOffset, secret.byteOffset + secret.byteLength),
+					digits: provider.options.digits,
+					period: provider.options.period,
+					verified: false,
+					name: typeof setupParams.name === "string" ? setupParams.name : void 0,
+					createdAt: Date.now()
 				});
-				return {
-					kind: "totpSetup",
-					uri,
-					secret: base32Secret,
-					verifier,
-					totpId: await mutateTotpInsert(ctx, {
-						userId,
-						secret: secret.buffer.slice(secret.byteOffset, secret.byteOffset + secret.byteLength),
-						digits: provider.options.digits,
-						period: provider.options.period,
-						verified: false,
-						name: typeof params.name === "string" ? params.name : void 0,
-						createdAt: Date.now()
-					})
-				};
-			},
-			err: (e) => Cv.error({
-				code: "INTERNAL_ERROR",
-				message: `TOTP setup failed: ${String(e)}`
-			})
-		}))),
-		confirm: ({ code, totpId, verifier }) => Fx.from({
-			ok: () => ctx.auth.getUserIdentity(),
-			err: (e) => Cv.error({
-				code: "INTERNAL_ERROR",
-				message: String(e)
-			})
-		}).pipe(Fx.chain((identity) => identity === null ? Cv.fail({
-			code: "TOTP_AUTH_REQUIRED",
-			message: "Sign in first, then set up two-factor authentication."
-		}) : Fx.succeed(userIdFromIdentitySubject(identity.subject))), Fx.chain((userId) => Fx.from({
-			ok: () => queryTotpById(ctx, totpId),
-			err: () => Cv.error({
-				code: "TOTP_NOT_FOUND",
-				message: "TOTP enrollment not found."
-			})
-		}).pipe(Fx.chain((doc) => doc === null ? Cv.fail({
-			code: "TOTP_NOT_FOUND",
-			message: "TOTP enrollment not found."
-		}) : Fx.succeed(doc)), Fx.chain((totpDoc) => totpDoc.verified ? Cv.fail({
-			code: "TOTP_ALREADY_VERIFIED",
-			message: "TOTP enrollment is already verified."
-		}) : Fx.succeed(totpDoc))).pipe(Fx.chain((totpDoc) => verifyTOTPWithGracePeriod(new Uint8Array(totpDoc.secret), provider.options.period, provider.options.digits, code, 30) ? Fx.succeed(totpDoc) : Cv.fail({
-			code: "TOTP_INVALID_CODE",
-			message: "Invalid TOTP code."
-		}))).pipe(Fx.chain((_totpDoc) => Fx.from({
-			ok: async () => {
+			} catch (error) {
+				throw asConvexError(error, "INTERNAL_ERROR", `TOTP setup failed: ${String(error)}`);
+			}
+			return {
+				kind: "totpSetup",
+				uri,
+				secret: base32Secret,
+				verifier,
+				totpId
+			};
+		},
+		confirm: async () => {
+			const { code, totpId, verifier } = dispatch;
+			const userId = await requireAuthenticatedUserId(ctx);
+			let doc;
+			try {
+				doc = await queryTotpById(ctx, totpId);
+			} catch {
+				throw convexError("TOTP_NOT_FOUND", "TOTP enrollment not found.");
+			}
+			if (doc === null) throw convexError("TOTP_NOT_FOUND", "TOTP enrollment not found.");
+			if (doc.verified) throw convexError("TOTP_ALREADY_VERIFIED", "TOTP enrollment is already verified.");
+			if (!verifyTOTPWithGracePeriod(new Uint8Array(doc.secret), provider.options.period, provider.options.digits, code, 30)) throw convexError("TOTP_INVALID_CODE", "Invalid TOTP code.");
+			let signInResult;
+			try {
 				await mutateTotpMarkVerified(ctx, totpId, Date.now());
 				await mutateVerifierDelete(ctx, verifier);
-				return callSignIn(ctx, {
+				signInResult = await callSignIn(ctx, {
 					userId,
 					generateTokens: true
 				});
-			},
-			err: (e) => Cv.error({
-				code: "INTERNAL_ERROR",
-				message: String(e)
-			})
-		}))).pipe(Fx.map((signInResult) => ({
-			kind: "signedIn",
-			signedIn: signInResult
-		}))))),
-		verify: ({ code, verifier }) => Fx.from({
-			ok: () => queryVerifierById(ctx, verifier),
-			err: () => Cv.error({
-				code: "TOTP_INVALID_VERIFIER",
-				message: "Invalid or expired TOTP verifier."
-			})
-		}).pipe(Fx.chain((doc) => doc === null ? Cv.fail({
-			code: "TOTP_INVALID_VERIFIER",
-			message: "Invalid or expired TOTP verifier."
-		}) : Fx.succeed(doc)), Fx.map((doc) => {
+			} catch (error) {
+				throw asConvexError(error, "INTERNAL_ERROR", String(error));
+			}
 			return {
-				userId: JSON.parse(doc.signature).userId,
-				code,
-				verifier
+				kind: "signedIn",
+				signedIn: signInResult
 			};
-		}), Fx.chain(({ userId, code: code$1, verifier: verifier$1 }) => Fx.from({
-			ok: () => queryTotpVerifiedByUserId(ctx, userId),
-			err: () => Cv.error({
-				code: "TOTP_NO_ENROLLMENT",
-				message: "No verified TOTP enrollment found."
-			})
-		}).pipe(Fx.chain((totpDoc) => totpDoc === null ? Cv.fail({
-			code: "TOTP_NO_ENROLLMENT",
-			message: "No verified TOTP enrollment found."
-		}) : Fx.succeed(totpDoc)), Fx.chain((totpDoc) => verifyTOTPWithGracePeriod(new Uint8Array(totpDoc.secret), totpDoc.period, totpDoc.digits, code$1, 30) ? Fx.succeed(totpDoc) : Cv.fail({
-			code: "TOTP_INVALID_CODE",
-			message: "Invalid TOTP code."
-		})), Fx.chain((totpDoc) => Fx.from({
-			ok: async () => {
-				await mutateTotpUpdateLastUsed(ctx, totpDoc._id, Date.now());
-				await mutateVerifierDelete(ctx, verifier$1);
-				return callSignIn(ctx, {
+		},
+		verify: async () => {
+			const { code, verifier } = dispatch;
+			let doc;
+			try {
+				doc = await queryVerifierById(ctx, verifier);
+			} catch {
+				throw convexError("TOTP_INVALID_VERIFIER", "Invalid or expired TOTP verifier.");
+			}
+			if (doc === null) throw convexError("TOTP_INVALID_VERIFIER", "Invalid or expired TOTP verifier.");
+			const userId = JSON.parse(doc.signature).userId;
+			let totp;
+			try {
+				totp = await queryTotpVerifiedByUserId(ctx, userId);
+			} catch {
+				throw convexError("TOTP_NO_ENROLLMENT", "No verified TOTP enrollment found.");
+			}
+			if (totp === null) throw convexError("TOTP_NO_ENROLLMENT", "No verified TOTP enrollment found.");
+			if (!verifyTOTPWithGracePeriod(new Uint8Array(totp.secret), totp.period, totp.digits, code, 30)) throw convexError("TOTP_INVALID_CODE", "Invalid TOTP code.");
+			let signInResult;
+			try {
+				await mutateTotpUpdateLastUsed(ctx, totp._id, Date.now());
+				await mutateVerifierDelete(ctx, verifier);
+				signInResult = await callSignIn(ctx, {
 					userId,
 					generateTokens: true
 				});
-			},
-			err: (e) => Cv.error({
-				code: "INTERNAL_ERROR",
-				message: String(e)
-			})
-		})), Fx.map((signInResult) => ({
-			kind: "signedIn",
-			signedIn: signInResult
-		})))))
-	})));
+			} catch (error) {
+				throw asConvexError(error, "INTERNAL_ERROR", String(error));
+			}
+			return {
+				kind: "signedIn",
+				signedIn: signInResult
+			};
+		}
+	}[dispatch.flow];
+	if (!handler) throw convexError("TOTP_MISSING_FLOW", `Unknown TOTP flow: ${dispatch.flow}`);
+	return handler();
 };
 
 //#endregion