fix(doorkeeperrefreshtokens): keep one row per Doorkeeper refresh token
What does this MR do and why?
IAM keeps one row per Doorkeeper refresh token. Rails rewrites a legacy PBKDF2 hash to SHA-512 when the token is used, and the upsert was keyed on the hash, so the old row stayed live beside a revoked new one. Daniele reproduced it in https://gitlab.com/gitlab-org/gitlab/-/work_items/631544#note_4069906522.
UpsertDoorkeeperRefreshToken now conflicts on (owning_cell_id, source_id), the Rails token id, backed by a unique index; token_hash stays the primary key because redemption only has the token string. A SHA-512 event replaces a stored PBKDF2 hash, a PBKDF2 event never replaces a SHA-512 one, the first revoked_at wins, and an event naming another client writes nothing. The two-row state cannot arise, so there are no sibling rules and no race window. Shape agreed in the review thread (Shilpa's Option 1, !947 (comment 4090787670)).
The unique index is not built CONCURRENTLY, so this must deploy before Layers 1-3 (gitlab-org/gitlab#632073 (closed)) while the table is still empty. No flag.
Cases (Postgres and YugabyteDB)
| Case | Result |
|---|---|
| SHA-512 event for a row holding the PBKDF2 hash | hash replaced in place, state and binding kept |
SHA-512 event carrying revoked_at |
hash replaced, row revoked |
| Live PBKDF2 event after the rewrite | nothing changes |
| Revoked PBKDF2 event after the rewrite | SHA-512 row revoked at the event's revoked_at |
| Revoke before create, revoke after create | tombstone stands; first timestamp kept |
| Same event re-sent | unchanged |
| Event naming another client for a stored token id | nothing written, INVALID_ARGUMENT |
| Same signature under a new cell and token id (Org Mover) | nothing written, INVALID_ARGUMENT |
| Two first inserts of one token at the same moment (Postgres only) | one row; the loser retries once and takes the conflict arm |
| Client not replicated | nothing written, FAILED_PRECONDITION |
Known limitations
- Org Mover: a moved token keeps its signature and gets a new cell and id, so every event for it from the new cell, revocations included, is rejected with
INVALID_ARGUMENTand the old row stays live and redeemable until gitlab-org/gitlab#636148 revokes the organisation's tokens before the move and stops copying them. Nothing implements that yet; the rejection log carriesowning_cell_idandsource_id. - A batch upsert must deduplicate events per
(owning_cell_id, source_id)before the statement (ON CONFLICT DO UPDATE command cannot affect row a second time).
References
- Work item: https://gitlab.com/gitlab-org/gitlab/-/work_items/631544 (scoping: https://gitlab.com/gitlab-org/gitlab/-/work_items/631544#note_4070362960)
- Accepts the PBKDF2 shape this fix protects: !941 (merged)
- Org Mover follow-up: gitlab-org/gitlab#636148
Screenshots or screen recordings
None: a storage-side change.
How to set up and validate locally
Start IAM Auth per docs/iam-auth-local-setup.md with one replicated client, upsert a refresh token with a $pbkdf2-sha512$ signature, then upsert the same client_id, owning_cell_id and source_id with a SHA-512 signature and revoked_at, then SELECT token_hash, revoked_at FROM doorkeeper_refresh_tokens WHERE source_id = <source_id>: one row, the SHA-512 hash, the second event's revoked_at.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist.