@adminforth/two-factors-auth 2.9.20 → 2.10.0

package/.woodpecker/buildSlackNotify.sh

@@ -4,8 +4,10 @@ set -x
 
 COMMIT_SHORT_SHA=$(echo $CI_COMMIT_SHA | cut -c1-8)
 
+STATUS=${1}  
 
-if [ "$CI_PREV_PIPELINE_STATUS" = "success" ]; then
+
+if [ "$STATUS" = "success" ]; then
   MESSAGE="Did a build without issues on \`$CI_REPO_NAME/$CI_COMMIT_BRANCH\`. Commit: _${CI_COMMIT_MESSAGE}_ (<$CI_COMMIT_URL|$COMMIT_SHORT_SHA>)"
 
   curl  -s -X POST -H "Content-Type: application/json" -d '{

package/.woodpecker/release.yml

@@ -16,25 +16,42 @@ steps:
     commands:
       - infisical export --domain https://vault.devforth.io/api --format=dotenv-export --env="prod" > /woodpecker/deploy.vault.env
 
-  release:
+  build:
     image: node:20
     when:
       - event: push
     commands:
       - apt update && apt install -y rsync
-      - export $(cat /woodpecker/deploy.vault.env | xargs)
+      - . /woodpecker/deploy.vault.env   
       - npm clean-install
       - /bin/bash ./.woodpecker/buildRelease.sh
       - npm audit signatures
+
+  release:
+    image: node:20
+    when:
+      - event:
+          - push
+        branch:
+          - main
+    commands:
+      - . /woodpecker/deploy.vault.env
       - npx semantic-release
 
   slack-on-failure:
+    image: curlimages/curl
     when:
       - event: push
-        status: [failure, success]
-      - event: push
+        status: [failure]
+    commands:
+      - . /woodpecker/deploy.vault.env
+      - /bin/sh ./.woodpecker/buildSlackNotify.sh failure
+      
+  slack-on-success: 
     image: curlimages/curl
+    when:
+      - event: push
+        status: [success]
     commands:
-      - export $(cat /woodpecker/deploy.vault.env | xargs)
-      - /bin/sh ./.woodpecker/buildSlackNotify.sh
-
+      - . /woodpecker/deploy.vault.env
+      - /bin/sh ./.woodpecker/buildSlackNotify.sh success

package/build.log

@@ -15,5 +15,5 @@ custom/package.json
 custom/tsconfig.json
 custom/utils.js
 
-sent 273,593 bytes  received 210 bytes  547,606.00 bytes/sec
+sent 273,582 bytes  received 210 bytes  547,584.00 bytes/sec
 total size is 272,766  speedup is 1.00

package/dist/index.js

@@ -12,6 +12,7 @@ import twofactor from 'node-2fa';
 import { generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions, verifyAuthenticationResponse } from '@simplewebauthn/server';
 import { isoUint8Array, isoBase64URL } from '@simplewebauthn/server/helpers';
 import aaguids from './custom/aaguid.json';
+import crypto from 'crypto';
 export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     constructor(options) {
         super(options, import.meta.url);
@@ -45,9 +46,63 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
             return { skipAllowed: false };
         });
     }
