Two-factor auth

The twoFactor() plugin adds TOTP (time-based one-time password) support compatible with Google Authenticator, Authy, 1Password, and any RFC 6238 app. Users enroll once by scanning a QR code, then provide a 6-digit code on every sign-in.

Setup

pnpm add kavachos

import { createKavach } from 'kavachos';
import { emailPassword } from 'kavachos/plugins/email-password';
import { twoFactor } from 'kavachos/plugins/two-factor'; 

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    emailPassword(),
    twoFactor({ 
      issuer: 'My App',  // Shown in the authenticator app
    }), 
  ],
});

Enrollment flow

All enrollment endpoints require an active session.

const res = await fetch('/auth/2fa/enroll', {
  method: 'POST',
  credentials: 'include',
});

const { secret, qrCodeUrl, backupCodes } = await res.json(); 

await fetch('/auth/2fa/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: '482910' }),
});

Login verification

When a user with 2FA enabled signs in, the primary auth endpoint returns a partial response instead of a session:

{ "status": "two_factor_required", "challengeToken": "..." }

Submit the TOTP code along with the challenge token to complete sign-in:

POST /auth/2fa/verify

const res = await fetch('/auth/2fa/verify', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    challengeToken,   // From the primary auth response
    code: '482910',   // From the user's authenticator app
  }),
});

On success, a session cookie is set.

Backup codes

Ten single-use backup codes are generated at enrollment. Each is a 10-character alphanumeric string. A backup code can be submitted in place of a TOTP code at the verify endpoint — useful when the user has lost access to their authenticator app.

Regenerate backup codes

POST /auth/2fa/backup-codes

This invalidates all existing backup codes and issues a new set. Requires an active session.

const res = await fetch('/auth/2fa/backup-codes', {
  method: 'POST',
  credentials: 'include',
});

const { backupCodes } = await res.json();

Disabling 2FA

POST /auth/2fa/disable

Requires the user's current TOTP code as confirmation:

await fetch('/auth/2fa/disable', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code: '482910' }),
});

Check enrollment status

GET /auth/2fa/status

const res = await fetch('/auth/2fa/status', { credentials: 'include' });
const { enabled, enrolledAt } = await res.json();

Endpoints

All endpoints require an authenticated session unless noted.

Options