fix(auth): widen fresh-session retry budget for Zitadel read-after-write lag

The post-register /authorize handback can transiently 404 on getSession when
the read lands on a replica that has not caught up with the just-written
session. A single 350ms retry lost that race intermittently (staging logs
showed signup.created immediately followed by session_stale, bouncing fresh
signups to /login).

Replace the single retry with a bounded increasing-backoff poll
(RETRY_BACKOFFS_MS = [300, 500, 800, 1200], ~2.8s max), scoped exactly as
before: fresh entries only (signed creationTs within RETRY_FRESHNESS_WINDOW_MS),
dead-code probes only, stopping the instant a probe comes back alive. An
old/stale/forged entry still self-heals immediately on the first dead response —
the anti-forgery guarantee is unchanged; the retry only adds patience for a
session we know we just created.

Adds a 'throw-times' fake-provider seam + a multi-retry regression test proving
the loop keeps polling past the first attempt.

Author: yahyafakhroji

app/modules/auth/providers/fake/fake-provider.ts

@@ -37,10 +37,15 @@ import { ProviderError } from '@/modules/auth/types';
 // entry is deleted) so every subsequent call falls through to the real in-memory session lookup
 // — i.e. "fail once, then behave normally," which is exactly what a transient replica-lag 404
 // followed by a successful retry looks like.
+//
+// 'throw-times' generalises that to N consecutive throws before falling through — it drives the
+// BOUNDED-backoff-loop test (a replica that lags more than one read cycle), proving the retry
+// keeps polling past the first attempt rather than giving up after one.
 type FakeOutcomeScript =
   | { mode: 'null' }
   | { mode: 'throw'; code: ProviderErrorCode }
-  | { mode: 'throw-once'; code: ProviderErrorCode };
+  | { mode: 'throw-once'; code: ProviderErrorCode }
+  | { mode: 'throw-times'; code: ProviderErrorCode; times: number };
 
 export const FIXED_NOW = '2026-01-01T00:00:00.000Z'; // deterministic for tests (no Date.now())
 // Factor verifiedAt is `Date | null`. A frozen Date keeps the fake deterministic.
@@ -383,6 +388,17 @@ export class FakeAuthProvider implements AuthProvider {
         this.sessionResults.delete(id);
         throw new ProviderError(scripted.code, `scripted getSession ${scripted.code} (once)`);
       }
+      if (scripted.mode === 'throw-times') {
+        // Throw for the next `times` calls, decrementing each time; on the last one consume the
+        // script so the following call falls through to the real lookup. Immutable update: re-set
+        // a decremented copy rather than mutating the stored script object.
+        if (scripted.times <= 1) this.sessionResults.delete(id);
+        else this.sessionResults.set(id, { ...scripted, times: scripted.times - 1 });
+        throw new ProviderError(
+          scripted.code,
+          `scripted getSession ${scripted.code} (${scripted.times} left)`
+        );
+      }
       throw new ProviderError(scripted.code, `scripted getSession ${scripted.code}`);
     }
     const s = this.sessions.get(id);

app/resources/authorize/authorize.service.ts

