@adminforth/two-factors-auth 4.5.0 → 4.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdminForthPlugin, RateLimiter } from "adminforth";
+import { AdminForthPlugin, HttpExtra, RateLimiter } from "adminforth";
 import type { AdminForthResource, AdminUser, IAdminForth, IHttpServer, IAdminForthAuth } from "adminforth";
 import { PluginOptions } from "./types.js";
 import { PasskeyService } from "./services/passkeyService.js";
@@ -6,6 +6,10 @@ import { TotpService } from "./services/totpService.js";
 import { type MfaConfirmationResult, type VerifyOptions } from "./services/verifyMfaConfirmation.js";
 import { CookieService } from "./services/cookieService.js";
 import { UserRepository } from "./repositories/userRepository.js";
+import { TwoFactorErrorCode } from "./utils/errors.js";
+import type { VerificationResult } from "./utils/types.js";
+export { TwoFactorErrorCode };
+export type { VerificationResult };
 export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     options: PluginOptions;
     adminforth: IAdminForth;
@@ -17,6 +21,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     userRepository: UserRepository;
     passkeyLoginRateLimiters: RateLimiter[];
     private ctx;
+    private readonly mfaRequestContext;
     constructor(options: PluginOptions);
     instanceUniqueRepresentation(pluginOptions: any): string;
     checkIfSkipSetupAllowSkipVerify(adminUser: AdminUser): Promise<{
@@ -25,12 +30,11 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     private pending;
     private waitForResponse;
     private resolveResponse;
-    verifyAuto(adminUser: AdminUser): Promise<any>;
-    verify(confirmationResult: MfaConfirmationResult, opts: VerifyOptions): Promise<{
-        ok: true;
-    } | {
-        error: string;
-    }>;
+    withVerificationContext<T>(confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra, callback: () => Promise<T>): Promise<(import("./utils/types.js").VerificationFailure & {
+        actionDescription?: string;
+    }) | T>;
+    verifyAuto(adminUser: AdminUser, actionDescription?: string): Promise<any>;
+    verify(confirmationResult: MfaConfirmationResult | undefined, opts: VerifyOptions): Promise<VerificationResult>;
     modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource): void;
     validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource): void;
     activate(resourceConfig: AdminForthResource, adminforth: IAdminForth): void;

package/dist/index.js

@@ -12,6 +12,7 @@ import * as AdminForthRuntime from "adminforth";
 import { PasskeyService } from "./services/passkeyService.js";
 import { TotpService } from "./services/totpService.js";
 import { verifyMfaConfirmation } from "./services/verifyMfaConfirmation.js";
+import { MfaRequestContext } from './services/mfaRequestContext.js';
 import { CookieService } from "./services/cookieService.js";
 import { UserRepository } from "./repositories/userRepository.js";
 import { registerPasskeyEndpoints } from "./endpoints/registerPasskeyEndpoints.js";
@@ -19,12 +20,15 @@ import { registerTwoFaEndpoints } from "./endpoints/registerTwoFaEndpoints.js";
 import { createPasskeyHandlers } from "./handlers/createPasskeyHandlers.js";
 import { createTwoFaHandlers } from "./handlers/createTwoFaHandlers.js";
 import { parsePeriod } from "./utils/parsePeriod.js";
+import { TwoFactorErrorCode } from "./utils/errors.js";
 import crypto from 'crypto';
+export { TwoFactorErrorCode };
 const getRequestWebsocketClientId = AdminForthRuntime.getRequestWebsocketClientId;
 export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     constructor(options) {
         super(options, import.meta.url);
         this.passkeyLoginRateLimiters = [];
+        this.mfaRequestContext = new MfaRequestContext();
         this.pending = new Map();
         this.options = options;
         this.shouldHaveSingleInstancePerWholeApp = () => true;
@@ -66,7 +70,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
             };
             timeout = setTimeout(() => {
                 cleanup();
-                resolve({ ok: false, error: 'Verification timed out' });
+                resolve({ ok: false, error: 'Verification timed out', code: TwoFactorErrorCode.TIMEOUT });
             }, timeoutMs);
             this.pending.set(id, (value) => {
                 cleanup();
@@ -80,16 +84,30 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
             resolve(data);
         }
     }
