docs(19.6-02): complete sm-mfa-plugin core plan summary

.planning/phases/19.6-two-factor-auth-and-device-flow-in-sm-user-plugin/19.6-02-SUMMARY.md

@@ -0,0 +1,369 @@
+---
+phase: 19.6-two-factor-auth-and-device-flow-in-sm-user-plugin
+plan: 02
+subsystem: auth
+tags: [sm-mfa-plugin, 2fa, totp, pquerna-otp, boombuler-barcode, qr-svg, recovery-codes, email-codes, trusted-devices, login-gate, cabana-settings, gormigrate]
+
+requires:
+  - phase: 19.6-01
+    provides: sm-user-plugin login-gate registry (classes.LoginGates), FinishLogin/IssueToken/APIArray/FireLoginEvent, AccessRevokedEvent.PasswordChanged(), TwoFactorAdmin slot, approved library pins
+provides:
+  - New local repository ../sm-mfa-plugin (module git.golem15.com/golem15/sm-mfa-plugin, package mfa, plugin golem15.mfa), no remote
+  - Login gate that answers PHP's {two_factor_required, challenge_token, available_methods, expires_at} for users with an enabled method
+  - Challenge routes /_user/api/v1/2fa/{verify,recovery,email/send} behind the 2fa-verify bucket (10/min per IP)
+  - Management routes status, totp/setup|confirm, DELETE totp, email/enable, DELETE email, recovery-codes (count, regenerate), trusted-devices (revoke one, revoke all)
+  - TOTP with SVG QR code, per-step replay refusal; recovery codes; email codes (A8, A9); per-user failure cap (A6); trusted devices (D-10) revoked on password change (D-07)
+  - Settings screen mfa (golem15_mfa_settings) applied per request; classes.Admin published as userclasses.TwoFactorAdmin (D-15)
+  - Five migrations 202610220001..202610220005
+affects: [19.6-03, 19.6-04, sm-demo-app, sm-bm-app, vue-demo-app, sm-sociallogin-plugin]
+
+actuals:
+  tokens: 52122      # chars/4 over every tracked file of ../sm-mfa-plugin except go.sum (208487 chars); go.sum adds 45100 chars
+  tasks: 3
+  commits: 0         # MEASURED in summercms.go: git rev-list --count 33920ed..33920ed (all code lives in ../sm-mfa-plugin)
+  sm_mfa_plugin_commits: 3   # MEASURED: git -C ../sm-mfa-plugin rev-list --count HEAD (5c6ad2f, 43d983b, 8a63f6f)
+plan_head_before: 33920ed558f19cda2b380340033b5fb95848dcb9
+plan_head_after: 33920ed558f19cda2b380340033b5fb95848dcb9
+sm_mfa_plugin_head_before: "(new repository)"
+sm_mfa_plugin_head_after: 8a63f6f
+sm_user_plugin_head: 3b22134   # unchanged by this plan
+
+tech-stack:
+  added:
+    - "github.com/pquerna/otp v1.5.0 (totp, hotp), sm-mfa-plugin only"
+    - "github.com/boombuler/barcode v1.1.0 (qr), sm-mfa-plugin only"
+  patterns:
+    - "Guarded single-statement transitions for attempts, completion, TOTP step acceptance, recovery-code consumption and email sends"
+    - "Per-request effective configuration: config defaults overlaid by a nullable settings singleton"
+    - "Mail capture in tests through postcard's log driver and a published *slog.Logger"
+
+key-files:
+  created:
+    - ../sm-mfa-plugin/plugin.go
+    - ../sm-mfa-plugin/routes.go
+    - ../sm-mfa-plugin/buckets.go
+    - ../sm-mfa-plugin/mail.go
+    - ../sm-mfa-plugin/admin_settings.go
+    - ../sm-mfa-plugin/admin_permissions.go
+    - ../sm-mfa-plugin/config/config.yaml
+    - ../sm-mfa-plugin/classes/config.go
+    - ../sm-mfa-plugin/classes/gate.go
+    - ../sm-mfa-plugin/classes/challenge.go
+    - ../sm-mfa-plugin/classes/login.go
+    - ../sm-mfa-plugin/classes/totp.go
+    - ../sm-mfa-plugin/classes/qr.go
+    - ../sm-mfa-plugin/classes/recovery.go
+    - ../sm-mfa-plugin/classes/email.go
+    - ../sm-mfa-plugin/classes/trusted.go
+    - ../sm-mfa-plugin/classes/methods.go
+    - ../sm-mfa-plugin/classes/events.go
+    - ../sm-mfa-plugin/classes/admin.go
+    - ../sm-mfa-plugin/controllers/helpers.go
+    - ../sm-mfa-plugin/controllers/challenge.go
+    - ../sm-mfa-plugin/controllers/management.go
+    - ../sm-mfa-plugin/models/ (registry, json_map, string_list, two_factor_method, two_factor_challenge, two_factor_recovery_code, trusted_device, settings, settings/fields.yaml)
+    - ../sm-mfa-plugin/updates/ (registry and 202610220001..202610220005)
+    - ../sm-mfa-plugin/views/mail/two_factor_code.htm
+    - ../sm-mfa-plugin/views/mail/two_factor_code-en.htm
+    - ../sm-mfa-plugin/testmain_test.go
+    - ../sm-mfa-plugin/harness_test.go
+    - ../sm-mfa-plugin/tracer_smoke_test.go
+    - ../sm-mfa-plugin/challenge_smoke_test.go
+    - ../sm-mfa-plugin/trusted_settings_smoke_test.go
+    - ../sm-mfa-plugin/README.md
+  modified: []
+
+key-decisions:
+  - "D-07 listener is Listen[*userclasses.AccessRevokedEvent] filtered by ev.PasswordChanged(), deleting trusted devices of ev.UserIDs on ev.Tx (plan 01 has no PasswordChangedEvent)."
+  - "The failure cap does not count the caller's own in-flight attempt (FailureCapReached inFlight=1 in verify routes, 0 at the gate and email/send), so the 10th failure, not the 9th, closes the window."
+  - "TOTP step acceptance is a guarded UPDATE inside the completion transaction, so two challenges racing with one code accept it once."
+  - "sm-mfa-plugin go.mod requires sm-user-plugin v0.1.11 and summercms v0.5.0; go.work replaces the user plugin with ../fonoteka.go/plugins/golem15/user (3b22134). Plan 03 moves the require to the released tag."
+  - "Migration IDs 202610220001..202610220005 in golem15.mfa's own history table; 202610220006 stays reserved for plan 03's WebAuthn credentials."
+
+patterns-established:
+  - "Second-factor routes: attempt() counts the attempt, resolves the user and checks the cap; completeSignIn() completes in one transaction, then mints through golem15.user and adds trusted_device_token"
+  - "Settings overlay: NULL column = config default; stored unknown mode behaves as optional"
+
+requirements-completed: [SC-1, SC-2, SC-4, D-01, D-04, D-05, D-06, D-07, D-09, D-10, D-12, D-13, D-15, D-16, D-18, D-19]
+
+coverage:
+  - id: D1
+    description: "TOTP tracer: setup with 200x200 SVG QR (matrix-exact), confirm stores ciphertext, password login answers the challenge with a SHA-256 token column, code completes once, replay refused, PHP 422 shape, 11th request from one IP is 429"
+    requirement: "SC-2"
+    verification:
+      - kind: unit
+        ref: "../sm-mfa-plugin/tracer_smoke_test.go#TestQRSVGSmoke"
+        status: pass
+      - kind: integration
+        ref: "../sm-mfa-plugin/tracer_smoke_test.go#TestTracerSmoke"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "Recovery codes (first set shown once, bcrypt, single use, count behind password, regenerate), email codes only for enabled users with 3-send cap and capped expiry in the rendered -en mail, five attempts, one token from 20 parallel verifies, per-user failure cap and window, last-method cleanup"
+    requirement: "D-18"
+    verification:
+      - kind: integration
+        ref: "../sm-mfa-plugin/challenge_smoke_test.go#TestChallengeSmoke (9 subtests)"
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "Trusted devices (hash, device name, skip, foreign/expired refused, revoke routes, off by setting), revocation on password change with rollback, settings saved through the admin API applying per request, social toggle, allow-lists, status keys and Carbon dates, published admin reset"
+    requirement: "D-12"
+    verification:
+      - kind: integration
+        ref: "../sm-mfa-plugin/trusted_settings_smoke_test.go#TestTrustedSettingsSmoke (9 subtests)"
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "Settings screen renders and is usable in the backend admin SPA (labels, tabs, dropdown empty choice, taglists)"
+    requirement: "D-12"
+    verification:
+      - kind: integration
+        ref: "TestTrustedSettingsSmoke/settings_row_applies and allow_lists (PUT /settings/mfa through the admin API)"
+        status: pass
+    human_judgment: true
+    rationale: "The API save path is tested; how the form looks and reads in the SPA is a visual judgement no test asserts."
+
+duration: 25min
+completed: 2026-10-26
+status: complete
+---
+
+# Phase 19.6 Plan 02: sm-mfa-plugin core Summary
+
+**New plugin golem15.mfa (../sm-mfa-plugin, three local commits): a login gate that answers PHP's two_factor_required challenge, TOTP via pquerna/otp with an SVG QR from boombuler/barcode and per-step replay refusal, recovery and email codes with the D-18 hardening, trusted devices revoked on any password change, a per-request settings screen and the TwoFactorAdmin reset service.**
+
+## Performance
+
+- **Duration:** about 25 min
+- **Started:** 2026-10-26T09:54:22Z
+- **Completed:** 2026-10-26T10:19Z
+- **Tasks:** 3 (one tracer, two expansions)
+- **Files:** 47 tracked files in the new repository; none changed in summercms.go or sm-user-plugin
+
+## Base commits
+
+- **sm-mfa-plugin** (`../sm-mfa-plugin`): new repository, branch master, no remote. HEAD `8a63f6f`.
+- **sm-user-plugin** (`../fonoteka.go/plugins/golem15/user`): unchanged at `3b22134`.
+- **summercms.go**: base `33920ed`; this plan's only commits here are the planning docs.
+
+## Task Commits
+
+| # | Repository | Commit | Message |
+|---|------------|--------|---------|
+| 1 (tracer) | sm-mfa-plugin | `5c6ad2f` | feat: TOTP second factor through the login gate |
+| 2 | sm-mfa-plugin | `43d983b` | feat: recovery codes, email codes and the per-user failure cap |
+| 3 | sm-mfa-plugin | `8a63f6f` | feat: trusted devices, the settings screen and the admin reset service |
+
+Nothing was pushed or tagged and no remote was created. The tracer feedback gate (interactive, end-of-phase, automated-only verify) re-ran both verify commands green before Task 2.
+
+## Accomplishments
+
+- **Plugin skeleton (D-01).** `golem15.mfa` requires `golem15.user`. Boot needs no database: it validates config, adds `&classes.Gate{}` to `*userclasses.LoginGates`, publishes `userclasses.TwoFactorAdmin` and registers the password-change listener. Only sm-mfa-plugin's go.mod requires pquerna/otp v1.5.0 and boombuler/barcode v1.1.0, and the archived YAML v3 module is not in `go list -deps`.
+- **Challenge (SC-2, D-05, D-06).** The token is 64 characters from crypto/rand and only its SHA-256 hex is stored. TTL is `two_factor_challenge_ttl`. Every verify counts an attempt in one guarded UPDATE (five real attempts, recorded A5), and a second guarded UPDATE completes the challenge, so at most one token is minted. Completion mints through golem15.user (`FinishLogin`, which restores a deactivated account only now, then `IssueToken`, `APIArray` and the login event with source `two_factor`), then fires `golem15.user.2fa.verified`. It honours `golem15.user.jwt.token_cookie`.
+- **TOTP (D-04).** Setup answers `{secret, qr_code_svg, qr_code_url}`; the QR is level M with a 4-module quiet zone, 200x200 px with a `viewBox`. Confirm stores the secret as `lagoon.Encrypted` with `last_counter`. Verify uses a one-step window, and accepting a step is a guarded UPDATE, so a code works once.
+- **Recovery codes (D-05, D-19).** Sets of 10 `XXXXX-XXXXX` codes are stored as bcrypt and consumed by a guarded UPDATE. The first set is returned by `totp/confirm` and `email/enable`. Listing gives only the count and needs the password; regenerate replaces the set in one transaction.
+- **Email codes (D-18 A8, A9).** Six digits, stored as bcrypt and mailed as `golem15.mfa::mail.two_factor_code` (pl) or `-en`. Only users with the email method enabled get one, at most 3 per challenge. The mail promises `min(email TTL, remaining challenge minutes)`.
+- **Failure cap (D-18 A6).** 10 failures in 15 minutes per user, counted from challenge rows. While the cap holds, the gate answers 401 `{"error":"Invalid or expired challenge."}` and creates no row, and every challenge route answers its generic 401. Failed rows are kept for the window.
+- **Trusted devices (D-10, D-07).** The token is stored as SHA-256 hex, with PHP's "{browser} on {os}" name and a 30-day TTL, off by default. A valid `trusted_device_token` in the login body skips the challenge; social sign-ins carry no fields and are never skipped. Devices are revoked by any password change (inside the write's transaction, so a failure rolls it back), by disabling the last method, and through the two revoke routes.
+- **Settings (D-12, D-13, D-09).** Screen `mfa` (permission `golem15.mfa.access_settings`, developer role) has a dropdown mode, array taglists with allow-lists, numbers and switches. A NULL column means the config value, and saved values apply on the next request. Only mode `disabled` exempts users. Social sign-ins are challenged only with `two_factor_social_login` on.
+- **Status.** `status` returns PHP's full shape. `trusted_devices` dates use Carbon's raw JSON form, and `webauthn_credentials` stays `[]` until plan 03.
+- **Admin reset (D-15).** `classes.Admin.Reset` disables every method and clears its secret and metadata, deletes recovery codes and trusted devices, and fires `golem15.user.2fa.disabled` with method `all`, all on cabana's transaction.
+
+## Exported identifiers, config keys and migration IDs (for plans 03 and 04)
+
+Package `mfa`:
+- `PluginID` (`golem15.mfa`), `Plugin`
+- `BucketTwoFactorVerify` (`2fa-verify`), `SettingsCode` (`mfa`), `PermissionAccessSettings` (`golem15.mfa.access_settings`)
+
+Package `classes`:
+- Config:
+  - `Config`, `LoadConfig`, `Effective` (struct embedding `Config`; `MethodAvailable`, `ChallengeDuration`), `LoadEffective(ctx, app, db)`
+  - `ConfigPrefix`, `KnownMethods`, `KnownModes`, `DefaultAvailableMethods`, `DefaultMode`, `DefaultEmailCodeTTL`, `DefaultChallengeTTL`, `DefaultTrustedDeviceTTLDays`, `DefaultFailureCapMax`, `DefaultFailureCapWindow`, `DefaultIssuer`
+- Gate: `Gate{App}`, `Database(app)`, `ClientIP(app, r)`
+- Challenge:
+  - `NewChallengeToken`, `HashToken`
+  - `CreateChallenge(ctx, db, user, ip, ua, ttl, keep)`, `FindChallenge`, `BeginAttempt`, `CompleteChallenge`
+  - `FailureCount`, `FailureCapReached(ctx, db, eff, userID, now, inFlight)`
+  - `ErrInvalidChallenge`, `ChallengeTokenLength`, `MaxAttempts`
+- TOTP and QR:
+  - `NewTOTPSecret`, `TOTPURL`, `NormalizeTOTPSecret`, `TOTPCounter`, `VerifyTOTP`, `TOTPPeriod`, `TOTPWindow`
+  - `QRSVG(text, size)`
+- Recovery codes:
+  - `RecoveryCodeAlphabet`, `RecoveryCodeCount`, `MaxRecoveryCodeLength`, `BcryptCost`
+  - `NewRecoveryCode`, `GenerateRecoveryCodes`, `EnsureRecoveryCodes`, `NormalizeRecoveryCode`
+  - `MatchRecoveryCode`, `MarkRecoveryCodeUsed`, `ConsumeRecoveryCode`, `RemainingRecoveryCodes`, `DeleteRecoveryCodes`
+- Email codes:
+  - `EmailCodeTemplate`, `MaxEmailSends`
+  - `NewEmailCode`, `MaskEmail`, `SendEmailCode(ctx, app, db, eff, ch, user)`, `EmailCodeMinutes`, `VerifyEmailCode`
+- Trusted devices:
+  - `UnknownDevice`, `ParseDeviceName`
+  - `IssueTrustedDevice`, `CheckTrustedDevice`, `RevokeTrustedDevices(ctx, tx, userIDs...)`, `RevokeTrustedDevice`, `TrustedDeviceList`
+- Methods and status:
+  - `EnabledMethods`, `MethodRow`, `MethodEnabled`, `EnableMethod`, `DisableMethod(ctx, app, tx, user, method)`
+  - `AcceptTOTPCounter`, `TouchMethod`, `LastCounter`
+  - `Enabled`, `Enforced`, `Status`
+- Login: `CompleteLogin`, `ChallengeUser`
+- Admin and listener: `Admin` (TwoFactorAdmin), `OnAccessRevoked(app)`
+- Events:
+  - `ChallengedEvent`, `FailedEvent`, `VerifiedEvent`, `RecoveryUsedEvent`, `EnabledEvent`, `DisabledEvent`, `RecoveryRegeneratedEvent`
+  - Names: `ChallengedEventName`, `FailedEventName`, `RecoveryUsedEventName`, `VerifiedEventName`, `EnabledEventName`, `DisabledEventName`, `RecoveryRegeneratedEventName`
+  - `MethodAll`, `Fire`
+
+Package `controllers`:
+- Challenge routes: `Verify`, `Recovery`, `EmailSend`
+- Management routes: `Status`, `TOTPSetup`, `TOTPConfirm`, `TOTPDisable`, `EmailEnable`, `EmailDisable`, `RecoveryCodesCount`, `RecoveryCodesRegenerate`, `TrustedDeviceRevoke`, `TrustedDevicesRevokeAll`
+- `QRSize`
+- Unexported helpers plan 03 reuses inside the package: `attempt`, `completeSignIn`, `withTrustedDevice`, `signedIn`, `validate`
+
+Package `models`:
+- `TwoFactorMethod`, `TwoFactorChallenge`, `TwoFactorRecoveryCode`, `TrustedDevice`, `Settings`, `LoadSettings`, `SettingsMethods`, `StringList`, `JSONMap`
+- `MethodTOTP`, `MethodEmail`, `MethodWebAuthn`, `MethodRecovery`, `ModeDisabled`, `ModeOptional`, `ModeEnforced`, `LangPrefix`
+
+Config keys (`golem15.mfa.*`, env `SUMMER_GOLEM15__MFA__...`):
+- `two_factor_mode` (optional), `two_factor_available_methods` ([totp, email]), `two_factor_enforce_groups` ([])
+- `two_factor_email_code_ttl` (10), `two_factor_challenge_ttl` (5)
+- `two_factor_passwordless_login` (false)
+- `trusted_device_enabled` (false), `trusted_device_ttl_days` (30)
+- `two_factor_social_login` (false)
+- `issuer` (app.name)
+- `failure_cap.max` (10), `failure_cap.window_minutes` (15)
+
+Migrations (golem15.mfa history):
+- `202610220001_create_golem15_user_two_factor_methods`
+- `202610220002_create_golem15_user_two_factor_challenges`
+- `202610220003_create_golem15_user_two_factor_recovery_codes`
+- `202610220004_create_golem15_user_trusted_devices`
+- `202610220005_create_golem15_mfa_settings`
+- Plan 03 takes `202610220006` for WebAuthn credentials.
+
+Routes:
+- Challenge (`throttle:2fa-verify`): `POST /_user/api/v1/2fa/{verify,recovery,email/send}`
+- Management (`throttle:user-api` plus `jwt.auth` per route): `GET status`, `POST totp/setup`, `POST totp/confirm`, `DELETE totp`, `POST email/enable`, `DELETE email`, `GET recovery-codes`, `POST recovery-codes/regenerate`, `DELETE trusted-devices/{id}` (digits), `DELETE trusted-devices`
+
+Mail templates: `golem15.mfa::mail.two_factor_code`, `golem15.mfa::mail.two_factor_code-en`.
+
+## Tests
+
+All Docker-backed tests ran against testcontainers Postgres. None were NOT RUN.
+
+- `go vet ./...` and `go test -count=1 -short ./...`: green at every commit.
+- `TestQRSVGSmoke` (short): pass.
+- `TestTracerSmoke`: pass.
+- `TestChallengeSmoke`, 9 subtests, all pass: `recovery_first_set`, `recovery_once`, `regenerate`, `email_only_when_enabled`, `email_send_cap`, `five_attempts`, `parallel_verify`, `failure_cap`, `disable_last_method`.
+- `TestTrustedSettingsSmoke`, 9 subtests, all pass: `trusted_skip`, `revoke_routes` (added), `trusted_disabled`, `password_change_revokes`, `settings_row_applies`, `social_toggle`, `allow_lists`, `status_shape`, `admin_reset`.
+- Full `go test -count=1 ./...` on the final commit: ok.
+
+## Decisions Made
+
+See key-decisions in the frontmatter. In addition:
+- `Effective` is a struct embedding `Config`, so plan 03 can add fields without changing `LoadEffective`'s signature.
+- The mode dropdown's empty choice, "Server configuration", stores NULL.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] The parent directory is not writable by golem**
+- **Found during:** Task 1 (`git init ../sm-mfa-plugin`)
+- **Issue:** `summercms.io/summercms` is owned by `jin` (0775, golem not in the group).
+- **Fix:** Created only `sm-mfa-plugin` with `sudo -n install -d -o golem -g golem -m 0775`, then ran `git init -b master` as golem. The golem-owned siblings sm-oauthserver-plugin and sm-journal-plugin are the precedent. Nothing else was created or changed with sudo.
+
+**2. [Plan 01 carry-forward - D-07] Listener on AccessRevokedEvent, not PasswordChangedEvent**
+- **Found during:** Task 3
+- **Fix:** `app.Events.Listen[*userclasses.AccessRevokedEvent](PluginID, classes.OnAccessRevoked(app))`, which skips events where `PasswordChanged()` is false and deletes the trusted devices of `ev.UserIDs` on `ev.Tx`.
+- **Acceptance impact:** The Task 3 grep for `Listen[*userclasses.PasswordChangedEvent]` prints 0 by design. `TestTrustedSettingsSmoke/password_change_revokes` proves D-07, including the rollback.
+- **Commit:** `8a63f6f`
+
+**3. [Rule 3 - Blocking] go.mod versions**
+- **Issue:** The plan named sm-user-plugin v0.1.5, which predates every seam.
+- **Fix:** go.mod requires `sm-user-plugin v0.1.11` (the phase base) and `summercms v0.5.0` (what sm-user-plugin requires), with go.mod `replace summercms => ../summercms.go` as sociallogin has. go.work replaces both with the local checkouts. Plan 03 bumps the user plugin to the released tag.
+- **Commit:** `5c6ad2f`
+
+**4. [Rule 1 - Race] TOTP replay guarded atomically**
+- **Issue:** The plan stored `last_counter` in the completion transaction. Two challenges verifying the same code in parallel could both read the old counter.
+- **Fix:** `AcceptTOTPCounter` is a guarded `UPDATE … WHERE last_counter < ?` in the completion transaction. Losing it rolls the completion back and answers the failure 401.
+- **Commit:** `5c6ad2f`
+
+**5. [Rule 2 - Security] Availability check on totp/confirm**
+- **Issue:** PHP checked availability only on setup, so a self-made secret bypassed the 403.
+- **Fix:** `totp/confirm` also answers 403 `{"error":"TOTP is not available."}`.
+- **Commit:** `5c6ad2f`
+
+**6. [Rule 2 - Correctness] Completed challenges honour token_cookie**
+- **Fix:** A completed challenge honours `golem15.user.jwt.token_cookie` as `/login` does: the cookie is set and `token` is left out of the body.
+- **Commit:** `5c6ad2f`
+
+**7. [Rule 2 - Correctness] The gate needs a usable method**
+- **Issue:** PHP challenged on any enabled row, including webauthn without credentials, which gives a challenge nobody can answer.
+- **Fix:** The gate challenges only when the filtered method list is non-empty. `status.enabled` and `status.methods` keep PHP's raw-row semantics.
+- **Commit:** `5c6ad2f`, `8a63f6f`
+
+**8. [Rule 1 - Correctness] The failure cap ignores the in-flight attempt**
+- **Fix:** `FailureCapReached(ctx, db, eff, userID, now, inFlight)`. The verify routes pass 1, because their own just-counted attempt is not yet a failure; the gate and email/send pass 0. Without this, a correct code after 9 failures would be refused.
+- **Signature changes:** `CreateChallenge` gained `keep` (the prune horizon). `SendEmailCode` takes `eff`.
+- **Recovery split:** `MatchRecoveryCode` (the bcrypt compares, outside the transaction) and `MarkRecoveryCodeUsed` (guarded, inside the completion transaction); `ConsumeRecoveryCode` is kept as the combined helper. Long bcrypt loops therefore hold no row lock.
+- **Commit:** `43d983b`
+
+**9. [Rule 1 - Bug] Carbon dates at second precision**
+- **Issue:** Postgres keeps microseconds, while PHP's columns had none.
+- **Fix:** `trusted_devices` dates are truncated to the second, so they read `….000000Z`.
+- **Commit:** `8a63f6f`
+
+**10. [Rule 3 - Test harness] Mail capture through the log driver**
+- **Issue:** party.Activate publishes `postcard.Mailer`, and it cannot be published twice.
+- **Fix:** The harness boots with `mail.driver: log` and publishes a capturing `*slog.Logger`, so tests read the rendered subject and text. This also checks template rendering.
+- **Other harness changes:** `bootMFA` returns `*mfaEnv` rather than `(app, server)`, and the harness sets `golem15.user.password.bcrypt_cost: 4`.
+
+**11. [Scope] Admin.HasTwoFactor is broader**
+- **Fix:** It is true for an enabled method, a recovery code or a trusted device, as the user plugin's `TwoFactorAdmin` doc defines it. The plan said only an enabled method.
+
+**12. [Scope] No `golem15.mfa::lang.mail.*` keys**
+- **Reason:** The templates carry their subject and body, as golem15.user's mails do, so mail lang keys would be unused. The `settings.*`, `permissions.*` and `plugin.*` keys exist in en and pl.
+
+**13. [Rule 2 - Hardening] Smaller additions**
+- The email-send guarded UPDATE also requires `attempts < max_attempts`.
+- A challenge or trusted token that is not 64 characters is refused before any query.
+- Tests added beyond the plan: `revoke_routes`, the 422 shape check in the tracer, and the settings save through the admin API.
+
+---
+
+**Total deviations:** 13: environment 1, carry-forward 1, versions 1, race and security fixes 4, correctness 3, harness 1, scope 2.
+**Impact on plan:** Every must-have truth holds. Only the D-07 listener grep fails, and it fails by design; no locked CONTEXT decision changed.
+
+## Known Stubs
+
+- `classes/methods.go` `Status`: `webauthn_credentials` is always `[]`, and `EnabledMethods` never lists `webauthn`. Plan 03 adds the credential table (migration 202610220006) and fills both in. Intentional.
+- `classes/admin.go` `Reset`: it does not yet delete WebAuthn credentials, because the table does not exist yet. Plan 03 adds that deletion.
+
+## Threat Flags
+
+None. Every new surface (challenge and management routes, settings screen, reset service, password-change listener) is in the plan's threat register.
+
+## Issues Encountered
+
+None beyond Deviation 1.
+
+## g15office
+
+This executor has no g15office tool, so it posted no comment on milestone task `avoroeb4`. The orchestrator should post the plan 02 update.
+
+## User Setup Required
+
+None.
+
+## Next Phase Readiness
+
+- Plan 03 can add WebAuthn inside sm-mfa-plugin:
+  - Migration `202610220006`.
+  - The webauthn verify and options routes in the challenge group, reusing `attempt`, `completeSignIn` and `withTrustedDevice`.
+  - `status.webauthn_credentials`, the `EnabledMethods` credential check, and WebAuthn deletion in `Admin.Reset`.
+  - The passwordless routes, gated by `two_factor_passwordless_login`.
+- Plan 03 still needs the user's go-ahead to create the remote and push sm-mfa-plugin and sm-user-plugin.
+- STATE.md already held uncommitted 19.6 hunks from another session or the orchestrator when this plan started. This plan ran the state handlers on top of them, but committed only SUMMARY.md and ROADMAP.md.
+
+## Self-Check: PASSED
+
+- All key files exist in ../sm-mfa-plugin.
+- Commits 5c6ad2f, 43d983b and 8a63f6f exist there; the working tree is clean and there is no remote.
+- The final full test run was green.