& so it begins

packages/logic/domains/2fa/controller.ts

@@ -0,0 +1,349 @@
+import { errAsync, okAsync, ResultAsync } from "neverthrow";
+import { FlowExecCtx } from "@core/flow.execution.context";
+import { UserRepository } from "@domains/user/repository";
+import { getRedisInstance, Redis } from "@pkg/redis";
+import { TwofaRepository } from "./repository";
+import { auth } from "../auth/config.base";
+import type { TwoFaSession } from "./data";
+import { User } from "@domains/user/data";
+import { settings } from "@core/settings";
+import { type Err } from "@pkg/result";
+import { twofaErrors } from "./errors";
+import { logger } from "@pkg/logger";
+import { db } from "@pkg/db";
+
+export class TwofaController {
+    constructor(
+        private twofaRepo: TwofaRepository,
+        private userRepo: UserRepository,
+        private store: Redis,
+    ) {}
+
+    checkTotp(secret: string, code: string) {
+        return this.twofaRepo.checkTotp(secret, code);
+    }
+
+    is2faEnabled(fctx: FlowExecCtx, userId: string) {
+        return this.twofaRepo
+            .getUsers2FAInfo(fctx, userId, true)
+            .map((data) => !!data)
+            .orElse(() => okAsync(false));
+    }
+
+    isUserBanned(fctx: FlowExecCtx, userId: string) {
+        return this.userRepo.isUserBanned(fctx, userId).orElse((error) => {
+            logger.error("Error checking user ban status:", error);
+            return okAsync(false);
+        });
+    }
+
+    setup2FA(fctx: FlowExecCtx, user: User) {
+        return this.is2faEnabled(fctx, user.id)
+            .andThen((enabled) =>
+                enabled
+                    ? errAsync(twofaErrors.alreadyEnabled(fctx))
+                    : this.twofaRepo.setup(fctx, user.id),
+            )
+            .map((secret) => {
+                const appName = settings.appName;
+                const totpUri = `otpauth://totp/${appName}:${user.email}?secret=${secret}&issuer=${appName}`;
+                return { totpURI: totpUri, secret };
+            });
+    }
+
+    verifyAndEnable2FA(
+        fctx: FlowExecCtx,
+        user: User,
+        code: string,
+        headers: Headers,
+    ) {
+        return this.is2faEnabled(fctx, user.id)
+            .andThen((enabled) => {
+                if (enabled) {
+                    return errAsync(twofaErrors.alreadyEnabled(fctx));
+                }
+                return okAsync(undefined);
+            })
+            .andThen(() => {
+                logger.info(`Verifying 2fa for ${user.id} : ${code}`, {
+                    flowId: fctx.flowId,
+                });
+                return this.twofaRepo.verifyAndEnable2FA(fctx, user.id, code);
+            })
+            .andThen((verified) => {
+                if (verified) {
+                    return ResultAsync.combine([
+                        ResultAsync.fromPromise(
+                            auth.api.revokeOtherSessions({ headers }),
+                            () => twofaErrors.revokeSessionsFailed(fctx),
+                        ),
+                        this.userRepo.updateLastVerified2FaAtToNow(
+                            fctx,
+                            user.id,
+                        ),
+                    ]).map(() => true);
+                }
+                return okAsync(verified);
+            });
+    }
+
+    disable(fctx: FlowExecCtx, user: User, code: string) {
+        return this.is2faEnabled(fctx, user.id)
+            .andThen((enabled) => {
+                if (!enabled) {
+                    return errAsync(twofaErrors.notEnabled(fctx));
+                }
+                return okAsync(undefined);
+            })
+            .andThen(() => this.twofaRepo.get2FASecret(fctx, user.id))
+            .andThen((secret) => {
+                if (!secret) {
+                    return errAsync(twofaErrors.invalidSetup(fctx));
+                }
+                if (!this.checkTotp(secret, code)) {
+                    return errAsync(twofaErrors.invalidCode(fctx));
+                }
+                return okAsync(undefined);
+            })
+            .andThen(() => this.twofaRepo.disable(fctx, user.id));
+    }
+
+    generateBackupCodes(fctx: FlowExecCtx, user: User) {
+        return this.is2faEnabled(fctx, user.id)
+            .andThen((enabled) => {
+                if (!enabled) {
+                    return errAsync(twofaErrors.notEnabled(fctx));
+                }
+                return okAsync(undefined);
+            })
+            .andThen(() => this.twofaRepo.generateBackupCodes(fctx, user.id));
+    }
+
+    requiresInitialVerification(
+        fctx: FlowExecCtx,
+        user: User,
+        sessionId: string,
+    ) {
+        return this.is2faEnabled(fctx, user.id).andThen((enabled) => {
+            if (!enabled) {
+                return okAsync(false);
+            }
+
+            return ResultAsync.fromPromise(
+                this.store.get(`initial_2fa_completed:${sessionId}`),
+                () => null,
+            )
+                .map((completed) => !completed && completed !== "0")
+                .orElse(() => okAsync(true));
+        });
+    }
+
+    requiresSensitiveActionVerification(fctx: FlowExecCtx, user: User) {
+        return this.is2faEnabled(fctx, user.id).andThen((enabled) => {
+            if (!enabled) {
+                return okAsync(false);
+            }
+
+            if (!user.last2FAVerifiedAt) {
+                return okAsync(true);
+            }
+
+            const requiredHours = settings.twofaRequiredHours || 24;
+            const verificationAge =
+                Date.now() - user.last2FAVerifiedAt.getTime();
+            const maxAge = requiredHours * 60 * 60 * 1000;
+
+            return okAsync(verificationAge > maxAge);
+        });
+    }
+
+    markInitialVerificationComplete(sessionId: string) {
+        return ResultAsync.fromPromise(
+            this.store.setex(
+                `initial_2fa_completed:${sessionId}`,
+                60 * 60 * 24 * 7,
+                "true",
+            ),
+            () => null,
+        )
+            .map(() => undefined)
+            .orElse((error) => {
+                logger.error("Error marking initial 2FA as complete:", error);
+                return okAsync(undefined);
+            });
+    }
+
+    startVerification(
+        fctx: FlowExecCtx,
+        params: {
+            userId: string;
+            sessionId: string;
+            ipAddress?: string;
+            userAgent?: string;
+        },
+    ) {
+        return this.twofaRepo.createSession(fctx, params).map((session) => ({
+            verificationToken: session.verificationToken,
+        }));
+    }
+
+    private validateSession(fctx: FlowExecCtx, session: TwoFaSession) {
+        if (session.status !== "pending") {
+            return errAsync(twofaErrors.sessionNotActive(fctx));
+        }
+
+        if (session.expiresAt < new Date()) {
+            return this.twofaRepo
+                .updateSession(fctx, session.id, { status: "expired" })
+                .andThen(() => errAsync(twofaErrors.sessionExpired(fctx)));
+        }
+
+        return okAsync(session);
+    }
+
+    private handleMaxAttempts(
+        fctx: FlowExecCtx,
+        session: TwoFaSession,
+        userId: string,
+    ) {
+        const banExpiresAt = new Date();
+        banExpiresAt.setHours(banExpiresAt.getHours() + 1);
+
+        return this.twofaRepo
+            .updateSession(fctx, session.id, { status: "failed" })
+            .andThen(() =>
+                this.userRepo.banUser(
+                    fctx,
+                    userId,
+                    "Too many failed 2FA verification attempts",
+                    banExpiresAt,
+                ),
+            )
+            .andThen(() => errAsync(twofaErrors.tooManyAttempts(fctx)));
+    }
+
+    private checkAttemptsLimit(
+        fctx: FlowExecCtx,
+        session: TwoFaSession,
+        userId: string,
+    ) {
+        if (session.attempts >= session.maxAttempts) {
+            return this.handleMaxAttempts(fctx, session, userId);
+        }
+        return okAsync(session);
+    }
+
+    private checkCodeReplay(
+        fctx: FlowExecCtx,
+        session: TwoFaSession,
+        code: string,
+    ): ResultAsync<TwoFaSession, Err> {
+        if (session.codeUsed === code) {
+            return this.twofaRepo
+                .incrementAttempts(fctx, session.id)
+                .andThen(() => errAsync(twofaErrors.codeReplay(fctx)));
+        }
+        return okAsync(session);
+    }
+
+    private verifyTotpCode(
+        fctx: FlowExecCtx,
+        session: TwoFaSession,
+        userId: string,
+        code: string,
+    ) {
+        return this.twofaRepo.get2FASecret(fctx, userId).andThen((secret) => {
+            if (!secret) {
+                return errAsync(twofaErrors.invalidSetup(fctx));
+            }
+
+            if (!this.checkTotp(secret, code)) {
+                return this.twofaRepo
+                    .incrementAttempts(fctx, session.id)
+                    .andThen(() => errAsync(twofaErrors.invalidCode(fctx)));
+            }
+
+            return okAsync(session);
+        });
+    }
+
+    private completeVerification(
+        fctx: FlowExecCtx,
+        session: TwoFaSession,
+        userId: string,
+        code: string,
+    ) {
+        return this.twofaRepo
+            .updateSession(fctx, session.id, {
+                status: "verified",
+                verifiedAt: new Date(),
+                codeUsed: code,
+            })
+            .andThen(() =>
+                ResultAsync.combine([
+                    this.userRepo.updateLastVerified2FaAtToNow(fctx, userId),
+                    this.markInitialVerificationComplete(session.sessionId),
+                ]),
+            )
+            .map(() => undefined);
+    }
+
+    verifyCode(
+        fctx: FlowExecCtx,
+        params: { verificationSessToken: string; code: string },
+        user?: User,
+    ) {
+        if (!user) {
+            return errAsync(twofaErrors.userNotFound(fctx));
+        }
+
+        return this.is2faEnabled(fctx, user.id)
+            .andThen((enabled) => {
+                if (!enabled) {
+                    return errAsync(
+                        twofaErrors.notEnabledForVerification(fctx),
+                    );
+                }
+                return okAsync(undefined);
+            })
+            .andThen(() =>
+                this.twofaRepo.getSessionByToken(
+                    fctx,
+                    params.verificationSessToken,
+                ),
+            )
+            .andThen((session) => {
+                if (!session) {
+                    return errAsync(twofaErrors.sessionNotFound(fctx));
+                }
+                return okAsync(session);
+            })
+            .andThen((session) => this.validateSession(fctx, session))
+            .andThen((session) =>
+                this.checkAttemptsLimit(fctx, session, user.id),
+            )
+            .andThen((session) =>
+                this.checkCodeReplay(fctx, session, params.code),
+            )
+            .andThen((session) =>
+                this.verifyTotpCode(fctx, session, user.id, params.code),
+            )
+            .andThen((session) =>
+                this.completeVerification(fctx, session, user.id, params.code),
+            )
+            .map(() => ({ success: true }));
+    }
+
+    cleanupExpiredSessions(fctx: FlowExecCtx) {
+        return this.twofaRepo.cleanupExpiredSessions(fctx);
+    }
+}
+
+export function getTwofaController() {
+    const _redis = getRedisInstance();
+    return new TwofaController(
+        new TwofaRepository(db, _redis),
+        new UserRepository(db),
+        _redis,
+    );
+}

