Skip to content

chore(auth): remove legacy session-token TOTP setup routes - #21334

Open
fxa-agent[bot] wants to merge 1 commit into
mainfrom
fxa-14626
Open

fxa-agent[bot] wants to merge 1 commit into
mainfrom
fxa-14626

Conversation

@fxa-agent

@fxa-agent fxa-agent Bot commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

Because

  • The auth server has two sets of TOTP setup routes. The legacy set accepts a session token. The /mfa/totp/* set requires an mfa:2fa JWT.
  • On main, the /mfa routes forward to the legacy handlers, so the legacy routes cannot go away on their own.

This pull request

  • Removes POST /v1/totp/create, /v1/totp/setup/verify and /v1/totp/setup/complete from totp.js, with their Swagger entries.
  • Moves the handler bodies onto the /mfa/totp/create, /mfa/totp/setup/verify and /mfa/totp/setup/complete routes.
  • Removes createTotpToken, verifyTotpSetupCode and completeTotpSetup from fxa-auth-client. The *WithJwt methods stay.
  • Removes the unused createTotpToken wrapper from the content-server fxa-client.js and Account, with its spec.
  • Changes the auth-server test client to call the /mfa routes with a JWT from signMfaToken.
  • Changes enableTotpOnAccount to use the *WithJwt methods with a JWT from testAccountTracker.getMfaJwtForScope, which is now public. Six functional specs use it.
  • Adds an it.each test in totp.spec.ts that checks that the three legacy paths are not registered.

Breaking change: external users of the three endpoints or the three removed client methods must move to /mfa/totp/*.

Issue that this pull request solves

Closes: https://mozilla-hub.atlassian.net/browse/FXA-14626

Checklist

Put an x in the boxes that apply

  • My commit is GPG signed.
  • If applicable, I have modified or added tests which pass locally.
  • I have added necessary documentation (if appropriate).
  • I have verified that my changes render correctly in RTL (if appropriate).
  • I have manually reviewed all AI generated code.

How to review (Optional)

  • Key files/areas to focus on: packages/fxa-auth-server/lib/routes/totp.js
  • Suggested review order: totp.js, totp.spec.ts, fxa-auth-client, then the test helpers.
  • Risky or complex parts: the deploy order with PyFxA (see below).

Screenshots (Optional)

Please attach the screenshots of the changes made in case of change in user interface.

Other information (Optional)

Any other information that is important to this pull request.

One reviewer call: can this deploy before mozilla/PyFxA#126 ships? PyFxA still calls /totp/create. The ticket says PyFxA#126 moves it to /mfa/totp/*.

Tests I ran on the local stack:

  • curl POST to the three legacy paths: 404 each (401 before the change). POST /v1/mfa/totp/create without a JWT: 401.
  • passwordlessApi.spec.ts "TOTP account returns unverified session": passed.
  • lib/routes/totp.spec.ts: 26 passed. mfa_totp.in.spec.ts and recovery_phone.in.spec.ts: 16 passed. fxa-auth-client mocha: 34 passing.
  • Type-check passed for auth-server, auth-client and content-server. ESLint passed on the 17 changed files. functional-tests tsc shows only the originalEmail errors in testAccountTracker.ts that exist on main.

Not run, left to CI:

  • signinPasswordless, passkey-signin, cms-2fa and stepUpAuth. They need the 123done relier or the CMS.
  • pairingFlow. The sandbox blocks the channel server, and the pairing test without TOTP fails there too.
  • The content-server mocha spec.

Kept on purpose: /totp/exists, /session/verify/totp and db.createTotpToken. The MFA routes use db.createTotpToken.

Follow-ups, not in this PR:

  • fxa_route_catalog.py is outside this repo and still lists the legacy routes. It needs a separate change.
  • packages/fxa-shared/sentry/tag.ts still lists /v1/totp/create as a critical endpoint. That file fails ESLint on main.

@fxa-agent fxa-agent Bot added the auto label Sep 29, 2026
@fxa-agent
fxa-agent Bot requested a review from a team as a code owner September 29, 2026 01:42
@fxa-agent fxa-agent Bot added the auto label Sep 29, 2026
## Because

- The `/v1/mfa/totp/*` routes replace the session-token TOTP setup routes `POST /v1/totp/create`, `/v1/totp/setup/verify` and `/v1/totp/setup/complete`.
- The functional tests and the test clients were the last callers of the old routes in the monorepo.

## This pull request

- Removes the three legacy routes from `totp.js` and their docs from `totp-api.ts`. The `/v1/mfa/totp/*` routes now hold the handler logic.
- Updates `totp.spec.ts` to test the MFA routes. The spec also checks that the old paths are not served.
- Removes `createTotpToken`, `verifyTotpSetupCode` and `completeTotpSetup` from `fxa-auth-client`, and removes the content-server wrappers for them.
- Moves the auth-server test client (`test/client/api.js`, `index.js`) to the MFA routes. The client signs an `mfa:2fa` JWT locally.
- Changes `enableTotpOnAccount` in `pairing-helpers.ts` to take an MFA JWT. Its callers get one from `testAccountTracker.getMfaJwtForScope('2fa', ...)`, which is now public.
- Round 1: fixes a 401 (errno 223) in `passkeySetPassword.spec.ts` and `passkeyPasswordFallback.spec.ts`. These calls still passed a session token.
- Round 2: no code change. It answers the CI failure on PR #21334 (56 of 89 functional tests with "Internal Server Error"). See "Other information".

**Breaking change:** `POST /v1/totp/create`, `/v1/totp/setup/verify` and `/v1/totp/setup/complete` now return 404. The one known external caller is PyFxA `Session.totp_create`. mozilla/PyFxA#126 moves it to `/mfa/totp/*`. That PR must land before this one. I did not check the Firefox desktop and mobile clients.

One reviewer call: merge this PR only after mozilla/PyFxA#126 lands.

## Issue that this pull request solves

Closes: FXA-14626

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant