@adminforth/two-factors-auth 4.4.9 → 4.6.0

package/services/mfaRequestContext.ts

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { AdminUser, HttpExtra } from 'adminforth';
+import type { MfaConfirmationResult } from './verifyMfaConfirmation.js';
+import type { VerificationFailure, VerificationResult } from '../utils/types.js';
+
+type Context = {
+  confirmationResult: MfaConfirmationResult | undefined;
+  extra: HttpExtra;
+  results: Map<string, Promise<VerificationResult>>;
+};
+
+type ContextualVerificationFailure = VerificationFailure & { actionDescription?: string };
+
+class MfaVerificationError extends Error {
+  constructor(readonly result: ContextualVerificationFailure) {
+    super(result.error);
+  }
+}
+
+/** Keeps verification within one external request, including every CRUD hook it invokes. */
+export class MfaRequestContext {
+  private readonly storage = new AsyncLocalStorage<Context>();
+
+  run<T>(confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra, callback: () => Promise<T>): Promise<T | ContextualVerificationFailure> {
+    return this.storage.run({ confirmationResult, extra, results: new Map() }, async () => {
+      try {
+        return await callback();
+      } catch (error) {
+        if (error instanceof MfaVerificationError) return error.result;
+        throw error;
+      }
+    });
+  }
+
+  async verify(
+    adminUser: AdminUser,
+    actionDescription: string | undefined,
+    verifier: (confirmationResult: MfaConfirmationResult | undefined, extra: HttpExtra) => Promise<VerificationResult>,
+  ): Promise<VerificationResult | undefined> {
+    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 = await result;
+    if ('error' in verified) throw new MfaVerificationError({ ...verified, actionDescription });
+    return verified;
+  }
+}

package/services/totpService.ts

@@ -1,12 +1,21 @@
-import type { AdminUser } from "adminforth";
+import { RateLimiter, type AdminUser, type IAdminForthAuth } from "adminforth";
 import twofactor from 'node-2fa';
 import type { PluginOptions } from "../types.js";
 import { UserRepository } from "../repositories/userRepository.js";