packages/logic/domains/2fa/data.ts

@@ -0,0 +1,48 @@
+import * as v from "valibot";
+
+export const startVerificationSchema = v.object({
+    userId: v.string(),
+    sessionId: v.string(),
+});
+
+export const verifyCodeSchema = v.object({
+    verificationToken: v.string(),
+    code: v.string(),
+});
+
+export const enable2FACodeSchema = v.object({
+    code: v.string(),
+});
+
+export const disable2FASchema = v.object({
+    code: v.string(),
+});
+
+export const twoFactorSchema = v.object({
+    id: v.string(),
+    secret: v.string(),
+    backupCodes: v.array(v.string()),
+    userId: v.string(),
+    createdAt: v.date(),
+    updatedAt: v.date(),
+});
+export type TwoFactor = v.InferOutput<typeof twoFactorSchema>;
+
+export type TwoFaSessionStatus = "pending" | "verified" | "failed" | "expired";
+
+export const twoFaSessionSchema = v.object({
+    id: v.string(),
+    userId: v.string(),
+    sessionId: v.string(),
+    verificationToken: v.string(),
+    codeUsed: v.optional(v.string()),
+    status: v.picklist(["pending", "verified", "failed", "expired"]),
+    attempts: v.number(),
+    maxAttempts: v.number(),
+    verifiedAt: v.optional(v.date()),
+    expiresAt: v.date(),
+    createdAt: v.date(),
+    ipAddress: v.string(),
+    userAgent: v.string(),
+});
+export type TwoFaSession = v.InferOutput<typeof twoFaSessionSchema>;

