Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
docs: require re-authentication for credential changes (T10) (#21235)
Danny Xu3c02a2fd8355
diff --git a/docs/design/reauthenticate-credential-changes.md b/docs/design/reauthenticate-credential-changes.mdnew file mode 100644index 0000000000..af3ce3e000--- /dev/null+++ b/docs/design/reauthenticate-credential-changes.md@@ -0,0 +1,2110 @@+# Require re-authentication to change your own credentials++Status: proposal · 2026-08-24++`UpdateUser` lets an authenticated caller rewrite their own password, TOTP secret, and recovery+codes without proving they still control the credential being replaced. Closes T10 in+[`v1-api-audit-2026-08.md`](v1-api-audit-2026-08.md) for every path `UpdateUser` and its neighbors+expose today: password and MFA lifecycle both move off `UpdateUser` onto their own methods, not just a+field addition — see [Resource design](#resource-design). A stolen access token may keep answering+requests until it expires (≤1h), but this design also stops it being *spent* on a replacement: every+path that mints a new token from an existing one is bound to the account's credential generation. See+G7 and Verification → Token-minting paths.++## Background++`UpdateUser` (`backend/api/v1/user_service.go:305`) serves two callers: a person editing their own+account (`callerUser.ID == user.ID`), and — self-hosted only — an admin with `bb.users.update`+editing someone else's, the recovery path [`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md)+covers. This doc is only about the first caller.++### Problem++The audit names two self-service paths: **password change** (`:371-378`) hashes and stores whatever+`password` the caller sends, and **2FA disable** (`:395-411`) clears `MFAConfig` on `mfa_enabled=false`+— neither checks that the caller still controls what's being replaced. Refresh tokens are revoked on+password change, but the attacker's access token keeps working for up to `access_token_duration`+(default 1h) after the account is already gone. A stolen laptop, shared browser, or leaked token is+enough to lock the real owner out permanently.++**Two more paths do the same damage without touching `password` or `mfa_enabled=false` at all**,+found while tracing what else writes `MFAConfig`:++- **`regenerate_recovery_codes=true`** (`:474-485`) promotes temp recovery codes to live ones,+ checked against nothing but an existing `OtpSecret`. The temp codes come from a prior+ `regenerate_temp_mfa_secret` call, itself unchecked. Two calls, no credential needed, and a+ stolen-session attacker holds working recovery codes.+- **`mfa_enabled=true`** (`:379-394`) promotes a temp TOTP secret over whatever is already live —+ reachable whether or not MFA was already on. Over an existing device, this **swaps it out without+ ever showing as "2FA disabled."** A victim checking their settings sees 2FA still on and has no+ reason to suspect the device isn't theirs anymore.++A fix scoped to literally the two audited lines leaves both of these open. All four live behind one+`update_mask` and three booleans on one RPC — itself part of why the gap existed (see+[Resource design](#resource-design)).++## Goals++- **G1** Every mutation that rewrites live authentication material — password hash, permanent TOTP+ secret, or permanent recovery codes — requires proof the caller currently holds a credential on the+ account: the current password, a live MFA code where the account has MFA, or a one-time email code+ where neither exists yet (Cloud, SSO, or a self-hosted account enrolling in MFA for the first time).+- **G2** Password change gets the same treatment as MFA: its own method, not a field plus a flag on+ a generic `Update` — matching this repo's own precedent. `UpdateEmail` already left `UpdateUser`+ for exactly this reason (it "changes the identity the person signs in with," per+ [`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md)); password is+ the same class of field.+- **G3** MFA enrollment, disablement, and recovery-code rotation are each their own method too, so a+ future MFA-adjacent change can't reopen this via a flag nobody thought to gate.+- **G4** No new elevated-session or token concept — proof is supplied inline, per request, from+ credentials the account already has.+- **G5** The check can't become a fresh guessing oracle — it shares the bound T9 already built for+ this exact problem shape, for both the password and MFA cases.+- **G6** Admin-assisted recovery (self-hosted only) is untouched: an admin resetting a locked-out+ user's password or MFA must not need the credential being replaced+ ([`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md)).+- **G7** Every mutation that actually changes live authentication material revokes the account's other+ refresh tokens (see Verification for why "actually changes" excludes the no-op enrollment check), same+ as password change already does, and — unlike password change today — atomically: the credential+ mutation and the revocation commit in one transaction, so a revocation failure fails the whole+ request instead of silently leaving refresh tokens live the way `UpdateUser`'s log-and-continue+ (`user_service.go:436-438`) does today. *Every* refresh token, not just web sessions — `web_refresh_token`+ and the OAuth2/MCP `oauth2_refresh_token` grants, plus outstanding `oauth2_authorization_code` rows+ that could still mint one, since G7's own claim is about what a stolen credential can do afterward,+ and an OAuth grant is exactly as persistent a credential as a web session is. Scoped precisely: this+ closes the ability to mint fresh access tokens afterward, not the access tokens already issued — those+ are self-contained JWTs `APIAuthInterceptor` accepts until they expire regardless of refresh-token+ state, so a stolen one already in use keeps answering requests for up to the workspace-configured+ access-token lifetime (default 1h, but see Verification → Token-minting paths — it has only a+ one-minute floor and no upper bound, so this window is not a fixed ceiling). What this design *does*+ bound is the *reuse* of that token to obtain a replacement: every path that mints a new token from an+ existing one — `SwitchWorkspace` and its two `workspace_service.go` callers, the MFA temp-token+ completion (`checkMFARequired`), and OAuth `/authorize` — is bound to `LastCredentialChangeTime` and+ refuses a token stamped before the change. Without that, the window is not an exposure ceiling but a+ renewal interval (unbounded for OAuth, which re-issues a full lifetime on every refresh), and G7's own+ sentence would be false. The atomicity, and the revocation coverage+ across all three OAuth/web token tables, are not carried forward unchanged — both are tightened here,+ not merely copied.++### Non-goals++- A time-boxed elevated session (GitHub sudo mode) or the formal OAuth step-up challenge (RFC 9470)+ — real session-state infrastructure for a handful of settings screens. See Alternatives.+- A general multi-factor collection (`users/{email}/mfaFactors/{id}`). Bytebase has one factor type+ and one factor per account; that cardinality doesn't exist yet.+- Whether SSO-provisioned accounts should be able to set a local password at all — pre-existing,+ orthogonal (`auth_service_idp.go:118-134`).+- Session/device listing and revocation — a separate feature (distinct from G7's automatic revocation+ on these specific actions, which is in scope).+- **Notifying the account owner by email when their password or MFA changes.** Standard elsewhere —+ GitLab, Google, and GitHub all do it (Reference) — but no such mechanism exists anywhere in this+ codebase today; the only email path near this code is the verification-code send for+ `RequestPasswordReset`. Detection, not prevention: T10 is closed by `CredentialProof` regardless of+ whether the owner is notified. Worth a follow-up, not bundled into this fix.+- **A `CredentialProof` channel that doesn't depend on SMTP** — most plausibly, re-authenticating+ against the account's own upstream IdP. Without it, a self-hosted, SSO-only workspace with+ `require_2fa` on and no mail server configured still has no way for a user to complete first-time+ MFA enrollment (see API → Messages, `email_code`'s own limits). Real, not closed by this design;+ needs its own integration with whatever OIDC/SAML flow already handles login, not a reuse of+ existing infrastructure the way `email_code` is.+- ~~**Blocking a still-valid access token from authorizing a brand-new OAuth grant.**~~ *Promoted into+ scope* — see Design → Verification, "Token-minting paths." This was a Non-goal on the grounds that+ closing it required a credential-generation claim in JWTs, which nothing else in the design needed.+ Two later findings removed that reasoning: `LastCredentialChangeTime` had to exist anyway for the MFA+ temp token, and `SwitchWorkspace` turned out to mint fresh access tokens off a stale JWT with *no*+ bound at all, which is strictly worse than the `/authorize` case and not deferrable. Once the claim+ has to be in access tokens for one, checking it in the other is a line of code, and leaving either+ open would keep G7's own sentence false.++## Resource design++MFA enrollment isn't a field edit — it's a two-step handshake (mint a secret, prove the caller+scanned it) plus two more state transitions that don't compose with a `FieldMask`. Every MFA-capable+API surveyed (Okta, Auth0, AWS IAM, WorkOS, Google Identity Platform, Zitadel, Keycloak — see+Reference) models it as its own resource or its own methods, never as flags on the account's generic+update call. None support the shape Bytebase has today: `mfa_enabled` doubling as both an output+status and a write trigger (disambiguated only by whether it's in `update_mask.paths`), and+`temp_otp_secret` / `temp_recovery_codes` — enrollment-flow-local scratch state — living as+permanent fields on `User` because they had nowhere else to go.++Password change is a plainer field, but the same argument applies once it needs a credential proof+rather than just a new value: AWS splits self-service `ChangePassword` from admin `UpdateLoginProfile`+outright, and this repo already draws that line for email — `UpdateEmail` is its own RPC because+identity-changing fields get their own call and their own confirmation, not a shared PATCH. Password+change moves to a new `ChangePassword` method for the same reason; `UpdateUser` keeps `password` only+for the admin-assisted path, where G6 means no proof is needed anyway.++## Design++**Verification.** `ChangePassword`, `EnableMfa`, `DisableMfa`, and `ConfirmRecoveryCodes` each take+a `CredentialProof` — the current password, a live OTP or recovery code where the account has MFA, or+an emailed code where neither exists — and check it before touching anything. One constraint on that+menu is not optional, and getting it wrong reopens the exact takeover `email_code`'s eligibility rule+exists to close: **when the account has a live MFA factor, a mutation that touches that factor must be+proven with the factor, not with `current_password`.** `DisableMfa`, and `EnableMfa`/`ConfirmRecoveryCodes`+when they replace an existing factor, therefore accept only `otp_code` or `recovery_code` while+`MFAConfig.OtpSecret` is live — never `current_password` or `email_code`. The reason is that+`current_password` is not a second, independent thing the caller knows: `ResetPassword` mints it from+mailbox possession alone, leaving MFA untouched (it "only ever touches the password," see below), so an+attacker with a stolen session and the account's mailbox could reset the password, then present that+fresh password as `CredentialProof` to strip the MFA the reset left standing. That is precisely the+mailbox-plus-session downgrade `email_code` refuses by requiring no-live-MFA; allowing+`current_password` against live MFA would leave the front door open beside the locked window. Requiring+the factor itself to change the factor closes both. (`ChangePassword` is unaffected — it accepts+`current_password` with or without MFA, since changing the password is not touching the factor, and a+password change already revokes sessions so it cannot be a step toward one.) "Check, then mutate"+has to be one transaction with the account row locked (`SELECT ... FOR UPDATE`) from before the check+to after the write, per this repo's own [row-lock ordering](../../backend/store/README.md#transaction-row-lock-ordering)+convention — not a read-verify-then-later-write sequence against a row nothing is holding. Without the+lock, two concurrent calls against the *same* still-current credential (an attacker who separately+obtained it, and the legitimate owner racing to rotate away from it) can both pass verification before+either commits; whichever write lands second overwrites the first regardless of who verified when —+so the owner's own password change could be silently undone by a request the attacker verified+*before* the owner's committed, using a credential that's supposed to already be dead by the time the+attacker's write lands. The lock removes the window: only one verify-and-write per account can be in+flight at a time, so a credential that stopped being current mid-flight fails the re-check the lock+forces before the write, not after.++That lock isn't only for the four proof-consuming methods, though — [a fifth+finding](https://github.com/bytebase/bytebase/pull/21235) caught that `StartMfaEnrollment` and+`RegenerateRecoveryCodes` need it too, for a reason that has nothing to do with proof freshness.+`Store.UpdateUser` writes the entire `mfa_config` JSONB column, not individual fields+(`principal.go:439-444`), so both mint methods have to read the account's current live `OtpSecret`/+`RecoveryCodes` and copy them into their own patch just to avoid clobbering them while only meaning to+touch the temp fields (`user_service.go:462-470` today). Without a lock, that read can happen *before*+a concurrent `ConfirmRecoveryCodes` promotes a rotation, and the mint's write can still land *after* —+resurrecting the exact live codes the owner just rotated away from, no credential needed to trigger it+at all. Locking and proof are answering different questions — is this row safe to read-then-write+concurrently, versus is the caller who they claim to be — and they only happen to overlap on four of+the six methods that touch this row. `StartMfaEnrollment`/`RegenerateRecoveryCodes` need the lock for+their own read-modify-write of `mfa_config`, same discipline, zero `CredentialProof` involved.++The lockout claim itself, though, has to stay *outside* that locked transaction, not inside it —+[a third finding](https://github.com/bytebase/bytebase/pull/21235) against an earlier version of this+paragraph, which said the opposite. A failed `CredentialProof` means the handler returns an error, and+an error inside the locked transaction rolls it back — if the claim were inside too, the rollback+would erase it right along with the abandoned mutation, so every wrong guess would vanish without a+trace and G5's five-attempt bound would never actually apply. T9's own design already has the right+shape for this, matching how login itself works: claim the matching slot (`PASSWORD`, `MFA`, or+`EMAIL_CODE`) in the `login_attempt` table for the account+([`login-attempt-lockout.md`](login-attempt-lockout.md)) as its own statement, committed unconditionally,+*before* the locked transaction opens — then verify with `bcrypt.CompareHashAndPassword` or the existing+`challengeMFACode` helper, both pure comparisons with no DB write and safe to call as-is, inside the lock,+clearing the already-committed slot on success. The `email_code` case is not a pure comparison, and+[not just a lookup either](https://github.com/bytebase/bytebase/pull/21235): a `REAUTH` code is a+one-time credential the same way a recovery code is, so verifying it has to *consume* it, atomically, in+the same transaction — an unconsumed match leaves the code valid for anyone who intercepts it again+before it expires. `verifyEmailCode` (`auth_service_email_code.go:420-446`) isn't reusable as-is for+exactly that: it reads the row (`:429`) and deletes it (`:443`) as two separate statements on the store's+own connection, and discards the delete's own success (`_ = s.store.DeleteEmailVerificationCodeIfMatch`)+— nothing stops two concurrent proofs from both reading the row before either deletes it, and both being+told they matched. `CredentialProof`'s `email_code` path needs the same shape as the recovery-code fix+below: a `DELETE ... WHERE email = ? AND purpose = ? AND code_hash = ? AND expires_at > now()` against+the open transaction, required to affect a row, not read-then-delete-and-ignore.+The `expires_at` clause isn't optional —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235): matching only on+email/purpose/hash would let an already-expired row still consume successfully for as long as it+survives until the hourly cleanup job removes it, `verifyEmailCode` itself checks `row.ExpiresAt` before+ever deleting (`:436-438`), and dropping that check here would leave an intercepted, expired code usable+against a credential change for up to that same hour. The atomic, expiry-checked, result-checked consume+is not `REAUTH`-only, either: `verifyEmailCode`'s read-then-delete-and-ignore shape is the *existing*+consume for the `LOGIN` and `PASSWORD_RESET` purposes too, so the same two-concurrent-proofs race lets an+attacker who intercepts a password-reset code race the legitimate owner and have *both* resets succeed.+The fix therefore replaces `verifyEmailCode` for all three purposes rather than adding a parallel path for+`REAUTH`, and it needs a store method that can report an affected-row count —+`DeleteEmailVerificationCodeIfMatch` (`email_verification_code.go:91-105`) uses `ExecContext` and discards+`RowsAffected` entirely, so a new `ConsumeEmailVerificationCode` returning the count (or a `RETURNING`+row) is a prerequisite for "required to affect a row" to be implementable at all. `challengeRecoveryCode`+(`auth_service.go:601-619`) is not reusable as-is the same+way — [a sixth finding](https://github.com/bytebase/bytebase/pull/21235): it consumes the code via+`s.store.UpdateUser`, a standalone statement on the store's own connection, not the transaction the lock+was just acquired on. Calling it while already holding `SELECT ... FOR UPDATE` on the same principal row+has that inner update wait on a lock its own outer call is holding — a session waiting on itself,+indistinguishable from a hang until `statement_timeout` fires, not a false positive to code around.+`CredentialProof`'s recovery-code path needs its own transaction-aware compare-and-consume: match and+delete the code, and write `mfa_config`, against the already-open transaction directly, instead of+routing through the top-level helper. This isn't only a `CredentialProof` problem, though — [a ninth+finding](https://github.com/bytebase/bytebase/pull/21235) against the claim just made: `Login`'s own+recovery-code completion (`completeMFALogin` → `challengeMFAAndClear` →+`s.challengeRecoveryCode`, `auth_service_lockout.go:78-88`) is not exempt either, because `Login`+already holds this same principal lock by the time it gets there — the session-issuance-fencing fix+above put it there deliberately ("the entire authenticate-or-consume-then-issue sequence runs while+holding it"), and `authenticateLogin` → `completeMFALogin` is exactly that authentication step for an+MFA-second-step login. A recovery-code login would hang the same way a `CredentialProof` recovery-code+check would. And `Login` is not the only such caller: `SwitchWorkspace`'s own MFA second step+(`auth_service.go:895-898`) reaches `challengeMFAAndClear` → `challengeRecoveryCode` too, *before*+`switchWorkspaceInternal` runs — so it consumes a recovery code outside every fence and lock this design+places on the switch path, with the same blind last-write-wins overwrite (two concurrent presentations of+the same recovery code each match their own `MFAConfig` snapshot, both write, the code is spent twice and+the later write resurrects whatever the earlier removed; a correct code clears the lockout, so T9 does not+bound it). All three call sites need the same fix: the transaction-aware compare-and-consume replaces+`challengeRecoveryCode` everywhere it would otherwise run inside — or, for `SwitchWorkspace`'s second+step, alongside — this lock, not just in the four new methods; and `SwitchWorkspace`'s MFA step joins the+fenced sequence rather than running ahead of it. `challengeMFACode` is still fine everywhere, since it+never writes.++Consuming a recovery code as `EnableMfa`'s own proof, specifically for a rotation, creates one more+place the whole-column-replace rule above already warned about —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235): a rotation's `CredentialProof`+can itself be `recovery_code` (see below), so the same request both consumes one live recovery code (the+proof) and promotes `TempOtpSecret` to `OtpSecret` (the mutation) — two writes to the same `mfa_config`+column, in the same transaction. Building the promotion's patch from the snapshot this transaction locked+at the *start* — before the proof consumed anything — would write back a `RecoveryCodes` list that still+contains the code the proof step just used, resurrecting a single-use credential the same request just+spent. The two writes have to be one: consume the code and promote the secret against a single patch+built from the post-consumption state (or folded into the same `UPDATE ... SET mfa_config = ?` as one+statement), never two sequential writes to a column `Store.UpdateUser` always replaces whole. Reusing T9's table+for all three means an attacker with a stolen session but no credential gets the same+five-guesses-per-ten-minutes bound as at login on every channel — not a fresh oracle, and no new+lockout kind to build; `RequestReauthCode`'s send side reuses the same table's existing resend+cooldown, so it can't be used to mail-bomb an account either. Accepting the old device's code (or a+recovery code) as an alternative to password on `EnableMfa` matters most exactly when replacing a lost+device; `email_code` covers the case neither of those helps — first-time enrollment, where nothing+prior exists to prove control of at all (see Cloud vs. self-hosted). Because each method requires its+proof in its own request message, whether it needs re-authentication is visible in its schema —+nothing to audit across a shared patch. On success — meaning a success that *actually changed live+credential material*, which is not every accepted call — the mutating methods call+`DeleteWebRefreshTokensByUser` and bump `LastCredentialChangeTime` in the same transaction as the+mutation itself. The qualifier is load-bearing for exactly one branch: `EnableMfa` on a first-time+passwordless enrollment requires no `CredentialProof` and promotes nothing (it only verifies the OTP and+leaves the account as unenrolled as it found it — see `EnableMfa` and the receipt-confirmation split), so+revoking sessions or bumping the generation there would let any stolen session run+`StartMfaEnrollment`+`EnableMfa` and knock the victim out of every session without holding any credential+at all — a no-credential griefing lever, and a direct contradiction of that branch's own "writes nothing,+harmless to retry" guarantee. Revocation and the bump follow the *mutation*, not the method name: they+fire in `EnableMfa` only on a rotation (a live secret is actually replaced), and for enrollment they+move to `ConfirmRecoveryCodes`, which is where the secret and codes actually go live and which does+require proof. `DisableMfa`, `ChangePassword`, and every rotation path change live material by+definition, so they always revoke — today only+`ChangePassword` inherits a call to it at all, from `UpdateUser`'s existing password branch+(`user_service.go:436`), and even there it's best-effort (`:437-438` logs and continues on error, the+password change commits regardless); `EnableMfa`/`DisableMfa`/`ConfirmRecoveryCodes` need the call+added, and all four need it atomic rather than copying that log-and-continue pattern (G7). Precisely:+this forces re-login, including the caller's own current session, the next time a refresh token would+have minted a new access token — it doesn't revoke an access token already in someone's hands, which+keeps working until it expires regardless (see G7).++Ordered wrong, though, as first written — [a sixth finding](https://github.com/bytebase/bytebase/pull/21235):+locking the principal row and only then deleting its `web_refresh_token` rows is parent-then-child,+backwards from this repo's mandatory rule of locking existing related rows child-to-parent+(`backend/store/README.md#transaction-row-lock-ordering`), and `web_refresh_token.user_email` is a+real foreign key to `principal.email` (`LATEST.sql:715-720`) — a `DELETE` on those rows counts as+acquiring a lock on them, same as an explicit `SELECT ... FOR UPDATE` would. Corrected order: lock the+account's *existing* `web_refresh_token` rows first (in primary-key order, if there's more than one),+then the principal row, then verify/mutate/delete within that same transaction. This is deliberately+the opposite of how session *issuance* orders its lock (principal first, since it's about to insert a+child row that doesn't exist yet — the `nextProjectID` shape, not the child-before-parent one)+— existing rows and not-yet-existing rows follow different rules in this repo's own convention, and+revocation and issuance land on opposite sides of that split for exactly that reason, not+inconsistently.++One more consequence of the same fix: before this design, nothing in this codebase ever locked+`web_refresh_token` before `principal` — this new child-before-parent ordering is the first, so it has+to be checked against every *existing* code path that touches both tables, not just the ones this doc+otherwise redesigns. `UpdateUserEmail` (`UpdateEmail`, unrelated to T10, untouched everywhere else in+this doc) runs `UPDATE principal SET email = ?` (`principal.go:496`), and `web_refresh_token.user_email`+is declared `ON UPDATE CASCADE` (`LATEST.sql:715-720`) — changing the email locks the principal first,+then cascades into locking and rewriting every `web_refresh_token` row referencing it, parent-then-child,+opposite of what revocation now does. `Store.UpdateUser` — the generic patch method all four+state-changing methods in this doc actually use — never sets `email` (`principal.go:419-450`), so+nothing else in this doc's own surface writes it.++That first pass [checked the wrong thing](https://github.com/bytebase/bytebase/pull/21235), though:+whether any other *code path* writes `principal.email`, not which *tables* `ON UPDATE CASCADE` off of+it — and there are three, not one. `grep -n "REFERENCES principal(email)" LATEST.sql` turns up+`oauth2_authorization_code.user_email` and `oauth2_refresh_token.user_email`+(`LATEST.sql:687,698`) alongside `web_refresh_token.user_email` (`:717`) — the same OAuth2+authorization-server tables `SwitchWorkspace`/token-exchange machinery uses, and the *only* three+`REFERENCES principal` anywhere in the schema (confirmed by grepping for that alone, not just the+`(email)` form, so there's no fourth relationship hiding behind a differently-named column). All three+cascade off the exact same `UPDATE principal SET email = ?`, so `UpdateUserEmail` needs to lock+existing rows in all three — `oauth2_authorization_code`, `oauth2_refresh_token`, and+`web_refresh_token` — not just the one this doc had already been discussing, each internally in+primary-key order and the three tables themselves in one fixed order, before running the `UPDATE+principal` that would otherwise cascade-lock them afterward.++That fixed order still has a gap when the email itself moves mid-sequence —+[a seventh finding](https://github.com/bytebase/bytebase/pull/21235): every child-row lock above runs+`WHERE user_email = ?` against whatever email the caller resolved *before* opening this locking+sequence — read once, from the account row a credential handler fetched to authorize the request, before+any lock is held. If a concurrent `UpdateEmail` commits between that read and these child-lock queries,+its cascade has already moved every matching row in `oauth2_authorization_code`, `oauth2_refresh_token`,+and `web_refresh_token` to the new email by the time `WHERE user_email = <old email>` runs — locking+nothing, not the rows this design needs held. Locking the principal row afterward by its stable ID still+finds the right account, so the credential mutation itself succeeds — but the child-table locks taken+moments earlier locked the wrong, now-vacated key, and any delete keyed off that same stale email (G7's+revocation included) deletes nothing: the tokens it exists to revoke survive, silently, on an account+that just proved it still controls its own credential. Re-deriving the email from *inside* the lock+doesn't avoid this, only moves it — the child rows still have to be located by some email before the+principal is locked, and that read is exactly what can go stale.++The fix is a check, not a different lock order: immediately after locking the principal row by ID,+compare its current `email` against the email the child-row locks were just taken under. A mismatch+means a concurrent `UpdateEmail` won the race and every child lock this sequence is holding is stale —+abort and retry the whole sequence from the top, re-reading the account's current email and re-locking+its child rows under it, rather than proceeding to mutate or delete against a key that no longer matches+any row. This is the same "whichever side reaches the shared row first determines the outcome" principle+this doc already applies to the issuance-vs-revocation race, with `UpdateEmail` as a third contender:+`UpdateEmail` first means it wins outright and the retry picks up the new email cleanly; one of these+four methods first means it holds the current email's child locks for the rest of its own transaction,+so `UpdateEmail`'s own child-lock step simply blocks behind them instead of racing past unlocked.++"Retry against the new email" is right for most proofs and [catastrophically wrong for+one](https://github.com/bytebase/bytebase/pull/21235), so the mismatch branch has to split by what the+proof was bound to. `current_password`, `otp_code`, and `recovery_code` are bound to the *account*: a+rename says nothing about whether the caller still holds them, so retrying against the account's new+address is correct and the caller is none the wiser. `email_code` is bound to a *mailbox address* — it+proves only that someone can read mail sent to the address it was mailed to. If the account has since+been renamed, that proof says nothing whatsoever about the account as it now exists, and retrying would+let control of the *former* address authorize a credential change on the renamed account. So: on+mismatch, account-bound proofs retry, `email_code` proofs **reject** — the caller must request a fresh+code, which will necessarily go to the account's current address.++The same split applies with more force to `ResetPassword`, which is `email_code`-shaped end to end and+otherwise exempt from this design. Its `PASSWORD_RESET` code proves control of one mailbox; if+`UpdateEmail` commits between that proof and the fenced write, proceeding by stable principal ID hands+control of the *old* mailbox a password reset on the renamed account. That is not a hypothetical ordering+nicety: renaming away from a compromised address is exactly why someone changes their email, and this+would let the attacker they were fleeing complete a reset afterward. Moving the write and revocation+inside the fence — the fix given for `ResetPassword` further below — does not address it at all, since+the problem is *which account* the transaction is entitled to act on, not whether its writes are atomic. After acquiring the+fence, `ResetPassword` re-reads the principal and proceeds only if its current email still equals the one+the code proved; otherwise it rejects, unconsumed work already done notwithstanding. Same rule as the+OAuth grant re-read below, with the opposite resolution — there a rename means "same grant, new address,+carry on," here it means "different account than the one that was proven, stop."++Finding all three tables here turned out to matter for more than lock ordering — [G7's revocation+scope was too narrow](https://github.com/bytebase/bytebase/pull/21235): `DeleteWebRefreshTokensByUser`+only ever touches `web_refresh_token`, so a stolen OAuth/MCP grant sails through every one of these+four methods untouched. `handleRefreshTokenGrant` consumes an `oauth2_refresh_token` row and issues a+replacement valid 30 days (`backend/api/oauth2/token.go:265-310,503-523`), and an unconsumed+`oauth2_authorization_code` can still be exchanged for a fresh one — neither participates in G7's+revocation at all today, so G7's own claim ("closes the ability to mint fresh access tokens+afterward") was false for exactly the credential class this table-discovery exercise was already+looking at. No bulk per-user delete exists yet for either table — `DeleteOAuth2RefreshTokensByUser`+needs writing (the existing `DeleteOAuth2RefreshTokensByUserAndClient` is scoped to one client, not+all of them) alongside an equivalent for `oauth2_authorization_code`. Revocation now locks and deletes+existing rows in all three tables — the same set, the same fixed cross-table order, as the+`UpdateEmail` fix above, so the two don't end up disagreeing with each other the way issuance and+revocation almost did.++Both new bulk-delete methods land on tables with [no index that serves+them](https://github.com/bytebase/bytebase/pull/21235): `oauth2_authorization_code` and+`oauth2_refresh_token` carry only their primary key and an `expires_at` index (`LATEST.sql:709-710`) —+no index on `user_email` for either. `web_refresh_token`, by contrast, already has+`idx_web_refresh_token_user_email` (`LATEST.sql:721`), which is exactly why+`DeleteWebRefreshTokensByUser` was cheap to add in the first place; `DeleteOAuth2RefreshTokensByUser`+and its authorization-code equivalent would be sequential scans without the same index, on tables an+active MCP integration can populate continuously. Add `idx_oauth2_authorization_code_user_email` and+`idx_oauth2_refresh_token_user_email` alongside the two new store methods, not as a follow-up — the+methods only exist because of this design, so there's no pre-existing caller to stay compatible with.+The *same two tables also lack a `client_id` index* — a gap that predates this design but that its new+client-fence locking turns from latent to load-bearing: `DeleteOAuth2Client`'s existing `ON DELETE+CASCADE` already fires an unindexed `DELETE … WHERE client_id = ?` per client (a locking sequential scan),+and the client-fence step this design adds ("lock every grant row referencing the client in primary-key+order") is a second unindexed locking scan, now run while holding the client fence — the worst place for+one. Add `idx_oauth2_authorization_code_client_id` and `idx_oauth2_refresh_token_client_id` in the same+migration.++Locking the account row for the mutation closes the credential-vs-credential race above, but not a+[separate one](https://github.com/bytebase/bytebase/pull/21235) between revocation and session+issuance, which never acquires that lock today. First found against `Refresh` specifically (it+consumes the caller's old refresh token, does its own work, and only inserts the replacement at the+end, `auth_service.go:479` through `:543`) — the same gap exists everywhere else a session gets minted:+`Login`/`Signup` (`finalizeLogin`, `auth_service.go:1036`) and `switchWorkspaceInternal` (`:1005`) call+the identical `issueSessionCookies` (`:1071`) with no lock either, and all four are one root cause, not+four separate ones.++Putting the lock only around `issueSessionCookies`'s own insert — this doc's own first attempt at this+fix — [turned out not to actually close it](https://github.com/bytebase/bytebase/pull/21235):+authentication (`Login`) and old-token consumption (`Refresh`, `switchWorkspaceInternal`) all happen+*before* `issueSessionCookies` is ever called, unlocked, so by the time the lock is finally acquired+there's nothing left for it to protect — the proof that justified issuing a session was already+established against whatever the row looked like earlier, and locking the insert doesn't retroactively+re-check it. The earlier reasoning that `Refresh` "finds its old token already gone" if a revocation+won the race was wrong for the same reason: `Refresh` consumes its own old token unconditionally, as+the first thing it does, regardless of whether a revocation ran concurrently — that consumption isn't+a signal about revocation at all. The lock has to move to *before* authentication/consumption, not just+before the insert, so the entire authenticate-or-consume-then-issue sequence runs while holding it —+matching how `nextProjectID` locks the project and requires it active *before* allocating an ID, not+after.++That "lock the principal first" framing was itself only half right, and the half that was wrong+[deadlocks against the revocation fix above](https://github.com/bytebase/bytebase/pull/21235):+`Login`/`Signup` have no existing token to consume, so locking the principal first before inserting a+brand-new child row is the correct `nextProjectID` shape. `Refresh` and `switchWorkspaceInternal`+aren't in that shape at all — both call `GetAndDeleteWebRefreshToken` (`auth_service.go:479,990`),+which deletes an *existing* `web_refresh_token` row, the same child-before-parent case revocation is.+Locking the principal before that delete, as issuance originally specified, is backwards for exactly+the reason it was backwards for revocation — and now the two disagree with each other in a way that+can deadlock: issuance holding the principal while waiting for the old-token row a concurrent+revocation is holding, revocation holding that row while waiting for the principal issuance is+holding. Split by whether there's an existing row to touch, matching revocation's own split: `Login`/+`Signup` lock the principal first (no existing child, `nextProjectID` shape); `Refresh`/+`switchWorkspaceInternal` lock their existing old-token row first, *then* the principal, consume the+token, re-authenticate against the now-current credential, and only then insert the new token (child,+then parent, then a fresh child — consistent with revocation's ordering, not opposed to it). With that+correction, whichever side — issuance or revocation — reaches the shared row first now determines the+outcome correctly without either one blocking the other indefinitely: issuance first means it+authenticates or consumes against the still-current credential, issues a session, and commits — then+revocation runs and deletes that session along with everything else, since+`DeleteWebRefreshTokensByUser` deletes whatever exists when it runs, not a snapshot from when the+request started; revocation first means it changes the credential and clears all tokens first — then+issuance acquires whatever lock it needs next and either re-authenticates against the *now-changed*+credential or finds the token it means to consume already gone, and fails closed instead of silently+minting a session that outlives the revocation meant to end it.++That "whichever side reaches the shared row first" framing only holds for two parties —+[a genuine three-party gap found in a later round](https://github.com/bytebase/bytebase/pull/21235):+`Login`/`Signup` locks the principal, inserts its new `web_refresh_token` row, and commits, releasing+the principal lock — but revocation's own child-row lock step ran *earlier*, against whatever rows+existed *before* that insert, so the newly-committed session isn't among the rows revocation already+locked. Revocation still has to catch it — "deletes whatever exists when it runs, not a snapshot from+when the request started" is the whole point of the paragraph above — so its actual deletion, run after+it finally acquires the principal lock, re-derives the current row set and reaches for that new row too.+If a *third* transaction — an ordinary `Refresh` against that same brand-new session — locks it first+(the correct child-before-parent order for an *existing* row, same as any other `Refresh`), the two+sides now deadlock exactly like the two-party case above, just assembled by three transactions instead+of two: revocation holds the principal, waiting on the row `Refresh` holds; `Refresh` holds the row,+waiting on the principal revocation holds. Neither one used the wrong order — revocation locked every+row that existed at scan time before touching the principal, and `Refresh` locked its row before+reaching for the principal — the row that breaks it is one neither transaction had anything to order+against, because a still-uncommitted `Login` created it in between.++Ordering alone can't close this — the row genuinely didn't exist yet when revocation did its own+child-locking pass, so no fixed table order helps. Closing it needs a lock that every participant shares+*before* it goes near the account's rows at all: one account-scoped advisory lock (keyed on the+principal's stable ID), held for the rest of the transaction that acquires it and released automatically+on commit or rollback, no separate unlock to forget.++Where in the transaction it's acquired is the whole point, and [getting that wrong reintroduces the+deadlock it exists to remove](https://github.com/bytebase/bytebase/pull/21235): an earlier version of+this paragraph had the inserting paths take it "immediately before that insert," which is *after*+`Login`/`Signup` has already locked the principal and after `Refresh`/`switchWorkspaceInternal` has+locked its old token row and the principal. That's a plain lock-order inversion against revocation, which+takes the fence first and reaches for rows second — issuance holding the principal while waiting for the+fence, revocation holding the fence while waiting for the principal. The fence is only a fence if it is+strictly first: **every** participating transaction acquires it as its opening statement, before any+`SELECT ... FOR UPDATE`, any consume, any insert, and any authentication step. It sits above this doc's+entire child-before-parent ordering rather than inside it — that ordering governs which *row* locks come+in which sequence, and this governs that no participant touches rows at all until it holds the account.++Who participates is a **rule, not a list** — stated that way deliberately, because the enumerated version+of this paragraph was wrong twice in a row, each time by naming the paths that had come up so far and+[missing ones found the round after](https://github.com/bytebase/bytebase/pull/21235). The rule: *any+transaction that reads or scans this account's token rows and then writes based on what it found, and any+transaction that inserts one, takes the fence as its first statement.* Both halves matter — a scanner+without the fence can have rows appear underneath it, and an inserter without the fence is what makes+them appear. (The one case that cannot take a fence first is an account that doesn't exist yet; see+account creation below, where the uncommitted principal row does the same job.) A path that satisfies the ordered-lock contract but skips the fence is still broken: ordering+governs rows that exist, the fence governs rows that don't exist yet, and every finding in this section+has been one or the other.++By that rule the participants are: G7's revocation on all four credential-mutating methods;+`Login`/`Signup`, `Refresh`, and `switchWorkspaceInternal`; the OAuth mint (`handleAuthorizePost`) and+both exchange paths; `UpdateEmail`; `handleReauthorize`; the three retained password resets —+`ResetPassword`, `UpdateUser`'s admin-assisted path, and the `bytebase recovery` CLI+(`backend/component/recovery/service.go:361-368`, see Token-minting paths for why it was the easiest to+miss and the worst to have missed). Several of these were missed by earlier enumerations the same way —+each had already been given the ordered-lock fix in an earlier round, which reads like the whole+treatment but is only half of it.++**One account fence is not enough**, though — [the rule above is right and its+single scope is wrong](https://github.com/bytebase/bytebase/pull/21235). OAuth grants hang off two+parents, and client deletion is a scan-then-write over the *client's* children with the identical+absent-child gap: `DeleteOAuth2Client`/`DeleteExpiredOAuth2Clients` scan the client's existing grants,+then `DELETE FROM oauth2_client` cascades and re-derives locks over whatever grants exist at that moment+— including an authorization code `/authorize` committed in between. A token exchange holding that unseen+code and waiting on the client row deadlocks against the deletion holding the client and cascade-waiting+for the code. The account fence cannot close it, and not just because client deletion wasn't listed: a+client's grants span *many* accounts, and `DeleteExpiredOAuth2Clients` spans many clients, so no+principal-keyed lock serializes a deletion against a mint for a different account on the same client —+including a client that had no grants at all when the scan ran.++So there are two fences, one per parent: the account fence keyed on `principal.id`, and a **client fence**+keyed on `oauth2_client.client_id`. A transaction takes whichever the rule implicates — and a transaction+touching grants implicates both, since every grant row has both parents. `handleAuthorizePost` and both+exchange paths take both; `handleReauthorize` takes both (it deletes by user *and* client);+`DeleteOAuth2Client`/`DeleteExpiredOAuth2Clients` take the client fence, before their own scan; the+web-session-only paths (`Login`/`Signup`, `Refresh`, `switchWorkspaceInternal`, `ResetPassword`,+`UpdateEmail`, the credential-mutating four) take the account fence, and also the client fence when their+revocation reaches OAuth grants — which G7's does, so in practice all four credential-mutating methods+take both.++Two fences means an ordering problem *between the fences*, which is the same failure this whole section+keeps rediscovering one level up, so it gets a fixed order rather than being left to chance: **account+fence first, then client fence**, always, by every path that takes both. For the bulk paths, the same+rule that governs rows governs fences — `DeleteExpiredOAuth2Clients` takes its client fences in+`client_id` order, and a revocation spanning several of an account's clients takes those in `client_id`+order too, after the account fence. Arbitrary but fixed is the whole requirement; picking account-first+just matches the order the rest of this doc already reads in.++One participant *cannot* obey "as its first statement," and saying so is the fix rather than an exception+to wave at — [caught the round after](https://github.com/bytebase/bytebase/pull/21235): account creation.+`Signup` (`auth_service.go:345,361`) calls `Store.CreateUser` and then `finalizeLogin` as two separate+calls, and `CreateUser` runs a bare `QueryRowContext` on the store's own handle (`principal.go`,+`INSERT INTO principal ... RETURNING id`) — autocommit. The same shape covers the other two creation+paths, SSO auto-provisioning (`auth_service_idp.go:129`) and Cloud email-code auto-provisioning+(`auth_service_email_code.go:267`), both of which flow into the same `finalizeLogin` (`:223`). The account+fence is keyed on `principal.id`, which does not exist until that insert commits, so a newborn account+literally has nothing to take a fence on when its flow begins.++The gap that leaves is not theoretical: the principal is committed and visible for the whole window+between `CreateUser` returning and `finalizeLogin` inserting the session. An admin deactivation or+admin-assisted password reset landing in that window finds a real account with zero sessions, revokes+nothing, and reports success — and then the original signup inserts its refresh token afterward, leaving+a live session on an account that was just deactivated or had its password reset out from under it. No+fence ordering helps, because the fence didn't exist yet on one side.++Creation and session issuance become one transaction: insert the principal, take the account fence on the+id that insert returns, insert the session, commit. Inside it the uncommitted parent does the fence's job+by itself — no other transaction can see the row at all, so none can act on the account in the window,+and an admin path racing it fails to find the user rather than half-succeeding against it. That is the+correct outcome: creation either happens completely, session and all, or not at all. This also folds the+creation paths into the same `nextProjectID`-shaped discipline the rest of this section uses — lock (or+here, own) the parent before writing the child, rather than committing the parent and hoping nothing+happens next. Needs its own interleaving test: an admin deactivation or reset issued against an account+mid-signup must either lose cleanly (user not yet visible) or win cleanly (signup rolls back), never+observe the account and miss its session.++A fence per transaction still doesn't make MFA login *one* authenticate-and-issue sequence, which is what+this section has been assuming all along — [the round after](https://github.com/bytebase/bytebase/pull/21235).+An MFA login is two HTTP requests: the first verifies the first factor and returns a signed+`mfaTempToken` good for five minutes (`auth_service.go:36,731`), committing and releasing its fence; the+second presents that token plus an OTP or recovery code, and `completeMFALogin`+(`:645-672`) re-reads the account but verifies *only* the second factor — it never revisits the password+that got the temp token issued. So a `ChangePassword` or `ResetPassword` can commit in between, revoke+everything, and the holder of a temp token minted against the **old** password still completes step two+and walks away with a brand-new session. No fence closes this: the two requests are separate+transactions, and the fence is correctly released when the first commits.++This one is not a caveat to accept alongside the access-token window (see G7). That window is about+already-issued tokens continuing to answer for ≤1h; this *mints a new session after the revocation*, which+is precisely the thing G7 claims to close, so leaving it would make G7's own sentence false for a+five-minute window on every MFA account. It is also the cheapest place to introduce the generation stamp:+this token is short-lived, single-purpose, minted by `Login` itself, and already carries account-specific+claims, so one more is a local change to a flow this doc already modifies. (At the time, the `/authorize`+gap was still a Non-goal precisely because *it* would have needed the stamp threaded through system-wide+JWT issuance. Token-minting paths, below, is where that stopped being avoidable.)++The temp token carries the credential generation it was issued against, and step two rejects it on+mismatch, re-read inside its own fence. Generation means *any* of the mutations that revoke sessions, not+just the password: all four methods here, plus `ResetPassword` and the admin-assisted reset, already write+the principal row inside the fence, so they bump one monotonic `Profile.LastCredentialChangeTime` while+they're there. `LastChangePasswordTime` is not reusable for this — it deliberately means "has this account+ever had a caller-chosen password" for `email_code` eligibility (see below), and MFA mutations must not+move it. A stale temp token then fails closed at step two rather than completing. Note the second factor+alone does not cover this even incidentally: `EnableMfa` rotating the secret would fail the OTP check by+luck, but `ChangePassword` and `ResetPassword` leave `MFAConfig` untouched, so the OTP still validates+perfectly against a credential the account no longer authenticates with. Needs the interleaving in the+regression tests: a temp token issued, a credential mutation committed, and step two attempted after —+which must fail, not mint.++**Token-minting paths.** The temp-token fix above is one instance of a question this design had never+asked systematically: *what, besides `Login`, can produce a fresh access token from something an attacker+might already hold?* Asking it turned up+[the one that matters most](https://github.com/bytebase/bytebase/pull/21235). `SwitchWorkspace`+(`auth_service.go:889-910`) authenticates from nothing but the interceptor-validated JWT — `user, ok :=+GetUserFromContext(ctx)` — checks workspace membership, and calls `switchWorkspaceInternal`, whose+`web == false` branch returns `response.Token = token` (`:1008-1010`): a brand-new access token minted+by `generateLoginToken` with a full `GetAccessTokenDuration` (`:743-749`). No refresh token is consumed,+no credential is proven, and `rejectMCPOriginatedTokenMint` blocks only MCP-origin requests, not a stolen+ordinary API token. `workspace_service.go:317,426` reach the same mint by two more routes.++So a stolen non-web access token can be spent, before it expires, on a fresh one with a fresh full+lifetime — and then again, and again. The ≤1h ceiling G7 claims is not a ceiling at all for a non-web+token; it is a renewal interval. That is worse than the `/authorize` case that was a Non-goal: that one+needs an OAuth client and yields a grant this design's revocation can at least delete, whereas this needs+nothing, leaves no row anywhere to revoke, and renews indefinitely. The account fence does not touch it —+fencing serializes the issuance, it does not ask whether the JWT presenting itself is still entitled to+one.++Fixing it is now cheap for a reason that did not hold when `/authorize` was deferred:+`Profile.LastCredentialChangeTime` already has to exist for the MFA temp token, so the remaining work is+to stamp it into access tokens at issuance and compare it against the account row at every path that mints+a *new* token from an *existing* one — `SwitchWorkspace` and its two `workspace_service.go` callers,+plus `/authorize`, which the same check closes for free. A token whose stamp is older than the account's+current value is refused; the holder must authenticate again. Ordinary API calls are deliberately *not*+in this set: rejecting those would turn every credential change into an immediate hard cutoff for+in-flight work, which is the caveat G7 knowingly accepts. The line is minting, not use.++Two rollout details this needs and the temp-token version does not. The first is a distinction the+naive version of "refuse on a missing stamp" gets fatally wrong — [caught in+review](https://github.com/bytebase/bytebase/pull/21235): there are *two* different things that can be+absent, and only one of them may cause a refusal. A **token** with no generation claim is a pre-upgrade+token, and refusing to let it mint is correct. But the **account row** also has no generation until its+first credential mutation — `LastCredentialChangeTime` starts nil on every account that exists today and+every account created after the upgrade — so a token freshly and legitimately minted *after* the upgrade,+for an account that has simply never changed a credential, would carry whatever that nil stamps to. If a+nil account value produces a missing claim and a missing claim is refused, `SwitchWorkspace` and+`/authorize` reject brand-new, perfectly valid tokens until the user happens to change a credential —+breaking normal operation for the entire existing user base on day one. The account's generation must+therefore always be *defined*, never nil: the same migration that backfills `LastChangePasswordTime`+(see Cloud vs. self-hosted) backfills `LastCredentialChangeTime` to the row's `created_at` for every+existing `END_USER`, and account creation sets it going forward. With that, the rule is a clean+comparison — a token is refused only when its claim is *strictly older* than the account's current+generation (a real credential change has happened since it was minted), a fresh token carries the+account's current generation and matches, and the only truly-missing *claim* is a pre-upgrade token,+refused as its own explicit case. And `LastCredentialChangeTime` is now load-bearing+for both this and the temp token, so the seven mutations that bump it — the four here plus `ResetPassword`,+the admin-assisted reset, and the `bytebase recovery` CLI reset (below) — must bump it inside their fenced+transaction, not before or after, or a token minted mid-mutation could carry a stamp that never matches+anything.++The seventh is the one a `backend/api/`-scoped search cannot see —+[caught by Codex](https://github.com/bytebase/bytebase/pull/21235): the self-hosted operator recovery CLI+(`backend/component/recovery/service.go:361-368`) writes `PasswordHash` through the same `Store.UpdateUser`,+and today it revokes nothing at all — not even the best-effort web-token delete the other two retained+resets have. A break-glass reset is the *most* adversarial context this design serves: the operator is+resetting the password precisely because the account may be compromised, and today every session, OAuth+grant, and MFA temp token the attacker holds survives it. It joins the other resets fully: account fence+first, password write, all-three-table revocation, and the generation bump, in one fenced transaction.+(Its `LastChangePasswordTime` was already handled — `Store.UpdateUser` bumps that automatically on any+`PasswordHash` write, `principal.go:429-434` — which is exactly why the *other* stamp has to be verified+per-writer rather than assumed to tag along.)++Four corrections to the paragraphs above, from a systematic sweep of every token-minting path (not the+one-at-a-time discovery that found `SwitchWorkspace`):++- *The MFA temp token has two mint sites, not one.* The temp-token fix says it is "minted by `Login`+ itself"; it is not. `checkMFARequired` (`auth_service.go:718-739`) is called from `Login` (`:209`) **and+ from `SwitchWorkspace` (`:903`)**, both reaching `GenerateMFATempToken` at `:731`. The+ `SwitchWorkspace` route is worse: it needs only the stolen access token, no password, to obtain a temp+ token, which then completes a full `Login` after the victim's credential change. The stamp is written+ and checked inside `checkMFARequired`, not at the `Login` call site, or the second door stays open.+- *`SwitchWorkspace` doesn't even expiry-check the session it consumes.* `switchWorkspaceInternal`+ consumes the web refresh token via `GetAndDeleteWebRefreshToken`, which carries no `expires_at`+ predicate (`web_refresh_token.go:62-84`); `Refresh` compensates by checking the returned row's expiry+ (`auth_service.go:488-490`), but `switchWorkspaceInternal` never does (`:994` nil-check and `:997`+ email-check only) and reuses the already-past `ExpiresAt` for the new session (`:1000`). So a session+ past its 7-day absolute lifetime still mints a fresh full-lifetime token through+ `SwitchWorkspace`/`LeaveWorkspace`/`DeleteWorkspace` until the hourly sweep removes the row — the+ absolute web-session cap is bypassed independently of the credential stamp. Both paths must check+ expiry at consume time, the same `expires_at > now()`-at-consume rule the credential codes get below.+- *"≤1h" and "30 days" are not real ceilings.* `access_token_duration` has only a one-minute *floor*+ (`setting_service.go:769-775`); a workspace with `FEATURE_TOKEN_DURATION_CONTROL` can set it to 90+ days, and every minted replacement inherits that (`generateLoginToken` reads it live). And OAuth refresh+ writes a *fresh* full `refreshTokenExpiry` on every rotation (`token.go:522`) with no absolute cap, so+ 30 days is the maximum *idle* gap, not a lifetime. Only the web refresh token has a true absolute cap+ (`Refresh`/`switchWorkspaceInternal` pass the original `ExpiresAt` through). G7's exposure-window+ numbers are restated as "up to the workspace-configured access-token lifetime, unbounded above" and+ "renewable indefinitely for OAuth," and closing the *renewal* is what the stamp does regardless of the+ window's size. An absolute cap on both is a worthwhile follow-up but not required for G7.+- *The stamp has nowhere to live for non-`END_USER` principals.* `SwitchWorkspace` itself guards+ `Type != END_USER` (`:850`), but its two `workspace_service.go` callers do not, and+ `generateLoginToken` has a live `SERVICE_ACCOUNT` branch (`:751`). Service accounts and workload+ identities are not in `principal` and have no `profile`, so `LastCredentialChangeTime` cannot exist for+ them and "refuse to mint on a missing stamp" would permanently break service-account-driven+ `LeaveWorkspace`/`DeleteWorkspace`. The stamp check applies to `END_USER` principals only, stated+ explicitly so it is a typed rule rather than a silent type-conditional bypass — non-`END_USER`+ credentials are not credential-changeable through any path this design touches, so there is nothing for+ the stamp to protect there anyway. (For the same reason, `RotateDirectorySyncToken`, service-account+ keys, and workload-identity config — the repo's `MINTS_CREDENTIAL_FOR_OTHERS` class — survive every+ revocation here and are correctly out of scope: they establish *other* principals' credentials, not a+ replacement for the acting account's.)++`UpdateEmail` earns membership without deleting anything: it scans and locks the child rows that exist,+then runs `UPDATE principal SET email = ?`, whose `ON UPDATE CASCADE` re-derives and locks whatever child+rows exist *at that moment*, including any a login committed in between. A third-party `Refresh` holding+one of those new rows and waiting on the principal deadlocks against the cascade holding the principal and+waiting on the row — the same three-party shape, with the email cascade where revocation's delete was.++For the three deleters, the fence closes a second failure the ordering fix leaves wide open, and it is+the more serious one: a row inserted after the scan is not in the deleting statement's snapshot, so it+simply *survives*. `handleReauthorize` returns success while a refresh grant minted mid-flight by a+concurrent OAuth exchange stays usable; `ResetPassword` and the admin password path report a completed+reset while a session created mid-flight stays live. Each is the exact guarantee the caller just told the+user it had made. So for those three the fence isn't only deadlock avoidance — and for the two password+paths it composes with the correctness fix above: fence first, then the password write and the revocation+in that same fenced transaction, so "the password changed but the sessions didn't" cannot be a reachable+state by either route.++With the fence held from the top by all of them, `Login` can't commit a new session while a revocation, an+email change, or a reset is anywhere between its scan and its commit, so there's no window left for a+third party to grab a row the scanning side hasn't accounted for, and no window for a row to slip past a+delete entirely; and none of the scanning paths can start while a new session or grant is mid-insert, so+none undercounts what it's about to delete or rewrite — and with the client fence, the same holds for a+client's grants across every account that has one, which the account fence alone could never cover. Needs+a deterministic real-PostgreSQL regression test for this three-transaction interleaving across the+variants that differ in *kind*, not merely in caller — a deleting one (revocation), the cascading one+(`UpdateEmail`), one whose failure mode is survival-not-deadlock (`handleReauthorize` or `ResetPassword`),+and one that turns on the client fence specifically: a client deletion racing an `/authorize` mint for an+account the deletion never touches, which no account-keyed fence can serialize. Plus one for the fence+order itself — a path taking both fences against a path taking them in the opposite order is precisely+the deadlock the fixed order exists to prevent, so the test has to prove the order is actually held, not+just that each fence works alone.++Holding that lock through the rest of the flow surfaces [one more standalone write in the same+sequence](https://github.com/bytebase/bytebase/pull/21235): `finalizeLogin` (shared by `Login`/`Signup`,+`auth_service.go:1044-1054`) and `switchWorkspaceInternal` (`:970-980`) both bump+`LastLoginTime`/`LastLoginWorkspace` via their own `s.store.UpdateUser` call, on `Store.UpdateUser`'s own+freshly-opened transaction (`principal.go:465`) — a second connection, not the one the surrounding lock+was just acquired on, so once that lock is held throughout authentication this call blocks on it exactly+like `challengeRecoveryCode` did. Moving it to after commit doesn't fix it either: `Store.UpdateUser`+replaces the whole `profile` column with whatever `Profile` message it's given+(`principal.go:446-451`), and both call sites build that message from `user.Profile` — the copy read+*before* the lock — carrying `LastChangePasswordTime` forward from that stale snapshot. A `ChangePassword`+that commits while this login is in flight would have its `LastChangePasswordTime` silently reverted to+the pre-lock value the moment this call lands afterward, which is exactly the field+[`email_code` eligibility](#design) is keyed on — turning a completed password change back into an+`email_code`-eligible account without ever touching `PasswordHash` again. Both writes move inside the+already-open transaction, built from the locked, re-read profile rather than the pre-lock one, so they+either land before the same commit the session insert does or lose to a concurrent credential change the+same way the rest of this sequence now does.++That is now the third separate finding of one pattern — `challengeRecoveryCode`, then these profile+writes, then [SSO auto-undelete](https://github.com/bytebase/bytebase/pull/21235) — so it is worth stating+as a rule and closing by audit rather than waiting for a fourth. The rule: **once a flow holds the+principal lock, every write to that principal inside it must go through the enclosing transaction.**+`Store.UpdateUser` opens its own (`principal.go:465`), so any call to it from inside a fenced flow is a+transaction waiting on a lock its own caller holds — a hang until `statement_timeout`, not an error, and+not something a retry helps.++The new instance: `getOrCreateUserWithIDP` reactivates a deactivated account on SSO login via a+standalone `Store.UpdateUser` (`auth_service_idp.go:179-186`), and that call *is* part of SSO's+authentication step, which this design now runs under the principal lock — so SSO login for a previously+deactivated user would stop working entirely. It moves into the enclosing transaction like the others.++That same SSO flow forces one bound on *how* the lock-before-authentication rule applies, or it becomes a+denial-of-service surface: `getOrCreateUserWithIDP` performs an outbound round-trip to the identity+provider (`auth_service_idp.go:55-64`, dispatching to `oauth2UserInfo`/`oidcUserInfo`/`ldapUserInfo`)+as part of "authentication," and the earlier rule ("move the lock before authentication") read literally+would hold the account's `FOR UPDATE` across that unbounded external call — a slow or hung IdP would pin+one account's row lock, blocking every concurrent login, refresh, and credential change for that account+until it times out. The resolution is that the IdP round-trip authenticates against the *provider*, not+against local mutable credential state, so it belongs *before* the lock, not inside it: resolve the+external identity first, unlocked, and take the fence and the principal lock only for the local+verify-consume-mutate-issue sequence that actually reads and writes rows. "Lock before authentication"+means before the part of authentication that inspects state the lock protects — never around a network+call to a third party. The same applies to `bcrypt` and `totp` verification, which are CPU-bound and+already pure, but the IdP call is the one that could hold the lock for seconds.++Auditing every `Store.UpdateUser`/`CreateUser`/`UpdateUserEmail` call site — across the whole `backend/`+tree, a scope [that itself had to be corrected](https://github.com/bytebase/bytebase/pull/21235): the+first version of this audit searched only `backend/api/`, and the `bytebase recovery` CLI's password+writer lives in `backend/component/recovery/`, which is precisely how it went unlisted — rather than+pattern-matching on the ones already found, the complete set reachable from a lock-holding flow is:+`challengeRecoveryCode` (`auth_service.go:606`), `switchWorkspaceInternal` (`:971`) and `finalizeLogin`+(`:1045`), the three account-creation paths (`auth_service.go:345`, `auth_service_idp.go:129`,+`auth_service_email_code.go:267`), `ResetPassword`'s own password write+(`auth_service_email_code.go:116`), the SSO undelete (`auth_service_idp.go:184`), `UpdateUser`/+`UpdateEmail` themselves (`user_service.go:487,703`), and the two SCIM profile writers+(`webhook.go:433,942`). All are addressed above. The remaining call sites — admin+`DeleteUser`/`UndeleteUser` (`user_service.go:558,637`), the SCIM create/delete pair+(`webhook.go:141,270`), and the recovery CLI's password write+(`backend/component/recovery/service.go:366`, a standalone process run while no server flow holds any+lock) — are operations that never run inside a login or credential flow, so they cannot self-deadlock;+they take the account fence under the rule above. Admin deactivation's separate problem (it revokes no+sessions at all today) is the one named in the account-creation paragraph, and the recovery CLI's+(it revokes nothing either, in the most adversarial context of all) is covered in Token-minting paths.++That same root cause [reaches OAuth token exchange too](https://github.com/bytebase/bytebase/pull/21235),+unfixed by any of the above: `handleAuthorizationCodeGrant` and `handleRefreshTokenGrant`+(`backend/api/oauth2/token.go:129-145,271-286`) each consume their existing child row — an+`oauth2_authorization_code` or `oauth2_refresh_token` — via an atomic single-use delete with no lock on+the account row at all, then call `issueTokens` (`:490-523`) afterward to insert the replacement, on the+opposite side of the same gap `Refresh`/`switchWorkspaceInternal` had before the fix above: the code or+token was already consumed, and the new one already queued for insertion, by the time a concurrent+revocation could have locked anything. `refuseIssuanceByCeiling`, called just before each consume+(`:129,271`), guards a different thing — the workspace's MCP capability toggle, not a+per-account credential race — and doesn't lock the principal row either, so it provides no fencing here.+Same fix, same shape: lock the existing `oauth2_authorization_code`/`oauth2_refresh_token` row first,+then the principal row, consume, and only then call `issueTokens`'s store writes — inside the+transaction, not around it — so a concurrent G7 revocation and a concurrent token exchange land in the+same deterministic order this doc already established for web sessions, instead of a fifth, OAuth-shaped+version of the same race surviving because the fix stopped one call site short.++**Store-layer prerequisite.** Every "inside the transaction," "before the insert," and "in one fenced+transaction" instruction in this section assumes the writes involved *can* join a caller-held+transaction. Today they cannot: `CreateWebRefreshToken` (`web_refresh_token.go:19-33`),+`CreateOAuth2AuthorizationCode` (`oauth2_authorization_code.go:30-51`), and `CreateOAuth2RefreshToken`+(`oauth2_refresh_token.go:32-53`) each run on `s.GetDB().ExecContext` — an autocommit statement on a+pooled connection — with no `*sql.Tx`-accepting variant, and the same is true of the `principal` writers+`Store.UpdateUser`/`CreateUser` open their own `BeginTx`. So the design's own prescriptions are not just+unimplemented but *unimplementable as written*, and in the worst way: because `web_refresh_token.user_email`+is a foreign key to `principal`, the autocommit `INSERT` takes a `FOR KEY SHARE` on the principal row —+which **conflicts with the `FOR UPDATE` the same request's outer transaction is already holding, on a+different pooled connection.** PostgreSQL sees no cycle (the outer transaction is idle-in-transaction,+blocked on the application, not on the database), so it does not abort — the insert simply hangs until+`statement_timeout`, and every web login, signup, refresh, and workspace switch hangs with it. This is+the same self-deadlock shape the doc flags for `challengeRecoveryCode`, one layer down, and it is why the+fence and the ordering are necessary but not sufficient on their own. The prerequisite for this whole+design is a `Tx`-accepting variant of each of these store writers (`CreateWebRefreshTokenTx(ctx, tx, …)`+and the two OAuth equivalents, plus the transaction-aware `Store.UpdateUser` the profile-write fixes+already require), so a handler can open one transaction, take the fence and the row locks, and do the+consume, the mutation, the revocation, and the insert all on that one connection. Without it, the OAuth+mint's "lock `principal` then `oauth2_client` before the insert" is inert — the insert runs on another+connection and orders against nothing — and the web paths hang outright.++Inserting that principal-lock wait ahead of the consume opens a narrower gap of its own —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235): `validateAuthorizationCode`/+`validateRefreshTokenGrant` check `expires_at` before this fix's lock is ever acquired, and+`ConsumeOAuth2AuthorizationCode`/`ConsumeOAuth2RefreshToken` (`oauth2_authorization_code.go:97-117`,+similarly for refresh tokens) match only on `code`/`token_hash` and `client_id` — no `expires_at`+predicate at all. Before this fix, the gap between that validation and the consume was negligible; now+it's however long the principal lock stays contended, which a concurrent revocation or another exchange+can stretch arbitrarily. A code or token that validated as not-yet-expired can cross its expiry while+waiting on the lock and still get consumed and exchanged once it's finally acquired, since nothing+re-checks. Same shape as the REAUTH fix above: add `AND expires_at > now()` to both consume queries+directly, rather than a separate re-check step, so a grant that expired mid-wait fails the consume itself+instead of relying on a check that already ran before the wait began.++Expiry isn't the only thing that can move during that wait —+[the same shape, one field over](https://github.com/bytebase/bytebase/pull/21235): both handlers keep+using the `authCode`/`refreshToken` struct they read *before* the fence, and after consuming the row they+resolve the account with `GetUserByEmail(authCode.UserEmail)` / `GetUserByEmail(refreshToken.UserEmail)`+(`token.go:149,290`). If `UpdateEmail` wins the fence first, its cascade rewrites `user_email` on that very+grant row. The exchange then resumes, consumes successfully — the consume matches on `code`/`token_hash`+and `client_id`, none of which changed — and looks the user up by an email that no longer exists. The+grant is burned, the client is told `invalid_grant`, and the user is forced to re-authorize, all because+they renamed their account mid-refresh. Nothing is left insecure, but a valid credential is destroyed by a+race the user can't see, and the retry has nothing to retry with.++The pre-fence read is a snapshot, so once the fence is held the row has to be read again rather than+trusted: re-read the locked grant inside the fence and use *its* `user_email`, not the copy from before+the wait. That resolves correctly — a cascaded rename leaves the same grant belonging to the same account+under its new address, so the exchange should simply succeed. Detecting the mismatch and refusing without+consuming would also be safe, but it's the worse behavior: it turns a rename into a spurious re-authorize+for a grant that is still perfectly valid. This is the general form of the rule the rest of this section+keeps applying to rows — anything read before a lock must be re-read after it — and it applies to the+grant's own columns just as much as to the set of rows a scan returned.++Putting `issueTokens` itself inside that transaction isn't quite right either — [a seventh+finding](https://github.com/bytebase/bytebase/pull/21235): `issueTokens` (`token.go:489-535`) writes the+HTTP response via `c.JSON` as its last step, in the same function that does the DB insert. Calling the+whole function from inside the open transaction means the response goes out with the transaction still+uncommitted; if the commit then fails, the insert rolls back but the client already has an access token+response describing a refresh token that no longer exists in the database — self-contained enough to+answer requests for up to an hour on a grant the server no longer believes it issued. `issueTokens` needs+splitting: the token generation and the `CreateOAuth2RefreshToken`/`UpdateOAuth2ClientLastActiveAt`+writes stay inside the transaction; the `c.JSON` response write moves to after it commits, using the+values the in-transaction part returns rather than writing the response itself.++That same transaction also has to be ordered against a table this design hasn't touched yet — [an eighth+finding](https://github.com/bytebase/bytebase/pull/21235): `DeleteOAuth2Client`+(`oauth2_client.go:107-120`) and `DeleteExpiredOAuth2Clients` (`:124-138`) both `DELETE FROM+oauth2_client` directly, and `oauth2_authorization_code.client_id`/`oauth2_refresh_token.client_id` are+both `REFERENCES oauth2_client(client_id) ON DELETE CASCADE` — so either delete locks the client row+first and cascades into locking and deleting its authorization-code and refresh-token rows afterward,+parent-then-child. The token-exchange fix above holds an existing authorization-code or refresh-token+row first, then reaches for the client row too — `CreateOAuth2RefreshToken`'s FK reference and+`UpdateOAuth2ClientLastActiveAt`'s own update both require a lock on `oauth2_client` — child-then-parent,+the opposite order. A token exchange racing either client-deletion path can deadlock: exchange holding+the grant row waiting on the client, deletion holding the client waiting on the grant row it's about to+cascade into. `DeleteOAuth2Client`/`DeleteExpiredOAuth2Clients` predate this doc and are otherwise+untouched by it, but the new transaction above is what turns a previously-harmless ordering into a live+deadlock surface, so both need the same correction: lock every existing+`oauth2_authorization_code`/`oauth2_refresh_token` row referencing the client (in primary-key order) —+and for the bulk expiry path, every such row across every client being deleted, clients themselves also+in primary-key order — before locking and deleting the client rows, matching the child-before-parent+rule this doc already applies everywhere else. Both also take the client fence before that scan (see the+fence rule above): the ordering fixes rows that exist when they look, and only the fence stops+`/authorize` from committing one they never saw.++Naming that correction "child-before-parent" is necessary but+[not sufficient on its own](https://github.com/bytebase/bytebase/pull/21235): it fixes ordering between+each child table and the client, but says nothing about the order *between* the two child tables, and+a user/client pair with both an authorization-code and a refresh-token row outstanding can still deadlock+if one transaction locks them in the opposite order from another. Revocation and the `UpdateEmail` fix+above already committed to "the three tables themselves in one fixed order" without ever pinning down+what that order is; this is where it stops being safe to leave implicit. One shared order, named once+and reused everywhere rows from more than one of these tables are locked together:+`oauth2_authorization_code`, then `oauth2_refresh_token`, then `web_refresh_token` — the order every+mixed-table mention in this doc has already been listing them in, now load-bearing rather than+incidental. G7's revocation, the `UpdateEmail` fix, `DeleteOAuth2Client`, and `DeleteExpiredOAuth2Clients`+all lock rows from more than one of these tables and must all use this exact order — not just each+internally consistent in primary-key order within its own table, but agreeing with every other path on+which table goes first. Needs the deterministic real-PostgreSQL regression test this repo's+row-lock-ordering convention requires for new multi-row coordination paths, covering both the+client-vs-grant direction above and this table-vs-table one: a token exchange started first should let a+racing client deletion proceed after it commits, a client deletion started first should let a racing+token exchange fail closed (invalid_grant, its row already gone) rather than deadlock either way, and a+revocation racing a client deletion for a user/client pair holding both an authorization-code and a+refresh-token row must resolve the same way, not deadlock on the two child tables disagreeing about which+comes first.++Naming `DeleteExpiredOAuth2Clients` doesn't cover the token tables' own expiry cleaners —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235):+`DeleteExpiredOAuth2AuthorizationCodes`, `DeleteExpiredOAuth2RefreshTokens`, and+`DeleteExpiredWebRefreshTokens` (`backend/runner/cleaner/data_cleaner.go:137-160`) each run today as a+single unordered bulk `DELETE ... WHERE expires_at < ?` — harmless before this design, since nothing else+ever locked more than one row across these tables at a time. Now that revocation, `UpdateEmail`, and+client deletion all lock multiple existing rows per table in primary-key order, an unordered bulk delete+overlapping any of them on two or more expired rows can lock those same rows in whatever order its own+scan (an `expires_at` index, most plausibly) happens to visit them — the opposite order from the other+side often enough to deadlock, for exactly the reason every other multi-row fix in this doc locks in+primary-key order in the first place. These three cleaners predate this doc and are otherwise untouched+by it, but so were `DeleteOAuth2Client`/`DeleteExpiredOAuth2Clients` before the finding above — same root+cause, a previously-harmless bulk operation turned live by this design's own new locking. Fixed the same+way: each cleaner locks its matching expired rows in primary-key order before deleting, folding them into+the same deterministic-ordering contract and its two-direction regression tests as every other path that+touches these tables.++Two *more* cleaners of the same shape were missed even after that fix, for a mechanical reason worth+recording: the cited cleaner range (`data_cleaner.go:137-160`) ends exactly one function before+`cleanupLoginAttempts` (`:168`) and `cleanupEmailVerificationCodes` (`:176`), so `DeleteStaleLoginAttempts`+(`login_attempt.go:83-97`) and `DeleteExpiredEmailVerificationCodes` (`email_verification_code.go:109-124`)+— both unordered bulk `DELETE`s — fell just outside the window and went unlisted. `login_attempt` and+`email_verification_code` have no foreign keys, so nothing *cascades* them into the token-table order; on+their own they would be a stall, not a deadlock, since the design moves a single-row `email_verification_code`+consume and `ClearLoginAttempt` inside the fenced transaction and either can queue behind the hourly bulk+delete while the fence and every token-row lock are held. But `login_attempt` becomes a genuine deadlock+surface the moment one fenced transaction holds *two* of its rows — and `ResetPassword` does exactly that+once folded into a single transaction: it clears `(email, EMAIL_CODE)` inside `verifyEmailCode`+(`auth_service_email_code.go:444`) and then `(email, PASSWORD)` (`:129`) in the same request, and the login+side clears a third kind (`MFA`) through `challengeMFAAndClear`. So both cleaners join the ordered-lock+contract, and the in-transaction `login_attempt` clears take their rows in primary-key (`identity, kind`)+order like everything else.++Scheduled cleanup isn't the only unordered multi-row deleter left, either — [one more of the same+shape](https://github.com/bytebase/bytebase/pull/21235), reachable on demand rather than hourly: the MCP+`reauthorize` tool. `handleReauthorize` (`backend/api/mcp/tool_reauthorize.go:35`) calls+`DeleteOAuth2RefreshTokensByUserAndClient`, a plain `DELETE ... WHERE user_email = ? AND client_id = ?`+with no ordering and no lock step (`oauth2_refresh_token.go:138-152`). A user/client pair holding two or+more refresh grants — ordinary for a long-lived MCP integration that has refreshed since its last+cleanup — gives it two rows to lock in scan order, against a credential revocation or client deletion+holding those same rows in primary-key order. Identical root cause to the cleaners, and identical fix:+lock the matching rows in primary-key order before deleting, inside the same contract and the same+two-direction tests. Worth naming separately because it's a user-triggered path rather than a background+one, so its overlap with a credential change isn't a rare scheduling coincidence — a user reauthorizing+an MCP client *because* they just changed a credential is the expected sequence, not an unlucky one. It+also takes the account fence, per the rule above — ordered locking alone would still let an OAuth exchange+mint a replacement grant after the scan, outside the deleting statement's snapshot, so `reauthorize` would+report success on a grant that is still live.++The last unordered deleter is the one this design otherwise *keeps* —+[found the round after](https://github.com/bytebase/bytebase/pull/21235):+`DeleteWebRefreshTokensByUser` itself (`web_refresh_token.go:103-118`) is a plain+`DELETE ... WHERE user_email = ?`, and while G7 moves it inside the locked transaction for the four new+methods, two callers deliberately stay outside that: `ResetPassword`+(`auth_service_email_code.go:123`), exempt because mailbox possession is its own proof channel, and+`UpdateUser`'s surviving admin-assisted password path (`user_service.go:436`), exempt under G6. Both+still call it unordered, on the store's own connection, against an account that can hold several+sessions — so both can deadlock against the primary-key-ordered revocation this design introduces, the+same way the cleaners could.++Here the deadlock is not the worst part. Both callers already committed the password write before this+delete runs, and both swallow its error and continue (`slog.Warn` at+`auth_service_email_code.go:124`, `slog.Error` at `user_service.go:437` — the very log-and-continue+pattern G7 exists to replace). If PostgreSQL picks one of them as the deadlock victim, the password+change stands, the delete is rolled back, and the caller reports success with every pre-reset session+still live — a silent failure of exactly the recovery path a locked-out user reaches for, and one that+looks identical to a clean reset from the outside. Both get the same ordered-lock fix as every other+multi-row deleter here, and both should stop treating the revocation as best-effort: a reset that cannot+revoke is a reset that did not do what it told the user it did. That is the same argument G7 already+makes for the four new methods — it applies just as well to the two paths G7 leaves alone, which is why+this shows up as a lock-ordering finding and a correctness one at once.++Ordering and error-handling still aren't the whole fix here, for the same reason they weren't for+`handleReauthorize` — per the fence rule above, both paths take the account fence first, and run the+password write and the revocation inside that one fenced transaction. Without the fence, a login that+commits a new session after the reset's scan is invisible to the reset's own delete statement, so the+session outlives the password change that was supposed to end it — the failure survives even if the+delete succeeds and its error is checked, because there was never an error to check. Fenced, with both+writes in one transaction, "password changed, sessions didn't" stops being reachable by either the+deadlock route or the snapshot route.++"Stop treating revocation as best-effort" generalizes past the two resets, to three more swallowed-error+sites a sweep for the pattern turns up — each one a security-relevant write that logs its failure and+reports success:++- `Logout` (`auth_service.go:459-463`, also reached from `workspace_service.go:312,421`) logs a+ `DeleteWebRefreshToken` failure and returns `Empty` with the cookies cleared, so a real transient DB+ error leaves the server-side session live for its full remaining lifetime while the user believes they+ logged out — the one moment a user is explicitly asking for revocation. The fix is to propagate the SQL+ *error*, not to treat a zero-row delete as failure: for `Logout` an absent row is the *normal success*+ case (a credential change, the expiry cleaner, or an earlier logout already removed it), and the+ desired end state — no server-side session — is already met. So `Logout` diverges from the+ single-use-consume rule deliberately: a consume needs exactly one row (the row *is* the single-use+ gate), but an idempotent revoke-if-present is satisfied by zero. Keep an absent row successful,+ surface only genuine errors, and *always* expire the cookies (never return before that), so a user can+ clear a stale browser session even when the server row is already gone.+- The OAuth2 revoke endpoint (`revoke.go:60-65`) logs a `DeleteOAuth2RefreshToken` failure and returns+ `200`, telling an MCP client its compromised grant is dead while the row survives up to 30 days. RFC 7009+ wants `200` for an *unknown* token, not a *failed* revocation (`503` is allowed); the two are conflated.+ Same idempotency caveat as `Logout`: an already-absent token is a legitimate `200`, only a real+ storage error becomes `503`.+- The audit interceptor (`audit.go:94-119`) is the deeper of the three, and "return the error instead of+ swallowing it" is *not* a sufficient fix — because the interceptor runs the handler first (`:94-96`)+ and writes the audit row afterward (`:98-119`), the credential mutation has **already committed** by+ the time `createAuditLog` fails, so returning an error only hands the client a misleading failure for a+ change that did happen, still with no audit record. The ordering is the problem, not the error+ handling. For the security-sensitive mutations that lean on audit as their control (`DisableMfa`, the+ admin-assisted resets), the audit row has to be written *inside the handler's own fenced transaction*,+ so the mutation and its record commit or roll back together — the generic post-hoc interceptor cannot+ provide that, because it does not share the handler's transaction. This is a real departure from how+ auditing works for ordinary RPCs, and it is the price of the doc's claim that "the `bb.users.update`+ permission check and audit log are the correct control": a control that can silently no-op on a write+ failure after the fact is not one. (An outbox/precommit record is the alternative if threading the+ audit write through every such handler's transaction proves too invasive; either gives atomicity, which+ the interceptor alone does not.)++None of the three is introduced by this design, but all three sit on paths it now depends on for its own+guarantees, so it names them rather than inheriting them silently — and the audit one in particular is a+correctness change, not just a stricter error check.++That fix closes the race around *exchanging* an existing grant, but not [a separate gap one step+earlier](https://github.com/bytebase/bytebase/pull/21235): `handleAuthorizePost`+(`authorize.go:103-171`) mints a brand-new `oauth2_authorization_code` — a grant that didn't exist+before the request — off nothing but `resolveConsentingUser` (`:200-228`) verifying a bearer access+token's signature and expiry and confirming the user row still exists (`:212,221-227`). No lock on an+*existing* row, because there's no existing `oauth2_authorization_code` row to lock: this part of the+`nextProjectID` shape, not the child-before-parent one, is correct as far as it goes. The problem isn't+the lock ordering, it's what "the user still exists" is being asked to+stand in for — proof the account's *credentials* haven't changed, which a still-valid JWT cannot carry,+since it was signed before whatever credential change just happened and self-contained JWTs are exactly+as valid the second after a revocation as the second before. This was carried as a Non-goal for a while,+on the grounds that closing it meant teaching `/authorize` to check a credential-generation signal no JWT+carried. That reasoning expired: the signal now exists for the MFA temp token, and `SwitchWorkspace`+forced it into access tokens regardless. `/authorize` performs the same+`LastCredentialChangeTime` check as every other mint-from-token path (see Token-minting paths above) —+which is why the account fence it takes is necessary but never sufficient on its own: the fence decides+*when* the mint may run, the stamp decides *whether* it may run at all.++"No existing row to lock" wasn't the whole picture either —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235): the new+`oauth2_authorization_code` row this insert creates still has two *parents*, not zero, and+`CreateOAuth2AuthorizationCode` acquires both through its own foreign keys — `client_id` against+`oauth2_client`, `user_email` against `principal` — as part of the insert itself, the same way any FK+reference locks the row it points to. The `nextProjectID` pattern this doc keeps citing for "no existing+child" cases doesn't skip locking on that basis; it explicitly locks its one parent *first*. This insert+has two, and nothing says which one the FK checks reach first — if that's `oauth2_client` before+`principal`, it's the opposite of the order the token-exchange fix above already commits to (principal,+then `oauth2_client`, via `issueTokens`/`UpdateOAuth2ClientLastActiveAt`), and the two can deadlock: the+mint holding `oauth2_client` while waiting on `principal`, an in-flight exchange holding `principal` while+waiting on `oauth2_client`. The fix is the same discipline as every other multi-table lock in this doc:+`handleAuthorizePost` explicitly locks `principal` then `oauth2_client` (`SELECT ... FOR KEY SHARE`, the+weakest lock that still orders against the FK check, taken in that order before the insert) rather than+leaving the order to whatever the FK constraints happen to check first — folding the mint into the same+shared order this doc already names for every other path that touches more than one of these tables.+Needs the same deterministic real-PostgreSQL regression test as the other lock-ordering fixes, covering+both directions: a mint racing an in-flight token exchange for the same user/client, and a mint racing+`DeleteOAuth2Client`/`DeleteExpiredOAuth2Clients`. (Strictly there is a *third* parent —+`oauth2_authorization_code.workspace REFERENCES workspace(resource_id)`, `LATEST.sql:690` — so the insert+also takes `FOR KEY SHARE` on the workspace row. It is benign today, because the only `workspace` writers+(`UpdateWorkspace`, `DeleteWorkspace`) take `FOR NO KEY UPDATE`, which `FOR KEY SHARE` is compatible with,+and nothing anywhere takes `FOR UPDATE` on a workspace row. It stops being benign the instant any path+does, so the fixed order is stated as principal → workspace → `oauth2_client`, with the workspace lock+noted as currently uncontended rather than omitted — an omission is how the two-parent framing missed it+in the first place.)++`email_code`'s eligibility is a server-side check, not a UI affordance — otherwise an attacker with a+stolen session and separate mailbox access could use it against an *already*-MFA-protected account,+weaker than the factor actually protecting it (a+[Codex finding](https://github.com/bytebase/bytebase/pull/21235) against an earlier draft that+accepted it unconditionally on all four methods). The rule — no live `MFAConfig.OtpSecret`, and either+`Profile.LastChangePasswordTime` is unset or the deployment is SaaS (added by the fourth finding below,+once the backfill made the account-level signal alone insufficient for pre-existing accounts) — is+checked once, in `CredentialProof` verification itself, not per-method, so it can't be forgotten on a+future caller of the same helper. Both halves of that `or` are deliberately principal-scoped:+`restriction.disallow_password_signin` was tried in the second position twice and is wrong there both+times — first unconditionally+([caught by Codex](https://github.com/bytebase/bytebase/pull/21235) as too coarse: a self-hosted+workspace can allow SSO and local password login at once, and a workspace-wide flag can't see that one+specific SSO-provisioned user in that mix has no usable password), then as an affirmative-only clause,+[caught again](https://github.com/bytebase/bytebase/pull/21235) because a workspace flag cannot speak+for a global principal at all (see the fourth finding below). The account-level+half leans entirely on `LastChangePasswordTime` meaning what it says, which took a second+[Codex finding](https://github.com/bytebase/bytebase/pull/21235) to get right: `CreateUser` and+`Signup` both construct a brand-new local account with an empty `Profile{}` even when the caller+supplies a real, self-chosen password (`auth_service.go:344-349`, `user_service.go:263-268`) — so+every local account starts out looking exactly like a passwordless one until its first subsequent+password change, which is backwards from what this rule needs. Both must set+`Profile.LastChangePasswordTime` at creation whenever the password came from the caller, not the+server — leaving it unset only for the genuinely passwordless creation paths, SSO auto-provisioning+(`auth_service_idp.go:119-127`) and Cloud email-code auto-provisioning+(`auth_service_email_code.go:252-258`), both of which generate the password themselves and never hand+it to anyone. `ResetPassword` never had this problem: it only ever touches the password, MFA stays+live regardless of how it's+reached.++Setting it going forward isn't enough on its own —+[a third finding](https://github.com/bytebase/bytebase/pull/21235): every local account that already+exists at rollout, including ones with a real password its owner has simply never changed since+signup, still has `LastChangePasswordTime` unset today, and this design would newly classify every one+of them as eligible for `email_code` alongside the accounts that actually are passwordless. This needs+a migration, not just a forward fix: backfill `LastChangePasswordTime` to a non-null value (the row's+own `created_at` is enough) for every existing `END_USER` row that doesn't already have one set. This+is deliberately the conservative direction — it can't distinguish, for any given pre-existing row,+"real password never changed" from "SSO/Cloud placeholder never disclosed," so it treats every unknown+row as *has* a real password. The alternative default — treat unknowns as passwordless — is the one+that actually matters here: it would reopen the downgrade this whole mechanism exists to prevent for+every real password that predates the migration. The same migration backfills `LastCredentialChangeTime`+to `created_at` for every existing `END_USER` (for a different reason — see Token-minting paths, where a+nil generation would otherwise make every fresh post-upgrade token unmintable): two columns, one+backfill, both to `created_at`, both then maintained forward.++Left there, the backfill is one-way and permanent for exactly the population `email_code` exists to+serve — [a fourth finding](https://github.com/bytebase/bytebase/pull/21235): once+`LastChangePasswordTime` is non-null, nothing ever unsets it again, and a pre-existing Cloud/SSO account+has no path back to eligibility — `ChangePassword` itself is rejected on Cloud (see Cloud+vs. self-hosted), so "until they change something that legitimately sets the field" was never an escape+for exactly the accounts most likely to need one. Combined with `require_2fa`, an existing passwordless+account with no MFA yet is redirected into an enrollment it now has no self-service way to complete. The+eligibility rule needs a second, durable clause, not just the account-level one: `LastChangePasswordTime`+unset **or** the deployment is SaaS (`s.profile.SaaS`).++The obvious candidate for that second clause was the workspace's own `restriction.disallow_password_signin`,+and [that was unsound](https://github.com/bytebase/bytebase/pull/21235) — worth recording, because the+reasoning behind it looked airtight and was wrong by one scope level. The argument was: the flag only+fires when affirmatively set, which means the entire *workspace* has no local passwords, so there's no+mixed population left to misidentify. True about the workspace, and irrelevant to the principal.+`getAccountRestriction` is workspace-scoped (`auth_service.go:1147-1153`), while `principal` has no+workspace column at all — one global account row per person, across every workspace. So in a self-hosted+multi-workspace deployment, a user with a real, caller-chosen password they use in workspace A becomes+`email_code`-eligible merely by being evaluated through workspace B, which happens to be SSO-only. That+is the precise downgrade this rule exists to prevent: a stolen session plus mailbox access, standing in+for a password the account genuinely has, ending in a replaced MFA configuration.++`s.profile.SaaS` is the same intent at the right scope. It is deployment-wide, not per-workspace, so+there is no other workspace for a password to hide in; SaaS forces `disallow_password_signin` on every+workspace and `ChangePassword` refuses to run at all there, so no caller-chosen password can exist on the+deployment in the first place. That is a property of the whole principal, which is what the rule needs.+Note this doc uses the workspace flag *elsewhere*, in `ChangePassword`'s own rejection, and that stays —+the two directions are not symmetric. Refusing to set a password is a safety judgment where being+over-broad costs a user an operation they can retry; granting `email_code` eligibility is a permission+judgment where being over-broad is a vulnerability. Same flag, opposite consequences of imprecision.++Self-hosted therefore keeps only the per-principal clause, and its residual gap is pre-existing+passwordless accounts anywhere self-hosted (not merely in mixed workspaces): they have no self-service+path back until something legitimately sets the field. Unlike Cloud they do have G6's admin-assisted+reset as a recovery route, which is exactly the asymmetry that justified giving Cloud a clause of its+own. That residual is the wider version of the already-accepted SMTP-less gap (see Non-goals), not a new+kind of gap.++Everything above assumes `LastChangePasswordTime`, once set, stays set — and the SCIM directory-sync+surface can clear it [without ever meaning to](https://github.com/bytebase/bytebase/pull/21235):+`updateUserFromSCIM` (`backend/api/directory-sync/webhook.go:930-943`) wants to change one subfield,+`Profile.Source`, but passes the whole `user.Profile` it read earlier into `Store.UpdateUser`, which+replaces the entire `profile` JSONB column (`principal.go:446-451`) — the same whole-column-replace+hazard already found in `finalizeLogin`, in a writer this doc hadn't looked at because SCIM has nothing+to do with credentials. A SCIM write that reads a profile with `LastChangePasswordTime` unset, then+loses the race to a `ChangePassword` that sets it, writes the stale profile back afterward and clears it+— leaving an account that genuinely has a password looking passwordless, which is precisely the state+that makes `email_code` eligible. The consequence is worse here than the login-timestamp version: that+one reverted a field to a stale value, this one reverts it to *unset*, straight into the eligibility+condition.++Fixing `updateUserFromSCIM` alone doesn't cover the surface, though — [a second SCIM writer, found the+round after](https://github.com/bytebase/bytebase/pull/21235): the `PATCH` handler+(`webhook.go:335-348,433`) never calls `updateUserFromSCIM` at all. It builds its own+`UpdateUserMessage` from the same previously-read `user.Profile` (`:343-345`), applies its operations,+and calls `Store.UpdateUser` directly (`:433`) — the identical whole-column replace, reached by a+different path. Both handlers need the same treatment; fixing only the shared-looking helper would leave+the standalone one open, which is exactly the shape of mistake this doc keeps finding.++Two acceptable fixes, and this design doesn't need to pick between them: each writer can update only the+`source` subfield (a targeted `jsonb_set`, leaving every other field untouched by construction), or it+can join the same lock-and-re-read discipline every other profile writer in this doc now follows — read+the profile inside the locked transaction, patch `source` on *that* copy, write it back before commit.+The subfield update is the smaller change and doesn't put a directory-sync webhook behind a per-account+lock; either one closes it. What isn't acceptable is leaving a whole-profile writer — either of them —+outside the coordination that the entire `email_code` eligibility rule depends on.++Three checks `UpdateUser` enforces today have to move with their fields, not just the credential+proof — existing behavior this design must carry forward, not decisions it makes new. `ChangePassword`+still calls `s.validatePassword` (`user_service.go:282-295`) on `new_password` before hashing — the+proof gates *who* can set it, not *what's* an acceptable value, and workspace password-complexity+policy is orthogonal to this doc's threat model. It also still rejects `new_password` matching the+*current* password (`bcrypt.CompareHashAndPassword`, `user_service.go:423-426`) — not just a UX nicety:+`Store.UpdateUser` bumps `Profile.LastChangePasswordTime` on any write to `PasswordHash`+(`principal.go:429-433`), whether or not the resulting hash represents an actual change, so skipping+this check would let a workspace's password-rotation deadline be reset by "changing" to the same+password. `DisableMfa` still checks `Require_2Fa` (`user_service.go:399-408`): a non-admin caller,+self-service or admin-assisted, cannot turn MFA off for anyone while the workspace requires it — only+a workspace admin can, unchanged from today.++Sharing T9's lockout buckets has one accepted side effect worth naming, not just inheriting silently:+a `PASSWORD` or `MFA` claim from a failed `CredentialProof` counts against the same budget a login+attempt would. A user who fumbles their password a few times inside `ChangePassword` can lock+themselves out of *logging in* too, not just out of changing it — a narrower version of the+lockout-as-availability-cost trade [`login-attempt-lockout.md`](login-attempt-lockout.md) already+accepted for a different reason. Anyone locked out this way still has the request's own error message+telling them when it clears.++Every `CredentialProof` channel must actually claim a slot, which is not automatic — today's+`UpdateUser` has an unbounded one to avoid inheriting: its `otp_code` branch runs+`totp.Validate(..., TempOtpSecret)` (`user_service.go:442-450`) with no `claimLoginAttempt`, an+unbounded guessing oracle against the pending TOTP seed (bounded in *impact* only because the minted+secret is returned solely to the same self-caller and cross-user reach needs `bb.users.update`, blocked+in SaaS — so it is an oracle, not a takeover). The design must not carry that forward: `EnableMfa` and+`ConfirmRecoveryCodes` verify `otp_code` too, and the enrollment branch of `EnableMfa` takes *no*+`CredentialProof` at all — so unless each `otp_code` verification claims the `MFA` bucket on its own+(independently of whether a `CredentialProof` is present), first-time enrollment would ship the same+unbounded oracle. `otp_code` verification claims `MFA`; the enrollment path claims it despite having no+`CredentialProof`, precisely so the oracle is closed there rather than reopened.++**What's exempt.** `title`/`phone` on `UpdateUser` aren't authentication material.+`StartMfaEnrollment` mints a secret but changes nothing live, so it needs no proof — same as AWS's+`CreateVirtualMFADevice` needing none while `EnableMFADevice` does. `RequestReauthCode` needs no proof+either, for a different reason: it's what *produces* a proof, not a consumer of one. It's still+bounded — by the resend cooldown on the send side, by the `EMAIL_CODE` lockout on redeeming it — same+split `RequestPasswordReset` already has between sending and verifying. `UpdateUser`'s `password` field+becomes admin-only: a self-service call (`callerUser.ID == user.ID`) that sets it is rejected,+pointing at `ChangePassword`. `ChangePassword` has no admin path at all (see its `name` field comment+in API). Admin-assisted resets of another user's password or MFA stay on `UpdateUser`'s `password`+field and `DisableMfa` respectively, both exempt: the `bb.users.update` permission check and audit log are the+correct control there, and an admin recovering a locked-out user cannot know the credential being+replaced. Both also carry forward the *other* half of `UpdateUser`'s existing cross-user gate, not just+the permission check —+[worth stating explicitly](https://github.com/bytebase/bytebase/pull/21235), since it's easy to+carry over only the part that reads as "the interesting check": `callerUser.ID != user.ID` is rejected+outright in SaaS mode, unconditionally, checked *before* `bb.users.update` is even evaluated+(`user_service.go:347-359`) — "the principal is global," per the comment already on that check today.+`DisableMfa`'s admin path is self-hosted only for the same reason `UpdateUser`'s already is, not a new+decision; a SaaS workspace admin gets exactly as little cross-user reach here as anywhere else.+`CreateUser`/`Signup` have no prior credential to prove. `ResetPassword` (emailed code)+already has its own proof channel — mailbox possession — including for SSO accounts whose+`PasswordHash` they never saw.++Ownership is enforced explicitly, not assumed. All seven methods are `auth_method = CUSTOM`, which+means the ACL interceptor's automatic IAM check is skipped entirely (`doIAMPermissionCheck` returns+true unconditionally for non-IAM methods, `acl.go:252-253`) — the same gap T11 in the original audit+flagged for 15 other CUSTOM RPCs whose declared `permission` is never enforced. `DisableMfa` is the+one method here with a real admin path, gated on `bb.users.update`; every other method —+`ChangePassword`, `StartMfaEnrollment`, `EnableMfa`, `RegenerateRecoveryCodes`, `ConfirmRecoveryCodes`,+`RequestReauthCode` — must independently reject any `name` other than the caller's own, since nothing+upstream of the handler does it for them. Without that check explicitly stated per method, a future+implementation reading only the proto could plausibly ship one of them missing it — silently letting+any authenticated workspace member read another account's freshly-minted MFA secret, or overwrite+their pending recovery codes.++**Cloud vs. self-hosted.** Cloud users never know their own local password — email-code signup and+SSO both assign a random, unseen one (`auth_service_email_code.go:252-258`,+`auth_service_idp.go:119-127`), and `Login` itself refuses the password path via+`restriction.disallow_password_signin`, which SaaS forces on unconditionally. `ChangePassword`+therefore rejects any call when that restriction is set, reusing the flag `Login`/`Signup` already+check rather than a separate `s.profile.SaaS` branch — the same behavior falls out for a self-hosted+deployment that goes SSO-only. This also closes a gap in today's code: `UpdateUser`'s password branch+has no SaaS check at all, harmless only because `Login` independently blocks the result. MFA is+unaffected either way — it's a second factor on top of whichever primary method a workspace allows, so+`Require_2Fa` and all four MFA methods behave identically on both deployments. `EnableMfa` needing+`CredentialProof` rather than password-only handles *replacing* a factor on a Cloud account, but not+enrolling the *first* one: a Cloud or SSO account has no password, and first-time enrollment by+definition has no existing OTP or recovery code either, so all three `CredentialProof` options are+simultaneously unsatisfiable — exactly the account `guard.ts:265-275` hard-redirects into MFA setup+with no escape route when the workspace requires it. `CredentialProof` gains a fourth option,+`email_code`, for this: a one-time code to the account's own registered email via a new+`RequestReauthCode`, reusing the `email_verification_code` table T9 already built for `LOGIN` and+`PASSWORD_RESET` — a third purpose, not new infrastructure.++**Frontend.** The four call sites in `AccountSettingsPage.tsx`, `TwoFactorSetupPage`, and+`RegenerateRecoveryCodesView` move to their matching new method and gain a credential-proof field —+no new dialogs, since [`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md)+already gives password and 2FA changes their own confirmations.+`RegenerateRecoveryCodesView`'s existing shape barely changes: it already calls one RPC on mount+(mint) and a second when the user confirms they've downloaded the codes (promote) — `credential` just+moves onto the second call (`ConfirmRecoveryCodes`), where the download-confirmation button already+lives. `TwoFactorSetupPage` gains that same second call: it already shows recovery codes and gates+advancing on a download confirmation (`:146-160,185-195,210-213`) — that confirmation now drives a real+`ConfirmRecoveryCodes` call instead of being purely client-side, since `EnableMfa` no longer promotes+recovery codes itself. For first-time enrollment specifically, that confirmation screen also gains a+fresh OTP input: the code entered earlier for `EnableMfa` has long since expired by the time the user+finishes saving their codes, so `ConfirmRecoveryCodes` needs its own, not a resend of the first (see+Design → Verification). That field needs a way to reach for+`email_code` when the account has no password and no MFA yet — a "email me a code" link inline with the+proof field, calling `RequestReauthCode`, rather than a fifth dialog. This is a breaking proto change;+frontend and backend ship as one rollout on both Cloud and self-hosted (a single `go:embed`'d image,+confirmed against `scripts/Dockerfile` and the Cloud deploy workflow — no separate frontend pipeline),+same as the other breaking changes already in flight this cycle (#21181, #21234). One residual edge,+inherent to any SPA rolling deploy rather than specific to this change: a browser tab already open+before the rollout is still running the old bundle and can call the old fields on `UpdateUser` against+an already-upgraded backend for the rest of that rollout window — they're reserved, so the call+silently no-ops rather than erroring. Self-correcting on the next page load; not worth engineering+around for a field that's disappearing anyway.++## API++Seven new methods on `UserService` (same service `UpdateEmail` already lives in, rather than a new+service): one per credential state transition, `RequestReauthCode` (the send side of the fourth+`CredentialProof` option), and `ConfirmRecoveryCodes` (recovery codes mint-then-confirm the same way+MFA enrollment does, for a different reason — see Alternatives). Full proto below, then what each+piece is doing.++### Service methods++```protobuf+service UserService {+ // ...existing RPCs...++ // Sends a one-time code to the caller's own registered email, usable as+ // CredentialProof.email_code. The one channel that works when neither a+ // usable password nor an existing MFA factor exists yet — Cloud, SSO, or+ // first-time MFA enrollment anywhere. name must be the caller's own — see+ // What's exempt.+ rpc RequestReauthCode(RequestReauthCodeRequest) returns (google.protobuf.Empty) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:requestReauthCode"+ body: "*"+ };+ option (google.api.method_signature) = "name";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = RESETS_CREDENTIAL;+ }++ // Changes the caller's own password. Rejected if the workspace disallows+ // password sign-in (Cloud always does) — see Design → Cloud vs. self-hosted.+ // new_password still runs through the workspace's password-complexity+ // policy before hashing, same as UpdateUser does today.+ // Permissions required: none beyond being signed in as `name`.+ rpc ChangePassword(ChangePasswordRequest) returns (User) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:changePassword"+ body: "*"+ };+ option (google.api.method_signature) = "name,new_password,credential";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = TAKES_OVER_ACCOUNT;+ }++ // Mints a new TOTP secret and recovery codes, persists them as the+ // account's temporary MFA state (store-level only — see API → Messages),+ // and returns them for the caller to confirm. Not yet live, so no proof+ // is required here, but the account row is still locked for the read of+ // current live MFAConfig fields and the write that preserves them — see+ // Design → Verification. name must be the caller's own — see What's exempt.+ rpc StartMfaEnrollment(StartMfaEnrollmentRequest) returns (MfaEnrollment) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:startMfaEnrollment"+ body: "*"+ };+ option (google.api.method_signature) = "name";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = MINTS_CREDENTIAL;+ }++ // Validates otp_code and pending_version against the temporary state+ // StartMfaEnrollment persisted for this account (re-read from the store+ // by name, not carried in this request). Replacing an existing factor+ // (the account already has a live OtpSecret) requires credential and+ // promotes *only* the secret here — recovery codes stay pending until a+ // separate ConfirmRecoveryCodes call, safely, since the old set keeps+ // working as a fallback in the meantime (see Design → Verification).+ // First-time enrollment (no live OtpSecret yet) has no such fallback, so+ // this call verifies otp_code but does *not* promote anything — promotion+ // of the secret moves to ConfirmRecoveryCodes, atomically with the+ // recovery codes, so the account is never left MFA-required with zero+ // usable codes (see Design → Verification). credential is required here+ // too for that branch, *unless* the account has neither a password nor+ // live MFA — email_code would be its only option, and email_code is+ // single-use, so it's checked once, at ConfirmRecoveryCodes, where the+ // mutation actually happens (see Design → Verification and+ // EnableMfaRequest.credential). Also rejects a pending set past its expiry+ // (isMFATempSecretExpired, checked today both before OTP verification and+ // before promotion — both carry forward, inside the locked transaction)+ // — pending_version alone only detects a *replaced* pending set, not one+ // that's simply gone stale with no replacement ever minted. name must be+ // the caller's own — no admin path, same reason as ChangePassword.+ rpc EnableMfa(EnableMfaRequest) returns (User) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:enableMfa"+ body: "*"+ };+ option (google.api.method_signature) = "name,otp_code,pending_version";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = TAKES_OVER_ACCOUNT;+ }++ // Turns MFA off for `name` by clearing the ENTIRE MFAConfig — the live+ // secret and recovery codes, and equally TempOtpSecret/TempRecoveryCodes+ // and their timestamps. Any pending enrollment or rotation dies with the+ // disable, deliberately: "turn MFA off" moots whatever was in flight, and+ // preserving pending state would let a later ConfirmRecoveryCodes+ // re-enable MFA through its first-time-enrollment branch, silently undoing+ // this call (see ConfirmRecoveryCodes). Matches what UpdateUser's+ // mfa_enabled=false already does today (patch.MFAConfig = &MFAConfig{},+ // user_service.go:410) — stated here because it is now load-bearing, not+ // incidental. Rejected for any non-admin caller while the+ // workspace requires MFA (Require_2Fa), self-service or admin-assisted+ // alike, same as UpdateUser enforces today. The admin path itself+ // (name != caller) is self-hosted only: SaaS rejects any cross-user call+ // outright before bb.users.update is even checked, same as UpdateUser's+ // existing cross-user gate.+ rpc DisableMfa(DisableMfaRequest) returns (User) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:disableMfa"+ body: "*"+ };+ option (google.api.method_signature) = "name,credential";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = TAKES_OVER_ACCOUNT;+ }++ // Mints a new set of recovery codes, persisted as the account's pending+ // set (storepb.MFAConfig.TempRecoveryCodes — reused, not new) alongside+ // the still-live old ones, and returns them, with a version token, for+ // the caller to save. Not yet live, so no proof is required here, same as+ // StartMfaEnrollment — but the account row is locked for the same reason+ // StartMfaEnrollment's is: this also reads and rewrites live MFAConfig+ // fields, not just temp ones (see Design → Verification). Requires a live+ // MFAConfig.OtpSecret already — recovery codes back up an existing+ // factor, so an account with none should enroll via StartMfaEnrollment+ // instead, same precondition the current regenerate_recovery_codes flag+ // enforces (user_service.go:475-477). name must be the caller's own — no+ // admin path.+ rpc RegenerateRecoveryCodes(RegenerateRecoveryCodesRequest) returns (RegenerateRecoveryCodesResponse) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:regenerateRecoveryCodes"+ body: "*"+ };+ option (google.api.method_signature) = "name";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = MINTS_CREDENTIAL;+ }++ // Promotes the pending set RegenerateRecoveryCodes minted to live,+ // invalidating the old set — but only the *exact* pending set named by+ // pending_version; a mismatch (superseded by a later RegenerateRecoveryCodes+ // call, own or someone else's) is rejected rather than silently promoting+ // whatever is currently pending. A DisableMfa in between is caught the same+ // way, because DisableMfa wipes the ENTIRE MFAConfig — pending temp state+ // included, see DisableMfa — so a stale confirmation finds no pending set+ // at all and fails on the pending_version check in either branch. That+ // wipe is load-bearing for the branch selector below: without it, an+ // account after a mid-rotation disable (no live OtpSecret, pending state+ // surviving) would be indistinguishable from a first-time enrollment+ // mid-flight, and this call would promote the pending secret down the+ // enrollment branch — silently re-enabling the MFA the owner just proved+ // they wanted off. The rotation branch still re-checks MFAConfig.OtpSecret+ // is live inside the locked transaction, as a structural guard: the branch+ // split's meaning depends on no path ever clearing the live secret while+ // leaving pending state behind, and this check is what turns a future+ // violation of that into a visible failure instead of a silent promote.+ // For first-time enrollment (no live+ // OtpSecret when StartMfaEnrollment minted this pending set — see+ // EnableMfa), that precondition doesn't apply; instead this call requires+ // otp_code and promotes the secret alongside the recovery codes, atomically,+ // completing what EnableMfa already verified but deliberately left+ // unpromoted (see Design → Verification). That branch also runs+ // isMFATempSecretExpired before promoting, the same check EnableMfa itself+ // runs — EnableMfa's own pass over it protects nothing here, since it+ // records no state ConfirmRecoveryCodes can see and this call may run+ // arbitrarily later, or without EnableMfa ever having run at all; a TOTP+ // code stays computable from a stale secret indefinitely, so otp_code+ // matching and pending_version matching together still say nothing about+ // whether the enrollment window has closed. The caller's acknowledgment that+ // they saved the new codes, not a proof step on its own — but promotion is+ // exactly the moment the old codes stop working, so it's gated like every+ // other promotion in this design. name must be the caller's own.+ rpc ConfirmRecoveryCodes(ConfirmRecoveryCodesRequest) returns (User) {+ option (google.api.http) = {+ post: "/v1/{name=users/*}:confirmRecoveryCodes"+ body: "*"+ };+ option (google.api.method_signature) = "name,credential,pending_version";+ option (bytebase.v1.auth_method) = CUSTOM;+ option (bytebase.v1.audit) = true;+ option (bytebase.v1.mcp_method_class) = FORBIDDEN;+ option (bytebase.v1.mcp_denial_reason) = TAKES_OVER_ACCOUNT;+ }+}+```++`mcp_denial_reason` isn't the same value across all seven methods, even though all seven are+`FORBIDDEN`: the enum distinguishes "rewrites credentials, response carries none"+(`TAKES_OVER_ACCOUNT`), "puts a usable secret directly in the response body" (`MINTS_CREDENTIAL`), and+"drives the out-of-band flow that delivers the secret a login accepts" (`RESETS_CREDENTIAL`).+`StartMfaEnrollment` returns a fresh TOTP secret; `RegenerateRecoveryCodes` returns fresh codes that+aren't live yet — both put a secret in the response body before anything is decided, so both get+`MINTS_CREDENTIAL`. `ChangePassword`/`EnableMfa`/`DisableMfa`/`ConfirmRecoveryCodes` return only+`User`, so they get `TAKES_OVER_ACCOUNT`, matching what `UpdateUser` already carries today for the+same operations. `RequestReauthCode` returns nothing but *sends* a credential-proving secret out of+band — the same shape `RequestPasswordReset` already carries this reason for — so it gets+`RESETS_CREDENTIAL`, the one value none of the other six use.++### Messages++```protobuf+// One proof that the caller currently controls a credential on the account.+// Exactly one field must be set; enforced in the handler, not via+// buf.validate.oneof.required — no other message in this repo uses that+// constraint, so this doesn't introduce a second convention for it.+message CredentialProof {+ oneof proof {+ // The account's current password. Accepted for ChangePassword always,+ // and for a factor-touching method (DisableMfa, or EnableMfa/+ // ConfirmRecoveryCodes when replacing an existing factor) ONLY when the+ // account has no live MFA — the handler rejects it while+ // MFAConfig.OtpSecret is set, because ResetPassword mints a password from+ // mailbox possession alone, so accepting it against live MFA would let a+ // stolen session plus mailbox strip the factor (see Design →+ // Verification).+ string current_password = 1 [+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_bytes = 72+ ];++ // A live code from the account's enrolled TOTP authenticator.+ string otp_code = 2 [+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_len = 64+ ];++ // A single-use MFA recovery code.+ string recovery_code = 3 [+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_len = 64+ ];++ // A one-time code from RequestReauthCode, sent to the account's own+ // registered email. Valid only when this account has no live MFA factor,+ // AND either its own Profile.LastChangePasswordTime is unset (no password+ // was ever legitimately written for it — see Design → Cloud vs.+ // self-hosted, and note CreateUser/Signup must set this field at creation+ // for it to mean that) OR the deployment is SaaS — bootstrap proof for an+ // account with nothing else yet, never a substitute for a factor that+ // already exists. The SaaS clause is an alternative path to eligibility,+ // not a replacement for the account-level check, and restores eligibility+ // for pre-existing Cloud/SSO accounts the LastChangePasswordTime backfill+ // migration would otherwise lock out permanently. It is deliberately NOT+ // the workspace's restriction.disallow_password_signin: principal has no+ // workspace column, so a workspace-scoped flag cannot speak for a global+ // account, and in a self-hosted multi-workspace deployment a user with a+ // real password in one workspace would become eligible via another that+ // happens to be SSO-only. SaaS is deployment-wide, forces that flag on+ // every workspace, and rejects ChangePassword outright, so no+ // caller-chosen password can exist there at all (see Design →+ // Verification). The handler checks this+ // eligibility itself; it is not just a+ // frontend choice of which field to show. The condition is never true for+ // DisableMfa, or for a rotation's ConfirmRecoveryCodes (both imply live+ // MFA already). It also is not the credential path for first-time+ // EnableMfa: that call omits credential entirely when the account has+ // neither a password nor live MFA (see EnableMfaRequest.credential), so+ // email_code is never consumed there. First-time ConfirmRecoveryCodes is+ // exactly where it's needed and used instead — that call still has no+ // live MFA at the time it runs, since promotion of the secret is deferred+ // to it precisely for this account shape (see Design → Verification) —+ // so email_code is only ever actually usable on ChangePassword or+ // first-time ConfirmRecoveryCodes.+ string email_code = 4 [+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_len = 64+ ];+ }+}++message RequestReauthCodeRequest {+ // Format: users/{email}. Must be the caller's own name — the code is+ // delivered to that account's own registered email, so requesting one for+ // someone else would only prove the target can read their own mail, not+ // anything about the caller.+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];+}++message ChangePasswordRequest {+ // Format: users/{email}. Must be the caller's own name — CredentialProof+ // proves control of *your* credential, which no one can supply for someone+ // else, so this is never valid on an admin-assisted call.+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];++ string new_password = 2 [+ (google.api.field_behavior) = REQUIRED,+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_bytes = 72+ ];++ CredentialProof credential = 3 [(google.api.field_behavior) = REQUIRED];+}++message StartMfaEnrollmentRequest {+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];+}++// The API-facing shape of an in-progress enrollment. What it's NOT is a claim+// about storage: EnableMfa still needs something server-side to validate+// otp_code against between the two calls, and that's the same store-level+// storepb.MFAConfig.TempOtpSecret / TempRecoveryCodes / TempOtpSecretCreatedTime+// StartMfaEnrollment already writes today (user_service.go's+// regenerate_temp_mfa_secret branch) — untouched by this design, a different+// proto package from v1pb.User, never itself exposed over the API. What+// changes is only the *API-facing* surface: those three fields disappear from+// User (see Existing messages) and reappear here, returned once by+// StartMfaEnrollment and never carried back into EnableMfaRequest — EnableMfa+// re-reads them from the account's store row instead.+message MfaEnrollment {+ string otp_secret = 1 [+ (google.api.field_behavior) = OUTPUT_ONLY,+ (bytebase.v1.audit_behavior) = SENSITIVE+ ];+ string provisioning_uri = 2 [+ (google.api.field_behavior) = OUTPUT_ONLY,+ (bytebase.v1.audit_behavior) = SENSITIVE+ ];+ repeated string recovery_codes = 3 [+ (google.api.field_behavior) = OUTPUT_ONLY,+ (bytebase.v1.audit_behavior) = SENSITIVE+ ];+ google.protobuf.Timestamp expire_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];++ // Same shared temp-state version RegenerateRecoveryCodesResponse.pending_version+ // identifies (see its comment) — StartMfaEnrollment and RegenerateRecoveryCodes+ // both mint into the same account's temp MFA state, so they share one version.+ // Echo to EnableMfa.+ google.protobuf.Timestamp pending_version = 5 [(google.api.field_behavior) = OUTPUT_ONLY];+}++message EnableMfaRequest {+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];++ // The code computed from the enrollment StartMfaEnrollment returned.+ string otp_code = 2 [+ (google.api.field_behavior) = REQUIRED,+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_len = 64+ ];++ // Proof for the *existing* factor being replaced, if any. Not the code+ // above — that proves the new enrollment, this proves the caller still+ // owns the account before the swap. Required whenever a reusable proof+ // exists — a rotation (there's a live factor to prove), or a first-time+ // enrollment where the account already has a password. Omitted only when+ // `email_code` would be the sole option: a first-time enrollment on an+ // account with neither a password nor live MFA — see Design → Verification+ // for why this call must not consume that code itself.+ CredentialProof credential = 3 [(google.api.field_behavior) = OPTIONAL];++ // Echoed from MfaEnrollment.pending_version. otp_code alone only proves+ // the caller knows the current TempOtpSecret; it says nothing about+ // whether TempRecoveryCodes — minted alongside it, promoted alongside it+ // — has since been overwritten by an intervening RegenerateRecoveryCodes+ // call. A mismatch here is rejected for the same reason a mismatched+ // ConfirmRecoveryCodesRequest.pending_version is.+ google.protobuf.Timestamp pending_version = 4 [(google.api.field_behavior) = REQUIRED];+}++message DisableMfaRequest {+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];++ // Required only when name is the caller's own. On an admin-assisted call+ // (name is someone else's), unset and unchecked — this is the one method+ // in this file with a real admin path, so its requirement is conditional+ // on caller identity, which a blanket proto REQUIRED can't express; the+ // conditionality is enforced in the handler, same as every other+ // identity-dependent check in this design. Also constrained by factor: on+ // a self-service call against an account with live MFA, the handler+ // accepts only otp_code/recovery_code, never current_password/email_code+ // (see CredentialProof.current_password and Design → Verification).+ CredentialProof credential = 2 [(google.api.field_behavior) = OPTIONAL];+}++message RegenerateRecoveryCodesRequest {+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];+}++message ConfirmRecoveryCodesRequest {+ string name = 1 [+ (google.api.field_behavior) = REQUIRED,+ (google.api.resource_reference) = {type: "bytebase.com/User"},+ (buf.validate.field).string.max_len = 260+ ];+ CredentialProof credential = 2 [(google.api.field_behavior) = REQUIRED];++ // Echoed from RegenerateRecoveryCodesResponse.pending_version. Must match+ // the account's current pending set exactly, or this is rejected — a+ // mismatch means a later RegenerateRecoveryCodes call (the caller's own,+ // in a second tab, or someone else's) has already superseded the set this+ // request thinks it's confirming.+ google.protobuf.Timestamp pending_version = 3 [(google.api.field_behavior) = REQUIRED];++ // Required only for first-time MFA enrollment (the account has no live+ // OtpSecret yet) — rejected if set otherwise. A *fresh* code, not the one+ // already submitted to EnableMfa — TOTP codes are only valid for one ~30s+ // period, and the recovery-code download screen in between routinely takes+ // longer than that, so resending the earlier value would just fail (see+ // Design → Verification and Frontend). Verified against the same pending+ // TempOtpSecret EnableMfa already validated, and promoted alongside the+ // recovery codes in this call rather than in EnableMfa, so the account is+ // never left MFA-required with zero usable recovery codes if this call+ // never arrives. Left unset for an ordinary rotation, where EnableMfa+ // already promoted the secret and this call only confirms recovery-code+ // receipt.+ string otp_code = 4 [+ (google.api.field_behavior) = OPTIONAL,+ (bytebase.v1.audit_behavior) = SENSITIVE,+ (buf.validate.field).string.max_len = 64+ ];+}++message RegenerateRecoveryCodesResponse {+ repeated string recovery_codes = 1 [+ (google.api.field_behavior) = OUTPUT_ONLY,+ (bytebase.v1.audit_behavior) = SENSITIVE+ ];++ // Identifies the account's current temp-MFA-state generation — the+ // store's own mint timestamp, not a newly invented token, shared with+ // MfaEnrollment.pending_version because StartMfaEnrollment and this+ // method mint into the same underlying temp state. Pass back to+ // ConfirmRecoveryCodes.+ google.protobuf.Timestamp pending_version = 2 [(google.api.field_behavior) = OUTPUT_ONLY];+}+```++`current_password`/`new_password` are bounded at `max_bytes = 72` — bcrypt's real limit, matching+`User.password` — not `LoginRequest.password`'s `max_bytes = 512`, which is wider only because `Login`+also serves LDAP bind; nothing reachable from the password-bearing methods here ever touches an+LDAP-bound principal. `otp_code`/`recovery_code`/`email_code` take `max_len = 64`, matching+`LoginRequest`'s existing fields of the same name. Each `name` field takes `max_len = 260` (`"users/"` ++a 254-char email; the workspace-wide 256-byte resource-name bound would reject a legal maximum-length+email), because every one of these methods turns `name` into a T9 lockout identity — the validate+interceptor must refuse an oversized identity before any handler claims a slot, the rule+`TestAuthEmailFieldsAreLengthBounded` already pins for every `email` field in `auth_service.proto`. That+test's inventory, and the audit-payload inventory `TestLintAuditPayloadInventory` pins, both have to gain+the seven new `name` fields, and `TestForbiddenClassMembership` has to gain all seven new procedures with+their `mcp_denial_reason`s — three enumerated lints that fail closed on anything unlisted, so they are+part of this change, not a follow-up.++`RegenerateRecoveryCodes`/`ConfirmRecoveryCodes` keep today's mint-then-promote shape — an earlier+draft of this doc collapsed it into one call, reasoning that recovery codes have no client-side proof+step the way a TOTP code does (nothing to "verify you can compute"), so the two-step shape looked like+an accident of sharing plumbing with TOTP enrollment. Wrong, per a+[Codex finding](https://github.com/bytebase/bytebase/pull/21235): the two steps aren't about proving+computation, they're about confirming *receipt* — `RegenerateRecoveryCodesView.tsx:60-75` already+disables the promote button until the user reports downloading the codes, precisely so a lost+response, a closed tab, or a crash between mint and promote can't leave someone with live MFA and zero+saved recovery codes. Splitting the RPC preserves that property structurally: the old codes stay valid+through `RegenerateRecoveryCodes` (mint) and only stop working once `ConfirmRecoveryCodes` runs, so a+client that never gets a chance to call `ConfirmRecoveryCodes` — for any reason — has lost nothing.++That split alone still had a hole, caught the same review pass: since `RegenerateRecoveryCodes` needs+no proof (matching `StartMfaEnrollment`), and `TempRecoveryCodes` is one mutable slot per account, a+stolen-session caller with no credential could mint *after* the real owner, overwriting the pending+set with one only the attacker knows — the owner's own, correctly-proofed `ConfirmRecoveryCodes` call+would then promote the attacker's set, not theirs, without the attacker ever needing to produce a+credential at all. TOTP enrollment doesn't have this hole: `EnableMfa`'s `otp_code` is itself proof of+which secret the caller actually has, so an overwritten `TempOtpSecret` just makes the legitimate+call fail closed (wrong code) rather than silently promote the wrong thing. Recovery codes have+nothing equivalent to check computation against, so `pending_version` — the mint's own timestamp,+echoed back and matched exactly — plays that role instead: it doesn't prove the caller's identity+(`CredentialProof` still does that), it proves the caller is confirming the *specific* set they+actually received, so a set superseded by any later mint is rejected rather than silently promoted.++That "fails closed" claim about `otp_code` turned out to only cover half of what `EnableMfa` used to+promote — [caught in the same review round](https://github.com/bytebase/bytebase/pull/21235):+`StartMfaEnrollment` mints `TempOtpSecret` *and* `TempRecoveryCodes` together, and `EnableMfa`+originally promoted both together in one call, but only `otp_code` was bound to anything. A+stolen-session caller with no credential could call the still-proof-free `RegenerateRecoveryCodes`+mid-enrollment, overwriting `TempRecoveryCodes` with a set only they know, while `TempOtpSecret` stays+untouched — so the real owner's `otp_code` still validates fine, `EnableMfa` still succeeds, and it+would have promoted the attacker's recovery codes right alongside the owner's legitimate TOTP secret.++A [later finding](https://github.com/bytebase/bytebase/pull/21235) made the fix simpler than patching+that race in place: `EnableMfa` shouldn't have been promoting recovery codes at all. The existing+enrollment UI validates the OTP, shows the recovery codes, and only promotes them after the user+confirms downloading — the exact same receipt-confirmation shape `RegenerateRecoveryCodesView.tsx`+already has for rotation, which is what motivated `ConfirmRecoveryCodes`'s own `pending_version` gate+above. `EnableMfa` combining OTP validation with recovery-code promotion in one atomic call had the+identical lost-response problem: if the response never arrives or the tab closes right after, the+account has live MFA and recovery codes the owner never actually saw, no different from the rotation+bug already fixed. So `EnableMfa` now promotes *only* the secret; the recovery codes it minted+alongside stay pending until a separate `ConfirmRecoveryCodes{name, pending_version}` call — reusing+the method already built for rotation rather than inventing a second confirmation mechanism, since+enrollment and rotation turn out to be the same "confirm receipt before the old thing goes away"+shape once the OTP-specific part is factored out.++That "no old thing" framing for enrollment was itself the bug —+[caught in a later review round](https://github.com/bytebase/bytebase/pull/21235): rotation's safety+net is precisely that old thing — the previous live recovery codes keep working right up until+`ConfirmRecoveryCodes` runs, so a lost response or a closed tab costs nothing. First-time enrollment has+no such fallback by construction: nothing was live before this flow started, so if `EnableMfa` promotes+the secret and `ConfirmRecoveryCodes` never runs, the account is left MFA-required with zero usable+recovery codes — worse than the two problems the split was built to fix, not equivalent to them. This+is also the point `email_code` eligibility can't rescue: it requires no live `OtpSecret`+(see Design → Verification), which `EnableMfa` promoting the secret already ruled out. Fixed by+splitting `EnableMfa` itself along the same line as before, one level deeper: for a rotation (the+account already had a live `OtpSecret`), it promotes the secret as already described, unaffected. For+first-time enrollment, it verifies `otp_code` (and `credential`, when the account has a password to+prove — see EnableMfaRequest.credential) but promotes nothing — the account stays exactly as unenrolled+as before the call — and the actual promotion of *both* `TempOtpSecret` and `TempRecoveryCodes` moves to+`ConfirmRecoveryCodes`, atomically, gated on a fresh `otp_code` verified there+(`ConfirmRecoveryCodesRequest.otp_code`, required only in the enrollment case — see API → Messages).+A client that never gets a chance to call `ConfirmRecoveryCodes` after enrolling has, once+again, lost nothing: no secret went live, no recovery codes exist to lose track of, and a retried+`EnableMfa` against the same still-pending `pending_version` is exactly as harmless as the first attempt,+since it never wrote anything either. `EnableMfaRequest.pending_version` still guards `StartMfaEnrollment`+against being silently superseded before `EnableMfa` runs — general temp-state freshness, not+specifically a recovery-codes protection, and for enrollment now doubles as the token that ties+`EnableMfa`'s verification to `ConfirmRecoveryCodes`'s promotion of the exact same pending set.++Deferring promotion to `ConfirmRecoveryCodes` also deferred the expiry check without saying so —+[caught in a later round](https://github.com/bytebase/bytebase/pull/21235): `EnableMfa` still runs+`isMFATempSecretExpired` before it verifies `otp_code`, but for enrollment that check now protects+nothing, since `EnableMfa` writes no state `ConfirmRecoveryCodes` can see and the two calls can be+separated by however long the user takes to save their codes — or `ConfirmRecoveryCodes` can be called+directly, `EnableMfa` never having run at all. A TOTP code stays computable from a stale secret+indefinitely; only `isMFATempSecretExpired` catches a pending set that's simply gone stale with no+replacement minted, the same gap `pending_version` alone was already established not to cover+(see `EnableMfa` above). `ConfirmRecoveryCodes`'s enrollment branch runs the identical+`isMFATempSecretExpired` check itself, immediately before promoting, rather than trusting whatever+`EnableMfa` may or may not have already checked.++Requiring `otp_code` again at `ConfirmRecoveryCodes` only works if it's a *different* code from the one+`EnableMfa` already validated — [caught in a later round](https://github.com/bytebase/bytebase/pull/21235):+a TOTP code is only valid for roughly one 30-second period, and the time between the two calls is+however long the user takes to read, download, and put away their recovery codes on+`TwoFactorSetupPage` — routinely longer than that. Resubmitting the value the client already has from+the `EnableMfa` step (`TwoFactorSetupPage.tsx:146-160` stores it before advancing to the recovery-code+screen) would fail almost every time, not occasionally. The frontend needs a real second input here, not+a replay: the confirm step prompts for a fresh code from the authenticator app immediately before+submitting `ConfirmRecoveryCodes`, the same way `EnableMfa`'s own step did — a second, deliberate proof+of live possession, not friction for its own sake, since it's standing in for the same `otp_code` gate+`EnableMfa` already carries for the accounts where a rotation's version of this call needs none.++Requiring `credential` on both `EnableMfa` and `ConfirmRecoveryCodes` is fine for a rotation, or for+enrollment on an account that already has a password — both proofs are pure comparisons or a spendable-+but-plentiful recovery code, reusable or numerous enough to supply twice in one flow. It breaks+[precisely the account this whole mechanism exists for](https://github.com/bytebase/bytebase/pull/21235):+a passwordless first-time enrollment, where `email_code` is the *only* available proof. `EnableMfa`+already requires and atomically consumes one `REAUTH` code there — even though, per the fix above, it+promotes nothing — so `ConfirmRecoveryCodes`'s own required `credential` demands a second code+immediately afterward, and `RequestReauthCode` silently no-ops for its full resend cooldown+(`auth_service_email_code.go:392-393`), stalling the flow this design built `email_code` to unblock in+the first place. The fix isn't a longer cooldown or a second exemption on the resend path — it's not+asking twice: `EnableMfaRequest.credential` becomes optional, required only when a reusable proof exists+(a rotation, or enrollment where the account has a password); omitted when the account has neither a+password nor live MFA, since `email_code` would be the only option and this call doesn't mutate anything+in that branch anyway. The actual gate moves entirely to `ConfirmRecoveryCodes`, which already requires+`credential` unconditionally and is the point where promotion — the thing worth gating — actually+happens. `otp_code` still runs in `EnableMfa` regardless of branch: it isn't the credential proof, it's+confirmation the caller correctly configured the new device, and skipping it would leave a typo'd+authenticator app undetected until the user is already locked out at their next login.++`email_code` verifies against a new `REAUTH` purpose on `email_verification_code`+(`storepb.EmailVerificationCodePurpose`), alongside the existing `LOGIN` and `PASSWORD_RESET` —+that table was already built to hold more than one purpose, so this is a third row shape, not new+storage. Without it, `EnableMfaRequest.credential` had exactly the failure mode+[a Codex review on this doc's own PR](https://github.com/bytebase/bytebase/pull/21235) caught: a Cloud+or SSO account has no password, and first-time enrollment has no existing OTP or recovery code either,+so all three original options were simultaneously unsatisfiable for precisely the accounts+`guard.ts:265-275` force-redirects into MFA setup under a `require_2fa` policy — a hard lockout, not+an edge case. `email_code` closes it for every Cloud account, and for any self-hosted account with no+password of its own — including a mixed-mode SSO user in a workspace that still allows local password+login generally — with mail configured, by giving them a proof they can always produce.++It doesn't close it for every account, though — a second+[Codex finding](https://github.com/bytebase/bytebase/pull/21235) on the same review caught the+remainder: `resolvePreLoginEmailSetting` returns `nil` with no workspace `EMAIL` setting and no+`EMAIL_CONFIG` env var (`auth_service_email_code.go:319-342`), and `sendEmailVerificationCode` then+fails outright rather than degrading (`:366-374`) — so a self-hosted, SSO-only workspace with+`require_2fa` on and no SMTP configured leaves an enrolling user with no password, no existing MFA,+*and* no deliverable code. Narrower than the original gap (self-hosted, SSO-only, no SMTP, all+required together) but real, and not something this design closes. Two things worth doing regardless+of that gap, both applied here: `RequestReauthCode` surfaces the send failure rather than swallowing+it like `ResetPassword` does — there's no existence-oracle reason to hide it, since the caller is+already authenticated as the only account it could possibly be about — so the failure is at least+diagnosable ("no email configured, contact your workspace admin") instead of a silent dead end. The+full fix — a proof channel that doesn't depend on SMTP, most plausibly re-authenticating against the+account's own upstream IdP for SSO deployments — is real scope beyond this doc: it means integrating+with whatever OIDC/SAML flow already exists for login, not reusing something already built the way+`email_code` reuses T9's table. Tracked as a follow-up, not silently left for someone to discover+later.++### Existing messages++```protobuf+message UpdateUserRequest {+ reserved 3, 4, 5; // otp_code, regenerate_temp_mfa_secret, regenerate_recovery_codes — moved above.+ User user = 1 [(google.api.field_behavior) = REQUIRED];+ google.protobuf.FieldMask update_mask = 2;+ bool allow_missing = 6;+ // `password` in update_mask is now admin-assisted only (callerUser.ID != user.ID);+ // a self-service caller is rejected and pointed at ChangePassword.+}+```++One store-level message changes too — `storepb.UserProfile` (`proto/store/store/user.proto:38-47`) gains+the credential-generation stamp the MFA temp token is validated against (see Design → Verification). Field+6, not the reserved 4:++```protobuf+message UserProfile {+ // ... last_login_time = 1, last_change_password_time = 2, source = 3,+ // reserved 4, last_login_workspace = 5 ...++ // Bumped by every mutation that revokes this account's sessions:+ // ChangePassword, EnableMfa, DisableMfa, ConfirmRecoveryCodes, ResetPassword,+ // and the admin-assisted password reset. Distinct from+ // last_change_password_time, which means "this account has had a+ // caller-chosen password" for email_code eligibility and must not move on+ // MFA-only changes.+ google.protobuf.Timestamp last_credential_change_time = 6;+}+```++`User.mfa_enabled` stays a bool — just gains `OUTPUT_ONLY`, since nothing sets it through `UpdateUser`+anymore. That's an annotation, not a wire change, so the field keeps its number; no new field, no+reservation needed for it. (An earlier pass here added a nested `MfaStatus` with a+`recovery_codes_remaining` count, reasoning that it would help a client prompt for regeneration before+a user runs out. Dropped: nothing in T10 needs it, no frontend surface consumes it today, and a+message wrapping one field is the same speculative-abstraction mistake at a different scale. Revisit+if a real reader shows up for it.)++```protobuf+message User {+ reserved 5, 7, 9, 10, 11, 15;+ // 9, 10, 11: temp_otp_secret / temp_recovery_codes / temp_otp_secret_created_time+ // — API-facing removal only; the underlying storepb.MFAConfig columns+ // these were read from are untouched (see MfaEnrollment's comment).+ // Enrollment now returns this data via MfaEnrollment instead of here.++ // ...name, state, email, title, password, phone, profile, groups, workspace unchanged...++ // The mfa_enabled flag means if the user has enabled MFA.+ bool mfa_enabled = 8 [(google.api.field_behavior) = OUTPUT_ONLY];+}+```++### Naming++`StartMfaEnrollment` is the only method that produces an `MfaEnrollment`, so it's the only one named+after that object — once confirmed, there's no standing "enrollment" left to refer to, only the+account's live MFA state, which `EnableMfa`/`DisableMfa` name directly as a matched pair, matching the+existing `handleEnable2FA`/`handleDisable2FA` vocabulary in `AccountSettingsPage.tsx`. `ChangePassword`+and `RegenerateRecoveryCodes` need no qualifier — recovery codes only ever mean the MFA kind, matching+today's `regenerate_recovery_codes` field name and `RegenerateRecoveryCodesView` component.+`ConfirmRecoveryCodes` isn't `EnableRecoveryCodes` — recovery codes aren't a feature with an on/off+state the way MFA is, they're always live once any exist, so "confirm" names what the caller is+actually doing (acknowledging receipt), not a state transition that doesn't exist.++Four conformance points where the proposal above still has to be brought into line with the repo's own+pinned conventions, none of which changes the design, all of which a lint or a reviewer will otherwise+catch:++- **`StartMfaEnrollment` returns a bare `MfaEnrollment`, which AIP-136 doesn't allow.** A custom method+ returns `<Rpc>Response` unless it returns an actual resource, and `MfaEnrollment` has no+ `google.api.resource` and no `name` — it is a response object, not a resource (the Alternatives section+ deliberately declines to model MFA as a `users/{email}/mfaFactors/{id}` collection). Rename it+ `StartMfaEnrollmentResponse`, matching `LoginResponse`/`ExchangeTokenResponse` in the same package.+- **Acronym casing: `Mfa` vs `MFA`.** Every acronym in the v1 protos is uppercase+ (`OIDCIdentityProviderContext`, `LDAPIdentityProviderConfig`, `AIChatMessage`), and the store side is+ already `MFAConfig`. `Mfa`/`EnableMfa`/`DisableMfa` would be the only lowercase-acronym names in the+ tree. Recommendation is to uppercase to `EnableMFA`/`DisableMFA`/`StartMFAEnrollment`/`MFAEnrollment`+ for consistency; flagged as a deliberate call rather than silently drifting, since it touches every+ MFA-named symbol and the HTTP verbs (`:enableMFA`).+- **`RESETS_CREDENTIAL` on `RequestReauthCode` contradicts the enum's own text**, which defines it as+ driving "the out-of-band reset flow that sets or delivers the secret a login accepts" — and the+ `REAUTH` code is deliberately *not* login-accepted. The enum comment in `annotation.proto` must be+ widened ("the secret a login *or a credential change* accepts") in the same change, or the reason is+ self-contradictory against `TestLintReasonsMatchTheClass`.+- **The prose paraphrases of `MINTS_CREDENTIAL`/`TAKES_OVER_ACCOUNT` don't match `annotation.proto`.**+ The real definitions are "puts a *token* for the caller's own principal in the response" and "rewrites+ an account's own credentials, which would let the session log in as that account" — nothing about+ whether the response body carries a secret. A not-yet-live TOTP secret or pending recovery-code set is+ neither a token nor a live credential, so `StartMfaEnrollment`/`RegenerateRecoveryCodes` fit+ `MINTS_CREDENTIAL` only once the enum comment is widened to name pending/enrollment material+ explicitly; do that alongside, since the reason-per-method mapping is lint-pinned.++## Alternatives++- **Collapse recovery-code regeneration into one call** (this doc's own earlier draft) rather than+ the `RegenerateRecoveryCodes`/`ConfirmRecoveryCodes` pair. Reasoned that recovery codes have no+ client-side proof step the way a TOTP code does, so the existing two-step shape looked accidental.+ Wrong: the two steps aren't about proof, they're about confirming receipt before the old codes stop+ working — `RegenerateRecoveryCodesView.tsx` already disables its promote button until the user+ reports downloading the codes, and one call would have silently dropped that safety property.+- **Skip the proof entirely for first-time MFA enrollment**, on the theory that there's nothing live+ yet to take over. Rejected: an attacker with a stolen session who enrolls their own device on a+ victim's account doesn't just add a factor — once `MFAConfig.OtpSecret` is non-empty, `Login`+ challenges it on *every* future login, including the real owner's, who never set it up and can't+ produce the attacker's code. Different shape of harm than a full impersonation, same severity: the+ real owner is locked out of their own account. Caught by+ [Codex's review](https://github.com/bytebase/bytebase/pull/21235) of this doc's own PR, which is what+ `email_code` closes.+- **Reuse `ResetPassword`'s existing send/verify flow directly for MFA enrollment**, instead of a new+ `RequestReauthCode` and a `REAUTH` purpose. Rejected: `ResetPassword`'s code is scoped to setting a+ new password, not to generic identity proof, and folding a second meaning into it is the same+ field-overload mistake `otp_code` already made once in the original `UpdateUser`. A third purpose on+ the same table costs one enum value; a second meaning on an existing purpose costs a code path that+ has to explain both.+- **Password only, no `CredentialProof` alternative** — the doc's own starting point, for all four+ methods and then, briefly, for `EnableMfa` alone even after the others got `CredentialProof`.+ Dropped on both counts: it forces an MFA-enabled user to produce the one factor they might+ legitimately be rotating away from (a suspected-leaked password), while the bookkeeping to accept+ their second factor instead (T9's `MFA` lockout kind, `challengeMFACode`/`challengeRecoveryCode`)+ already exists — and for `EnableMfa` specifically, restricting to password broke Cloud entirely,+ since a Cloud account has no password to supply (see Cloud vs. self-hosted).+- **Boolean flags on `UpdateUser`, gated by a single check on the built patch** (this doc's own first+ draft). Smaller diff, but keeps `mfa_enabled` on status-and-trigger double duty and the scratch+ fields on `User`. Superseded once every comparable product turned out to reject this shape.+- **Time-boxed elevated session** (GitHub sudo mode: 2h, resets per action; Google Cloud console:+ 15min). Real session-state infrastructure for a handful of rarely-touched screens, and the+ elevated flag would live in the same access token T10 says an attacker already holds. Revisit if+ the number of sensitive self-service endpoints grows enough to justify a shared mechanism.+- **RFC 9470 OAuth step-up** (`401` + `insufficient_user_authentication`, `max_age`). The formal+ version of the above — same objection, plus it needs an `auth_time` claim Bytebase's access token+ doesn't carry (only a per-refresh `IssuedAt`, unrelated to when the user last typed a credential).+- **Grace window off token freshness.** Rejected outright: `IssuedAt` resets on ordinary hourly+ refresh, so this would wave a stolen, recently-refreshed token straight through.+- **Overload the existing `otp_code` field for re-authentication.** Two different secrets+ (`TempOtpSecret` for enrollment vs. the account's real credential) behind one field name is the+ ambiguity this bug already came from.+- **Keep password on `UpdateUser` with a `current_password` field**, as in this doc's own earlier+ draft. Once the proof became a three-way `CredentialProof` rather than one string, it stopped+ reading as "one more field on a PATCH" and started reading as exactly the kind of dedicated,+ confirmed action `UpdateEmail` already models for a less sensitive field.+- **A general `users/{email}/mfaFactors/{id}` collection.** Correct once Bytebase supports more than+ one factor type; not yet.++## Reference++| Element | Same as |+|---|---|+| MFA as its own resource/methods, not flags on the account's update call | [Okta Factors](https://developer.okta.com/docs/reference/api/factors/), [Auth0 multifactor delete](https://auth0.com/docs/api/management/v2/users/delete-multifactor-by-provider), [AWS IAM MFA devices](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateVirtualMFADevice.html), [WorkOS MFA](https://workos.com/docs/mfa), [Keycloak credentials](https://www.keycloak.org/docs-api/latest/rest-api/index.html) |+| Start / finalize / withdraw enrollment lifecycle, proto-first API (closest architectural analog) | [Google Identity Platform `mfaEnrollment`](https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/accounts.mfaEnrollment/start) |+| Distinct RPCs per MFA transition, gRPC-first API (other close analog, already cited in this repo for its lockout model) | Zitadel `AddTOTP` / `VerifyTOTP` / `RemoveTOTP` |+| Mint step needs no re-auth; promotion does | AWS `CreateVirtualMFADevice` (no re-auth) → `EnableMFADevice` (two consecutive codes) |+| Password *or* a live second factor accepted as interchangeable proof | GitHub sudo mode confirms with password, security key, or TOTP interchangeably |+| Current password required to change your own password | [GitLab](https://docs.gitlab.com/user/profile/user_passwords.html), OWASP ASVS 3.7.1 |+| Current password required to disable your own second factor | [GitLab](https://docs.gitlab.com/user/profile/account/two_factor_authentication.html) |+| Enrolling/replacing a second factor gated the same as disabling it | [Google](https://support.google.com/accounts/answer/7162782) lists "Turn on 2-Step Verification" at the same reauth tier as password change |+| Self-service credential change split into its own method from admin-assisted reset; one needs the old value, one doesn't | [AWS `ChangePassword` vs. `UpdateLoginProfile`](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ChangePassword.html); this repo's own `UpdateEmail` split from `UpdateUser` |+| Re-auth attempts bounded per identity, not a free-standing oracle | [`login-attempt-lockout.md`](login-attempt-lockout.md) (T9, this repo) |+| Admin-assisted recovery exempt from proving the credential being replaced | [`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md) (this repo); GitLab, Okta, AWS IAM admin consoles all reset without the old value |+| Sensitive-attribute re-auth as a general requirement, not just password | OWASP ASVS re-auth for changes to email, phone, MFA config, or other recovery-relevant fields ([ASVS #2727](https://github.com/OWASP/ASVS/issues/2727)) |++Considered, not adopted — specifically GitHub's *time-boxed session*, not its factor-choice model+(adopted above): [GitHub sudo mode](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/sudo-mode) ·+[RFC 9470 explained](https://workos.com/blog/rfc-9470-step-up-authentication-challenge) ·+[Google Cloud console reauthentication](https://docs.cloud.google.com/docs/authentication/reauthentication) ·+[Okta account management policy](https://developer.okta.com/docs/concepts/policies/).++Related: [`v1-api-audit-2026-08.md`](v1-api-audit-2026-08.md) T10 ·+[`login-attempt-lockout.md`](login-attempt-lockout.md) (T9) ·+[`split-profile-self-service-vs-admin.md`](split-profile-self-service-vs-admin.md).