+import { TwoFactorErrorCode } from "../utils/errors.js";
+import type { VerificationFailure, VerificationResult } from "../utils/types.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 {
+  private readonly codeAttemptLimiters = CODE_ATTEMPT_RATE_LIMITS.map((rate) => new RateLimiter(rate));
+
   constructor(
     private readonly options: PluginOptions,
     private readonly userRepository: UserRepository,
+    private readonly auth: IAdminForthAuth,
   ) {}
 
   public generateSecret(issuerName: string, userName: string): string {
@@ -17,18 +26,32 @@ export class TotpService {
     return Boolean(twofactor.verifyToken(secret, code, this.options.timeStepWindow));
   }
 
-  public async verifyUserCode(userPk: string, code: string): Promise<{ ok: true } | { error: string }> {
+  public async verifyUserCode(userPk: string, code: string): Promise<VerificationResult> {
+    const attemptsAllowed = await 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 = await this.userRepository.getAuthUser(userPk);
-    if (!user) return { error: "User not found" };
+    if (!user) 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" };
+    if (!secret) 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 };
+  }
 
-    return this.verifySecret(secret, code) ? { ok: true } : { error: "Wrong or expired OTP code" };
+  public async verifyAdminUserCode(adminUser: AdminUser, code: string): Promise<{ ok: true; verifiedCodeToken: string } | VerificationFailure> {
+    const result = await this.verifyUserCode(this.userRepository.getUserPk(adminUser), code);
+    if ('error' in result) return result;
+    return { ok: true, verifiedCodeToken: this.auth.issueJWT({ pk: adminUser.pk }, VERIFIED_CODE_JWT_TYPE, VERIFIED_CODE_TOKEN_TTL) };
   }
 
-  public async verifyAdminUserCode(adminUser: AdminUser, code: string): Promise<{ ok: true } | { error: string }> {
-    return this.verifyUserCode(this.userRepository.getUserPk(adminUser), code);
+  public async isVerifiedCodeToken(token: string, userPk: string): Promise<boolean> {
+    const payload = await this.auth.verify(token, VERIFIED_CODE_JWT_TYPE, false);
+    return payload?.pk === userPk;
   }
 
   public async saveSecret(userPk: string, secret: string): Promise<void> {

package/services/verifyMfaConfirmation.ts

@@ -1,11 +1,17 @@
 import type { AdminUser, HttpExtra, IAdminForthHttpResponse } from "adminforth";
-import type { CookieList } from "../utils/types.js";
+import { TwoFactorErrorCode } from "../utils/errors.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: {
@@ -18,7 +24,7 @@ type GraceConfirmationResult = {
   mode?: undefined;
 };
 
-export type MfaConfirmationResult = TotpConfirmationResult | PasskeyConfirmationResult | GraceConfirmationResult;
+export type MfaConfirmationResult = TotpConfirmationResult | VerifiedTotpConfirmationResult | PasskeyConfirmationResult | GraceConfirmationResult;
 
 export type VerifyOptions = {
   adminUser: AdminUser;
@@ -30,11 +36,10 @@ export type VerifyOptions = {
 
 export async function verifyMfaConfirmation(
   ctx: any,
-  confirmationResult: MfaConfirmationResult,
+  confirmationResult: MfaConfirmationResult | undefined,
   opts: VerifyOptions,
-): Promise<{ ok: true } | { error: string }> {
-  if (!confirmationResult) return { error: "Confirmation result is required" };
-
+): Promise<VerificationResult> {
+  const mode = confirmationResult?.mode;
   const cookies = opts.extra?.cookies || opts.cookies;
   const response = opts.extra?.response || opts.response;
 
@@ -50,43 +55,44 @@ export async function verifyMfaConfirmation(
       return { ok: true };
     }
   }
-  if ( ctx.options.stepUpMfaGracePeriodSeconds && opts.extra?.headers && !confirmationResult.mode) {
+  if ( ctx.options.stepUpMfaGracePeriodSeconds && opts.extra?.headers && !mode) {
     const verificationResult = await 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 = (): VerificationResult => {
+    if (ctx.options.stepUpMfaGracePeriodSeconds) {
+      ctx.cookieService.issueMfaGrace({ headers: opts.extra?.headers, response }, cookies);
+    }
+    return { ok: true };
+  };
+
   if (mode === "totp") {
     const { result: code } = confirmationResult as TotpConfirmationResult;
     const verificationResult = await ctx.totpService.verifyUserCode(opts.userPk, code);
-
-    if ( 'ok' in verificationResult && verificationResult.ok ) {
-      if (ctx.options.stepUpMfaGracePeriodSeconds) {
-        ctx.cookieService.issueMfaGrace({ headers: opts.extra?.headers, response }, cookies);
-      }
-      return { ok: true }
-    }
-    return verificationResult;
+    return 'error' in verificationResult ? verificationResult : confirmed();
+  } else if (mode === "verifiedTotp") {
+    const { result: token } = confirmationResult as VerifiedTotpConfirmationResult;
+    return await 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 as PasskeyConfirmationResult;
     const cookiesValidationResult = await ctx.passkeyService.validateLoginChallengeCookie(cookies);
     if (!cookiesValidationResult.ok) {
-      return { error: cookiesValidationResult.error };
+      return { error: cookiesValidationResult.error, code: TwoFactorErrorCode.INVALID };
     }
     const verificationResult = await ctx.passkeyService.verifyPasskeyResponse(result, opts.userPk, cookiesValidationResult.decodedPasskeysCookies );
 
     if (verificationResult.ok && verificationResult.passkeyConfirmed) {
-      if (ctx.options.stepUpMfaGracePeriodSeconds) {
-        ctx.cookieService.issueMfaGrace({ headers: opts.extra?.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/tests/mfaRequestContext.test.mjs

@@ -0,0 +1,79 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { MfaRequestContext } from '../dist/services/mfaRequestContext.js';
+const user = { pk: 'user-1' };
+
+test('without external context normal browser verification is unaffected', async () => {
+  const context = new MfaRequestContext();
+  assert.equal(await context.verify(user, undefined, () => assert.fail('verification must not run')), undefined);
+});
+
+test('missing verification stops a CRUD hook before it can strip the error code', async () => {
+  const context = new MfaRequestContext();
+  let written = false;
+  const result = await context.run(undefined, {}, async () => {
+    await context.verify(user, undefined, async () => ({ error: 'Required', code: 'TWO_FACTOR_REQUIRED' }));
+    written = true;
+    return { ok: true };
+  });
+  assert.equal(written, false);
+  assert.equal(result.code, 'TWO_FACTOR_REQUIRED');
+});
+
+test('a failed verification carries the action description for the confirmation page', async () => {
+  const context = new MfaRequestContext();
+  const result = await context.run(undefined, {}, async () => {
+    await context.verify(user, 'Approve $100,000 bonus', async () => ({ error: 'Required', code: 'TWO_FACTOR_REQUIRED' }));
+  });
+  assert.deepEqual(result, { error: 'Required', code: 'TWO_FACTOR_REQUIRED', actionDescription: 'Approve $100,000 bonus' });
+});
+
+test('invalid TOTP or passkey cannot reach the mutation', async () => {
+  for (const mode of ['totp', 'passkey']) {
+    const context = new MfaRequestContext();
+    const result = await context.run({ mode, result: 'invalid' }, {}, async () => {
+      await context.verify(user, undefined, async () => ({ error: 'Invalid', code: 'TWO_FACTOR_INVALID' }));
+      assert.fail('mutation must not execute');
+    });
+    assert.equal(result.code, 'TWO_FACTOR_INVALID');
+  }
+});
+
+test('valid verification is reused only within the same request and user', async () => {
+  const context = new MfaRequestContext();
+  const token = { mode: 'totp', result: '123456' };
+  const extra = { cookies: [{ key: 'session', value: 'browser' }] };
+  let checks = 0;
+  const verify = async (result, passedExtra) => { checks++; assert.equal(result, token); assert.equal(passedExtra, extra); return { ok: true }; };
+  const run = () => context.run(token, extra, async () => {
+    await context.verify(user, undefined, verify);
+    await context.verify(user, undefined, verify);
+    await context.verify({ pk: 'other-user' }, undefined, verify);
+    return { ok: true };
+  });
+  await run();
+  assert.equal(checks, 2);
+  await run();
+  assert.equal(checks, 4);
+});
+
+test('concurrent requests do not share verification or cookies', async () => {
+  const context = new MfaRequestContext();
+  const run = (token, cookie, code) => context.run(token, { cookie }, async () => {
+    await context.verify(user, undefined, async (received, extra) => {
+      await new Promise(resolve => setTimeout(resolve, 1));
+      assert.equal(received, token);
+      assert.equal(extra.cookie, cookie);
+      return code ? { error: 'Required', code } : { ok: true };
+    });
+    return { ok: true };
+  });
+  const [accepted, rejected] = await Promise.all([run('valid', 'a'), run(undefined, 'b', 'TWO_FACTOR_REQUIRED')]);
+  assert.equal(accepted.ok, true);
+  assert.equal(rejected.code, 'TWO_FACTOR_REQUIRED');
+});
+
+test('unrelated execution errors propagate to MCP', async () => {
+  const context = new MfaRequestContext();
+  await assert.rejects(context.run(undefined, {}, async () => { throw new Error('DB error'); }), /DB error/);
+});

package/tests/totpService.test.mjs

@@ -0,0 +1,38 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import twofactor from 'node-2fa';
+import { TotpService } from '../dist/services/totpService.js';
+import { TwoFactorErrorCode } from '../dist/utils/errors.js';
+
+const SECRET = 'JBSWY3DPEHPK3PXP';
+const userRepository = { getAuthUser: async (pk) => ({ pk }), getSecret: () => SECRET, getUserPk: (adminUser) => adminUser.pk };
+
+function createService() {
+  const jwts = new Map();
+  const auth = {
+    issueJWT: (payload, type) => {
+      const token = `jwt-${jwts.size}`;
+      jwts.set(token, { ...payload, type });
+      return token;
+    },
+    verify: async (token, type) => (jwts.get(token)?.type === type ? jwts.get(token) : null),
+  };
+  return new TotpService({ timeStepWindow: 1 }, userRepository, auth);
+}
+
+test('limits code attempts of each user to stop brute force of a stolen session', async () => {
+  const service = createService();
+  for (let attempt = 0; attempt < 30; attempt++) {
+    assert.equal((await service.verifyUserCode('user-1', 'wrong')).code, TwoFactorErrorCode.INVALID);
+  }
+  assert.equal((await service.verifyUserCode('user-1', 'wrong')).code, TwoFactorErrorCode.RATE_LIMITED);
+  assert.equal((await service.verifyUserCode('user-2', 'wrong')).code, TwoFactorErrorCode.INVALID);
+});
+
+test('a correct code gives a token that confirms the code only for its user', async () => {
+  const service = createService();
+  const { verifiedCodeToken } = await service.verifyAdminUserCode({ pk: 'user-1' }, twofactor.generateToken(SECRET).token);
+  assert.equal(await service.isVerifiedCodeToken(verifiedCodeToken, 'user-1'), true);
+  assert.equal(await service.isVerifiedCodeToken(verifiedCodeToken, 'user-2'), false);
+  assert.equal(await service.isVerifiedCodeToken('forged', 'user-1'), false);
+});

package/utils/errors.ts

@@ -9,6 +9,20 @@ export enum HttpStatus {
   INTERNAL_SERVER_ERROR = 500,
 }
 
+export 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 function respondWithStatus<T>(body: T, response: IAdminForthHttpResponse, status: HttpStatus): T {
   response.setStatus(status);
   return body;

package/utils/types.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"];
@@ -15,3 +16,6 @@ export type OkResponse<T extends AnyRecord = AnyRecord> = {
 } & T;
 
 export type PluginResponse<T extends AnyRecord = AnyRecord> = OkResponse<T> | ErrorResponse;
+
+export type VerificationFailure = { error: string; code: TwoFactorErrorCode };
+export type VerificationResult = { ok: true } | VerificationFailure;