packages/logic/domains/2fa/errors.ts

@@ -0,0 +1,180 @@
+import { FlowExecCtx } from "@/core/flow.execution.context";
+import { ERROR_CODES, type Err } from "@pkg/result";
+import { getError } from "@pkg/logger";
+
+export const twofaErrors = {
+    dbError: (fctx: FlowExecCtx, detail: string): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.DATABASE_ERROR,
+            message: "Database operation failed",
+            description: "Please try again later",
+            detail,
+        }),
+
+    alreadyEnabled: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "2FA already enabled",
+            description: "Disable it first if you want to re-enable it",
+            detail: "2FA already enabled",
+        }),
+
+    notEnabled: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "2FA not enabled for this user",
+            description: "Enable 2FA to perform this action",
+            detail: "2FA not enabled for this user",
+        }),
+
+    userNotFound: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "User not found",
+            description: "Session is invalid or expired",
+            detail: "User ID not found in database",
+        }),
+
+    sessionNotActive: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Verification session is no longer active",
+            description: "Please request a new verification code",
+            detail: "Session status is not 'pending'",
+        }),
+
+    sessionExpired: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Verification session has expired",
+            description: "Please request a new verification code",
+            detail: "Session expired timestamp passed",
+        }),
+
+    sessionNotFound: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.NOT_FOUND,
+            message: "Invalid or expired verification session",
+            description: "Your verification session has expired or is invalid",
+            detail: "Session not found by verification token",
+        }),
+
+    tooManyAttempts: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.BANNED,
+            message: "Too many failed attempts",
+            description:
+                "Your account has been banned, contact us to resolve this issue",
+            detail: "Max attempts reached for 2FA verification",
+        }),
+
+    codeReplay: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "This code has already been used",
+            description: "Please request a new verification code",
+            detail: "Code replay attempt detected",
+        }),
+
+    invalidSetup: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Invalid 2FA setup found",
+            description: "Please contact us to resolve this issue",
+            detail: "Invalid 2FA data found",
+        }),
+
+    invalidCode: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Invalid verification code",
+            description: "Please try again with the correct code",
+            detail: "Code is invalid",
+        }),
+
+    notEnabledForVerification: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "2FA not enabled for this user",
+            description:
+                "Two-factor authentication is not enabled on your account",
+            detail: "User has 2FA disabled but verification attempted",
+        }),
+
+    revokeSessionsFailed: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Failed to revoke sessions",
+            description: "Please try again later",
+            detail: "Failed to revoke other sessions",
+        }),
+
+    // Repository errors
+    notFound: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.NOT_FOUND,
+            message: "2FA not found",
+            description: "Likely not enabled, otherwise please contact us :)",
+            detail: "2FA not found",
+        }),
+
+    setupNotFound: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.VALIDATION_ERROR,
+            message: "Cannot perform action",
+            description: "If 2FA is not enabled, please refresh and try again",
+            detail: "2FA setup not found",
+        }),
+
+    maxAttemptsReached: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Too many failed attempts",
+            description: "Please refresh and try again",
+            detail: "Max attempts reached for session",
+        }),
+
+    backupCodesNotFound: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.NOT_FOUND,
+            message: "2FA info not found",
+            description: "Please setup 2FA or contact us if this is unexpected",
+            detail: "2FA info not found for user",
+        }),
+
+    backupCodesAlreadyGenerated: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.AUTH_ERROR,
+            message: "Backup codes already generated",
+            description:
+                "Can only generate if not already present, or all are used up",
+            detail: "Backup codes already generated",
+        }),
+
+    sessionNotFoundById: (fctx: FlowExecCtx): Err =>
+        getError({
+            flowId: fctx.flowId,
+            code: ERROR_CODES.NOT_FOUND,
+            message: "2FA session not found",
+            description: "The verification session may have expired",
+            detail: "Session ID not found in database",
+        }),
+};

packages/logic/domains/2fa/repository.ts

@@ -0,0 +1,554 @@
+import { errAsync, okAsync, ResultAsync } from "neverthrow";
+import { FlowExecCtx } from "@core/flow.execution.context";
+import { hashString, verifyHash } from "@/core/hash.utils";
+import { twoFactor, twofaSessions } from "@pkg/db/schema";
+import { TwoFactor, type TwoFaSession } from "./data";
+import { and, Database, eq, gt, lt } from "@pkg/db";
+import { settings } from "@core/settings";
+import type { Err } from "@pkg/result";
+import { twofaErrors } from "./errors";
+import { authenticator } from "otplib";
+import { logger } from "@pkg/logger";
+import { Redis } from "@pkg/redis";
+import { nanoid } from "nanoid";
+
+type TwoFaSetup = {
+    secret: string;
+    lastUsedCode: string;
+    tries: number;
+};
+
+export class TwofaRepository {
+    private PENDING_KEY_PREFIX = "pending_enabling_2fa:";
+    private EXPIRY_TIME = 60 * 20; // 20 mins
+    private DEFAULT_BACKUP_CODES_AMT = 8;
+    private MAX_SETUP_ATTEMPTS = 3;
+
+    constructor(
+        private db: Database,
+        private store: Redis,
+    ) {}
+
+    checkTotp(secret: string, code: string) {
+        const checked = authenticator.verify({ secret, token: code });
+        logger.debug("TOTP check result", { checked });
+        return checked;
+    }
+
+    async checkBackupCode(hash: string, code: string) {
+        return verifyHash({ hash, target: code });
+    }
+
+    private getKey(userId: string) {
+        if (userId.includes(this.PENDING_KEY_PREFIX)) {
+            return userId;
+        }
+        return `${this.PENDING_KEY_PREFIX}${userId}`;
+    }
+
+    getUsers2FAInfo(
+        fctx: FlowExecCtx,
+        userId: string,
+        returnUndefined?: boolean,
+    ): ResultAsync<TwoFactor | undefined, Err> {
+        logger.info("Getting user 2FA info", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.db.query.twoFactor.findFirst({
+                where: eq(twoFactor.userId, userId),
+            }),
+            () => twofaErrors.dbError(fctx, "Failed to query 2FA info"),
+        ).andThen((found) => {
+            if (!found) {
+                logger.debug("2FA info not found for user", {
+                    ...fctx,
+                    userId,
+                });
+                if (returnUndefined) {
+                    return okAsync(undefined);
+                }
+                return errAsync(twofaErrors.notFound(fctx));
+            }
+            logger.info("2FA info retrieved successfully", { ...fctx, userId });
+            return okAsync(found as TwoFactor);
+        });
+    }
+
+    isSetupPending(
+        fctx: FlowExecCtx,
+        userId: string,
+    ): ResultAsync<boolean, Err> {
+        logger.debug("Checking if 2FA setup is pending", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.store.get(this.getKey(userId)),
+            () =>
+                twofaErrors.dbError(
+                    fctx,
+                    "Failed to check setup pending status",
+                ),
+        ).map((found) => {
+            const isPending = !!found;
+            logger.debug("Setup pending status checked", {
+                ...fctx,
+                userId,
+                isPending,
+            });
+            return isPending;
+        });
+    }
+
+    setup(fctx: FlowExecCtx, userId: string): ResultAsync<string, Err> {
+        logger.info("Starting 2FA setup", { ...fctx, userId });
+
+        return ResultAsync.fromSafePromise(
+            (async () => {
+                const secret = authenticator.generateSecret();
+                const payload = {
+                    secret,
+                    lastUsedCode: "",
+                    tries: 0,
+                } as TwoFaSetup;
+                await this.store.setex(
+                    this.getKey(userId),
+                    this.EXPIRY_TIME,
+                    JSON.stringify(payload),
+                );
+                logger.info("Created temp 2FA session", {
+                    ...fctx,
+                    userId,
+                    expiresIn: this.EXPIRY_TIME,
+                });
+                return secret;
+            })(),
+        ).mapErr(() =>
+            twofaErrors.dbError(fctx, "Setting to data store failed"),
+        );
+    }
+
+    verifyAndEnable2FA(
+        fctx: FlowExecCtx,
+        userId: string,
+        code: string,
+    ): ResultAsync<boolean, Err> {
+        logger.info("Verifying and enabling 2FA", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.store.get(this.getKey(userId)),
+            () => twofaErrors.dbError(fctx, "Failed to get setup session"),
+        )
+            .andThen((payload) => {
+                if (!payload) {
+                    logger.error("Setup session not found", {
+                        ...fctx,
+                        userId,
+                    });
+                    return errAsync(twofaErrors.setupNotFound(fctx));
+                }
+                return okAsync(JSON.parse(payload) as TwoFaSetup);
+            })
+            .andThen((payloadObj) => {
+                const key = this.getKey(userId);
+
+                if (payloadObj.tries >= this.MAX_SETUP_ATTEMPTS) {
+                    logger.warn("Max setup attempts reached", {
+                        ...fctx,
+                        userId,
+                        tries: payloadObj.tries,
+                    });
+                    return ResultAsync.fromPromise(this.store.del(key), () =>
+                        twofaErrors.dbError(
+                            fctx,
+                            "Failed to delete setup session",
+                        ),
+                    ).andThen(() =>
+                        errAsync(twofaErrors.maxAttemptsReached(fctx)),
+                    );
+                }
+
+                if (
+                    !this.checkTotp(payloadObj.secret, code) ||
+                    code === payloadObj.lastUsedCode
+                ) {
+                    logger.warn("Invalid 2FA code during setup", {
+                        ...fctx,
+                        userId,
+                        tries: payloadObj.tries + 1,
+                        codeReused: code === payloadObj.lastUsedCode,
+                    });
+                    return ResultAsync.fromPromise(
+                        this.store.setex(
+                            key,
+                            this.EXPIRY_TIME,
+                            JSON.stringify({
+                                secret: payloadObj.secret,
+                                lastUsedCode: code,
+                                tries: payloadObj.tries + 1,
+                            }),
+                        ),
+                        () =>
+                            twofaErrors.dbError(
+                                fctx,
+                                "Failed to update setup session",
+                            ),
+                    ).map(() => false);
+                }
+
+                logger.info("2FA code verified successfully, enabling 2FA", {
+                    ...fctx,
+                    userId,
+                });
+
+                return ResultAsync.fromPromise(this.store.del(key), () =>
+                    twofaErrors.dbError(fctx, "Failed to delete setup session"),
+                )
+                    .andThen(() =>
+                        ResultAsync.fromPromise(
+                            this.db
+                                .insert(twoFactor)
+                                .values({
+                                    id: nanoid(),
+                                    secret: payloadObj.secret,
+                                    userId: userId,
+                                    createdAt: new Date(),
+                                    updatedAt: new Date(),
+                                })
+                                .execute(),
+                            () =>
+                                twofaErrors.dbError(
+                                    fctx,
+                                    "Failed to insert 2FA record",
+                                ),
+                        ),
+                    )
+                    .map(() => {
+                        logger.info("2FA enabled successfully", {
+                            ...fctx,
+                            userId,
+                        });
+                        return true;
+                    });
+            });
+    }
+
+    disable(fctx: FlowExecCtx, userId: string): ResultAsync<boolean, Err> {
+        logger.info("Disabling 2FA", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.db
+                .delete(twoFactor)
+                .where(eq(twoFactor.userId, userId))
+                .execute(),
+            () => twofaErrors.dbError(fctx, "Failed to delete 2FA record"),
+        ).map((result) => {
+            logger.info("2FA disabled successfully", { ...fctx, userId });
+            return true;
+        });
+    }
+
+    generateBackupCodes(
+        fctx: FlowExecCtx,
+        userId: string,
+    ): ResultAsync<string[], Err> {
+        logger.info("Generating backup codes", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.db.query.twoFactor.findFirst({
+                where: eq(twoFactor.userId, userId),
+            }),
+            () => twofaErrors.dbError(fctx, "Failed to query 2FA info"),
+        )
+            .andThen((found) => {
+                if (!found) {
+                    logger.error("2FA not enabled for user", {
+                        ...fctx,
+                        userId,
+                    });
+                    return errAsync(twofaErrors.backupCodesNotFound(fctx));
+                }
+                if (found.backupCodes && found.backupCodes.length) {
+                    logger.warn("Backup codes already generated", {
+                        ...fctx,
+                        userId,
+                    });
+                    return errAsync(
+                        twofaErrors.backupCodesAlreadyGenerated(fctx),
+                    );
+                }
+                return okAsync(found);
+            })
+            .andThen(() => {
+                const codes = Array.from(
+                    { length: this.DEFAULT_BACKUP_CODES_AMT },
+                    () => nanoid(12),
+                );
+
+                logger.debug("Backup codes generated, hashing", {
+                    ...fctx,
+                    userId,
+                    count: codes.length,
+                });
+
+                return ResultAsync.fromPromise(
+                    (async () => {
+                        const hashed = [];
+                        for (const code of codes) {
+                            const hash = await hashString(code);
+                            hashed.push(hash);
+                        }
+                        return { codes, hashed };
+                    })(),
+                    () =>
+                        twofaErrors.dbError(
+                            fctx,
+                            "Failed to hash backup codes",
+                        ),
+                ).andThen(({ codes, hashed }) =>
+                    ResultAsync.fromPromise(
+                        this.db
+                            .update(twoFactor)
+                            .set({ backupCodes: hashed })
+                            .where(eq(twoFactor.userId, userId))
+                            .returning(),
+                        () =>
+                            twofaErrors.dbError(
+                                fctx,
+                                "Failed to update backup codes",
+                            ),
+                    ).map(() => {
+                        logger.info("Backup codes generated successfully", {
+                            ...fctx,
+                            userId,
+                        });
+                        return codes;
+                    }),
+                );
+            });
+    }
+
+    get2FASecret(
+        fctx: FlowExecCtx,
+        userId: string,
+    ): ResultAsync<string | null, Err> {
+        logger.debug("Getting 2FA secret", { ...fctx, userId });
+
+        return ResultAsync.fromPromise(
+            this.db
+                .select()
+                .from(twoFactor)
+                .where(eq(twoFactor.userId, userId))
+                .limit(1),
+            () => twofaErrors.dbError(fctx, "Failed to query 2FA secret"),
+        ).map((result) => {
+            if (!result.length) {
+                logger.debug("No 2FA secret found", { ...fctx, userId });
+                return null;
+            }
+            logger.debug("2FA secret retrieved", { ...fctx, userId });
+            return result[0].secret;
+        });
+    }
+
+    createSession(
+        fctx: FlowExecCtx,
+        params: {
+            userId: string;
+            sessionId: string;
+            ipAddress?: string;
+            userAgent?: string;
+        },
+    ): ResultAsync<TwoFaSession, Err> {
+        logger.info("Creating 2FA verification session", {
+            ...fctx,
+            userId: params.userId,
+            sessionId: params.sessionId,
+        });
+
+        return ResultAsync.fromSafePromise(
+            (async () => {
+                const expiryMinutes = settings.twofaSessionExpiryMinutes || 10;
+                const now = new Date();
+                const expiresAt = new Date(
+                    now.getTime() + expiryMinutes * 60 * 1000,
+                );
+
+                return { expiresAt, now, params };
+            })(),
+        ).andThen(({ expiresAt, now, params }) =>
+            ResultAsync.fromPromise(
+                this.db
+                    .insert(twofaSessions)
+                    .values({
+                        id: nanoid(),
+                        userId: params.userId,
+                        sessionId: params.sessionId,
+                        verificationToken: nanoid(32),
+                        status: "pending",
+                        attempts: 0,
+                        maxAttempts: 5,
+                        expiresAt,
+                        createdAt: now,
+                        ipAddress: params.ipAddress,
+                        userAgent: params.userAgent,
+                    })
+                    .returning(),
+                () => twofaErrors.dbError(fctx, "Failed to create 2FA session"),
+            ).map(([session]) => {
+                logger.info("2FA verification session created", {
+                    ...fctx,
+                    sessionId: session.id,
+                    userId: params.userId,
+                });
+                return session as TwoFaSession;
+            }),
+        );
+    }
+
+    getSessionByToken(
+        fctx: FlowExecCtx,
+        token: string,
+    ): ResultAsync<TwoFaSession | null, Err> {
+        logger.debug("Getting 2FA session by token", { ...fctx });
+
+        return ResultAsync.fromPromise(
+            this.db
+                .select()
+                .from(twofaSessions)
+                .where(
+                    and(
+                        eq(twofaSessions.verificationToken, token),
+                        gt(twofaSessions.expiresAt, new Date()),
+                    ),
+                )
+                .limit(1),
+            () => twofaErrors.dbError(fctx, "Failed to query 2FA session"),
+        ).map((result) => {
+            if (!result.length) {
+                logger.warn("2FA session not found or expired", { ...fctx });
+                return null;
+            }
+            logger.debug("2FA session found", {
+                ...fctx,
+                sessionId: result[0].id,
+            });
+            return result[0] as TwoFaSession;
+        });
+    }
+
+    updateSession(
+        fctx: FlowExecCtx,
+        id: string,
+        updates: Partial<
+            Pick<
+                TwoFaSession,
+                "status" | "attempts" | "verifiedAt" | "codeUsed"
+            >
+        >,
+    ): ResultAsync<TwoFaSession, Err> {
+        logger.debug("Updating 2FA session", {
+            ...fctx,
+            sessionId: id,
+            updates,
+        });
+
+        return ResultAsync.fromPromise(
+            this.db
+                .update(twofaSessions)
+                .set(updates)
+                .where(eq(twofaSessions.id, id))
+                .returning(),
+            () => twofaErrors.dbError(fctx, "Failed to update 2FA session"),
+        ).andThen(([session]) => {
+            if (!session) {
+                logger.error("2FA session not found for update", {
+                    ...fctx,
+                    sessionId: id,
+                });
+                return errAsync(twofaErrors.sessionNotFoundById(fctx));
+            }
+            logger.debug("2FA session updated successfully", {
+                ...fctx,
+                sessionId: id,
+            });
+            return okAsync(session as TwoFaSession);
+        });
+    }
+
+    incrementAttempts(
+        fctx: FlowExecCtx,
+        id: string,
+    ): ResultAsync<TwoFaSession, Err> {
+        logger.debug("Incrementing session attempts", {
+            ...fctx,
+            sessionId: id,
+        });
+
+        return ResultAsync.fromPromise(
+            this.db.query.twofaSessions.findFirst({
+                where: eq(twofaSessions.id, id),
+                columns: { id: true, attempts: true },
+            }),
+            () =>
+                twofaErrors.dbError(
+                    fctx,
+                    "Failed to query session for increment",
+                ),
+        )
+            .andThen((s) => {
+                if (!s) {
+                    logger.error("Session not found for increment", {
+                        ...fctx,
+                        sessionId: id,
+                    });
+                    return errAsync(twofaErrors.sessionNotFoundById(fctx));
+                }
+                return okAsync(s);
+            })
+            .andThen((s) =>
+                ResultAsync.fromPromise(
+                    this.db
+                        .update(twofaSessions)
+                        .set({ attempts: s.attempts + 1 })
+                        .where(eq(twofaSessions.id, id))
+                        .returning(),
+                    () =>
+                        twofaErrors.dbError(
+                            fctx,
+                            "Failed to increment attempts",
+                        ),
+                ).andThen(([session]) => {
+                    if (!session) {
+                        logger.error("Session not found after increment", {
+                            ...fctx,
+                            sessionId: id,
+                        });
+                        return errAsync(twofaErrors.sessionNotFoundById(fctx));
+                    }
+
+                    logger.warn("Failed verification attempt", {
+                        ...fctx,
+                        sessionId: session.id,
+                        attempts: session.attempts,
+                    });
+
+                    return okAsync(session as TwoFaSession);
+                }),
+            );
+    }
+
+    cleanupExpiredSessions(fctx: FlowExecCtx): ResultAsync<number, Err> {
+        logger.info("Cleaning up expired 2FA sessions", { ...fctx });
+
+        return ResultAsync.fromPromise(
+            this.db
+                .delete(twofaSessions)
+                .where(lt(twofaSessions.expiresAt, new Date())),
+            () =>
+                twofaErrors.dbError(fctx, "Failed to cleanup expired sessions"),
+        ).map((result) => {
+            const count = result.rowCount || 0;
+            logger.info("Expired sessions cleaned up", { ...fctx, count });
+            return count;
+        });
+    }
+}

packages/logic/domains/2fa/router.ts

@@ -0,0 +1,170 @@
+import {
+    disable2FASchema,
+    enable2FACodeSchema,
+    startVerificationSchema,
+    verifyCodeSchema,
+} from "./data";
+import { sValidator } from "@hono/standard-validator";
+import { HonoContext } from "@/core/hono.helpers";
+import { getTwofaController } from "./controller";
+import { auth } from "@domains/auth/config.base";
+import { Hono } from "hono";
+
+const twofaController = getTwofaController();
+
+export const twofaRouter = new Hono<HonoContext>()
+    .post("/setup", async (c) => {
+        const res = await twofaController.setup2FA(
+            c.env.locals.fCtx,
+            c.env.locals.user,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    })
+    .post(
+        "/verify-and-enable",
+        sValidator("json", enable2FACodeSchema),
+        async (c) => {
+            const data = c.req.valid("json");
+            const res = await twofaController.verifyAndEnable2FA(
+                c.env.locals.fCtx,
+                c.env.locals.user,
+                data.code,
+                c.req.raw.headers,
+            );
+            return c.json(
+                res.isOk()
+                    ? { data: res.value, error: null }
+                    : { data: null, error: res.error },
+                res.isOk() ? 200 : 400,
+            );
+        },
+    )
+    .get("/generate-backup-codes", async (c) => {
+        const res = await twofaController.generateBackupCodes(
+            c.env.locals.fCtx,
+            c.env.locals.user,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    })
+    .delete("/disable", sValidator("json", disable2FASchema), async (c) => {
+        const data = c.req.valid("json");
+        const res = await twofaController.disable(
+            c.env.locals.fCtx,
+            c.env.locals.user,
+            data.code,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    })
+    .get("/requires-verification", async (c) => {
+        const user = c.env.locals.user;
+        const sessionId = c.req.query("sessionId")?.toString() ?? "";
+        const res = await twofaController.requiresInitialVerification(
+            c.env.locals.fCtx,
+            user,
+            sessionId,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    })
+    .get("/requires-sensitive-action", async (c) => {
+        const res = await twofaController.requiresSensitiveActionVerification(
+            c.env.locals.fCtx,
+            c.env.locals.user,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    })
+    .post(
+        "/start-verification-session",
+        sValidator("json", startVerificationSchema),
+        async (c) => {
+            const data = c.req.valid("json");
+
+            const ipAddress =
+                c.req.header("x-forwarded-for") ||
+                c.req.header("x-real-ip") ||
+                "unknown";
+            const userAgent = c.req.header("user-agent") || "unknown";
+
+            const res = await twofaController.startVerification(
+                c.env.locals.fCtx,
+                {
+                    userId: data.userId,
+                    sessionId: data.sessionId,
+                    ipAddress,
+                    userAgent,
+                },
+            );
+
+            return c.json(
+                res.isOk()
+                    ? { data: res.value, error: null }
+                    : { data: null, error: res.error },
+            );
+        },
+    )
+    .post(
+        "/verify-session-code",
+        sValidator("json", verifyCodeSchema),
+        async (c) => {
+            const data = c.req.valid("json");
+
+            let user = c.env.locals.user;
+            if (!user) {
+                const out = await auth.api.getSession({
+                    headers: c.req.raw.headers,
+                });
+                user = out?.user as any;
+            }
+
+            const res = await twofaController.verifyCode(
+                c.env.locals.fCtx,
+                {
+                    verificationSessToken: data.verificationToken,
+                    code: data.code,
+                },
+                user,
+            );
+
+            return c.json(
+                res.isOk()
+                    ? { data: res.value, error: null }
+                    : { data: null, error: res.error },
+                res.isOk() ? 200 : 400,
+            );
+        },
+    )
+    .post("/cleanup-expired-sessions", async (c) => {
+        const res = await twofaController.cleanupExpiredSessions(
+            c.env.locals.fCtx,
+        );
+        return c.json(
+            res.isOk()
+                ? { data: res.value, error: null }
+                : { data: null, error: res.error },
+            res.isOk() ? 200 : 400,
+        );
+    });

packages/logic/domains/2fa/sensitive-actions.ts

@@ -0,0 +1,43 @@
+import { FlowExecCtx } from "@core/flow.execution.context";
+import { getTwofaController } from "./controller";
+import type { User } from "@/domains/user/data";
+
+const twofaController = getTwofaController();
+
+/**
+ * Check if user needs 2FA verification for sensitive actions
+ * Call this before executing sensitive operations like:
+ * - Changing password
+ * - Viewing billing info
+ * - Deleting account
+ * - etc.
+ */
+export async function requiresSensitiveAction2FA(
+    fctx: FlowExecCtx,
+    user: User,
+): Promise<boolean> {
+    const result = await twofaController.requiresSensitiveActionVerification(
+        fctx,
+        user,
+    );
+    return result.match(
+        (data) => data,
+        () => true, // On error, require verification for security
+    );
+}
+
+export async function checkInitial2FaRequired(
+    fctx: FlowExecCtx,
+    user: User,
+    sessionId: string,
+): Promise<boolean> {
+    const result = await twofaController.requiresInitialVerification(
+        fctx,
+        user,
+        sessionId,
+    );
+    return result.match(
+        (data) => data,
+        () => true,
+    );
+}