@lacspace/mfa

Orchestrate 2FA / 3FA step-up flows with NIST assurance levels.

The conductor for your factors. Track which factors a user has cleared, compute the Authenticator Assurance Level (AAL), and decide when a policy is satisfied — combining a password, a TOTP code and a passkey into 2FA or 3FA. Pair it with @lacspace/password, @lacspace/otp and @lacspace/webauthn to verify each factor.

• 🧩 MfaSession — mark factors verified, ask if the policy is satisfied
• 📊 assuranceLevel — AAL1 / AAL2 / AAL3 from factor types
• 🎯 Policies by min factors, min AAL, and required types
• ✅ verifyTotpFactor convenience (wraps @lacspace/otp)
• ⚡ Zero deps (bar @lacspace/otp) · 🌍 isomorphic · fully typed

Install

npm install @lacspace/mfa

Usage

import { mfaSession } from "@lacspace/mfa";

const session = mfaSession({
  factors: [
    { id: "password", type: "knowledge" },
    { id: "totp", type: "possession" },
    { id: "passkey", type: "inherence" },
  ],
  policy: { minFactors: 2, minAAL: 2 },
});

session.markVerified("password");
session.satisfied;          // false — one factor

session.markVerified("totp");
session.satisfied;          // true
session.aal;                // 2

// require the strongest assurance (adds a passkey → AAL3)
const step3 = session.state(); // { satisfied, aal, needFactors, needTypes, verifiedFactors }

Verify a TOTP factor in one call:

import { verifyTotpFactor } from "@lacspace/mfa";
if (await verifyTotpFactor(code, userSecret)) session.markVerified("totp");

Assurance levels

AAL1 a single factor · AAL2 two distinct factor types · AAL3 two+ including a hardware-bound inherence factor (passkey).

The Lacspace Security Kit

| Package | For | | --- | --- | | @lacspace/crypto | AES encryption & hashing | | @lacspace/password | Password hashing | | @lacspace/jwt | JWTs & tokens | | @lacspace/apikey | API keys | | @lacspace/otp | TOTP/HOTP 2FA | | @lacspace/webauthn | Passkeys / biometric | | @lacspace/mfa | 2FA/3FA orchestration (this package) | | @lacspace/lock | Account lockout | | @lacspace/headers | Secure headers / CSP | | @lacspace/redact | Log redaction |

New in 1.1 — factor verifiers & persistable sessions

import { mfaSession, MfaSession, verifyPasswordFactor, verifyTotpFactor, verifyBackupCodeFactor } from "@lacspace/mfa";

// Verify each factor with one call (wraps @lacspace/password + @lacspace/otp)
if (await verifyPasswordFactor(password, user.hash)) session.markVerified("password");
if (await verifyTotpFactor(code, user.totpSecret)) session.markVerified("totp");

// Persist step-up state across requests (signed cookie / store)
const saved = JSON.stringify(session.toJSON());
const session2 = MfaSession.fromJSON(config, JSON.parse(saved));

// Step-up windows: verified factors expire after factorTtlMs
const s = mfaSession({ factors, policy: { minAAL: 2 }, factorTtlMs: 5 * 60_000 });

Licensing

This package is free under the Lacspace Free Licence — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice.

Not every Lacspace package is free. We also offer Commercial (paid), Client-specific, and Private (proprietary) packages under separate terms. See the full Lacspace Licence Centre.

Part of the Lacspace ecosystem — 35 zero-dependency, isomorphic TypeScript packages.

All packages ↗ · npm org ↗ · Licence Centre ↗ · GitHub ↗