feat: connect planner via OAuth 2.1 / OIDC by mroderick · Pull Request #32 · codebar/auth

mroderick · 2026-06-18T08:41:12Z

Summary

Connect the auth service to the planner via OAuth 2.1 / OIDC using Better Auth's built-in oauthProvider and jwt plugins. The planner acts as a first-party OAuth client.

Commits

Commit	Description
`chore: add @better-auth/oauth-provider and @playwright/test dependencies`	Add `@better-auth/oauth-provider` runtime dep, bump `better-auth` to 1.6.20, add `@playwright/test` dev dep
`feat: add JWT and OAuth provider plugins with login flow, seeding, and tests`	Core feature: Better Auth config with `jwt`/`oauthProvider`/`magicLink` plugins, OAuth authorize login flow, PKCE seeding, test infrastructure with schema isolation, 49 new unit/integration tests
`ci: add CI pipeline and Playwright e2e test for OAuth flow`	CI workflow with parallel test groups + e2e Playwright job testing full magic link OAuth flow
`docs: add architecture documentation covering OAuth 2.1 flows`	Architecture doc with sequence diagrams for GitHub OAuth and Magic Link flows

Changes

Auth configuration (`src/auth.js`)

Add jwt() plugin — issues id_tokens with email and name claims for the planner (RS256)
Add oauthProvider() plugin — exposes OAuth 2.1 authorize/token endpoints (/api/auth/oauth2/*)
Add account.skipStateCookieCheck: true — cross-site OAuth callback compatibility
Add trustedOrigins with localhost + auth base URL

Config (`src/config.js`)

Add AUTH_DEFAULT_PORT and PLANNER_DEFAULT_PORT constants
Add planner_redirect_uris and allowed_redirects from PLANNER_REDIRECT_URIS env var (comma-separated, supports multiple environments)

Login flow (`src/app/routes/auth.js`, `src/app/components/login.js`)

Replace redirect_url-based flow with callbackURL pointing to the OAuth authorize endpoint
Extract named route handlers (showLogin, showMagicLinkForm, sendMagicLink, startGitHubOAuth)
getCallbackURL preserves OAuth query params (PKCE, state, etc.) from the authorize request
GitHub and magic link buttons now POST/GET with callbackURL

Database seeding

src/app/db/seed-client.js — inserts the planner OAuth client via raw SQL with ON CONFLICT DO UPDATE for idempotency. Accepts redirect URIs as JSON array via $1::jsonb. Validates schemaName to prevent SQL injection.
scripts/migrate.js — runs migrations and seeds the planner client
scripts/heroku-release.sh — runs node scripts/migrate.js on every deploy

Dev test helpers

src/dev/magic-links.js — captures sent magic links when SENDGRID_API_KEY is unset
src/app/app.js — exposes /api/test/magic-links GET/DELETE in non-production, magic link endpoint localhost-restricted

CI

Add e2e job running Playwright after unit tests
Use chromium-headless-shell for smaller download
Add permissions: contents: read at workflow level

Documentation

docs/architecture.md — architecture overview with sequence diagrams, environment layout, env vars, and operational details

Testing

158 unit tests, 0 failures. New tests cover:

OAuth provider: planner client seeded correctly (public, PKCE-required, redirect URIs as JSON array)
Authorize endpoint: redirects unauthenticated users to login, issues code when authenticated
Token endpoint: exchanges code for access token with PKCE, rejects missing/invalid PKCE, invalid code, mismatched redirect_uri
Integration: full flow — authenticate -> authorize -> exchange code -> verify JWT via JWKS
E2E (Playwright): unauthenticated authorize -> login -> magic link -> verify -> authorize -> code

till · 2026-06-22T07:48:53Z

+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: ".nvmrc"
+      - run: npm ci
+      - run: |
+          npm run prettier:check
+          npm run lint
+          npm run fallow


Maybe pull these into another pr to fix?

mroderick · 2026-06-23T12:09:37Z

@till, would you mind reviewing this one?

till

I started, but I need to look more.

till · 2026-06-22T07:48:53Z

+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version-file: ".nvmrc"
+      - run: npm ci
+      - run: |
+          npm run prettier:check
+          npm run lint
+          npm run fallow


Maybe pull these into another pr to fix?

till · 2026-06-22T07:49:54Z

      - run: npm ci
-      - run: |
-          npm run prettier:check
-          npm run lint


I don't understand these changes.

Yeah, that was really not well implemented.
I added an e2e test, but the workflow file took a beating in the process. I've added a commit, that makes the final diff read well.
Once review is complete, I'll rebase the confusion away.

…d tests Core changes: - Configure Better Auth with jwt, oauthProvider, magicLink plugins - Route login flow through OAuth authorize endpoint with callbackURL - Add skipStateCookieCheck for cross-site redirect compatibility - Add database seeding for planner OAuth client (jsonb, idempotent, multi-URI) - Add heroku-release.sh running migrate.js on every deploy - Add dev helper for magic link capture in non-production - Add test helper with isolated PG schema per test Tests cover: provider seeding, authorize, token exchange with PKCE, JWKS verification, and full integration flow.

Adds a CI workflow with unit tests, coverage, and a Playwright e2e job. The e2e test covers the full magic link OAuth flow end-to-end.

mroderick · 2026-06-25T15:14:00Z

I have deployed both PRs for planner and auth to Heroku, in order to verify things in staging before we merge the PRs.

I also reviewed the PRs against OWASP top 10 for 2025, and fixed the few minor things that surfaced.

This unfortunately meant that I had to make some changes since I originally marked this as ready for review. I chose to rewrite the git history, in order to make the PRs easier to follow ... i.e. without any side quests. They should read fairly linearly now.

Testing on Heroku

To verify the OAuth 2.1 flow end-to-end:

Flow A: Sign in with GitHub

Open https://codebar-staging.herokuapp.com/ — confirm the app loads
Navigate to https://codebar-staging.herokuapp.com/auth/codebar << this is not linked in the UI, we'll only do that, once it is proven to work in production
Observe you're redirected to https://auth.codebar.io/login?... with OAuth params
(client_id=planner, response_type=code, code_challenge=..., state=...) in the URL
Click "Sign In with GitHub" — authenticate with your GitHub account
Observe you're redirected back to the staging app, signed in

Flow B: Sign in with Magic Link

Clear all cookies for *.codebar.io and *.herokuapp.com to start fresh
Navigate to https://codebar-staging.herokuapp.com/auth/codebar again
Observe you're redirected to https://auth.codebar.io/login?...
Enter your email address and click "Send Magic Link"
Check your inbox for the magic link email from auth-noreply@codebar.io
Click the link in the email
Observe you're redirected back to the staging app, signed in

If something goes wrong

Check the staging app logs:

  heroku logs --tail -a codebar-staging

OAuth errors from the planner side show as (codebar) Authentication failure! <error_type>. The auth
app is already in production — let us know if you need access to its logs too.

till

This is a lot. But LMK, what you think, not hard no's on anything. I will have a look again.

till · 2026-06-26T14:08:08Z

+
+## Overview
+
+The auth app (`auth.codebar.io`) is an OAuth 2.1 / OIDC provider built with


It already serves profile, logout and I think link/unlink capabilities today. Those will stay around.

You're right. That sentence is misleading.

I've pushed a better version in 1a4ed9f

till · 2026-06-26T14:11:49Z

+ */
+
+// ponytail: raw SQL because Better Auth doesn't expose a public API to
+// create OAuth clients without admin auth. If the schema changes, update here.


Just curious, why would we not use admin-api?

It requires a user session, so we would have create the OAuth client using the endpoint after the code has been deployed.

That seemed a bit clunky to me, so I opted for a simpler solution.

Admittedly, getting all this working in Heroku had a few other steps that were clumsy to me, so in the grand scheme of things, it wouldn't have added that much more.

till · 2026-06-26T14:13:14Z

-    const error = c.req.query("error");
-    const success = c.req.query("success");
-    const redirectUrl = validateRedirectUrl(c.req.query("redirect_url"), "");
+function getCallbackURL(c) {


Maybe this should be somewhere else, like in the utlities. This will is pretty large already.

Sure. I've extracted it to a different file in afbcbac

till · 2026-06-26T14:14:10Z


  app.route("/demo", demoHandler);

+  // Dev-only endpoint for Playwright tests to retrieve captured magic links


Similar, maybe spin them out to another file.

You're right. I've created another fixup commit: 7e02c87

till · 2026-06-26T14:15:32Z


        if (!apiKey) {
          console.log(`Magic Link for ${email}: ${url}`);
+          devMagicLinks.push({


This should be more obvious, e.g. not rely on apiKey to be set (which could be a mistake), but instead use the same environment guard.

I agree. fixup in 7c8fed6

till · 2026-06-26T14:16:42Z

+export const AUTH_DEFAULT_PORT = 3001;
+export const PLANNER_DEFAULT_PORT = 3000;
+
+const parseRedirectUris = () =>


Does the auth app have a staging? Otherwise, how would this work.

It doesn't have a staging environment. The allowed redirect uris are in PLANNER_REDIRECT_URIS.

It is explained in the architecture doc, which is easy to overlook.

I've added a comment in a fixup commit 6977b55

till · 2026-06-26T14:18:37Z

+      const testInstance = await getTestInstance();
+      const app = createApp(testInstance.auth, testInstance.db);
+
+      const params = new URLSearchParams({


I'd put this into a helper and make it more descriptive. But the params repeats itself.

Maybe generally, I haven't look at it all in detail, but it could use some test helpers for all the tests.

That's a good point.

I've created another fixup for this in 37e1b9a

till · 2026-06-26T14:20:11Z

@@ -0,0 +1,17 @@
+import { defineConfig, devices } from "@playwright/test";


till · 2026-06-26T14:22:46Z

+  // extra signed cookie check fails on Heroku/Cloudflare because the
+  // `__Secure-better-auth.state` cookie (SameSite=Lax) doesn't survive
+  // the cross-site redirect from GitHub back to the callback.
+  // This is a known pattern: https://github.com/better-auth/better-auth/issues/4969


The issue is closed and from last year, is this even applicable?

⚠️ Written by my synthetic assistant ⚠️

Good catch on the issue being old and about a different problem. I investigated whether it's still needed, and it is. Here's what I found:

The account.skipStateCookieCheck option controls a second signed cookie check in parseGenericState's database strategy. The state is already validated against the verification table — the cookie is a redundant additional check that sets a __Secure-better-auth.state cookie (SameSite=Lax, httpOnly) and verifies it on callback.

This fails in the GitHub OAuth flow (user signs in with GitHub on the login page) because Cloudflare strips __Secure- prefix cookies on ingress. The same issue is present behind Heroku's router. The database verification passes fine, but the cookie check throws "State mismatch" before the user ever reaches the oauthProvider flow.

The option is not deprecated — it's still wired in v1.6.20 (create-context.mjs:130), and even Better Auth's own oauth-proxy plugin hardcodes skipStateCookieCheck: true when parsing state for cross-domain flows.

I updated the ponytail comment to explain this properly and dropped the stale issue link.

till · 2026-06-26T14:23:25Z

+  // Dev-only endpoint for Playwright tests to retrieve captured magic links
+  // Guarded by NODE_ENV check AND remote address — requests from non-local
+  // sources are rejected even if NODE_ENV isn't production (e.g. staging).
+  if (process.env.NODE_ENV !== "production") {


Could also fetch this in config and re-use it here. So the code is not using process.env everywhere?

⚠️ Written in collaboration with my synthetic assistant ⚠️

Good call. We had three raw process.env.NODE_ENV references across auth.js and app.js. After the other fixups (environment guards in sendMagicLink and trustedOrigins), this was the last one that couldn't be derived from config values.

I added isProduction: process.env.NODE_ENV === "production" to src/config.js and replaced all three process.env.NODE_ENV checks with appConfig.isProduction / !appConfig.isProduction. The changes are in 9cb7eb9.

The only remaining direct process.env reads in the app code are the env vars that are genuinely per-environment config (database URLs, API keys, etc.) — those are already centralised through getter functions in config.js.

…ing, and tests

mroderick force-pushed the feature/magic-link-code-exchange branch 3 times, most recently from 2c4d394 to 9826035 Compare June 18, 2026 09:42

till reviewed Jun 19, 2026

View reviewed changes

Comment thread src/app/routes/auth.js Outdated

Comment thread src/auth.js

mroderick force-pushed the feature/magic-link-code-exchange branch 6 times, most recently from f302a42 to 5ff85f2 Compare June 21, 2026 21:16

github-advanced-security AI found potential problems Jun 21, 2026

View reviewed changes

mroderick force-pushed the feature/magic-link-code-exchange branch 2 times, most recently from 714f6dc to 215a38d Compare June 21, 2026 21:32

mroderick marked this pull request as ready for review June 21, 2026 21:42

mroderick requested a review from till June 21, 2026 21:42

mroderick changed the title ~~feat: add code exchange endpoint and auth callback for planner integration~~ feat: connect planner via OAuth 2.1 / OIDC Jun 21, 2026

mroderick force-pushed the feature/magic-link-code-exchange branch 2 times, most recently from 82dbb02 to 8e0c04b Compare June 22, 2026 10:44

mroderick mentioned this pull request Jun 22, 2026

feat: add magic link auth provider with code exchange codebar/planner#2649

Open

till reviewed Jun 23, 2026

View reviewed changes

mroderick force-pushed the feature/magic-link-code-exchange branch from e31a213 to 326ae91 Compare June 24, 2026 09:50

mroderick marked this pull request as draft June 24, 2026 09:55

mroderick force-pushed the feature/magic-link-code-exchange branch 3 times, most recently from 1c48d90 to 430959a Compare June 24, 2026 10:06

mroderick requested a review from till June 24, 2026 10:11

mroderick marked this pull request as ready for review June 24, 2026 10:11

mroderick force-pushed the feature/magic-link-code-exchange branch 2 times, most recently from 6ad9514 to 6fe91f7 Compare June 25, 2026 11:11

mroderick added 4 commits June 25, 2026 16:57

chore: add @better-auth/oauth-provider and @playwright/test dependencies

701d3ad

ci: add CI pipeline and Playwright e2e test for OAuth flow

491c8cc

Adds a CI workflow with unit tests, coverage, and a Playwright e2e job. The e2e test covers the full magic link OAuth flow end-to-end.

docs: add architecture documentation covering OAuth 2.1 flows

14c1035

mroderick force-pushed the feature/magic-link-code-exchange branch from cc6b9fe to 14c1035 Compare June 25, 2026 15:00

till reviewed Jun 26, 2026

View reviewed changes

fixup! docs: add architecture documentation covering OAuth 2.1 flows

1a4ed9f

mroderick force-pushed the feature/magic-link-code-exchange branch from 781e320 to 090aa86 Compare June 29, 2026 08:54

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

afbcbac

…ing, and tests

mroderick force-pushed the feature/magic-link-code-exchange branch from 090aa86 to afbcbac Compare June 29, 2026 08:57

mroderick added 5 commits June 29, 2026 11:07

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

7e02c87

…ing, and tests

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

7c8fed6

…ing, and tests

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

6977b55

…ing, and tests

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

37e1b9a

…ing, and tests

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

8594ee4

…ing, and tests

mroderick force-pushed the feature/magic-link-code-exchange branch from bd17b15 to 8594ee4 Compare June 29, 2026 10:03

fixup! feat: add JWT and OAuth provider plugins with login flow, seed…

9cb7eb9

…ing, and tests

mroderick requested a review from till June 29, 2026 10:22


		## Overview

		The auth app (`auth.codebar.io`) is an OAuth 2.1 / OIDC provider built with


		app.route("/demo", demoHandler);

		// Dev-only endpoint for Playwright tests to retrieve captured magic links

		@@ -0,0 +1,17 @@
		import { defineConfig, devices } from "@playwright/test";

Uh oh!

Conversation

mroderick commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Commits

Changes

Auth configuration (src/auth.js)

Config (src/config.js)

Login flow (src/app/routes/auth.js, src/app/components/login.js)

Database seeding

Dev test helpers

CI

Documentation

Testing

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mroderick commented Jun 23, 2026

Uh oh!

till left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mroderick commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Flow A: Sign in with GitHub

Flow B: Sign in with Magic Link

If something goes wrong

Uh oh!

till left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mroderick commented Jun 18, 2026 •

edited

Loading

Auth configuration (`src/auth.js`)

Config (`src/config.js`)

Login flow (`src/app/routes/auth.js`, `src/app/components/login.js`)

mroderick commented Jun 25, 2026 •

edited

Loading