Firebase TOTP MFA Setup for Next.js

Add TOTP-based 2FA to your Firebase + Next.js app without writing auth boilerplate. Uses Firebase Identity Platform under the hood. Works on Next.js App Router and Pages Router.

1. Install

Run the CLI in your Next.js project. It detects your framework, copies the source files into app/(auth)/mfa-enroll, and wires the route into your existing layout.

npx firebase-totp-mfa add next --area /admin --issuer "MyApp"

2. Enable Identity Platform

Identity Platform must be turned on in your Firebase project before TOTP MFA works. Dry-run first to preview the API call:

npx firebase-totp-mfa enable --project YOUR-PROJECT-ID --dry-run

Then run without --dry-run to apply. The CLI sets adjacentIntervals=5 on the Identity Platform config so slow phones do not get locked out.

3. Verify

The CLI ships with a verification walkthrough that prints manual test scenarios — enrollment, login challenge, recovery code, lockout.

npx firebase-totp-mfa verify

Why this CLI

  • Shadcn-style ownership: source files land in your repo. No runtime dependency on this kit. You can edit anything.
  • AI-orchestration friendly: CLAUDE.md ships with the kit so Claude Code and Codex CLI follow hard rules (never read .env, never run destructive shells).
  • Identity Platform aware: the enable command flips the GCP-side config, not just the Firebase console.

Common errors

  • 403 on enable: the gcloud account is missing Project Owner. Run gcloud auth list and verify the active account has owner role on the project.
  • "Identity Platform not enabled":upgrade the project in the Firebase console first (Authentication → Settings → Identity Platform).
  • Wrong gcloud project: gcloud config set project YOUR-PROJECT-ID before re-running enable.

Full manual setup: docs/manual-setup.md · Troubleshooting: docs/troubleshooting.md