Stage 4: real OAuth locally, over a tunnel - #21
Merged
Conversation
Stage 4, documentation only. The seeded cookie from Stage 3 covers most dev
work; this covers the case it cannot — changing the login or character-link
flows themselves, which needs the real providers to redirect back to your
machine.
Every concrete claim was verified against the code rather than described from
memory:
- Redirect URIs are string-concatenated, not URL-joined, so a trailing slash
on APP_BASE_URL yields `//auth/eve/callback` and z.string().url() accepts it
silently — it surfaces much later as an unexplained redirect mismatch.
- One EVE entry covers both flows: /auth/eve/login and /auth/eve/link both
call buildEveAuthorizeUrl, so they share /auth/eve/callback.
- EVE sends redirect_uri only on authorize; exchangeEveCode sends grant_type,
code and code_verifier. Discord sends it TWICE — authorize and token
exchange — and they must match. Changing APP_BASE_URL mid-flow therefore
breaks Discord linking while EVE login keeps working, which reads like a
Discord outage and is not.
- Once APP_BASE_URL is https the session cookie is issued Secure, so the
browser will not return it over http://localhost — you appear logged out no
matter how often you log in. Browse the tunnel origin.
Recommends .env.local for the override: it wins over .env, .env* is gitignored
apart from .env.example, and switching back is deleting one file.
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
guarzo
added a commit
that referenced
this pull request
Aug 3, 2026
Stage 4, documentation only. The seeded cookie from Stage 3 covers most dev
work; this covers the case it cannot — changing the login or character-link
flows themselves, which needs the real providers to redirect back to your
machine.
Every concrete claim was verified against the code rather than described from
memory:
- Redirect URIs are string-concatenated, not URL-joined, so a trailing slash
on APP_BASE_URL yields `//auth/eve/callback` and z.string().url() accepts it
silently — it surfaces much later as an unexplained redirect mismatch.
- One EVE entry covers both flows: /auth/eve/login and /auth/eve/link both
call buildEveAuthorizeUrl, so they share /auth/eve/callback.
- EVE sends redirect_uri only on authorize; exchangeEveCode sends grant_type,
code and code_verifier. Discord sends it TWICE — authorize and token
exchange — and they must match. Changing APP_BASE_URL mid-flow therefore
breaks Discord linking while EVE login keeps working, which reads like a
Discord outage and is not.
- Once APP_BASE_URL is https the session cookie is issued Secure, so the
browser will not return it over http://localhost — you appear logged out no
matter how often you log in. Browse the tunnel origin.
Recommends .env.local for the override: it wins over .env, .env* is gitignored
apart from .env.example, and switching back is deleting one file.
guarzo
added a commit
that referenced
this pull request
Aug 3, 2026
* feat: dev seed script with paste-able session cookies EVE SSO rejects the fake client id in .env.example, so there was no way to browse a running dev app as a real account — least of all an admin. The seeding machinery existed but was e2e-only: pinned to the test database and port 3111, and insert-only, because e2e gets a truncated database before every test and never had to survive a second run. npm run db:seed upsert; safe to re-run npm run db:seed -- --reset TRUNCATE first, for a clean slate Seeds six accounts — an admin with two alts, a flygd member with an alt, blue, green, plus cryo and tier_locked so the admin pages have those states to render — and prints a session cookie for each. IDEMPOTENT BY DEFAULT, which is the whole design. Character ids are fixed (a reserved 91_000_0xx block, clear of e2e's 90_000_0xx counter so the two can never collide) and every row is upserted, so a second run converges instead of dying on a duplicate primary key. The account and its main character are upserted in ONE transaction because account_main_character_fk is DEFERRABLE INITIALLY DEFERRED and only checked at commit. Both paths write rows — --reset destructively, the default by adding fixture accounts — and a dev seed has no legitimate remote use, so the script refuses any DATABASE_URL that is not provably loopback. ALLOW_REMOTE_SEED=1 overrides. The host is lower-cased first: `postgres:` is a NON-SPECIAL URL scheme, so WHATWG preserves host case (`http:` would not), and without that postgres://LOCALHOST/... is refused — which would train developers to reach for the override to work around a false rejection. Deliberately NOT shared with e2e/helpers.ts or tests/helpers/seed.ts. The repo already runs two independent seed helpers with different contracts; this is a third. Unifying them would need one helper parameterised for insert-only AND upsert, which costs more than the ~20 duplicated lines and puts the e2e suite at risk to make dev nicer. The session hashing is NOT duplicated — createSession from src/services/session.ts is the real one. Also removes a duplicate "engines" key in package.json: main carried both ">=22" (#13) and ">=22.9" (#12). JSON.parse keeps the last, so it resolved correctly by luck of ordering; a tool taking the first would have read a floor below the one fly.toml's release command depends on. Stage 3 of docs/superpowers/specs/2026-08-03-local-dev-setup.md * docs: testing EVE SSO and Discord linking over a tunnel (#21) Stage 4, documentation only. The seeded cookie from Stage 3 covers most dev work; this covers the case it cannot — changing the login or character-link flows themselves, which needs the real providers to redirect back to your machine. Every concrete claim was verified against the code rather than described from memory: - Redirect URIs are string-concatenated, not URL-joined, so a trailing slash on APP_BASE_URL yields `//auth/eve/callback` and z.string().url() accepts it silently — it surfaces much later as an unexplained redirect mismatch. - One EVE entry covers both flows: /auth/eve/login and /auth/eve/link both call buildEveAuthorizeUrl, so they share /auth/eve/callback. - EVE sends redirect_uri only on authorize; exchangeEveCode sends grant_type, code and code_verifier. Discord sends it TWICE — authorize and token exchange — and they must match. Changing APP_BASE_URL mid-flow therefore breaks Discord linking while EVE login keeps working, which reads like a Discord outage and is not. - Once APP_BASE_URL is https the session cookie is issued Secure, so the browser will not return it over http://localhost — you appear logged out no matter how often you log in. Browse the tunnel origin. Recommends .env.local for the override: it wins over .env, .env* is gitignored apart from .env.example, and switching back is deleting one file. * fix: address CodeRabbit review on #20 Seven findings, all verified against the code first. Two were real bugs: - The non-local refusal message called new URL(cfg.databaseUrl).host to name the host — but that branch is reached BY unparseable URLs, so it threw a TypeError and printed a stack trace instead of the guidance. Confirmed: `new URL("not a url")` throws. Now degrades to "unparseable DATABASE_URL". - The entry-point guard was process.argv[1]?.endsWith("seed-dev.ts"). Rename the file or emit it as .js and main() silently stops running: the command exits 0 having seeded nothing. Now compares resolved paths against fileURLToPath(import.meta.url). The truncation table list was duplicated between scripts/seed-dev.ts and tests/helpers/db.ts. Drift there is silent — a new table missing from one copy leaves stale rows after --reset and fails no test. Both now import src/db/tables.ts, and a new test asserts the list matches information_schema, so adding a table without registering it breaks a test instead of leaking rows. Test fix: the session-reissue assertion compared two Sets for inequality, which passes if only one of six cookies changed. Now asserts full disjointness. Docs: the cookie step said the "value" is the printed string, but the script prints a full name=value assignment and devtools has separate fields — pasting the whole line fails to authenticate. The documented id range said 91_000_0xx while alts use 91_000_1xx; corrected to the reserved 91_000_000-91_999_999 range. And "later file first" was a confusing way to describe env precedence — now states that Next applies its own .env.local-wins rule while the tsx scripts get the same result from flag order.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stage 4 — the last one. Documentation only, one file, +85 lines.
Scope
The seeded cookie from Stage 3 covers most dev work. This covers the case it can't: changing the login or character-link flows themselves, which needs the real providers to redirect back to your machine. Written for ngrok with a stable domain — a fresh random hostname per run means re-registering redirect URIs in two portals every time.
Four steps: start the tunnel, override
APP_BASE_URLin.env.local, register two redirect URIs, browse the tunnel origin.Every claim was verified against the code, not written from memory
Trailing slash. The URIs are string-concatenated, not URL-joined, and
z.string().url()accepts a trailing slash silently — so it fails much later as an unexplained redirect mismatch:Exact URIs, produced by running the real builders:
One EVE entry covers both flows —
/auth/eve/loginand/auth/eve/linkboth callbuildEveAuthorizeUrl, so they share/auth/eve/callback.The
Securecookie trap. OnceAPP_BASE_URLis https the session cookie is issuedSecure(src/app/auth/eve/callback/route.ts), so the browser won't send it back overhttp://localhost:3000— you appear logged out no matter how many times you log in.The finding worth reading
EVE and Discord treat
redirect_uridifferently:exchangeEveCodesendsgrant_type,code,code_verifier— noredirect_uri.So changing
APP_BASE_URL— or restarting with a different tunnel domain — between clicking "link Discord" and the redirect landing breaks the exchange, while EVE login keeps working. That asymmetry makes it read like a Discord outage when it's a mid-flight config change. Documented with the fix (restart the flow from the current origin).Verification
Docs-only, so the suites are unchanged from #20; re-run to confirm no drift. I could not test against the live EVE or Discord portals — that needs your developer-portal credentials and a running tunnel. Everything the code determines is verified above; what each portal accepts in its redirect-URI field is the part you'll confirm on first use.
Follow-up I did NOT implement
APP_BASE_URLcould normalize its trailing slash insrc/config.ts(a one-line.transform), turning this footgun into a non-issue rather than a documented caution. I left it out deliberately:CLAUDE.mdsays to stop and ask before touching the OAuth flow, andAPP_BASE_URLdrives both callbacks. Happy to send it as its own small PR if you want it.🤖 Generated with Claude Code