-    verifyAuto(adminUser) {
+    withVerificationContext(confirmationResult, extra, callback) {
+        return this.mfaRequestContext.run(confirmationResult, extra, callback);
+    }
+    verifyAuto(adminUser, actionDescription) {
         return __awaiter(this, void 0, void 0, function* () {
+            const contextualResult = yield this.mfaRequestContext.verify(adminUser, actionDescription, (confirmationResult, extra) => this.verify(confirmationResult, {
+                adminUser,
+                userPk: adminUser.pk,
+                extra,
+            }));
+            if (contextualResult)
+                return contextualResult;
             const websocketClientId = getRequestWebsocketClientId === null || getRequestWebsocketClientId === void 0 ? void 0 : getRequestWebsocketClientId();
             if (!websocketClientId) {
-                return { ok: false, error: '2FA auto verification requires an active browser request context' };
+                return {
+                    ok: false,
+                    error: '2FA auto verification requires an active browser request context',
+                    code: TwoFactorErrorCode.BROWSER_CONTEXT_REQUIRED,
+                };
             }
             const sessionId = crypto.randomUUID();
             const jwt = this.adminforth.auth.issueJWT({ sessionId, adminUserPk: adminUser.pk }, 'auto2FA', '5m');
             const resultPromise = this.waitForResponse(jwt, 5 * 60 * 1000);
-            this.adminforth.websocket.publish(`/user2fa/${adminUser.pk}/${websocketClientId}`, { sessionId: jwt });
+            this.adminforth.websocket.publish(`/user2fa/${adminUser.pk}/${websocketClientId}`, { sessionId: jwt, actionDescription });
             const result = yield resultPromise;
             this.adminforth.websocket.publish(`/user2fa/${adminUser.pk}/${websocketClientId}/resolve`, { sessionId: jwt });
             return result;
@@ -107,7 +125,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
         this.adminForthAuth = adminforth.auth;
         this.userRepository = new UserRepository(this.adminforth, this.options);
         this.cookieService = new CookieService(this.adminforth, this.options);
-        this.totpService = new TotpService(this.options, this.userRepository);
+        this.totpService = new TotpService(this.options, this.userRepository, this.adminforth);
         this.passkeyService = new PasskeyService(this.options, this.adminforth, this.userRepository, undefined, this.cookieService);
         this.passkeyLoginRateLimiters = adminforth.config.auth.rateLimit.map((rate) => new RateLimiter(rate));
         this.ctx = {

package/dist/services/mfaRequestContext.d.ts

@@ -0,0 +1,13 @@
+import type { AdminUser, HttpExtra } from 'adminforth';
+import type { MfaConfirmationResult } from './verifyMfaConfirmation.js';
+import type { VerificationFailure, VerificationResult } from '../utils/types.js';
+type ContextualVerificationFailure = VerificationFailure & {
+    actionDescription?: string;
+};
+/** Keeps verification within one external request, including every CRUD hook it invokes. */
+export declare class MfaRequestContext {
+    private readonly storage;
+    run<T>(confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra, callback: () => Promise<T>): Promise<T | ContextualVerificationFailure>;
+    verify(adminUser: AdminUser, actionDescription: string | undefined, verifier: (confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra) => Promise<VerificationResult>): Promise<VerificationResult | undefined>;
+}
+export {};

package/dist/services/mfaRequestContext.js

@@ -0,0 +1,50 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AsyncLocalStorage } from 'node:async_hooks';
+class MfaVerificationError extends Error {
+    constructor(result) {
+        super(result.error);
+        this.result = result;
+    }
+}
+/** Keeps verification within one external request, including every CRUD hook it invokes. */
+export class MfaRequestContext {
+    constructor() {
+        this.storage = new AsyncLocalStorage();
+    }
+    run(confirmationResult, extra, callback) {
+        return this.storage.run({ confirmationResult, extra, results: new Map() }, () => __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield callback();
+            }
+            catch (error) {
+                if (error instanceof MfaVerificationError)
+                    return error.result;
+                throw error;
+            }
+        }));
+    }
+    verify(adminUser, actionDescription, verifier) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = this.storage.getStore();
+            if (!context)
+                return undefined;
+            let result = context.results.get(adminUser.pk);
+            if (!result) {
+                result = verifier(context.confirmationResult, context.extra);
+                context.results.set(adminUser.pk, result);
+            }
+            const verified = yield result;
+            if ('error' in verified)
+                throw new MfaVerificationError(Object.assign(Object.assign({}, verified), { actionDescription }));
+            return verified;
+        });
+    }
+}

