MFA

The IAM service provides two MFA mechanisms: adaptive MFA triggered automatically by anomaly detection when a suspicious session event occurs, and custom MFA flows that your application triggers explicitly for sensitive user actions such as changing a password, transferring funds, or deleting an account.

Both mechanisms share the same infrastructure: a signed temporary JWT link, a 7-digit OTP code stored as a SHA-256 hash with a 7-minute expiry, multi-layer rate limiting, and an atomic verification function that rotates tokens on success.

Adaptive MFA lifecycle

When strangeThings() determines that a session event is suspicious (IP change, device mismatch, session limit exceeded, or proxy/hosting anomaly), it returns reqMFA: true. The calling controller then invokes sendTempMfaLink, which triggers the full adaptive MFA flow.

sendTempMfaLink

import { sendTempMfaLink } from '@riavzon/auth'

const result = await sendTempMfaLink(
  { userId: user.id, visitor: user.visitor_id },
  rawRefreshToken,
  req.ip!,
  res,
  {
    device: 'Safari on iOS',
    browser: 'Safari 17',
    location: 'Paris, FR',
  }
)

if (result === 'rate_limited') {
  res.status(429).json({ error: 'Too many MFA requests. Try again later.' })
  return
}

The function returns one of three values:

The metadata parameter accepts the EmailMetaDataOTP shape with three fields: device, browser, and location. The date field shown in the email template is generated server-side automatically.

OTP generation

generateMfaCode produces a cryptographically secure 7-digit numeric code using crypto.randomInt(1_000_000, 9_999_999), zero-padded to 7 characters. The raw code is returned to the caller for email delivery, while a SHA-256 hash of the code is stored in the database.

import { generateMfaCode } from '@riavzon/auth'

const result = await generateMfaCode(log, sessionToken, userId, jti)

if (result.ok) {
  // result.code  — the raw 7-digit string, send to the user
  // result.data  — insertion metadata
}

The function uses a database transaction with idempotency logic:

The mfa_codes table

Each row in the mfa_codes table represents a single pending OTP challenge. The table enforces uniqueness on user_id, code_hash, jti, and token, meaning each user can have at most one active code at any time.

OTP verification

verifyMfaCode is the central verification function used by all MFA flows: adaptive MFA, custom MFA, and email update. It validates the submitted code, performs the database lookup, and on success rotates tokens, updates fingerprints, and records the verification timestamp.

Rate limiting

Verification is protected by four rate limiters and three consecutive-failure caches that work together to prevent brute-force attacks:

Verification flow

Custom MFA flows

Custom MFA flows let you protect any sensitive action behind a second-factor check. The user must be authenticated (valid access and refresh tokens) to initiate a custom flow. Unlike adaptive MFA, which triggers automatically, custom flows are initiated by your application through a service-to-service call.

Reserved reasons

The following reason strings are reserved for internal flows and cannot be used with the custom MFA API:

Initiating a custom flow

POST /custom/mfa/:reason initiates a custom MFA flow. The controller enforces IP restrictions (the request must originate from service.clientIp or service.proxy.ipToTrust), applies four layers of rate limiting, and validates the parameters with Zod.

The reason comes from the URL path parameter and random comes from the query string. There is no request body:

POST /custom/mfa/payment?random=<254-500 char string>
Authorization: Bearer <access_token>
Cookie: session=...; canary_id=...

The controller extracts device fingerprint metadata from the request (device, browser, location via IP geolocation), then calls generateCustomMfaFlow which:

1. Generates a unique JTI (random UUID + 64 bytes of crypto.randomBytes)
2. Hashes the random challenge with SHA-256
3. Signs a temporary JWT with purpose set to the reason and subject set to {reason}_{visitor}
4. Builds the verification URL using pathForCustomFlow
5. Calls generateMfaCode to create and store the OTP
6. Sends the OTP email via mfaEmail

The endpoint enforces a 3-second minimum response time to prevent timing-based user enumeration, and always returns HTTP 200 on success.

Verifying a custom flow

After the user clicks the email link, two routes handle verification:

The POST handler is a thin wrapper: it checks for JSON content type, extracts the code from the request body, and passes it to verifyMfaCode. On success, the response includes the full token metadata (access token, refresh token, IAT) so the calling application can update its session.

Wiring custom MFA into routes

Import the verification middleware and controller to protect any route with a custom MFA check:

import {
  customMfaFlowsVerification,
  initCustomMfaFlow,
  verifyCustomMfa,
} from '@riavzon/auth'

Email update flow

The email update flow is a specialized use of the MFA system that requires the user to verify their identity with both their current password and a valid OTP code before their email address is changed.

{
  "email": "[email protected]",
  "newEmail": "[email protected]",
  "password": "current-password",
  "code": "1234567"
}

Post-MFA bypass window

After a successful MFA verification, the service records last_mfa_at on the user record with UTC_TIMESTAMP(). For the duration configured in byPassAnomaliesFor, anomaly checks that would normally require MFA (such as exceeding the session limit or connecting from a new IP) are skipped. This prevents users from being immediately challenged again on a device they have just verified.

The bypass also sets proxy_allowed = 1 and hosting_allowed = 1 on the user's visitor record, granting trusted status to connections from proxies or hosting providers that would otherwise trigger anomaly detection.

Routes reference

Configuration reference

OTP settings

Bypass window

Rate limiters

Email images

Image URLs for the OTP email template. Configured under magic_links.emailImages.otp. See the emails configuration reference for the full list of image fields.