feat(auth): surface OIDC callback errors with distinct codes + log cause (#100) #101

Merged

james merged 1 commit from 100-oauth-callback-diagnostics into main 2026-06-18 03:51:01 +00:00

Conversation 0 Commits 1 Files changed 2 +32 -6

james commented 2026-06-18 03:46:26 +00:00

Owner

Copy link

Summary

The OAuth callback's catch block (added in #85) collapsed every error other than NoVerifiedEmailError into a generic 400 with "Failed to fetch profile" and no log line. For OIDC, that swallowed three distinct failure classes (IdTokenSignatureError, IdTokenClaimError, NonceMismatchError) and left a self-hoster with nothing to grep for. Hit while deploying #85 against Authentik on carol.int.wynning.tech — the only signal was "Failed to fetch profile."

Now the catch:

• Logs the underlying error to console.error with the provider id, so the cause shows up in container logs.
• Redirects to /login with a distinct ?error= code per failure class:
  • IdTokenSignatureError → oidc_signature
  • IdTokenClaimError → oidc_claim (iss / aud / exp / email / missing id_token)
  • NonceMismatchError → oidc_nonce_mismatch
  • NoVerifiedEmailError → no_verified_email (unchanged)
  • other → oauth_profile

Either signal alone is enough to diagnose a misconfigured IdP.

Decision: 302 + log (not 400 + log)

The pre-existing NoVerifiedEmailError path already redirected to /login?error=…, so this lands all "we got a token, validation failed" cases on the same shape. Protocol-level failures (cookies missing, state mismatch, provider mismatch, RFC 9207 iss mismatch) stay 400 — those indicate browser or attack-shaped problems where landing on /login would be misleading.

Reviewer note: see the "Out of scope" section of #100 — I'm open to flipping these back to 400 if a reviewer prefers the cleaner security-review story.

Test plan

• npm run typecheck — clean.
• npm run lint — clean.
• npm test — 214 / 38 skipped.
• Three existing OIDC scenarios that asserted 400 now assert 302 + matching ?error= code: bad signature (oidc_signature), email_verified: false (oidc_claim), nonce mismatch (oidc_nonce_mismatch).
• Manual re-probe against Authentik on carol.int.wynning.tech — confirm container logs show the specific error class.

Closes #100.

🤖 Generated with Claude Code

## Summary The OAuth callback's catch block (added in #85) collapsed every error other than `NoVerifiedEmailError` into a generic 400 with "Failed to fetch profile" and no log line. For OIDC, that swallowed three distinct failure classes (`IdTokenSignatureError`, `IdTokenClaimError`, `NonceMismatchError`) and left a self-hoster with nothing to grep for. Hit while deploying #85 against Authentik on `carol.int.wynning.tech` — the only signal was "Failed to fetch profile." Now the catch: - Logs the underlying error to `console.error` with the provider id, so the cause shows up in container logs. - Redirects to `/login` with a distinct `?error=` code per failure class: - `IdTokenSignatureError` → `oidc_signature` - `IdTokenClaimError` → `oidc_claim` (iss / aud / exp / email / missing id_token) - `NonceMismatchError` → `oidc_nonce_mismatch` - `NoVerifiedEmailError` → `no_verified_email` (unchanged) - other → `oauth_profile` Either signal alone is enough to diagnose a misconfigured IdP. ## Decision: 302 + log (not 400 + log) The pre-existing `NoVerifiedEmailError` path already redirected to `/login?error=…`, so this lands all "we got a token, validation failed" cases on the same shape. Protocol-level failures (cookies missing, state mismatch, provider mismatch, RFC 9207 iss mismatch) stay 400 — those indicate browser or attack-shaped problems where landing on `/login` would be misleading. Reviewer note: see the "Out of scope" section of #100 — I'm open to flipping these back to 400 if a reviewer prefers the cleaner security-review story. ## Test plan - [x] `npm run typecheck` — clean. - [x] `npm run lint` — clean. - [x] `npm test` — 214 / 38 skipped. - [x] Three existing OIDC scenarios that asserted 400 now assert 302 + matching `?error=` code: bad signature (`oidc_signature`), `email_verified: false` (`oidc_claim`), nonce mismatch (`oidc_nonce_mismatch`). - [ ] Manual re-probe against Authentik on `carol.int.wynning.tech` — confirm container logs show the specific error class. Closes #100. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-18 03:46:26 +00:00

feat(auth): surface OIDC callback errors with distinct codes + log cause ... f8ed6588e2

The previous catch in /api/auth/oauth/callback collapsed every error
other than NoVerifiedEmailError into a generic "Failed to fetch
profile" 400 with no log line. A self-hoster hitting an
IdTokenSignatureError / IdTokenClaimError / NonceMismatchError had no
way to tell which one.

Now: log the underlying cause to console.error (with provider id) and
redirect to /login with a distinct error code per failure class:

- IdTokenSignatureError  -> oidc_signature
- IdTokenClaimError      -> oidc_claim (iss/aud/exp/email/missing id_token)
- NonceMismatchError     -> oidc_nonce_mismatch
- NoVerifiedEmailError   -> no_verified_email (unchanged)
- other                  -> oauth_profile

Discovered while deploying #85 against Authentik.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

james force-pushed 100-oauth-callback-diagnostics from f8ed6588e2 to 6fd6509547 2026-06-18 03:49:54 +00:00 Compare

james merged commit 73ddb10ed5 into main 2026-06-18 03:51:01 +00:00

james deleted branch 100-oauth-callback-diagnostics 2026-06-18 03:51:02 +00:00

james referenced this pull request from a commit 2026-06-18 03:51:03 +00:00

Merge pull request 'feat(auth): surface OIDC callback errors with distinct codes + log cause (#100)' (#101) from 100-oauth-callback-diagnostics into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!101

No description provided.