v1.9.0: SuperTokens client login + refresh (and the bug that made every SuperTokens login impossible)

[NeverEndingCode]

Phase 5 of the SuperTokens migration: the client can now log in through SuperTokens and refresh its own session. Plan: docs/superpowers/plans/2026-08-08-v1.9-supertokens-client.md.

The headline is a bug, not a feature

Task 1 of the plan was "drive the login by hand against production dual, no code". It failed immediately, for both providers:

GET /auth/authorisationurl?thirdPartyId=github
400 {"message":"the provider github could not be found in the configuration"}

server/supertokens/init.js passed the OAuth providers to ThirdParty.init as signInUpFeature. The SDK reads signInAndUpFeature. That key is optional in its TypeInput and JavaScript does not reject unknown properties, so the provider list was discarded silently — no throw, no warning, no log. No SuperTokens login was possible on any v1.8 build.

Verified causally against a real SuperTokens core 12, same request, same core, both ways:

init.js says	result
signInUpFeature (v1.8)	400 {"message":"the provider github could not be found in the configuration"} — byte-for-byte production
signInAndUpFeature (v1.9)	200 {"status":"OK","urlWithQueryParams":"https://github.com/login/oauth/authorize?..."}

Why a whole release hid it:

• The boot log printed providers=github,discord in both runs — it logs what buildProviders() returned, not what the recipe received.
• v1.8 tested both halves and never the seam: that buildProviders() returns the right list, and that init refuses to start when the list is empty. Nothing asserted the list arrives.
• buildProviders' own "no OAuth provider configured" guard structurally cannot catch it — the list is non-empty, it just never lands.
• dual never exercised it, because the client logged in via passport. A quiet dual deployment was not evidence the path worked; it could not have been.

Same shape as the superTokensUserId capital-T bug from v1.8. The new test runs the config init.js actually passes through the SDK's own normaliser, so it fails on a wrong key and on a future SDK rename, rather than restating the fix.

The client work

• client/src/game/auth.js — the three-call flow, hand-rolled rather than supertokens-web-js, whose signOut() targets the /auth/signout v1.8 removed for clearing only half of a dual-stack session.
• GET /api/auth-info (public) — tells the client which stack to drive. It could not go on /api/config as the plan proposed: that route is behind requireAuth and the caller is by definition not logged in yet. One build therefore serves passport and supertokens alike, so the documented rollback keeps working.
• Session refresh — one shared in-flight promise. SuperTokens rotates the refresh token on use, so a refresh-per-401 would have calls 2..N present an already-spent token; the core reads that as token theft and revokes the session. A routine renewal becomes a forced logout, and only under concurrency.
• Cancelled logins, unconfigured providers and refused sign-ins each land back on the login screen with a readable message.

Testing

696 vitest (SQLite) / 722 (Postgres) / 49 smoke — up from 662 / 688 / 39.

Two tests were confirmed by mutation rather than inspection:

• Deleting the single-flight guard makes the concurrency test report 3 refreshes instead of 1. Its first version passed with the guard deleted — the stub keyed "already expired" off the URL, so only one of the three requests ever got a 401. The test now carries a comment recording that.
• Disabling the client's callback leg fails two smoke checks.

tests/e2e/smoke-v19.mjs drives the whole redirect round trip over the built client by pointing the stubbed authorisation URL back at the app's own callback, so no external service and no core are needed.

What this does NOT prove

POST /auth/signinup and the identity mapping have still never run against a real core — that needs a real OAuth round trip, so every automated test stubs it. Since the mapping decides whether a returning player lands on their own save or an empty one, do not skip to AUTH_MODE=supertokens.

Plan Task 1 Steps 2–3 and Task 4 Steps 1–2 remain open and are the operator's, on a deployed build. The four-step gate is written up in docs/authentication-methods.md Phase 5 and runbook D6:

1. Log in with the normal button (it now goes through SuperTokens).
2. signinup must return user.id equal to the existing users.id, not a UUID.
3. identities.supertokens_user_id must hold a real SuperTokens id, not our own.
4. shadow:check still 6/6 with no new identities.

Docs in five places that called supertokens mode unusable now say what is actually true, without claiming it is proven.

Order of operations

This was opened as a draft "until the gate has been run", which was circular — the gate needs a build carrying the fix, and that build only exists once this is merged and tagged. The gate gates AUTH_MODE=supertokens, not this merge.

1. Merge, then tag main (never the branch) — the tag push is what publishes to GHCR. Without it the Unraid box cannot get the fix.
2. Update the container. It stays on AUTH_MODE=dual; nothing about logins changes yet, because dual keeps accepting existing sessions either way.
3. Run the four-step gate above.
4. Only then consider AUTH_MODE=supertokens.

Merging is safe ahead of the gate: dual remains the resting state, legacy 90-day JWT cookies stay valid throughout, and rollback is still AUTH_MODE=passport + restart.

🤖 Generated with Claude Code