feat(security): a TOTP code can be used once

RFC 6238 says the verifier must reject a code it has already accepted: a code
stays valid for its whole thirty-second window, so one seen in flight — a
phishing page, a proxy, over the shoulder — could be replayed until it expired.

Tasks now record the counter of the last accepted step (totp_last_step), and a
login accepts a code only when its step is strictly greater. The guard is in the
UPDATE, not a read-then-write, so two logins racing with the same stolen code
cannot both find the old value and both proceed — exactly one moves the row.

auth.TOTPStep is VerifyTOTP that also reports which step matched, walking the
same one-step window; the code entered a little early or late spends the step it
was issued at, not the step it was checked at, so a late-but-valid code is still
single-use. Verified end to end: the same code presented to two logins in one
window is accepted once and refused the second time.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

internal/auth/auth_test.go

@@ -265,6 +265,39 @@ func TestRecoveryCodes(t *testing.T) {
 	}
 }
 
+// TOTPStep returns the step a code matched, and it must be the same step across
+// the tolerance window — that number is what makes a code single-use, so a code
+// entered a little early or late has to spend the same step, not a new one.
+func TestTOTPStepIsStableAcrossTheWindow(t *testing.T) {
+	secret, _, err := NewTOTPSecret("verdande", "k@example.com")
+	if err != nil {
+		t.Fatal(err)
+	}
+	now := time.Date(2026, 3, 10, 10, 0, 15, 0, time.UTC)
+	code := codeAt(t, secret, now)
+
+	want, err := TOTPStep(secret, code, now)
+	if err != nil {
+		t.Fatalf("the current code did not match: %v", err)
+	}
+	// Verified one step late — the code is still valid, and must report the step it
+	// was issued at, not the step it was checked at.
+	got, err := TOTPStep(secret, code, now.Add(30*time.Second))
+	if err != nil {
+		t.Fatalf("code rejected one step late: %v", err)
+	}
+	if got != want {
+		t.Errorf("same code reported step %d then %d; a replay check keyed on that would not catch it", want, got)
+	}
+
+	if _, err := TOTPStep(secret, "000000", now); err == nil {
+		t.Error("a wrong code returned a step")
+	}
+	if _, err := TOTPStep("", code, now); err != ErrNoTOTPSecret {
+		t.Errorf("empty secret: %v, want ErrNoTOTPSecret", err)
+	}
+}
+
 // codeAt produces the code an authenticator app would display at that moment,
 // using the same settings VerifyTOTP checks against.
 func codeAt(t *testing.T, secret string, now time.Time) string {

internal/auth/totp.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"crypto/rand"
+	"crypto/subtle"
 	"encoding/base32"
 	"errors"
 	"fmt"
@@ -82,6 +83,40 @@ func VerifyTOTP(secret, code string, now time.Time) error {
 	return nil
 }
 
+// TOTPStep verifies a code and returns the counter of the step it matched, so the
+// caller can refuse to accept the same step twice.
+//
+// ValidateCustom answers only yes or no, and "yes" for a code inside the skew
+// window is not enough to stop a replay: a code seen in flight stays valid for the
+// rest of its period, and the fix is to record which step was spent and never
+// accept that step or an earlier one again. That needs the number, so this walks
+// the same window ValidateCustom would — one step either side — and reports the
+// counter of the match. The comparison is constant time for the same reason the
+// password check is: a code is a secret being checked against a computed value.
+func TOTPStep(secret, code string, now time.Time) (int64, error) {
+	if secret == "" {
+		return 0, ErrNoTOTPSecret
+	}
+	code = strings.ReplaceAll(strings.TrimSpace(code), " ", "")
+
+	for offset := -int64(totpSkew); offset <= int64(totpSkew); offset++ {
+		at := now.Add(time.Duration(offset) * totpPeriod * time.Second)
+		want, err := totp.GenerateCodeCustom(secret, at, totp.ValidateOpts{
+			Period:    totpPeriod,
+			Skew:      0,
+			Digits:    totpDigits,
+			Algorithm: otp.AlgorithmSHA1,
+		})
+		if err != nil {
+			return 0, ErrInvalidCode
+		}
+		if subtle.ConstantTimeCompare([]byte(want), []byte(code)) == 1 {
+			return at.Unix() / totpPeriod, nil
+		}
+	}
+	return 0, ErrInvalidCode
+}
+
 // NewRecoveryCodes returns single-use codes for someone who has lost their phone,
 // and the hashes to store. Without these, losing a device means losing the account,
 // and the only fix left is editing the database by hand.