Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

update comments

Thiago Araujo da Silvae240e5aa6c6e
diff --git a/backend/src/server/routes/mfa-step-up-fns.ts b/backend/src/server/routes/mfa-step-up-fns.ts
index 5b9609f24a..19b9976d4d 100644
--- a/backend/src/server/routes/mfa-step-up-fns.ts
+++ b/backend/src/server/routes/mfa-step-up-fns.ts
@@ -19,28 +19,20 @@ export const getStepUpSessionId = (req: FastifyRequest): string => {
};
/**
- * Enforces that the caller has completed a fresh MFA challenge before a sensitive
- * action, reusing the Redis-backed step-up MFA session primitive (mirrors the PAM
- * account-access flow).
+ * Gates a sensitive action behind a fresh MFA challenge, on the same Redis step-up
+ * primitive PAM uses.
*
- * A verified session is reusable for the remainder of its TTL (5 min) and is bound
- * to `resourceId` and to the factor it proved, so it cannot be replayed against a
- * different action, nor against one that would not have challenged that factor.
+ * A verified session lives for its TTL (5 min) and is tied to the resource and to the
+ * factor it proved, so it can't be replayed on another action, or on one that would
+ * never have asked for that factor. Without a usable proof we mint a pending session
+ * (emailing the code when that's the method) and throw SESSION_MFA_REQUIRED with the
+ * session id and method, so the client runs the challenge and retries.
*
- * - With a valid, verified session for this user + resource whose proven factor is
- * one this action would challenge: returns immediately.
- * - Otherwise (no session id, or one that is missing/expired/unverified/foreign, or
- * proving a factor this action does not accept): mints a fresh pending session
- * (emailing the code when the required method is email) and throws
- * `SESSION_MFA_REQUIRED` carrying the new session id + method so the client can
- * drive the challenge and retry.
- *
- * By default the challenged method is the one the current org context requires (the
- * enforced method, or the user's preference otherwise). Pass `mfaMethod` to override
- * this when the action dictates the method independently of org enforcement — e.g.
- * enabling MFA challenges the factor being enabled, not a stronger org-enforced one.
- * Pass `excludeMfaMethod` when the action removes a factor, so the challenge never
- * demands the factor being removed (which is usually the one the user has lost).
+ * The challenged method is what the current org context requires: the enforced method,
+ * else the user's preference. `mfaMethod` overrides that when the action itself picks
+ * the factor, e.g. enabling MFA challenges the factor being enabled. `excludeMfaMethod`
+ * is for removing a factor: never ask for the one being removed, it's usually the one
+ * that got lost.
*/
export const ensureStepUpMfa = async (
server: FastifyZodProvider,
@@ -68,9 +60,8 @@ export const ensureStepUpMfa = async (
if (isMfaManagement && !(await server.services.user.isStepUpMfaRequired(userId))) return;
- // Resolved before honouring any prior proof: a factor-removal action falls back to a
- // substitute factor, and a proof of that substitute must not satisfy the other
- // management actions, which would never have challenged it.
+ // Resolve the method first: a removal action may fall back to a substitute factor,
+ // and a proof of that substitute must not unlock the other management actions.
const { challenge: mfaMethod, accepted: acceptedMfaMethods } = mfaMethodOverride
? { challenge: mfaMethodOverride, accepted: [mfaMethodOverride] }
: await server.services.user.getStepUpMfaMethod(userId, orgId, excludeMfaMethod);
diff --git a/backend/src/services/auth/auth-login-service.ts b/backend/src/services/auth/auth-login-service.ts
index 7c4ee58127..2f649cdc48 100644
--- a/backend/src/services/auth/auth-login-service.ts
+++ b/backend/src/services/auth/auth-login-service.ts
@@ -741,8 +741,8 @@ export const authLoginServiceFactory = ({
// Open the grace window for THIS session only (the one that just proved MFA), so
// MFA-management step-up isn't re-prompted right after login - including recovery-code
// logins, which is what lets a user with a lost factor still manage their MFA. Keyed
- // by the new session's tokenVersionId so no other session inherits it. The factor
- // proven is the required one (anything else was rejected above), so record that.
+ // by the new session's tokenVersionId so no other session inherits it. A non-recovery
+ // login can only have proven the required method.
await mfaLockoutService.recordRecentMfaAuth(
user.id,
token.tokenVersionId,
diff --git a/backend/src/services/auth/mfa-lockout-service.ts b/backend/src/services/auth/mfa-lockout-service.ts
index 9a712f3896..860d3f1a34 100644
--- a/backend/src/services/auth/mfa-lockout-service.ts
+++ b/backend/src/services/auth/mfa-lockout-service.ts
@@ -196,16 +196,12 @@ export const mfaLockoutServiceFactory = ({
await keyStore.deleteItem(KeyStorePrefixes.UserStepUpMfaLockout(userId));
};
- // Records that a specific login SESSION just proved a second factor, either at login
- // or in an MFA-management step-up, together with the factor it proved. Within this
- // window an MFA-management step-up on that same session is skipped when the recorded
- // factor is one the route would itself challenge (see isMfaProofAccepted). A
- // recovery-code login is accepted by every route, which is what lets a user who lost
- // their only configured factor still reach their MFA settings to disable it or switch
- // the preferred method. Keyed by userId + tokenVersionId (the session), NOT the user
- // alone, so proving MFA in one session never authorizes another (older/stolen) session;
- // the userId prefix namespaces the session id to its owner. Self-clears on TTL; if the
- // window lapses, another login on that session re-opens it.
+ // Marks that THIS login session just proved a second factor, and which one. Management
+ // step-ups on the same session skip the challenge while the marker lives, as long as the
+ // recorded factor is one they'd have asked for (isMfaProofAccepted). Recovery-code logins
+ // pass everywhere; that's how a user who lost their only factor still reaches MFA
+ // settings. Keyed by session, never by user alone, so one session's proof never unlocks
+ // an older or stolen one.
const recordRecentMfaAuth = async (userId: string, tokenVersionId: string, assurance: TMfaAssurance) => {
await keyStore.setItemWithExpiry(
KeyStorePrefixes.RecentMfaAuth(userId, tokenVersionId),
diff --git a/backend/src/services/mfa-session/mfa-session-service.ts b/backend/src/services/mfa-session/mfa-session-service.ts
index c913c4c44f..4a9a5d5c1d 100644
--- a/backend/src/services/mfa-session/mfa-session-service.ts
+++ b/backend/src/services/mfa-session/mfa-session-service.ts
@@ -60,10 +60,9 @@ export const mfaSessionServiceFactory = ({
// re-implementing the checks, so a session minted for one resource (e.g. a
// low-value PAM account) can never be replayed against another (e.g. recovery
// codes). verifyMfaSession only flips PENDING -> ACTIVE; the resource binding
- // is enforced here at the point of use. Callers whose challenge method varies
- // per action within one resource pass `acceptedMfaMethods`, so a session proven
- // with a factor one action fell back to cannot be replayed against another action
- // that would never have challenged that factor.
+ // is enforced here at the point of use. `acceptedMfaMethods` narrows it further where
+ // the challenged factor varies per action, so a proof of a fallback factor can't be
+ // replayed on an action that would never have asked for it.
const isMfaSessionActive = async ({
mfaSessionId,
userId,
@@ -278,10 +277,7 @@ export const mfaSessionServiceFactory = ({
await mfaLockoutService.enforceStepUpMfaLockStatus(userId);
};
- // True when THIS session (tokenVersionId) completed a full MFA login or management
- // step-up recently with one of `acceptedMfaMethods` (or a recovery code), so an
- // MFA-management step-up can be skipped within the grace window (see
- // recordRecentMfaAuth). Session-scoped, never user-scoped.
+ // Session-scoped grace after a login or management step-up, see recordRecentMfaAuth.
const hasRecentMfaAuth = async (
userId: string,
tokenVersionId: string,
diff --git a/backend/src/services/user/user-service.ts b/backend/src/services/user/user-service.ts
index 3a1e5a1663..2c21c8a427 100644
--- a/backend/src/services/user/user-service.ts
+++ b/backend/src/services/user/user-service.ts
@@ -256,10 +256,10 @@ export const userServiceFactory = ({
}
};
- // With MFA required nowhere, login is password-only, so challenging here protects
- // nothing: the same session could just enrol and enable its own factor instead.
- // Every org is checked, not only the current one, so switching to a non-enforcing
- // org is not a way to strip a factor another org relies on.
+ // If nothing requires MFA, login is password-only and a step-up here protects nothing:
+ // the same session could just enrol and enable its own factor. Every org counts, not
+ // just the current one, so switching to a non-enforcing org can't strip a factor
+ // another org relies on.
const isStepUpMfaRequired = async (userId: string) => {
const user = await userDAL.findById(userId);
if (user?.isMfaEnabled) return true;
@@ -647,17 +647,16 @@ export const userServiceFactory = ({
// the method, otherwise the user's own preference applies. Reaching a step-up-gated
// route already proves membership of this org, so no permission check is needed.
//
- // Removing a factor is never gated on that same factor, since the usual reason to
- // remove one is that it was lost. Another configured factor stands in, falling back
- // to the required method when nothing else is set up (e.g. no SMTP on a self-hosted
- // instance). The exception is a factor some accepted org enforces: that org has ruled
- // the alternatives insufficient, so the factor itself is still challenged and a lost
- // device is recovered via recovery-code login instead. Every org is checked, not only
- // the current context, so org switching cannot bypass it.
+ // Removing a factor never challenges that same factor, it's usually the lost one.
+ // Another configured factor stands in, or the required method if there's nothing else
+ // (e.g. no SMTP on self-hosted). Exception: a factor one of the user's orgs enforces is
+ // still challenged, that org already ruled the alternatives out, and a lost device goes
+ // through recovery-code login instead. All orgs are checked so org switching can't
+ // bypass it.
//
- // `accepted` lists every method a prior proof may carry for this action: the required
- // method always, plus the substitute when one is challenged. A proof of the substitute
- // must not be honoured by actions that would never have challenged it.
+ // `accepted` is every factor a prior proof may carry for this action: the required
+ // method, plus the substitute when one is challenged. Other actions never accept the
+ // substitute.
const getStepUpMfaMethod = async (
userId: string,
orgId: string,