Provider linking: Steam associate flow + connect/disconnect settings UI

[amrtgaber]

The API now supports bidirectional account linking via a unified provider registry — landed in ag-tech-group/criticalbit-auth-api#40. The frontend needs three pieces of work to expose this to users.

New API surface

Method	Path	Notes
GET	/auth/{provider}/associate/authorize	Authenticated. Starts the link flow. In dev returns {authorization_url} JSON; in prod 302s. Provider can be google or steam (Twitch / Battle.net / YouTube when those land).
GET	/auth/{provider}/associate/callback	Authenticated. Finishes the link. 302 to /callback/{provider}-associate-complete on success. 409 with {detail: {code: "oauth_account_already_linked"}} if the identity is already on another account.
GET	/auth/me/connections	Returns [{provider, account_id, account_email}] — what to render on the settings page.

What the frontend needs

1. New /callback/{provider}-associate-complete landing page

After a successful associate-callback the API redirects here. The page should:

• Confirm the link succeeded (likely via GET /auth/me/connections and showing the new entry).
• Return the user to the settings/profile page.

2. New /callback/steam page handling associate (in dev)

In dev mode the API points Steam's openid.return_to at ${FRONTEND_URL}/callback/steam — the same URL used for login. The frontend page already forwards login callbacks to the API; it now needs to ALSO forward associate callbacks. The way to tell them apart: decode the state JWT (no signature verification needed, just base64) and check the purpose field — "login" vs "associate". Forward to /auth/steam/callback or /auth/steam/associate/callback respectively. Same logic for Google's /callback/google.

3. "Connections" section on the account settings page

• Call GET /auth/me/connections to see what's linked.
• Show a "Connect Google" / "Connect Steam" button for each provider not in the list.
• Show "Connected as <account_email>" (or <account_id> for Steam) for each provider in the list.
• (Future PR 3) "Disconnect" buttons — coming when the API ships DELETE /auth/me/connections/{provider}.

Error handling for the merge-refusal case

The associate-callback can return:

• 409 oauth_account_already_linked — surface the existing message: "This <Provider> account is already linked to another criticalbit account. Unlink it there first." Don't auto-retry.
• 400 oauth_state_invalid / oauth_state_expired / oauth_csrf_mismatch — session got stale; tell the user to retry. The "expired" case is the common one (state TTL is 1h).
• 400 oauth_state_user_mismatch — should not happen in normal flow; signals tampering. Surface generically and log.
• 400 oauth_verify_failed — provider rejected the response (e.g., Steam OpenID assertion failed). Generic retry.

Order of operations

You can ship the connections UI first (item 3, read-only listing) without items 1 and 2. The link flow itself is item 1 + 2 together — both are needed to complete an associate round-trip.

Related

• This issue replaces the manual "link Google" feature that's been live since before this refactor. The Google associate URL stays at /auth/google/associate/authorize — same path as before — so any existing frontend code targeting it should still work.
• Disconnect UX waits on PR 3 (API DELETE endpoint + User.has_usable_password column to enforce "must keep at least one login method").

[amrtgaber]

PR 3 just landed — ag-tech-group/criticalbit-auth-api#41. The disconnect side of this issue is now fully unblocked.

New API surface (in addition to what was already in this issue)

Method	Path	Notes
DELETE	/auth/me/connections/{provider}	204 success, 404 if not linked, 409 if it would strand the user.
GET	/auth/me	Now includes has_usable_password: bool.

What to build on the frontend

Connections section on settings page (updated)

The "Disconnect" button should be enabled only when removing the connection leaves the user with another way in. Compute it client-side from:

const remainingAfterUnlink = connections.length - 1
const hasPasswordLogin = user.has_usable_password && user.email
const canUnlink = remainingAfterUnlink > 0 || hasPasswordLogin

If canUnlink === false, render the button disabled with a tooltip like "You'd have no way to sign in. Set a password first or link another provider." — this avoids the user hitting the 409 to learn they can't.

Handle the 409 response

If the disabled-button check is skipped somehow (race condition, refreshed /auth/me mid-flow, etc.), the DELETE call can return 409. The response body shape:

{
  "detail": {
    "code": "unlink_would_strand_user",
    "message": "Disconnecting this account would leave you with no way to sign in. set a password via /auth/forgot-password first.",
    "provider": "google",
    "remediation": ["set a password via /auth/forgot-password first"]
  }
}

Render remediation as a list. Items contain hints we generate server-side; the frontend can match patterns:

• "set a password" → link to /forgot-password.
• "link another provider" → link to a settings section showing Connect buttons.
• "link an account that provides an email" → same as above but emphasize Google (Steam-only users without email hit this).

Handle the 404

If the user clicks Disconnect on a provider they're not actually linked to (stale UI), the response is:

{
  "detail": {
    "code": "connection_not_found",
    "message": "You don't have a google account linked.",
    "provider": "google"
  }
}

Surface generically and refresh /auth/me/connections to re-sync state.

"Set a password" entry point for OAuth-first users

A user who came in via Google or Steam OAuth has has_usable_password: false and can't disconnect their only OAuth. They need a way to claim a password without knowing an existing one — the standard /auth/forgot-password → /auth/reset-password flow works for this: the API will email them a token, they pick a new password, and has_usable_password flips to True.

Two UX nits worth considering:

1. The "Set a password" button on settings could prefill the forgot-password flow with the user's existing email so they don't have to retype it.
2. After a successful set-password from this entry point, refresh /auth/me and unlock the Disconnect buttons.

Status

Backend feature	Status
Email verification (auto on register, takeover-vector closed)	✅ shipped in auth-api#39
Bidirectional account linking (registry, connections endpoint)	✅ shipped in auth-api#40
Unlink endpoint with safety rule	✅ shipped in auth-api#41

The API side of the original "let users connect accounts" request is now complete. The frontend work in this issue is the last piece.

[amrtgaber]

Frontend portion shipped in #41 (Connect flow + callback purpose dispatch) and #42 (Disconnect + stranding guard + Set-a-password CTA). API counterparts already shipped in ag-tech-group/criticalbit-auth-api#40 and #41.