package/dist/services/totpService.d.ts

@@ -1,21 +1,20 @@
-import type { AdminUser } from "adminforth";
+import { type AdminUser, type IAdminForth } from "adminforth";
 import type { PluginOptions } from "../types.js";
 import { UserRepository } from "../repositories/userRepository.js";
+import type { VerificationFailure, VerificationResult } from "../utils/types.js";
 export declare class TotpService {
     private readonly options;
     private readonly userRepository;
-    constructor(options: PluginOptions, userRepository: UserRepository);
+    private readonly adminforth;
+    private readonly codeAttemptLimiters;
+    constructor(options: PluginOptions, userRepository: UserRepository, adminforth: IAdminForth);
     generateSecret(issuerName: string, userName: string): string;
     verifySecret(secret: string, code: string): boolean;
-    verifyUserCode(userPk: string, code: string): Promise<{
-        ok: true;
-    } | {
-        error: string;
-    }>;
+    verifyUserCode(userPk: string, code: string): Promise<VerificationResult>;
     verifyAdminUserCode(adminUser: AdminUser, code: string): Promise<{
         ok: true;
-    } | {
-        error: string;
-    }>;
+        verifiedCodeToken: string;
+    } | VerificationFailure>;
+    isVerifiedCodeToken(token: string, userPk: string): Promise<boolean>;
     saveSecret(userPk: string, secret: string): Promise<void>;
 }

package/dist/services/totpService.js

@@ -7,11 +7,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { RateLimiter } from "adminforth";
 import twofactor from 'node-2fa';
