security(auth): a TOTP code can be replayed within its validity window

[alex-dembele]

Problem

A TOTP code is accepted as many times as it is typed within its window. The server checks it with otp.VerifyTOTP (pquerna/otp totp.Validate, ±1 step, so about 90 s) and never records that it was used: MFASecret.LastUsedAt is written after a login challenge but never read.

So someone who watches a user type a code (shoulder-surfing, screen share, a recorded session) and also has the password or an open session can use the same code again within that window. The second factor is then not a second proof, and a replay goes through anywhere a code is checked:

Where	File
Login challenge	backend/internal/application/auth/mfa_usecase.go — ChallengeMFAUseCase.Execute
Enrolment verification	mfa_usecase.go — VerifyMFAUseCase.Execute
Turning MFA off (SSO accounts, #754 / D-061)	mfa_usecase.go — DisableMFAUseCase.Execute
Step-up for sensitive actions	backend/internal/infrastructure/authmfa/gate.go — Gate.VerifyRequired

Found while working on #754 (PR #848).

Acceptance criteria

1. A TOTP code accepted once for an account is refused if presented again, at any of the four places above, for as long as it would otherwise still be valid. The refusal looks exactly like a wrong code (same status, same body, same audit reason).
2. A code from an earlier time step than the last accepted one is refused too, so an older code seen on screen can't be used after a newer one.
3. Accepting a code and recording it happen atomically: two concurrent requests carrying the same code cannot both succeed. Proven by a test that fires them in parallel against Postgres.
4. Backup codes behave as today (already single use).
5. Additive schema only: one nullable column on mfa_secrets, carried by AutoMigrate and by a numbered SQL migration with a down file. Nothing dropped or renamed.
6. Tests: TestChallengeMFA_ReplayedCodeIsRefused, TestDisableMFA_ReplayedCodeIsRefused, TestGate_ReplayedCodeIsRefused, one test for an earlier step, and the concurrency test from criterion 3. The existing Success / NotFound / Unauthorized tests stay green.

Definition of Done

• The criteria above are met, with test output pasted in the PR.
• Full go test ./... passes, and the Postgres-gated tests pass with DATABASE_URL set on PostgreSQL 16.
• A live run against a booted server shows a replayed login code refused.
• No secret or code is logged.

[alex-dembele]

backend-go — 2026-09-30

Done — PR #851, stacked on #848 (base 754-…). Two commits:

• 2fb36537 pkg/otp/totp.go: MatchTOTPStep
• 7e6c668d:
  • domain/mfa.go: LastTOTPStep
  • gorm_mfa_repository.go: ConsumeTOTPStep, a conditional UPDATE; UpdateMFASecret now omits the column
  • migrations/0066_mfa_secrets_last_totp_step.{up,down}.sql: additive; the down removes nothing
  • mfa_usecase.go: acceptTOTP used by the challenge, the enrolment verification and the disable
  • authmfa/gate.go: same logic
  • tests in mfa_replay_test.go, authmfa/gate_test.go, gorm_mfa_replay_pg_test.go

Verified — The new tests PASS; with the step recording neutralised, 4 of them FAIL. On postgres:16-alpine (16.15): the concurrency test (20 racers → 1 winner) PASSES, and FAILS both without the WHERE clause and without the Omit. The full go test ./... passes, with 8 Postgres tests PASS. Migration 0066 is idempotent on a fresh database. Live, on the branch server with PG 16: first use 200, replay 400, previous step 400; last_totp_step is recorded.

Criteria — 1 ✅ · 2 ✅ · 3 ✅ · 4 ✅ (backup codes unchanged) · 5 ✅ · 6 ✅

Next — Owner review of #851, after #848 (stacked).

Blocked on — #848 (merge order)