feat(two-factor): add storeSecret hook for TOTP secret encryption - #11234

Implements #11233.

Why

The TOTP shared secret is encrypted at rest with XChaCha20-Poly1305 (@noble/ciphers), via symmetricEncrypt in packages/better-auth/src/crypto/index.ts. ChaCha20-Poly1305 is not a FIPS-approved algorithm, so a deployment constrained to FIPS 140-3 cannot use the TOTP second factor at all. The same function also derives its key by hashing the configured secret directly, which is not an approved KDF.

Scoping note: TOTP code generation itself was never the problem. createOTP from @better-auth/utils computes HMAC-SHA-1 through WebCrypto, and HMAC-SHA-1 remains approved for HMAC use under SP 800-131A Rev. 2. The secret is 32 characters from a 64-character alphabet (192 bits). So the only blocker was encryption of the secret at rest, and that is the only thing this PR changes. In particular it does not reimplement HOTP to get SHA-256, which would break real authenticator apps for no compliance benefit.

What

An opt-in totpOptions.storeSecret:

twoFactor({
  totpOptions: {
    storeSecret: { encrypt, decrypt },
  },
})

This deliberately mirrors the two hooks that already exist in this plugin rather than introducing a new shape:

The TOTP secret was the only value this plugin stores with no pluggable cipher. "plain" and "hashed" are intentionally absent — the secret must stay recoverable to generate codes, and it is a long-lived credential rather than a single-use code. Both the JSDoc and the docs now say so, since otherwise mirroring storeOTP: "plain" produces an unexplained startup error.

The built-in cipher remains the default. Behavior is unchanged unless the option is set.

encrypt and decrypt are required together, and an unrecognized value throws BetterAuthError at construction. This is the one intentional divergence from the sibling hooks: falling back to the built-in cipher when the pair is incomplete would write the secret under one cipher and read it under another, and silently using a non-approved cipher would defeat the entire reason for configuring a custom one. Validating options in the plugin factory follows jwt(), which does the same.

Files

• plugins/two-factor/totp/index.ts — the option, encodeTOTPSecret / decodeTOTPSecret, and the paired-config guard
• plugins/two-factor/index.ts — the encrypt site in /two-factor/enable routes through the helper
• plugins/two-factor/two-factor.test.ts — tests
• docs/content/docs/plugins/2fa.mdx — option docs and a migration guide

All three sites that touch the TOTP secret ciphertext are converted (enable, get-totp-uri, verify-totp); nothing outside plugins/two-factor/ reads twoFactor.secret.

Migration

Existing secrets are not re-encrypted, and are only rewritten when a user re-enrolls, so decrypt has to read both formats or existing users cannot sign in. The docs cover this with a tested recipe that tags new ciphertext and branches on the tag, rather than relying on the previous cipher throwing — that holds for an AEAD but a non-AEAD mode can return garbage instead of failing. There is also a callout for secrets: [...] rotation, where stored values are $ba$<version>$<hex> envelopes that a plain string key cannot decrypt.

Lazy re-encryption on read is a deliberate follow-up, not included here.

Testing

Verified on this branch rebased onto main (9b9638ec), in a Node 24 container with the docker compose services CI uses:

New tests cover: custom-cipher round trip using a real AES-256-GCM WebCrypto implementation and asserting the built-in cipher provably did not produce the stored value; the TOTP URI path; rejection of a non-matching code; the unchanged default and the explicit "encrypted" sentinel; all four misconfiguration guards (missing encrypt, missing decrypt, unrecognized string, null, and a non-serializable value); and the documented legacy-migration recipe reading a row written by the built-in cipher.

Known limitations, disclosed rather than fixed here

• getTOTPURI decrypts before the password check. This ordering predates the PR and is unchanged, but with this hook it means an integrator's KMS/HSM decrypt is now reachable one step ahead of that gate. The endpoint is behind sessionMiddleware and the URI is only built after the check, so it is not a disclosure — but moving decodeTOTPSecret below shouldRequirePassword is behavior-preserving and worth doing separately.
• Column width. twoFactor.secret is index: true, so it is generated as varchar(255) on MySQL/MSSQL and varchar(191) under Prisma. The built-in cipher's 144 hex characters always fit; a wrapped KMS key may not. Documented in both the JSDoc and the docs, with no runtime assertion.
• Backup codes and the 2FA OTP still default to the built-in cipher. Both already have their own hooks, so a FIPS deployment must set all three; only the TOTP gap was missing. Related: storeBackupCodes: { encrypt } alone currently writes ciphertext and reads it back through safeJSONParse, yielding null — a silent failure where storeSecret now fails loudly. Pre-existing and out of scope, but the inconsistency is worth an issue.

Separately, account.encryptOAuthTokens is documented as using "AES-256-GCM" (packages/core/src/types/init-options.ts) but routes through the same XChaCha20-Poly1305 symmetricEncrypt. Not touched here, but the docs are inaccurate.

Process note

CONTRIBUTING.md asks for features to be discussed in an issue first, so I opened #11233 alongside this and would rather you redirect the design there than review a shape you don't want. This PR is the concrete proposal for that discussion; close it without ceremony if the direction is wrong. The changeset is minor, so I believe the retarget automation will move this to next — happy to re-cut it as patch against main instead if you'd prefer, since the change is opt-in and existing users need take no action.

🤖 Generated with Claude Code

Summary by cubic

Implements #11233 by adding an opt-in totpOptions.storeSecret hook for custom TOTP secret encryption, including FIPS 140-3 validated modules and KMS/HSM integrations. TOTP previously always used the built-in XChaCha20-Poly1305 cipher; that remains the default, so existing behavior is unchanged unless the option is configured.

Migration

• Accepts "encrypted" or a custom { encrypt, decrypt } pair; plaintext and hashed modes are not supported because the secret must remain recoverable.
• Requires both custom functions and rejects invalid configuration at plugin startup instead of silently falling back.
• Existing secrets are not re-encrypted, so custom decrypt implementations must support the built-in format until users re-enroll.
• Documents tagged ciphertext migration, secret rotation, and database column size considerations.

Tests

• Covers custom encryption, TOTP URI generation, code verification, legacy ciphertext fallback, default storage, and configuration validation.

^{Written for commit 0e1435e. Summary will update on new commits.}