+import { TwoFactorErrorCode } from "../utils/errors.js";
+const CODE_ATTEMPT_RATE_LIMITS = ['30/1m', '300/1h', '1000/1d'];
+const VERIFIED_CODE_JWT_TYPE = 'verifiedTotpCode';
+const VERIFIED_CODE_TOKEN_TTL = '1m';
 export class TotpService {
-    constructor(options, userRepository) {
+    constructor(options, userRepository, adminforth) {
         this.options = options;
         this.userRepository = userRepository;
+        this.adminforth = adminforth;
+        this.codeAttemptLimiters = CODE_ATTEMPT_RATE_LIMITS.map((rate) => new RateLimiter(rate));
     }
     generateSecret(issuerName, userName) {
         return twofactor.generateSecret({ name: issuerName, account: userName }).secret;
@@ -21,18 +28,33 @@ export class TotpService {
     }
     verifyUserCode(userPk, code) {
         return __awaiter(this, void 0, void 0, function* () {
+            const attemptsAllowed = yield Promise.all(this.codeAttemptLimiters.map((limiter) => limiter.consume(userPk)));
+            if (!attemptsAllowed.every(Boolean)) {
+                return { error: "Too many attempts to enter the code. Try again later.", code: TwoFactorErrorCode.RATE_LIMITED };
+            }
             const user = yield this.userRepository.getAuthUser(userPk);
             if (!user)
-                return { error: "User not found" };
+                return { error: "User not found", code: TwoFactorErrorCode.USER_NOT_FOUND };
             const secret = this.userRepository.getSecret(user);
             if (!secret)
-                return { error: "2FA is not set up for this user" };
-            return this.verifySecret(secret, code) ? { ok: true } : { error: "Wrong or expired OTP code" };
+                return { error: "2FA is not set up for this user", code: TwoFactorErrorCode.NOT_SET_UP };
+            return this.verifySecret(secret, code)
+                ? { ok: true }
+                : { error: "Wrong or expired OTP code", code: TwoFactorErrorCode.INVALID };
         });
     }
     verifyAdminUserCode(adminUser, code) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.verifyUserCode(this.userRepository.getUserPk(adminUser), code);
+            const result = yield this.verifyUserCode(this.userRepository.getUserPk(adminUser), code);
+            if ('error' in result)
+                return result;
+            return { ok: true, verifiedCodeToken: this.adminforth.auth.issueJWT({ pk: adminUser.pk }, VERIFIED_CODE_JWT_TYPE, VERIFIED_CODE_TOKEN_TTL) };
+        });
+    }
+    isVerifiedCodeToken(token, userPk) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const payload = yield this.adminforth.auth.verify(token, VERIFIED_CODE_JWT_TYPE, false);
+            return (payload === null || payload === void 0 ? void 0 : payload.pk) === userPk;
         });
     }
     saveSecret(userPk, secret) {

package/dist/services/verifyMfaConfirmation.d.ts

@@ -1,9 +1,13 @@
 import type { AdminUser, HttpExtra, IAdminForthHttpResponse } from "adminforth";
-import type { CookieList } from "../utils/types.js";
+import type { CookieList, VerificationResult } from "../utils/types.js";
 type TotpConfirmationResult = {
     mode: "totp";
     result: string;
 };
+type VerifiedTotpConfirmationResult = {
+    mode: "verifiedTotp";
+    result: string;
+};
 type PasskeyConfirmationResult = {
     mode: "passkey";
     result: {
@@ -14,7 +18,7 @@ type PasskeyConfirmationResult = {
 type GraceConfirmationResult = {
     mode?: undefined;
 };
-export type MfaConfirmationResult = TotpConfirmationResult | PasskeyConfirmationResult | GraceConfirmationResult;
+export type MfaConfirmationResult = TotpConfirmationResult | VerifiedTotpConfirmationResult | PasskeyConfirmationResult | GraceConfirmationResult;
 export type VerifyOptions = {
     adminUser: AdminUser;
     userPk: string;
@@ -22,9 +26,5 @@ export type VerifyOptions = {
     response?: IAdminForthHttpResponse;
     extra?: HttpExtra;
 };
-export declare function verifyMfaConfirmation(ctx: any, confirmationResult: MfaConfirmationResult, opts: VerifyOptions): Promise<{
-    ok: true;
-} | {
-    error: string;
-}>;
+export declare function verifyMfaConfirmation(ctx: any, confirmationResult: MfaConfirmationResult | undefined, opts: VerifyOptions): Promise<VerificationResult>;
 export {};

package/dist/services/verifyMfaConfirmation.js

@@ -7,11 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { TwoFactorErrorCode } from "../utils/errors.js";
 export function verifyMfaConfirmation(ctx, confirmationResult, opts) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
-        if (!confirmationResult)
-            return { error: "Confirmation result is required" };
+        var _a, _b, _c;
+        const mode = confirmationResult === null || confirmationResult === void 0 ? void 0 : confirmationResult.mode;
         const cookies = ((_a = opts.extra) === null || _a === void 0 ? void 0 : _a.cookies) || opts.cookies;
         const response = ((_b = opts.extra) === null || _b === void 0 ? void 0 : _b.response) || opts.response;
         if (ctx.options.usersFilterToApply) {
@@ -26,42 +26,45 @@ export function verifyMfaConfirmation(ctx, confirmationResult, opts) {
                 return { ok: true };
             }
         }
-        if (ctx.options.stepUpMfaGracePeriodSeconds && ((_c = opts.extra) === null || _c === void 0 ? void 0 : _c.headers) && !confirmationResult.mode) {
+        if (ctx.options.stepUpMfaGracePeriodSeconds && ((_c = opts.extra) === null || _c === void 0 ? void 0 : _c.headers) && !mode) {
             const verificationResult = yield ctx.cookieService.isMfaGraceValid(opts.extra.headers, cookies);
             if (verificationResult === true) {
                 return { ok: true };
             }
         }
-        const mode = confirmationResult.mode;
         if (!mode) {
-            return { error: "Unsupported confirmation mode" };
+            return { error: "Confirmation result is required", code: TwoFactorErrorCode.REQUIRED };
         }
+        const confirmed = () => {
+            var _a;
+            if (ctx.options.stepUpMfaGracePeriodSeconds) {
+                ctx.cookieService.issueMfaGrace({ headers: (_a = opts.extra) === null || _a === void 0 ? void 0 : _a.headers, response }, cookies);
+            }
+            return { ok: true };
+        };
         if (mode === "totp") {
             const { result: code } = confirmationResult;
             const verificationResult = yield ctx.totpService.verifyUserCode(opts.userPk, code);
-            if ('ok' in verificationResult && verificationResult.ok) {
-                if (ctx.options.stepUpMfaGracePeriodSeconds) {
-                    ctx.cookieService.issueMfaGrace({ headers: (_d = opts.extra) === null || _d === void 0 ? void 0 : _d.headers, response }, cookies);
-                }
-                return { ok: true };
-            }
-            return verificationResult;
+            return 'error' in verificationResult ? verificationResult : confirmed();
+        }
+        else if (mode === "verifiedTotp") {
+            const { result: token } = confirmationResult;
+            return (yield ctx.totpService.isVerifiedCodeToken(token, opts.userPk))
+                ? confirmed()
+                : { error: "The code confirmation expired. Enter the code again.", code: TwoFactorErrorCode.INVALID };
         }
         else if (mode === "passkey") {
             const { result } = confirmationResult;
             const cookiesValidationResult = yield ctx.passkeyService.validateLoginChallengeCookie(cookies);
             if (!cookiesValidationResult.ok) {
-                return { error: cookiesValidationResult.error };
+                return { error: cookiesValidationResult.error, code: TwoFactorErrorCode.INVALID };
             }
             const verificationResult = yield ctx.passkeyService.verifyPasskeyResponse(result, opts.userPk, cookiesValidationResult.decodedPasskeysCookies);
             if (verificationResult.ok && verificationResult.passkeyConfirmed) {
-                if (ctx.options.stepUpMfaGracePeriodSeconds) {
-                    ctx.cookieService.issueMfaGrace({ headers: (_e = opts.extra) === null || _e === void 0 ? void 0 : _e.headers, response }, cookies);
-                }
-                return { ok: true };
+                return confirmed();
             }
-            return { error: "Invalid passkey" };
+            return { error: "Invalid passkey", code: TwoFactorErrorCode.INVALID };
         }
-        return { error: "Unsupported confirmation mode" };
+        return { error: "Unsupported confirmation mode", code: TwoFactorErrorCode.UNSUPPORTED_MODE };
     });
 }

package/dist/utils/errors.d.ts

@@ -7,6 +7,19 @@ export declare enum HttpStatus {
     TOO_MANY_REQUESTS = 429,
     INTERNAL_SERVER_ERROR = 500
 }
+export declare enum TwoFactorErrorCode {
+    REQUIRED = "TWO_FACTOR_REQUIRED",
+    INVALID = "TWO_FACTOR_INVALID",
+    RATE_LIMITED = "TWO_FACTOR_RATE_LIMITED",
+    NOT_SET_UP = "TWO_FACTOR_NOT_SET_UP",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    UNSUPPORTED_MODE = "UNSUPPORTED_CONFIRMATION_MODE",
+    BROWSER_CONTEXT_REQUIRED = "BROWSER_CONTEXT_REQUIRED",
+    CANCELLED = "VERIFICATION_CANCELLED",
+    TIMEOUT = "VERIFICATION_TIMEOUT",
+    INVALID_SESSION = "INVALID_VERIFICATION_SESSION",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
 export declare function respondWithStatus<T>(body: T, response: IAdminForthHttpResponse, status: HttpStatus): T;
 export declare function errorMessage(error: unknown): string;
 export declare function errorResult(message: string): ErrorResponse;

package/dist/utils/errors.js

@@ -6,6 +6,20 @@ export var HttpStatus;
     HttpStatus[HttpStatus["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
     HttpStatus[HttpStatus["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
 })(HttpStatus || (HttpStatus = {}));
+export var TwoFactorErrorCode;
+(function (TwoFactorErrorCode) {
+    TwoFactorErrorCode["REQUIRED"] = "TWO_FACTOR_REQUIRED";
+    TwoFactorErrorCode["INVALID"] = "TWO_FACTOR_INVALID";
+    TwoFactorErrorCode["RATE_LIMITED"] = "TWO_FACTOR_RATE_LIMITED";
+    TwoFactorErrorCode["NOT_SET_UP"] = "TWO_FACTOR_NOT_SET_UP";
+    TwoFactorErrorCode["USER_NOT_FOUND"] = "USER_NOT_FOUND";
+    TwoFactorErrorCode["UNSUPPORTED_MODE"] = "UNSUPPORTED_CONFIRMATION_MODE";
+    TwoFactorErrorCode["BROWSER_CONTEXT_REQUIRED"] = "BROWSER_CONTEXT_REQUIRED";
+    TwoFactorErrorCode["CANCELLED"] = "VERIFICATION_CANCELLED";
+    TwoFactorErrorCode["TIMEOUT"] = "VERIFICATION_TIMEOUT";
+    TwoFactorErrorCode["INVALID_SESSION"] = "INVALID_VERIFICATION_SESSION";
+    TwoFactorErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(TwoFactorErrorCode || (TwoFactorErrorCode = {}));
 export function respondWithStatus(body, response, status) {
     response.setStatus(status);
     return body;

package/dist/utils/types.d.ts

@@ -1,4 +1,5 @@
 import type { HttpExtra } from "adminforth";
+import type { TwoFactorErrorCode } from "./errors.js";
 export type AnyRecord = Record<string, any>;
 export type CookieList = HttpExtra["cookies"];
 export type HttpHeaders = HttpExtra["headers"];
@@ -11,3 +12,10 @@ export type OkResponse<T extends AnyRecord = AnyRecord> = {
     ok: true;
 } & T;
 export type PluginResponse<T extends AnyRecord = AnyRecord> = OkResponse<T> | ErrorResponse;
+export type VerificationFailure = {
+    error: string;
+    code: TwoFactorErrorCode;
+};
+export type VerificationResult = {
+    ok: true;
+} | VerificationFailure;

package/handlers/createPasskeyHandlers.ts

@@ -1,5 +1,6 @@
 import type { HttpExtra } from "adminforth";
-import { HttpStatus, errorMessage, respondWithStatus } from "../utils/errors.js";
+import { HttpStatus, TwoFactorErrorCode, errorMessage, respondWithStatus } from "../utils/errors.js";
+import type { VerificationResult } from "../utils/types.js";
 
 export function createPasskeyHandlers(ctx: any) {
   return {
@@ -83,8 +84,8 @@ export function createPasskeyHandlers(ctx: any) {
       const confirmationResult = body?.confirmationResult;
       const idsToResolve = Array.isArray(sessionsIds) ? sessionsIds : [];
 
-      const resolveAllIdsAsFailed = (message, code?: string) => {
-        const payload = code ? { ok: false, code, error: message } : { ok: false, error: message };
+      const resolveAllIdsAsFailed = (message: string, code: TwoFactorErrorCode) => {
+        const payload = { ok: false, code, error: message };
         for (const id of idsToResolve) {
           ctx.autoVerify.resolveResponse(id, payload);
         }
@@ -94,7 +95,7 @@ export function createPasskeyHandlers(ctx: any) {
       try {
         if (!idsToResolve.length || !confirmationResult) {
           return respondWithStatus(
-            resolveAllIdsAsFailed('Confirmation window was closed', 'VERIFICATION_CANCELLED'),
+            resolveAllIdsAsFailed('Confirmation window was closed', TwoFactorErrorCode.CANCELLED),
             response,
             HttpStatus.BAD_REQUEST,
           );
@@ -103,14 +104,22 @@ export function createPasskeyHandlers(ctx: any) {
         for (const id of idsToResolve) {
           const validationResult = await ctx.adminforth.auth.verify(id, 'auto2FA', false);
           if (!validationResult) {
-            return respondWithStatus(resolveAllIdsAsFailed('Invalid session ID or confirmation result'), response, HttpStatus.FORBIDDEN);
+            return respondWithStatus(
+              resolveAllIdsAsFailed('Invalid session ID or confirmation result', TwoFactorErrorCode.INVALID_SESSION),
+              response,
+              HttpStatus.FORBIDDEN,
+            );
           }
           if (validationResult.adminUserPk !== adminUser.pk) {
-            return respondWithStatus(resolveAllIdsAsFailed('Session does not belong to the authenticated user'), response, HttpStatus.FORBIDDEN);
+            return respondWithStatus(
+              resolveAllIdsAsFailed('Session does not belong to the authenticated user', TwoFactorErrorCode.INVALID_SESSION),
+              response,
+              HttpStatus.FORBIDDEN,
+            );
           }
         }
 
-        const verificationResult = await ctx.verifyMfaConfirmation(confirmationResult, {
+        const verificationResult: VerificationResult = await ctx.verifyMfaConfirmation(confirmationResult, {
           adminUser: adminUser,
           userPk: adminUser.pk,
           cookies: cookies,
@@ -119,19 +128,24 @@ export function createPasskeyHandlers(ctx: any) {
             headers: headers,
           } as HttpExtra
         });
-        if ( !verificationResult || !('ok' in verificationResult) ) {
-          return respondWithStatus(resolveAllIdsAsFailed(verificationResult?.error ?? 'Verification failed'), response, HttpStatus.FORBIDDEN);
+        if ('error' in verificationResult) {
+          return respondWithStatus(
+            resolveAllIdsAsFailed(verificationResult.error, verificationResult.code),
+            response,
+            HttpStatus.FORBIDDEN,
+          );
         }
-        if ('ok' in verificationResult && verificationResult.ok){
-          for (const id of idsToResolve) {
-            ctx.autoVerify.resolveResponse(id, { ok: true, passkeyConfirmed: verificationResult });
-          }
-          return { ok: true };
+        for (const id of idsToResolve) {
+          ctx.autoVerify.resolveResponse(id, { ok: true, passkeyConfirmed: verificationResult });
         }
-        return respondWithStatus(resolveAllIdsAsFailed('Verification failed'), response, HttpStatus.FORBIDDEN);
+        return { ok: true };
       } catch (error) {
         console.error('[AdminForth 2FA] Error resolving automatic 2FA verification', error);
-        return respondWithStatus(resolveAllIdsAsFailed(errorMessage(error)), response, HttpStatus.INTERNAL_SERVER_ERROR);
+        return respondWithStatus(
+          resolveAllIdsAsFailed(errorMessage(error), TwoFactorErrorCode.INTERNAL_ERROR),
+          response,
+          HttpStatus.INTERNAL_SERVER_ERROR,
+        );
       }
     },
   };

package/handlers/createTwoFaHandlers.ts

@@ -167,14 +167,10 @@ export function createTwoFaHandlers(ctx: any) {
         }
       }
 
-      if ( ctx.options.stepUpMfaGracePeriodSeconds ) {
-        const verificationResult = await ctx.cookieService.isMfaGraceValid(headers, cookies, true);
-        if ( verificationResult === true ) {
-          return { skipAllowed: true };
-        }
-      }
+      const gracePeriod = Boolean(ctx.options.stepUpMfaGracePeriodSeconds)
+        && await ctx.cookieService.isMfaGraceValid(headers, cookies, true);
 
-      return { skipAllowed: false };
+      return { skipAllowed: false, gracePeriod };
     },
 
     verifyTotp: async ({ adminUser, body, response }) => {

package/index.ts

@@ -5,6 +5,7 @@ import  { PluginOptions } from "./types.js"
 import { PasskeyService } from "./services/passkeyService.js";
 import { TotpService } from "./services/totpService.js";
 import { verifyMfaConfirmation, type MfaConfirmationResult, type VerifyOptions } from "./services/verifyMfaConfirmation.js";
+import { MfaRequestContext } from './services/mfaRequestContext.js';
 import { CookieService } from "./services/cookieService.js";
 import { UserRepository } from "./repositories/userRepository.js";
 import { registerPasskeyEndpoints } from "./endpoints/registerPasskeyEndpoints.js";
@@ -12,8 +13,13 @@ import { registerTwoFaEndpoints } from "./endpoints/registerTwoFaEndpoints.js";
 import { createPasskeyHandlers } from "./handlers/createPasskeyHandlers.js";
 import { createTwoFaHandlers } from "./handlers/createTwoFaHandlers.js";
 import { parsePeriod } from "./utils/parsePeriod.js";
+import { TwoFactorErrorCode } from "./utils/errors.js";
+import type { VerificationResult } from "./utils/types.js";
 import crypto from 'crypto';
 
+export { TwoFactorErrorCode };
+export type { VerificationResult };
+
 const getRequestWebsocketClientId = (AdminForthRuntime as typeof AdminForthRuntime & {
   getRequestWebsocketClientId?: () => string | undefined;
 }).getRequestWebsocketClientId;
@@ -29,6 +35,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
   userRepository: UserRepository;
   passkeyLoginRateLimiters: RateLimiter[] = [];
   private ctx: any;
+  private readonly mfaRequestContext = new MfaRequestContext();
 
   constructor(options: PluginOptions) {
     super(options, import.meta.url);
@@ -78,7 +85,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
       };
       timeout = setTimeout(() => {
         cleanup();
-        resolve({ ok: false, error: 'Verification timed out' });
+        resolve({ ok: false, error: 'Verification timed out', code: TwoFactorErrorCode.TIMEOUT });
       }, timeoutMs);
       this.pending.set(id, (value: any) => {
         cleanup();
@@ -94,16 +101,30 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     }
   }
 
-  public async verifyAuto(adminUser: AdminUser) {
+  public withVerificationContext<T>(confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra, callback: () => Promise<T>) {
+    return this.mfaRequestContext.run(confirmationResult, extra, callback);
+  }
+
+  public async verifyAuto(adminUser: AdminUser, actionDescription?: string) {
+    const contextualResult = await this.mfaRequestContext.verify(adminUser, actionDescription, (confirmationResult, extra) => this.verify(confirmationResult, {
+      adminUser,
+      userPk: adminUser.pk!,
+      extra,
+    }));
+    if (contextualResult) return contextualResult;
     const websocketClientId = getRequestWebsocketClientId?.();
     if (!websocketClientId) {
-      return { ok: false, error: '2FA auto verification requires an active browser request context' };
+      return {
+        ok: false,
+        error: '2FA auto verification requires an active browser request context',
+        code: TwoFactorErrorCode.BROWSER_CONTEXT_REQUIRED,
+      };
     }
     const sessionId = crypto.randomUUID();
     const jwt = this.adminforth.auth.issueJWT({sessionId, adminUserPk: adminUser.pk}, 'auto2FA', '5m');
     const resultPromise = this.waitForResponse(jwt, 5 * 60 * 1000);
 
-    this.adminforth.websocket.publish(`/user2fa/${adminUser.pk}/${websocketClientId}`, { sessionId: jwt });
+    this.adminforth.websocket.publish(`/user2fa/${adminUser.pk}/${websocketClientId}`, { sessionId: jwt, actionDescription });
 
     const result = await resultPromise;
 
@@ -113,9 +134,9 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
   }
 
   public async verify(
-    confirmationResult: MfaConfirmationResult,
+    confirmationResult: MfaConfirmationResult | undefined,
     opts: VerifyOptions
-  ): Promise<{ ok: true } | { error: string }> {
+  ): Promise<VerificationResult> {
     return verifyMfaConfirmation(this.ctx, confirmationResult, opts);
   }
 
@@ -125,7 +146,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     this.adminForthAuth = adminforth.auth;
     this.userRepository = new UserRepository(this.adminforth, this.options);
     this.cookieService = new CookieService(this.adminforth, this.options);
-    this.totpService = new TotpService(this.options, this.userRepository);
+    this.totpService = new TotpService(this.options, this.userRepository, this.adminforth);
     this.passkeyService = new PasskeyService(this.options, this.adminforth, this.userRepository, undefined, this.cookieService);
     this.passkeyLoginRateLimiters = (adminforth.config.auth as any).rateLimit.map((rate) => new RateLimiter(rate));
     this.ctx = {