+    generateHashForStepUpMfaGraceCookie(headers) {
+        const ip = this.adminforth.auth.getClientIp(headers);
+        const userAgent = headers['user-agent'] || '';
+        const acceptLanguage = headers['accept-language'] || '';
+        if (!ip || !userAgent || !acceptLanguage) {
+            console.error("❗️❗️❗️ Cannot set step-up MFA grace cookie: missing required request headers to identify client ❗️❗️❗️");
+            return null;
+        }
+        else {
+            const hmac = crypto.createHmac('sha256', process.env.ADMINFORTH_SECRET)
+                .update(`${acceptLanguage}_${userAgent}_${ip}`)
+                .digest('hex');
+            return hmac;
+        }
+    }
+    issueTempSkip2FAGraceJWT(opts) {
+        if (opts.response) {
+            if (opts.extra.headers) {
+                const hash = this.generateHashForStepUpMfaGraceCookie(opts.extra.headers);
+                if (!hash) {
+                    return;
+                }
+                const jwt = this.adminforth.auth.issueJWT({ hash: hash }, 'MfaGrace', `${this.options.stepUpMfaGracePeriodSeconds}s`);
+                //TODO: fix ts-ignore after releasing new version of adminforth with updated types
+                //@ts-ignore 
+                this.adminforth.auth.setCustomCookie({ response: opts.response, payload: { name: "TempSkip2FA_Modal_JWT", value: jwt, expirySeconds: this.options.stepUpMfaGracePeriodSeconds, httpOnly: true } });
+            }
+        }
+        else {
+            console.error("❗️❗️❗️ Cannot set step-up MFA grace cookie: response object is missing. You probably called verify() method without response parameter ❗️❗️❗️");
+        }
+    }
+    isTempSkip2FAGraceValid(headers_1, cookies_1) {
+        return __awaiter(this, arguments, void 0, function* (headers, cookies, checkIfJWTAboutToExpire = false) {
+            const hash = this.generateHashForStepUpMfaGraceCookie(headers);
+            if (!hash) {
+                return false;
+            }
+            const jwt = this.adminforth.auth.getCustomCookie({ cookies: cookies, name: "TempSkip2FA_Modal_JWT" });
+            const jwtVerificationResult = yield this.adminforth.auth.verify(jwt, 'MfaGrace', false);
+            if (!jwtVerificationResult) {
+                return false;
+            }
+            const jwtHash = jwtVerificationResult['hash'];
+            if (checkIfJWTAboutToExpire && (jwtVerificationResult["exp"] - (Date.now() / 1000)) < 30) {
+                console.error("❗️❗️❗️ Cannot validate step-up MFA grace cookie: token is expired or about to expire ❗️❗️❗️");
+                return false;
+            }
+            if (hash === jwtHash) {
+                return true;
+            }
+            return false;
+        });
+    }
     verify(confirmationResult, opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             if (!confirmationResult)
                 return { error: "Confirmation result is required" };
             if (this.options.usersFilterToApply) {
@@ -62,6 +117,12 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
                     return { ok: true };
                 }
             }
+            if (this.options.stepUpMfaGracePeriodSeconds && ((_a = opts.extra) === null || _a === void 0 ? void 0 : _a.headers) && !confirmationResult.mode) {
+                const verificationResult = yield this.isTempSkip2FAGraceValid(opts.extra.headers, opts.cookies);
+                if (verificationResult === true) {
+                    return { ok: true };
+                }
+            }
             if (confirmationResult.mode === "totp") {
                 const code = confirmationResult.result;
                 const authRes = this.adminforth.config.resources
@@ -69,10 +130,10 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
                 if (!authRes)
                     return { error: "Auth resource not found" };
                 const connector = this.adminforth.connectors[authRes.dataSource];
-                const pkName = (_a = authRes.columns.find(c => c.primaryKey)) === null || _a === void 0 ? void 0 : _a.name;
+                const pkName = (_b = authRes.columns.find(c => c.primaryKey)) === null || _b === void 0 ? void 0 : _b.name;
                 if (!pkName)
                     return { error: "Primary key not found on auth resource" };
-                const pk = (_b = opts === null || opts === void 0 ? void 0 : opts.userPk) !== null && _b !== void 0 ? _b : (_d = (_c = opts === null || opts === void 0 ? void 0 : opts.adminUser) === null || _c === void 0 ? void 0 : _c.dbUser) === null || _d === void 0 ? void 0 : _d[pkName];
+                const pk = (_c = opts === null || opts === void 0 ? void 0 : opts.userPk) !== null && _c !== void 0 ? _c : (_e = (_d = opts === null || opts === void 0 ? void 0 : opts.adminUser) === null || _d === void 0 ? void 0 : _d.dbUser) === null || _e === void 0 ? void 0 : _e[pkName];
                 if (!pk)
                     return { error: "User PK is required" };
                 const user = yield connector.getRecordByPrimaryKey(authRes, pk);
@@ -82,7 +143,17 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
                 if (!secret)
                     return { error: "2FA is not set up for this user" };
                 const verified = twofactor.verifyToken(secret, code, this.options.timeStepWindow);
-                return verified ? { ok: true } : { error: "Wrong or expired OTP code" };
+                //* SET GRACE COOKIE *//
+                if (verified) {
+                    if (this.options.stepUpMfaGracePeriodSeconds) {
+                        this.issueTempSkip2FAGraceJWT(opts);
+                    }
+                    return { ok: true };
+                }
+                else {
+                    return { error: "Wrong or expired OTP code" };
+                }
+                ;
             }
             else if (confirmationResult.mode === "passkey") {
                 const passkeysCookies = this.adminforth.auth.getCustomCookie({ cookies: opts.cookies, name: `passkeyLoginTemporaryJWT` });
@@ -95,6 +166,10 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
                 }
                 const verificationResult = yield this.verifyPasskeyResponse(confirmationResult.result, opts.userPk, decodedPasskeysCookies);
                 if (verificationResult.ok && verificationResult.passkeyConfirmed) {
+                    //* SET GRACE COOKIE *//
+                    if (this.options.stepUpMfaGracePeriodSeconds) {
+                        this.issueTempSkip2FAGraceJWT(opts);
+                    }
                     return { ok: true };
                 }
                 return { error: "Invalid passkey" };
@@ -543,7 +618,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
         server.endpoint({
             method: "GET",
             path: "/plugin/twofa/skip-allow-modal",
-            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ adminUser }) {
+            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ adminUser, headers, cookies }) {
                 if (this.options.usersFilterToApply) {
                     const res = this.options.usersFilterToApply(adminUser);
                     if (res === false) {
@@ -556,6 +631,12 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
                         return { skipAllowed: true };
                     }
                 }
+                if (this.options.stepUpMfaGracePeriodSeconds) {
+                    const verificationResult = yield this.isTempSkip2FAGraceValid(headers, cookies, true);
+                    if (verificationResult === true) {
+                        return { skipAllowed: true };
+                    }
+                }
                 return { skipAllowed: false };
             }),
         });
@@ -582,14 +663,16 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
             method: 'POST',
             path: `/plugin/passkeys/registerPasskeyRequest`,
             noAuth: false,
-            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, cookies }) {
+            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, cookies, extra }) {
                 var _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
                 const mode = body === null || body === void 0 ? void 0 : body.mode;
                 const confirmationResult = body === null || body === void 0 ? void 0 : body.confirmationResult;
                 const verificationResult = yield this.verify(confirmationResult, {
                     adminUser: adminUser,
                     userPk: adminUser.pk,
-                    cookies: cookies
+                    cookies: cookies,
+                    response: response,
+                    extra: Object.assign({}, extra)
                 });
                 if (!verificationResult || !('ok' in verificationResult)) {
                     return { ok: false, error: 'Verification failed' };

package/index.ts

@@ -10,6 +10,7 @@ import {
 } from '@simplewebauthn/server';
 import { isoUint8Array, isoBase64URL } from '@simplewebauthn/server/helpers';
 import aaguids from './custom/aaguid.json';
+import crypto from 'crypto';
 
 export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
   options: PluginOptions;
@@ -54,9 +55,62 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     return { skipAllowed: false };
   }
 
+  private generateHashForStepUpMfaGraceCookie(headers): string {
+    const ip = this.adminforth.auth.getClientIp(headers);
+    const userAgent = headers['user-agent'] || '';
+    const acceptLanguage = headers['accept-language'] || '';
+    if (!ip || !userAgent || !acceptLanguage) {
+      console.error("❗️❗️❗️ Cannot set step-up MFA grace cookie: missing required request headers to identify client ❗️❗️❗️");
+      return null;
+    } else {
+      const hmac = crypto.createHmac('sha256', process.env.ADMINFORTH_SECRET)
+        .update(`${acceptLanguage}_${userAgent}_${ip}`)
+        .digest('hex');
+      return hmac;
+    }
+  }
+
+  private issueTempSkip2FAGraceJWT(opts): void {
+    if (opts.response) {
+      if (opts.extra.headers) {
+        const hash = this.generateHashForStepUpMfaGraceCookie(opts.extra.headers);
+        if (!hash) {
+          return;
+        }
+        const jwt = this.adminforth.auth.issueJWT({ hash: hash }, 'MfaGrace', `${this.options.stepUpMfaGracePeriodSeconds}s`);
+        //TODO: fix ts-ignore after releasing new version of adminforth with updated types
+        //@ts-ignore 
+        this.adminforth.auth.setCustomCookie({response: opts.response, payload: {name: "TempSkip2FA_Modal_JWT", value: jwt, expirySeconds: this.options.stepUpMfaGracePeriodSeconds, httpOnly: true}});
+      }
+    } else {
+      console.error("❗️❗️❗️ Cannot set step-up MFA grace cookie: response object is missing. You probably called verify() method without response parameter ❗️❗️❗️");
+    }
+  }
+
+  private async isTempSkip2FAGraceValid(headers, cookies, checkIfJWTAboutToExpire: boolean = false): Promise<boolean> {
+    const hash = this.generateHashForStepUpMfaGraceCookie(headers);
+    if (!hash) {
+      return false;
+    }
+    const jwt = this.adminforth.auth.getCustomCookie({cookies: cookies, name: "TempSkip2FA_Modal_JWT"});
+    const jwtVerificationResult = await this.adminforth.auth.verify(jwt, 'MfaGrace', false) 
+    if (!jwtVerificationResult) {
+      return false;
+    }
+    const jwtHash = jwtVerificationResult['hash'];
+    if (checkIfJWTAboutToExpire && (jwtVerificationResult["exp"] - ( Date.now() / 1000)) < 30 ) {
+      console.error("❗️❗️❗️ Cannot validate step-up MFA grace cookie: token is expired or about to expire ❗️❗️❗️");
+      return false;
+    }
+    if (hash === jwtHash) {
+      return true;
+    }
+    return false;
+  }
+
   public async verify(
     confirmationResult: Record<string, any>,
-    opts?: { adminUser?: AdminUser; userPk?: string; cookies?: any }
+    opts?: { adminUser?: AdminUser; userPk?: string; cookies?: any, response?: IAdminForthHttpResponse, extra?: HttpExtra }
   ): Promise<{ ok: true } | { error: string }> {
     if (!confirmationResult) return { error: "Confirmation result is required" };
     if (this.options.usersFilterToApply) {
@@ -71,6 +125,13 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
         return { ok: true };
       }
     }
+    if ( this.options.stepUpMfaGracePeriodSeconds && opts.extra?.headers && !confirmationResult.mode) {
+      const verificationResult = await this.isTempSkip2FAGraceValid(opts.extra.headers, opts.cookies);
+      if ( verificationResult === true ) {
+        return { ok: true };
+      }
+    }
+
     if (confirmationResult.mode === "totp") {
       const code = confirmationResult.result;
       const authRes = this.adminforth.config.resources
@@ -92,7 +153,16 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
       if (!secret) return { error: "2FA is not set up for this user" };
 
       const verified = twofactor.verifyToken(secret, code, this.options.timeStepWindow);
-      return verified ? { ok: true } : { error: "Wrong or expired OTP code" };
+
+      //* SET GRACE COOKIE *//
+      if ( verified ) { 
+        if (this.options.stepUpMfaGracePeriodSeconds) {
+          this.issueTempSkip2FAGraceJWT(opts);
+        }
+        return { ok: true } 
+      } else { 
+        return { error: "Wrong or expired OTP code" } 
+      };
     } else if (confirmationResult.mode === "passkey") {
       const passkeysCookies = this.adminforth.auth.getCustomCookie({cookies: opts.cookies, name: `passkeyLoginTemporaryJWT`});
       if (!passkeysCookies) {
@@ -106,6 +176,11 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
       const verificationResult = await this.verifyPasskeyResponse(confirmationResult.result, opts.userPk, decodedPasskeysCookies );
 
       if (verificationResult.ok && verificationResult.passkeyConfirmed) {
+
+        //* SET GRACE COOKIE *//
+        if (this.options.stepUpMfaGracePeriodSeconds) {
+          this.issueTempSkip2FAGraceJWT(opts);
+        }
         return  { ok: true }
       }
       return { error: "Invalid passkey" }
@@ -601,7 +676,7 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
     server.endpoint({
       method: "GET",
       path: "/plugin/twofa/skip-allow-modal",
-      handler: async ({ adminUser }) => {
+      handler: async ({ adminUser, headers, cookies }) => {
         if ( this.options.usersFilterToApply ) {
           const res = this.options.usersFilterToApply(adminUser);
           if ( res === false ) {
@@ -614,6 +689,14 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
             return { skipAllowed: true };
           }
         }
+
+        if ( this.options.stepUpMfaGracePeriodSeconds ) {
+          const verificationResult = await this.isTempSkip2FAGraceValid(headers, cookies, true);
+          if ( verificationResult === true ) {
+            return { skipAllowed: true };
+          }
+        }
+
         return { skipAllowed: false };
       },
     });
@@ -641,14 +724,16 @@ export default class TwoFactorsAuthPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/plugin/passkeys/registerPasskeyRequest`,
       noAuth: false,
-      handler: async ({ body, adminUser, response, cookies }) => {
+      handler: async ({ body, adminUser, response, cookies, extra }) => {
         const mode = body?.mode;
 
         const confirmationResult = body?.confirmationResult;
         const verificationResult = await this.verify(confirmationResult, {
           adminUser: adminUser,
           userPk: adminUser.pk, 
-          cookies: cookies
+          cookies: cookies,
+          response: response,
+          extra: { ...extra }
         });
         if ( !verificationResult || !('ok' in verificationResult) ) {
           return { ok: false, error: 'Verification failed' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/two-factors-auth",
-  "version": "2.9.20",
+  "version": "2.10.0",
   "description": "AdminForth plugin for two factors authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/types.ts

@@ -16,6 +16,12 @@ export type PluginOptions = {
      */
     timeStepWindow?: number;
 
+    /**
+     * Number of seconds for step-up MFA grace period.
+     * During this period, user will not be challenged with 2FA on sensitive actions.
+     */
+    stepUpMfaGracePeriodSeconds?: number;
+
     customBrandPrefix?: string;
 
     /**