v1.8: SuperTokens behind an AUTH_MODE switch (WIP — tasks 1-2 of 7)

[NeverEndingCode]

Status: in progress — safe to deploy, not yet ready to roll out

v1.8 introduces SuperTokens as an alternative login stack behind a strangler switch. Tasks 1–2 of 7 are complete. The switch exists, SuperTokens can be brought up behind it, and the default is still the legacy stack — so this branch is safe to deploy today and changes nothing until an operator opts in.

Task	State
1. AUTH_MODE switch + containment	✅ complete
2. SuperTokens init + provider config	✅ complete
3. Identity mapping (signInUp override)	⬜ not started
4. Auth middleware chain	⬜ not started
5. Shadow-mode verification gate	⬜ not started
6. OAuth callback URL changes	📄 documented, applies before cutover
7. Deployment config + release	⬜ not started

Documents

• Plan: docs/superpowers/plans/2026-08-06-v1.8-supertokens.md — new; no v1.8 plan existed, only the design
• Design: docs/superpowers/specs/2026-08-01-postgres-supertokens-design.md §5
• Operator runbook: docs/supertokens-rollout-runbook.md — new, honest about what is and isn't built

Sequencing precondition, stated plainly

The design gates v1.8 on v1.7 being confirmed in production. v1.7 is tagged and published, but the Unraid cutover to Postgres has not happened, and the production export §5.5 depends on has not been supplied.

That gates two specific things — running shadow mode against real identities, and cutting over to AUTH_MODE=dual. It does not gate building, because AUTH_MODE defaults to passport and every task is inert until an operator changes it. Nothing in this release claims to be verified against production data.

What Task 1 ships

server/authMode.js resolves AUTH_MODE to passport (default), dual, or supertokens. Two decisions worth reviewing:

Blank means passport, but a typo throws. Blanking the field in the Unraid UI is the documented rollback, so it must not error. But an unrecognised value stops the container at boot rather than falling back — AUTH_MODE=supertoken that quietly served the legacy stack would be indistinguishable from a finished rollout, and would surface weeks later from the wrong symptom. Matching is case-sensitive for the same reason, with the error naming the likely intent.

${AUTH_MODE-passport} in compose, deliberately not the colon form. Per the v1.7 finding, ${VAR:-default} treats an explicitly empty value as unset and substitutes the default right back — which would defeat the documented rollback.

Documented in all four places an operator can set it: .env.example, README.md, unraid-template.xml (Display="advanced"), docker-compose.yml.

The OAuth change, written early on purpose

Part A of the runbook is complete even though it belongs to Task 6, because it is pure documentation, fully knowable now, and must be applied before any cutover — days early is fine.

SuperTokens uses /auth/callback/<provider>; RackStack uses /auth/<provider>/callback. GitHub requires a redirect path to be a subdirectory of the registered callback URL, and /auth/callback/github is not a subdirectory of /auth/github/callback. Left alone, every SuperTokens GitHub login fails with a redirect_uri mismatch while passport logins keep working — which reads as "SuperTokens is broken" rather than "the OAuth app needs one field widened."

The fix widens the GitHub registration to /auth, so both paths qualify. It is additive and reversible; nothing is removed and passport works throughout.

A design claim corrected

The design warns that postgres:// is rejected. v1.7 disproved that for RackStack's own DATABASE_URL — pg-connection-string parses both schemes identically, verified directly. The SuperTokens core is a different component and genuinely does reject it, so the plan and runbook scope the warning there instead of restating the debunked general claim.

How existing Discord and GitHub logins carry over

Documented in full in the runbook, since it's the part that decides whether a returning player finds their save or a blank one. In short: nothing about a player's account changes. users.id stays the literal provider:providerId string; SuperTokens issues its own internal id and RackStack maps it onto the existing one, so session.getUserId() returns github:37058311 exactly as the old JWT did. No save is rewritten, no id renumbered, no foreign key moves. Nobody is asked to re-link or re-authorise, and there is no "migrate your account" screen because there is nothing for a player to do.

Discord and GitHub remain separate accounts with separate saves, as they always have. Account linking stays out of scope (design §7).

A design assumption, now verified

Spec §5.5 called "SuperTokens' thirdPartyUserId equals passport's profile.id" load-bearing and unverified. It is now verified at source level against the pinned versions:

• GitHub — SuperTokens sets thirdPartyUserId = `${user.id}`; passport-github2 sets profile.id = String(json.id). Same field, same stringification.
• Discord — SuperTokens maps userInfoMap.fromUserInfoAPI.userId to id; passport-discord passes Discord's raw JSON through, so profile.id is that same id.

This raises confidence and does not retire the shadow gate — what matters is the values already in your identities rows, which may predate these library versions. Recorded in the spec.

npm audit: 2 high, assessed and accepted

Both trace to nodemailer via supertokens-node. No patched 8.x exists, and npm's suggested remediation is downgrading supertokens-node from 24 to 9.2.3 — a major downgrade, not a fix.

The vulnerable surface is the message-level raw option, reachable only when sending email. nodemailer is referenced only under recipe/{emailverification,emailpassword,passwordless,webauthn}/emaildelivery/services/smtp — verified by grepping the installed package. This release initialises ThirdParty and Session only, so none of those services is ever constructed and no email is ever sent. Unreachable in this configuration; revisit if an email-bearing recipe is ever added.

Verification

npm run test:all green on both backends:

• SQLite: 526 passed, 26 skipped
• Postgres: 549 passed, 3 skipped

All six e2e smoke suites pass (39 assertions, zero errors).

Real boots in both modes, which is what proves the conditional mount rather than assuming it:

Mode	GET /auth/authorisationurl?thirdPartyId=github
passport	200 text/html — the SPA fallback; nothing handles /auth/*
dual	400 application/json — SuperTokens' middleware answering

A gap I found in my own work: the first Task 2 commit claimed the Node 20 engine check passed, but no test ever imported the SDK — the containment tests run in passport mode and every config-error test throws before the dynamic import. The suite would have been green on a runtime where supertokens-node couldn't load at all, which is exactly how v1.7 shipped four commits of silently-red CI. Closed with tests that actually import the SDK, both recipes, and the express bindings; CI runs Node 20, so that check now means something.

Not verified: a live SuperTokens core — the image pull hit a Docker Hub rate limit on this machine.

🤖 Generated with Claude Code

https://claude.ai/code/session_011JYNx69xztWN2qDLe5m1aS