@playstack/mfa

@playstack/mfa provides passkey-first step-up authentication, TOTP, recovery codes, recent-auth proofs, trusted-device decisions, and account policy without taking session ownership from @playstack/auth.

Install

npm install @playstack/mfa @playstack/core @playstack/crypto @playstack/devices @playstack/events

Install @simplewebauthn/server only when using the optional Node adapter.

Compose the service

import { createMfa } from '@playstack/mfa'
import { simpleWebAuthnPasskeys } from '@playstack/mfa/webauthn'

export const mfa = createMfa({
  persistence,
  crypto: applicationCrypto,
  webCrypto: globalThis.crypto,
  recoveryHasher: passwordGradeRecoveryHasher,
  passkeys: simpleWebAuthnPasskeys(),
  limiter: mfaAttemptLimiter,
  events,
  clock,
  ids,
  issuer: 'Example App',
  rpId: 'app.example.com',
  rpName: 'Example App',
  origins: ['https://app.example.com'],
  trustedDevices: devices,
})

Configuration reference

Passkey bridge

PasskeyAdapter builds registration/authentication options and verifies both ceremonies against the service-supplied challenge, exact origins, RP ID, credential public key, and sign count. The service owns challenge lifetime and single use, credential uniqueness, discovery, and persisted sign counts.

The included simpleWebAuthnPasskeys adapter defaults user verification to required, prefers discoverable credentials, requests no attestation, hashes internal user IDs into fixed-size handles, and omits the allowlist for discoverable sign-in. Use userVerification: 'preferred' only if another factor provides verification.

Other bridge contracts

Security behavior

• TOTP uses HMAC-SHA1, a 30-second period, six digits, a one-step window, encrypted secrets, and counter replay prevention.
• Recovery codes are displayed once, activated only after acknowledgement, consumed atomically, and retained after use.
• Regenerating codes does not invalidate the previous set until the replacement is acknowledged.
• Sign-count regressions are persisted for detection but do not hard-lock synced passkeys.

MfaService implements auth’s StepUpVerifier. Register auth’s MFA-change handler for both enrollment and disable events so credential changes revoke existing sessions atomically. Route mfa.verification.locked to security notifications as a transactional event that bypasses preferences.

Persistence and testing

@playstack/mfa/prisma provides locked PostgreSQL persistence. Its managed, security-critical fragment is non-ejectable and declares its reverse User relations as model extensions. playstack database sync composes those fields into the selected managed auth artifact and validates the complete Prisma relation graph before writing. If an application owns the User model, it must supply the extension target explicitly. Applications still own migrations. @playstack/mfa/testing provides in-memory persistence and deterministic bridge fakes.

Boundary

MFA does not identify devices, issue sessions, choose account policy, or send lockout notifications. The Workers-safe core accepts any passkey adapter; Node-only WebAuthn support remains an optional subpath.

API entry points and requirements

Reference snapshot: @playstack/mfa@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.