@@ -65,10 +65,15 @@ const DEAD_SESSION_CODES: ReadonlySet<ProviderError['code']> = new Set([
 //     itself a retry. This preserves the existing anti-forgery guarantee: a stale post-logout
 //     cookie (or a genuinely forged sessionId) still self-heals to /login on the FIRST dead
 //     response, with zero added latency or leniency.
-//   • It retries AT MOST ONCE. If the retry still comes back dead (or errors again), the
-//     function falls through to the exact same self-heal path as if there had been no retry.
+//   • It retries a BOUNDED number of times (RETRY_BACKOFFS_MS, ~2.8s total max), stopping early
+//     the moment a probe comes back alive or non-dead. If every attempt still comes back dead (or
+//     errors), the function falls through to the exact same self-heal path as if there had been no
+//     retry — the retry only ever *adds* patience for a fresh session, never leniency.
 const RETRY_FRESHNESS_WINDOW_MS = 5000; // 5s — covers redirect latency + replica lag, nothing more
-const RETRY_BACKOFF_MS = 350; // short pause before the single retry attempt
+// Increasing backoffs between fresh-session liveness re-probes (~2.8s total max). A single short
+// retry loses the race when a replica lags >1 read cycle; a bounded poll rides out the write→read
+// replication for a session we KNOW we just created. Only ever applied to a fresh entry.
+const RETRY_BACKOFFS_MS = [300, 500, 800, 1200] as const;
 
 /** True when `entry` was created within RETRY_FRESHNESS_WINDOW_MS of `nowMs`. A malformed or
  *  missing creationTs (tsMs → NaN) is treated as NOT fresh — the safe default is the original,
@@ -232,7 +237,8 @@ function errorRedirect(url: URL, code: AuthErrorCode): Response {
  *     and never mistaken for a genuine error. (The post-logout stale-cookie case.)
  *
  *     EXCEPT: a DEAD_SESSION_CODES code on a FRESH entry (isFreshEntry — see the retry block
- *     above) gets ONE retry, after a short backoff, before this self-heal fires — see the
+ *     above) is re-probed with a BOUNDED increasing backoff (RETRY_BACKOFFS_MS, ~2.8s total max),
+ *     stopping the instant it comes back alive, before this self-heal fires — see the
  *     RETRY_FRESHNESS_WINDOW_MS comment for the full scoping rationale (Zitadel read-after-write
  *     lag on a session THIS request just created). An old/stale/forged entry skips the retry
  *     entirely and self-heals immediately, exactly as before.
@@ -260,13 +266,18 @@ async function healIfSessionDead(
 ): Promise<AuthorizeOutcome | { session: Session }> {
   let probe = await probeSession(provider, entry);
 
-  // RETRY-ON-FRESH: see the RETRY_FRESHNESS_WINDOW_MS block above for the full scoping
-  // rationale. Bounded to exactly one retry, and ONLY for a dead-code result on a genuinely
-  // fresh cookie entry — every other case (already alive, confirmed-null, transient error, or a
-  // dead code on an old/stale/forged entry) falls straight through to the original behavior.
-  if (probe.kind === 'dead-code' && isFreshEntry(entry, nowMs)) {
-    await sleep(RETRY_BACKOFF_MS);
-    probe = await probeSession(provider, entry);
+  // RETRY-ON-FRESH: see the RETRY_FRESHNESS_WINDOW_MS block above for the full scoping rationale.
+  // Zitadel's read-after-write lag on a session THIS request just created can exceed a single
+  // retry, so poll with increasing backoff (RETRY_BACKOFFS_MS, ~2.8s total max) — but ONLY while
+  // the entry is genuinely fresh (isFreshEntry, signed creationTs) AND the probe is still a dead
+  // code. Every other case (already alive, confirmed-null, transient error, or a dead code on an
+  // old/stale/forged entry) falls straight through to the original behavior with no wait.
+  if (isFreshEntry(entry, nowMs)) {
+    for (const backoff of RETRY_BACKOFFS_MS) {
+      if (probe.kind !== 'dead-code') break;
+      await sleep(backoff);
+      probe = await probeSession(provider, entry);
+    }
   }
 
   switch (probe.kind) {

cypress/component/resources/authorize/logout.cy.ts

@@ -69,9 +69,9 @@ describe('/authorize — stale-cookie self-heal (validate before reuse)', () =>
 // Read-after-write retry (Zitadel eventual consistency): a session THIS request just created
 // (the post-register /authorize handback is the concrete case) can transiently 404 on getSession
 // if the read lands on a replica that hasn't caught up with the write yet. healIfSessionDead
-// retries exactly once — but ONLY when the cookie entry's creationTs is fresh — before treating
-// a dead code as ground truth. See authorize.service.ts's RETRY_FRESHNESS_WINDOW_MS block for
-// the full scoping rationale.
+// re-probes with a bounded increasing backoff (stopping the instant it comes back alive) — but
+// ONLY when the cookie entry's creationTs is fresh — before treating a dead code as ground truth.
+// See authorize.service.ts's RETRY_FRESHNESS_WINDOW_MS block for the full scoping rationale.
 describe('/authorize — read-after-write retry on a freshly-created session (NOT_FOUND)', () => {
   const NOW_MS = Date.parse('2026-06-24T12:00:00.000Z');
 
@@ -109,6 +109,40 @@ describe('/authorize — read-after-write retry on a freshly-created session (NO
     });
   });
 
+  it('FRESH session lagging MORE than one read cycle: NOT_FOUND twice then alive → the bounded backoff loop keeps polling and finalizes (no self-heal)', () => {
+    callService({
+      fn: 'resolveAuthorize',
+      provider: 'singleton',
+      // Throws NOT_FOUND for the first TWO getSession calls (the initial probe + the first retry),
+      // then falls through to this live session on the third — a replica that lags past a single
+      // retry. Proves healIfSessionDead's loop keeps going instead of giving up after one attempt.
+      liveSessions: [{ id: 'fresh-race-2', token: 'tok-fresh-race-2' }],
+      sessionResults: {
+        'fresh-race-2': { mode: 'throw-times', code: 'NOT_FOUND', times: 2 },
+      },
+      nowMs: NOW_MS,
+      request: {
+        url: `http://localhost/id/authorize?requestId=oidc_${RAW_ID}&sessionId=fresh-race-2`,
+        sessions: [
+          {
+            id: 'fresh-race-2',
+            token: 'tok-fresh-race-2',
+            loginName: 'alice@acme.test',
+            // 2s old — inside the retry window.
+            creationTs: new Date(NOW_MS - 2000).toISOString(),
+          },
+        ],
+      },
+    }).then((v) => {
+      expect(v.response?.status).to.equal(302);
+      const loc = v.response?.location ?? '';
+      expect(loc).to.include('client.acme.test/callback');
+      expect(loc).to.include(`code=fake_${RAW_ID}_fresh-race-2`);
+      expect(loc).to.not.include('/login');
+      expect(v.audit.some((e) => e.event === 'session_stale')).to.equal(false);
+    });
+  });
+
   it('OLD session (creationTs outside the retry window): NOT_FOUND self-heals immediately — no retry, anti-forgery preserved', () => {
     callService({
       fn: 'resolveAuthorize',

cypress/support/node/scenario.ts

@@ -260,7 +260,10 @@ export type SessionResultScript =
   | { mode: 'throw'; code: ProviderErrorCode }
   // Fails the FIRST getSession call for that id, then falls through to the real fake behavior —
   // drives the healIfSessionDead read-after-write retry tests ("fail once, then succeed").
-  | { mode: 'throw-once'; code: ProviderErrorCode };
+  | { mode: 'throw-once'; code: ProviderErrorCode }
+  // Fails the next `times` getSession calls, then falls through — drives the bounded-backoff-loop
+  // test where a replica lags more than one read cycle ("fail N times, then succeed").
+  | { mode: 'throw-times'; code: ProviderErrorCode; times: number };
 export type CallbackResultScript = { mode: 'throw'; code: ProviderErrorCode };
 
 export interface Scenario {