Database governance built for humans and agents — controlling changes and access across every major database.
Require re-authentication to change your own credentials
Status: implemented with deltas · proposed 2026-08-24, shipped 2026-08-27
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 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. A stolen access token may keep answering
requests until it expires (≤1h); this design stops it being spent on a replacement credential.
What shipped differs from this document. The change that landed is the credential-proof surface only; several mechanisms below were cut or deferred, and the text still describes them as designed.
Shipped.
CredentialProof— current password, OTP, recovery code, or an emailedRequestReauthCodecode — required byChangePassword,EnableMFA,DisableMFA(self-service), andConfirmRecoveryCodes. Every proof claims a T9 login-attempt slot, so no channel is an unbounded guessing oracle. Factor-touching methods refuse the password while a live factor exists.email_codeis Bytebase Cloud only and only when no factor exists — bootstrap proof for a Cloud account that has nothing else.Cut.
- Credential generation.
Profile.last_credential_change_time, thecred_genJWT claim, and the consume-time checks are gone. Service accounts and SSO accounts stop being exceptions to a rule that only ever fit password users.- The enrollment stamp. Whether a caller can prove a password is answered by whether they can supply one. With the stamp went the migration: this change needs none.
- MFA revocation. Enrolling, rotating, or disabling a factor no longer ends other sessions — MFA gates minting a session, not using one, so a new phone must not sign the owner out everywhere. Only a password change revokes, and only the account's web sessions; OAuth grants are untouched, which is a separate change with its own blast radius.
Deferred. The fenced credential transaction (
store.RunUserCredentialTx) and the issuance guard are not here; they are a store-concurrency change of their own. Handlers verify against a read and write through the ordinary store methods, so readDesign → the fenced transactionas intent, not as shipped code.Kept from the existing implementation. Promotion stays in
ConfirmRecoveryCodesfor every flow, under thepending_versioncompare-and-set, so a first factor is never live with no saved recovery codes and a replacement promotes the authenticator the user just scanned.EnableMFAverifies and writes nothing. First-time enrollment therefore submits a second, freshotp_codeat confirmation, since promotion — not verification — is the moment MFA starts gating logins.DisableMFAasks for a proof only when there is a live factor to prove, so an abandoned enrollment can still be cancelled.
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
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 existingOtpSecret. The temp codes come from a priorregenerate_temp_mfa_secretcall, 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).
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.UpdateEmailalready leftUpdateUserfor exactly this reason (it "changes the identity the person signs in with," persplit-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). - 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_tokenand the OAuth2/MCPoauth2_refresh_tokengrants, plus outstandingoauth2_authorization_coderows 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 JWTsAPIAuthInterceptoraccepts 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 —SwitchWorkspaceand its twoworkspace_service.gocallers, the MFA temp-token completion (checkMFARequired), and OAuth/authorize— is bound toLastCredentialChangeTimeand 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 byCredentialProofregardless of whether the owner is notified. Worth a follow-up, not bundled into this fix. - A
CredentialProofchannel 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 withrequire_2faon 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 wayemail_codeis. 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:LastCredentialChangeTimehad to exist anyway for the MFA temp token, andSwitchWorkspaceturned out to mint fresh access tokens off a stale JWT with no bound at all, which is strictly worse than the/authorizecase 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
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 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 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) 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: 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: 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: 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 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: 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:
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/AGENTS.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, 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: 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, 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: 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: 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 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:
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:
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:
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: 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. 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. 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: 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.
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. 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: 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: 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
Loginitself"; it is not.checkMFARequired(auth_service.go:718-739) is called fromLogin(:209) and fromSwitchWorkspace(:903), both reachingGenerateMFATempTokenat:731. TheSwitchWorkspaceroute is worse: it needs only the stolen access token, no password, to obtain a temp token, which then completes a fullLoginafter the victim's credential change. The stamp is written and checked insidecheckMFARequired, not at theLogincall site, or the second door stays open. SwitchWorkspacedoesn't even expiry-check the session it consumes.switchWorkspaceInternalconsumes the web refresh token viaGetAndDeleteWebRefreshToken, which carries noexpires_atpredicate (web_refresh_token.go:62-84);Refreshcompensates by checking the returned row's expiry (auth_service.go:488-490), butswitchWorkspaceInternalnever does (:994nil-check and:997email-check only) and reuses the already-pastExpiresAtfor the new session (:1000). So a session past its 7-day absolute lifetime still mints a fresh full-lifetime token throughSwitchWorkspace/LeaveWorkspace/DeleteWorkspaceuntil 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 sameexpires_at > now()-at-consume rule the credential codes get below.- "≤1h" and "30 days" are not real ceilings.
access_token_durationhas only a one-minute floor (setting_service.go:769-775); a workspace withFEATURE_TOKEN_DURATION_CONTROLcan set it to 90 days, and every minted replacement inherits that (generateLoginTokenreads it live). And OAuth refresh writes a fresh fullrefreshTokenExpiryon 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/switchWorkspaceInternalpass the originalExpiresAtthrough). 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_USERprincipals.SwitchWorkspaceitself guardsType != END_USER(:850), but its twoworkspace_service.gocallers do not, andgenerateLoginTokenhas a liveSERVICE_ACCOUNTbranch (:751). Service accounts and workload identities are not inprincipaland have noprofile, soLastCredentialChangeTimecannot exist for them and "refuse to mint on a missing stamp" would permanently break service-account-drivenLeaveWorkspace/DeleteWorkspace. The stamp check applies toEND_USERprincipals only, stated explicitly so it is a typed rule rather than a silent type-conditional bypass — non-END_USERcredentials 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'sMINTS_CREDENTIAL_FOR_OTHERSclass — 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: 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 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 — 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: 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,
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: 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: 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: 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: 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: 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:
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 DELETEs — 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, 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:
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 fromworkspace_service.go:312,421) logs aDeleteWebRefreshTokenfailure and returnsEmptywith 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: forLogoutan 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. SoLogoutdiverges 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 aDeleteOAuth2RefreshTokenfailure and returns200, telling an MCP client its compromised grant is dead while the row survives up to 30 days. RFC 7009 wants200for an unknown token, not a failed revocation (503is allowed); the two are conflated. Same idempotency caveat asLogout: an already-absent token is a legitimate200, only a real storage error becomes503. - 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 timecreateAuditLogfails, 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 "thebb.users.updatepermission 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: 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: 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 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 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 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 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: 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: 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 — 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:
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: 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 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, 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
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
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
// 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_reasons — 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: 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:
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 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: 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: 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:
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:
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 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 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
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:
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.)
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:
StartMfaEnrollmentreturns a bareMfaEnrollment, which AIP-136 doesn't allow. A custom method returns<Rpc>Responseunless it returns an actual resource, andMfaEnrollmenthas nogoogle.api.resourceand noname— it is a response object, not a resource (the Alternatives section deliberately declines to model MFA as ausers/{email}/mfaFactors/{id}collection). Rename itStartMfaEnrollmentResponse, matchingLoginResponse/ExchangeTokenResponsein the same package.- Acronym casing:
MfavsMFA. Every acronym in the v1 protos is uppercase (OIDCIdentityProviderContext,LDAPIdentityProviderConfig,AIChatMessage), and the store side is alreadyMFAConfig.Mfa/EnableMfa/DisableMfawould be the only lowercase-acronym names in the tree. Recommendation is to uppercase toEnableMFA/DisableMFA/StartMFAEnrollment/MFAEnrollmentfor consistency; flagged as a deliberate call rather than silently drifting, since it touches every MFA-named symbol and the HTTP verbs (:enableMFA). RESETS_CREDENTIALonRequestReauthCodecontradicts 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 theREAUTHcode is deliberately not login-accepted. The enum comment inannotation.protomust be widened ("the secret a login or a credential change accepts") in the same change, or the reason is self-contradictory againstTestLintReasonsMatchTheClass.- The prose paraphrases of
MINTS_CREDENTIAL/TAKES_OVER_ACCOUNTdon't matchannotation.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, soStartMfaEnrollment/RegenerateRecoveryCodesfitMINTS_CREDENTIALonly 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/ConfirmRecoveryCodespair. 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.tsxalready 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.OtpSecretis non-empty,Loginchallenges 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 of this doc's own PR, which is whatemail_codecloses. - Reuse
ResetPassword's existing send/verify flow directly for MFA enrollment, instead of a newRequestReauthCodeand aREAUTHpurpose. 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 mistakeotp_codealready made once in the originalUpdateUser. 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
CredentialProofalternative — the doc's own starting point, for all four methods and then, briefly, forEnableMfaalone even after the others gotCredentialProof. 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'sMFAlockout kind,challengeMFACode/challengeRecoveryCode) already exists — and forEnableMfaspecifically, 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 keepsmfa_enabledon status-and-trigger double duty and the scratch fields onUser. 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 anauth_timeclaim Bytebase's access token doesn't carry (only a per-refreshIssuedAt, unrelated to when the user last typed a credential). - Grace window off token freshness. Rejected outright:
IssuedAtresets on ordinary hourly refresh, so this would wave a stolen, recently-refreshed token straight through. - Overload the existing
otp_codefield for re-authentication. Two different secrets (TempOtpSecretfor enrollment vs. the account's real credential) behind one field name is the ambiguity this bug already came from. - Keep password on
UpdateUserwith acurrent_passwordfield, as in this doc's own earlier draft. Once the proof became a three-wayCredentialProofrather than one string, it stopped reading as "one more field on a PATCH" and started reading as exactly the kind of dedicated, confirmed actionUpdateEmailalready 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, Auth0 multifactor delete, AWS IAM MFA devices, WorkOS MFA, Keycloak credentials |
| Start / finalize / withdraw enrollment lifecycle, proto-first API (closest architectural analog) | Google Identity Platform mfaEnrollment |
| 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, OWASP ASVS 3.7.1 |
| Current password required to disable your own second factor | GitLab |
| Enrolling/replacing a second factor gated the same as disabling it | Google 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; this repo's own UpdateEmail split from UpdateUser |
| Re-auth attempts bounded per identity, not a free-standing oracle | login-attempt-lockout.md (T9, this repo) |
| Admin-assisted recovery exempt from proving the credential being replaced | 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) |
Considered, not adopted — specifically GitHub's time-boxed session, not its factor-choice model (adopted above): GitHub sudo mode · RFC 9470 explained · Google Cloud console reauthentication · Okta account management policy.
Related: v1-api-audit-2026-08.md T10 ·
login-attempt-lockout.md (T9) ·
split-profile-self-service-vs-admin.md.