Expired account session recovery¶
Release status: The account recovery changes were merged in PR #85 and deployed. Isolated Cosmos-backed acceptance and live Google recovery passed, including a check that selecting a second account leaves the first account's puzzle progress isolated. Browser Back returned to the Account page from the provider picker. Production guest smoke checks passed. Recovery after a signed-in production session naturally expires remains pending.
See the journey verification record for the current scenario-to-test coverage matrix, latest browser/backend snapshot, and remaining manual checks.
The frontend presents sign-in and account-switch callback failures in a shared, accessible notice
from the root layout. It offers a plain retry link and retains the current page and non-auth query
parameters. /account leaves these errors to the shared notice to avoid duplicate messages or
clearing the return URL. The shared notice records one existing account_action event with fixed
intent, outcome, and reason values; it never includes URL or provider-supplied text. Other
account-management callback notices remain on their existing path.
Incident findings¶
A validly signed account-session cookie can outlive the session it represents. Historically, the browser proxy set a one-year cookie lifetime while the signed session payload remained valid for 30 days. After the payload expired, the browser still sent the cookie, account UI state could disagree across surfaces, and account-bound API calls failed with a missing-user-identity error. The one-year proxy lifetime is an earlier measured behavior, not the intended session lifetime.
Observed behavior included an account-settings view showing controls despite the feature flag hiding the account UI elsewhere. Some game reads still succeeded, while saved-play reads and writes failed; in another game, validation succeeded while player reads and autosaves failed without a visible message. Ordinary sign-in completed provider authentication but failed during the internal prepare request, with a generic backend error. The existing explicit account-switch prepare/commit flow succeeded and issued a fresh session for the canonical account.
Scope and recovery contract¶
The work records and reproduces the incident, then lets the ordinary /api/auth/start callback
recover an expired versioned session. After fresh OIDC verification, the callback uses the existing
account-lookup synthetic-source prepare/commit flow also used for explicit account switching. It
does not copy data from the expired account session.
- An expired cookie is not authorization for gameplay or account reads.
- Recovery restores the canonical account only after provider verification and successful prepare/commit. It does not demote the previous account to guest or merge guest data.
- Preserve the validated
returnTo, including puzzle-specific query parameters. - Cancellation or failure must not replace
userId; return an actionable error at the requested destination. - Existing guest sign-in and merge behavior remains unchanged. No general session system is added.
Session and recovery-cookie lifetime¶
- The authenticated
userIdsession remains valid for 30 days. The proxy must never slide or extend that identity beyond the signed payload'sExpiresAt; the browser's absolute deadline is unchanged by proxy requests. - The auth route handlers under
/api/auth/exclusively own writes to the authenticated cookie. The proxy must not overwrite a newer cookie written by an auth handler. - The current Step 4 marker is a separate signed, host-only
account_recoverycookie,HttpOnlyandSecurein production, with{purpose:"account-recovery",version:2,sessionExpiresAt,playerId}. It expires absolutely 30 days after that signed session'sExpiresAt.playerIdis retained only as an identity hint for the narrowly scoped recovery-eligibility check; it never authorizes normal features, account data, or gameplay. - Version 2 is a finite identity hint only. It cannot authorize normal API reads or writes, account
data, gameplay, or other feature targeting. The marker may be sent only to
GET /v1/account-recovery/eligibilityto determine whether the browser may targetAccountsUi; this endpoint grants no account or game access. The backend accepts proof from the original signed expired session cookie or the signed version 2 marker; it does not trust an arbitrary identity ID header. Older identity-free version 1 markers remain valid continuity hints but cannot target recovery without the original signed expired session cookie. Never infer or invent an identity for a v1 marker. A v1 marker alone cannot recover entitlement; wait for fresh sign-in or the original signed expired cookie. While a marker is valid, a missinguserIdmust not trigger automatic guest creation. Fresh sign-in can still perform account lookup after OIDC proof even when account UI is hidden. - A successful fresh sign-in replaces the marker for the new session. Explicit sign-out, account deletion, and session-deleted recovery clear it. A legacy expired signed cookie may bridge into a marker only through the remaining portion of the fixed 30-day window after that session's expiry. Once that window ends, the browser is indistinguishable from a new visitor; recovery recognition is not indefinite.
- Choosing Continue as a guest explicitly calls the existing sign-out endpoint to clear the marker and rotate to a new guest identity before navigating home. A failed request keeps the recovery view visible and offers a retry; navigating home alone does not discard recovery state.
- The guest cookie has a rolling one-year lifetime. When the proxy reissues it on a visit, it keeps the same guest player ID and restarts the countdown. If the cookie expires or is lost, guest stats remain stored, but the browser loses its link to them. Link a sign-in method while the guest cookie is available to make that account recoverable.
- Sign in again starts a new 30-day authenticated session after successful sign-in. Automatic renewal of authenticated sessions remains deferred.
Recovery restores account access only after fresh OIDC verification and successful prepare/commit; it
cannot reconstruct unsaved games without a valid matching browser draft or invent streak days.
Step 4 makes the home/menu Account link,
Settings Account section, and /account use the same AccountsUi decision. The server-only BFF
GET /api/auth/account-visibility carries the host-only marker and returns a boolean only. The same
decision gates /account/finish and /account/link-conflict. If AccountsUi is off, show no
Account section or sign-in controls and return 404 for those pages and /account;
ordinary guest-data deletion remains available through its existing independent controls. Eligible
normal users and guests continue through existing features. If the new backend eligibility endpoint
is unavailable before backend deployment, fail closed for expired-session recovery UI; normal active
and guest sessions continue through existing features. Eligibility or feature-lookup failures resolve
to false. Steps 1-6 are complete locally; game recovery and validation are recorded below.
Game progress recovery (Steps 5-6)¶
The game recovery contract applies to Letter Golf and Reverse Cross. It preserves only an explicitly bounded in-browser progress draft across fresh authentication; the draft is never proof of identity or authority to write.
- Both games distinguish an explicitly expired account session from network errors and a 404
missing puzzle/play. Show one Sign in again to save your progress action only when the
browser is eligible for
AccountsUi. The existingAuthReturnNoticecontinues to present callback errors safely. - A failed initial authoritative load blocks start, resume, autosave, and submission. Offer retry; enable writes only after a real retry fetch succeeds. Do not treat cached state or a local draft as a successful server load.
GET /api/auth/game-sessionexposes only a minimal cryptographically validated{status, playerId, canRecover}result. The ID may bind a local draft but never authorizes an API request. A signed current/expired session or a host-only signed recovery v2 marker can provide that identity. A v1 marker has no identity and therefore cannot bind an account draft.- Store progress drafts in browser local storage with a two-hour TTL after the last edit, at most eight drafts, and at most 32 KiB per draft. Bind each draft exactly to game, player, and puzzle; include only words or placements plus a server-base signature/revision. Never store cookies, tokens, score, timer, or a completed flag. If browser storage is blocked, retain progress in memory and do not promise durable recovery.
- After fresh authentication, load the authoritative server attempt first. A completed server result wins and clears its matching old draft. Never apply a draft to another account. If the server base changed, require explicit review or discard; never silently overwrite the server state. Late submit errors remain visible.
- Writes with a known draft owner carry
X-Expected-Player-Id. This is a constraint, never an authentication mechanism: the backend independently resolves its cookie identity and rejects a mismatch with409 account_changedbefore persistence. This also closes the race where another tab changes accounts after the browser's session check. Existing clients may omit the additive constraint; it never replaces their cookie authorization. - Letter Golf reports autosave and submission errors visibly. Reverse Cross replaces the restore/retry loop while preserving its server board-revision, timing, and conflict flow; a draft cannot invent or backdate duration. If a pause was not acknowledged before expiry, time continues according to the server state; recovery never subtracts time spent signing in. The return URL pins the original Daily puzzle key across Pacific midnight. It must not silently fetch a new date. A fresh visit without a puzzle key selects today's puzzle.
- Preserve the existing backend Daily policy: the exact original global puzzle key/date controls eligibility and streaks, and the server records the actual completion instant. A late validated submission for its original puzzle date is allowed. An older out-of-order completion does not rewind a newer streak; sequential late completions may advance the existing streak. Never backdate timestamps, synthesize wins, void a future Daily, or move a draft between dates.
- Completed Daily state remains immutable. First-persist compare-and-set creation prevents the Letter Golf upsert race from producing duplicate eligible completions per account and puzzle. Stats updating remains best effort after persistence: a retry cannot duplicate a completion but does not guarantee repair of a missed stats update.
Steps 5-6 are complete locally. Release is additive and backend-first, with a stable 401 error code for expired sessions. Rollback leaves the additive API unused by older clients and does not require data migration. See the implementation plan and platform roadmap.
Historical local verification record (Steps 1-2)¶
These counts and results are from the earlier Step 1-2 validation and do not represent final Step 3 validation.
- New callback regressions exposed six failures before the recovery change. After the fix, all 47 callback and session-cookie tests passed, including ordinary start/callback recovery, guest progress decisions, changed browser identity, failed OIDC verification, provider errors, backend prepare/commit failures, and refusal of unexpected merge decisions.
- The full frontend unit/component suite passed: 873 tests across 95 files.
- Related backend endpoint and cookie suites passed: 61 tests. Three focused regressions reject expired signed cookies for account reads, Letter Golf saved-play reads/autosaves, and Reverse Cross saved-play reads/starts without creating records. Touched endpoint fixtures use the existing in-memory account-deletion store so revocation checks cannot contact live Cosmos.
- A browser check of the actionable sign-in return notice passed in desktop Chromium and the Android-sized Chromium project. The retry retains the intended page and non-auth query values.
- Frontend ESLint, TypeScript checking, the production frontend build, backend format verification
with
--no-restore, Markdown lint, and Git whitespace checks passed.
Normal .NET restore fails because transitive System.Security.Cryptography.Pkcs and
System.Security.Cryptography.Xml version 10.0.10 have known advisories, which the repository treats
as errors. Initial local test assets were restored with a command-only NuGetAudit=false; the
backend commit hook was subsequently run with command-only WarningsNotAsErrors=NU1902;NU1903,
retaining audit reporting while allowing the formatter to run. No dependency version, audit
configuration, or CI policy was changed. A normal clean restore/CI run is not claimed to pass; the
dependency issue must be addressed separately before release. npm ci also reported existing
dependency advisories; dependency upgrades are outside this recovery change.
Local verification record (Step 3)¶
- The full frontend unit/component suite passed: 885 tests across 96 files. Coverage includes fixed proxy deadlines, legacy expired-cookie migration, marker tampering and expiry, marker-only fresh account lookup, explicit guest rotation, and sign-out/recovery clearing.
- A real-browser cookie lifecycle test passed in desktop Chromium and Android-sized Chromium. It starts with a synthetic overlong browser cookie, checks the corrected signed deadline, removes the authentication cookie to simulate browser expiry, confirms repeated navigation retains the same marker without creating a guest, and verifies explicit sign-out clears it.
- Frontend ESLint, production build with TypeScript checking, repository Markdown lint, and Git whitespace checks passed. No backend code or infrastructure changed in this step.
Local verification record (Step 4)¶
- The full frontend suite passed: 902 tests across 99 files. A regression for expired sessions
with
AccountsUioff was also checked against the old rendering conditions: it failed there and passed with the fix. Page tests ensure hidden Account routes stop before private reads and entitled expired sessions render recovery without fetching account data. - All six browser cases passed across desktop and Android-sized Chromium: entitled and ineligible expired sessions have consistent home-menu, Account-page, and Settings visibility; the prior cookie-lifetime checks still pass. Existing navigation-dialog accessibility and brand-image warnings are outside this visibility change; these runs are not a clean-console claim.
- The focused backend suite passed 51 tests covering recovery eligibility, ordinary identity
resolution, revocation, session decoding, and expired account/game persistence boundaries.
Real feature targeting admits the expired identity only in the scoped check; ordinary
/v1/featuresdoes not acquire that identity. The new HTTP fixture uses the existing in-memory revocation store rather than a real Cosmos adapter. - ESLint, the production frontend build with TypeScript checking, Markdown lint, backend
formatting verification for the three changed C# files, and Git whitespace checks passed.
Backend checks used existing restored assets with
--no-restore; the dependency advisory limitation above remains. No cloud configuration, feature audience, or infrastructure changed.
Local verification record (Steps 5-6)¶
- Full frontend validation passed 932 tests across 103 files with four Vitest workers. Focused follow-up checks cover the final Letter Golf pending-result message and Reverse Cross actor binding. An earlier unconstrained run alongside builds timed out in an unchanged menu test; no timeout or assertion was weakened, and the complete bounded-worker run passed.
- The affected backend endpoint, cookie, revocation, group, and practice/debug suites passed
113 tests in Release with
--no-restore. Stale-first-read regressions verify that a concurrent completed play cannot be overwritten by autosave and that retried completion cannot count twice. Expected-player mismatches stop before storage. HTTP fixtures use in-memory revocation stores. - Twenty desktop/mobile browser checks passed: both expired-session actions, same-account draft recovery, different-account isolation, ordinary Letter Golf Daily/Practice completion, and Reverse Cross save/reload/completion, revision conflict, pause/resume and visibility recovery. These browser tests use a local API fixture; live provider sign-in remains a deployment check.
- ESLint, TypeScript, the production frontend build, Markdown lint, backend format verification and commit hooks passed. Existing NuGet advisories still limit a normal clean backend restore; no dependency, audit policy, cloud resource, or feature audience changed.
Manual validation after deployment¶
- Reproduce an expired, validly signed versioned account cookie and confirm it is rejected for gameplay and account reads before recovery.
- Complete ordinary sign-in for that account; verify OIDC-verified callback prepare/commit restores the canonical account with a fresh session and does not copy stale account data.
- Start recovery from a puzzle URL with puzzle query parameters; verify the complete
returnTosurvives successful recovery. - Cancel provider sign-in and simulate prepare/commit failure; verify neither case replaces
userIdand the return destination shows an actionable error. - Verify a previous account is never changed into a guest, and guest sign-in/merge behavior is unchanged.
- Verify the existing explicit account-switch prepare/commit flow still succeeds.
- Confirm the browser's authenticated cookie deadline matches its signed expiry and requests do not extend it. After that cookie disappears, confirm the bounded marker retains recovery state; choosing Continue as a guest explicitly clears it and creates a new guest identity.
- Confirm recovered sessions can read and save account data, while recovery does not claim to reconstruct games without a valid matching draft or fabricate missed streak days.
- With
AccountsUioff, verify home/game menus and Settings show no Account controls and direct Account routes return 404. With an entitled expired session or v2 marker, verify those surfaces offer recovery while account/game data remain unavailable until fresh sign-in. - Expire a session with unsaved moves in each game, sign in as the same account, and verify authoritative loading and bounded draft recovery. Repeat with a different account and confirm no draft or pending write transfers. Check cancelled sign-in and blocked browser storage.
- Cross Pacific midnight during recovery: retain the original puzzle key and server timing, preserve an already completed attempt, and open today's Daily only through explicit navigation.
See the account identity UX implementation plan Phase 4 and the platform roadmap for status and follow-up scope.