Real auth: /v1/oauth/{state,exchange,handoff/{id}} with PKCE-S256, S2S guard, atomic getDel

[rainxchzed]

Summary

Server-side half of the GitHub OAuth web flow with PKCE-S256 and a short-lived handoff. App opens browser → GitHub → website callback → backend swaps code for token → backend mints opaque handoff_id → app receives id via deep link → app calls backend with id → gets token. Token traverses the network only inside the handoff response body; never appears in a URL, never logged, lives in Postgres for ≤60s, single-use.

8 commits. The last two are review fixes from a Backend Architect + Security Engineer pass.

Endpoints

Endpoint	Auth	Notes
POST /v1/oauth/state	S2S (shared secret + Host allowlist)	Website pre-registers {state, code_challenge}. 60s TTL. 60/hr/IP.
POST /v1/oauth/exchange	S2S	Verifies PKCE via atomic getDel(state), swaps with GitHub, mints handoff. 30/hr/IP.
POST /v1/oauth/handoff/{id}	Public	Atomic DELETE ... RETURNING value — single-use, second call 404s. 60/min/IP.

Storage

Postgres-backed via oauth_ephemeral table (V16 migration). Single table, two namespaces (state, handoff). 60s TTL enforced in two ways:

1. Every read filters expires_at > NOW() — expired-but-unswept rows appear absent
2. OAuthCleanupWorker reaps expired rows every 5min (with OAUTH_CLEANUP_DISABLED=true kill switch)

Interface-abstracted (OAuthEphemeralStore) for a possible future Redis swap.

Security baseline compliance

Spec	Implementation
PKCE S256 mandatory	MessageDigest.isEqual(SHA256(verifier), stored_challenge) — constant-time
State 32 bytes base64url	Regex ^[A-Za-z0-9_-]{43}$ enforced on every value
HTTPS only	Caddy terminates TLS
No tokens in URLs	Token only in {access_token} body of /handoff response
Single-use handoff	DELETE … RETURNING value is atomic at the SQL row-lock level
Replay → 404	Second call sees the deleted row
Short TTLs (60s × 3)	Single TTL = Duration.ofSeconds(60) constant
No logging of code/verifier/token/handoff_id	Test seeds gho_test_secret_token + raw code + verifier, asserts none appear in log capture
Rate-limit /exchange 30/hr/IP	Bucket registered in Plugins.kt
Rate-limit /handoff brute-force	60/min/IP; 256-bit handoff_id entropy already makes guessing infeasible

Review fixes (last two commits)

Security:

• F1+F4: atomic getDel(state) at top of /exchange — closes race between two concurrent (state, verifier) requests + collapses the state-burn asymmetry (GitHub's authorization code is single-use upstream, so retry-with-same-state is never legitimate)
• F6: GitHub upstream error code whitelist — anything outside 12 documented codes normalised to github_unknown
• F7: misconfig (missing token or empty host allowlist in prod) returns identical 401 service_auth_required body as wrong-secret — anonymous prober can't fingerprint deploy state
• F8: MessageDigest.isEqual for both service-token compare and PKCE compare — no length-side-channel
• F9: Cache-Control: no-store set as first action on every /handoff response, including 404 paths
• F13: X-Oauth-Service-Token added to Sentry.beforeSend header scrubber

Architecture:

• F5: validateProductionEnv now requires OAUTH_SERVICE_ALLOWED_HOSTS + OAUTH_WEB_CALLBACK_URL — both fail-fast at boot instead of 401-on-every-request at runtime
• F10: OAUTH_CLEANUP_DISABLED=true per-iteration kill switch in OAuthCleanupWorker
• F11: dropped the unused Exposed OAuthEphemeral declaration; replaced with a comment explaining why the table is JDBC-only (footgun removal)

Deep-link contract (operator → website agent)

Website emits githubstore://auth?handoff=<id>&state=<state>. State round-trips: app generated, website stored in its KV, included in deep link, app re-validates locally before consuming handoff. Backend never emits the URL. Earlier draft oauth-done?handoff=<id> is superseded.

New env vars

OAUTH_CLIENT_ID                 # renamed from GITHUB_OAUTH_CLIENT_ID
OAUTH_CLIENT_SECRET             # never commit
OAUTH_WEB_CALLBACK_URL          # must match GitHub OAuth App callback config
OAUTH_SERVICE_TOKEN             # openssl rand -base64 48; share with website
OAUTH_SERVICE_ALLOWED_HOSTS     # default api.github-store.org; append api-direct if you serve it
# OAUTH_CLEANUP_DISABLED=true   # optional kill switch

All required under APP_ENV=production — backend refuses to start without them. Old GITHUB_OAUTH_CLIENT_ID is no longer read.

Test plan

• Full Gradle test suite green (route + service auth + privacy + race-with-same-state)
• After deploy: curl -X POST -H 'X-Oauth-Service-Token: \$TOKEN' -H 'Host: api.github-store.org' -d '{"state":"x","code_challenge":"y"}' https://api.github-store.org/v1/oauth/state → 400 invalid_state (proves endpoint up + auth gates work + validation rejects dummies)
• After deploy: same call without service token → 401 service_auth_required
• After website + client land their halves: end-to-end OAuth login on Desktop

[greptile-apps]

rainxchzed has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

Warning

Rate limit exceeded

@rainxchzed has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 5 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c4e15196-a4b6-4dda-8e0c-f7d4269a89f4

📥 Commits

Reviewing files that changed from the base of the PR and between 71ebd12 and 2615ed6.

📒 Files selected for processing (18)

• .env.example
• CLAUDE.md
• src/main/kotlin/zed/rainxch/githubstore/AppModule.kt
• src/main/kotlin/zed/rainxch/githubstore/Application.kt
• src/main/kotlin/zed/rainxch/githubstore/Plugins.kt
• src/main/kotlin/zed/rainxch/githubstore/db/DatabaseFactory.kt
• src/main/kotlin/zed/rainxch/githubstore/db/Tables.kt
• src/main/kotlin/zed/rainxch/githubstore/ingest/GitHubDeviceClient.kt
• src/main/kotlin/zed/rainxch/githubstore/oauth/OAuthCleanupWorker.kt
• src/main/kotlin/zed/rainxch/githubstore/oauth/OAuthEphemeralStore.kt
• src/main/kotlin/zed/rainxch/githubstore/oauth/OAuthExchangeService.kt
• src/main/kotlin/zed/rainxch/githubstore/oauth/OAuthServiceAuth.kt
• src/main/kotlin/zed/rainxch/githubstore/oauth/PostgresOAuthEphemeralStore.kt
• src/main/kotlin/zed/rainxch/githubstore/routes/OAuthRoutes.kt
• src/main/kotlin/zed/rainxch/githubstore/routes/Routing.kt
• src/main/resources/db/migration/V16__oauth_ephemeral.sql
• src/test/kotlin/zed/rainxch/githubstore/oauth/InMemoryOAuthEphemeralStore.kt
• src/test/kotlin/zed/rainxch/githubstore/oauth/OAuthRoutesTest.kt

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/oauth-web-flow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

rainxchzed has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.