kandev/docs/plans/integration-provider-auth-errors/task-01-classify-session-challenges.md

id, title, status, wave, depends_on, plan, spec, related_spec

id	title	status	wave	depends_on	plan	spec	related_spec
01-classify-session-challenges	Classify session challenges and preserve PAT errors	done	1		plan.md	../../specs/auth/requirements/auth.md	../../specs/integrations/requirements/github-authentication.md

Task 01: Classify session challenges and preserve PAT errors

Intent

Prevent third-party provider 401 responses from invoking the global Kandev login redirect while preserving the redirect for a real Kandev session challenge. Prove that an invalid GitHub PAT save remains visible and retryable in the existing connection dialog.

Acceptance

1. fetchJson invokes onUnauthorized only for a 401 carrying Kandev's WWW-Authenticate: Bearer challenge and still throws ApiError for both challenged and unchallenged failures.
2. An unchallenged provider 401 preserves its parsed error message for the calling integration UI.
3. A PAT-only GitHub connection save failure leaves the dialog open, retains the submitted token, displays the error, and does not call the saved callback.

TDD

1. Add the challenged/unchallenged 401 unit cases and the PAT-only dialog rejection case.
2. Run them against current code and confirm the unchallenged-401 case fails because onUnauthorized is called.
3. Implement the smallest shared-client classification change.
4. Rerun the focused tests and refactor only if needed.

Files Likely Touched

• apps/web/lib/api/client.ts
• apps/web/lib/api/client.test.ts
• apps/web/components/github/github-connection-dialog.test.tsx

Dependencies

None.

Parallelism

sequential — Task 02 depends on this behavior.

Verification

cd apps && pnpm --filter @kandev/web test -- lib/api/client.test.ts components/github/github-connection-dialog.test.tsx

Inputs

• docs/specs/auth/requirements/auth.md — session challenge versus provider failure behavior.
• docs/specs/integrations/requirements/github-authentication.md — invalid PAT save behavior.
• apps/backend/internal/auth/httpmw/middleware.go — authoritative Kandev session challenge.
• apps/web/src/main.tsx — global unauthorized callback.

Output Contract

Verification record:

• RED: before the challenge gate, the focused provider-401 test failed because onUnauthorized was invoked for an unchallenged 401.
• Changed files: apps/web/lib/api/client.ts, apps/web/lib/api/client.test.ts, and apps/web/components/github/github-connection-dialog.test.tsx.
• Final focused result: 14 tests passed; the managed provider-auth E2E spec passed all 5 scenarios; web typecheck and changed-file lint passed.
• Follow-up review fix: apps/backend/internal/backendapp/middleware.go now exposes WWW-Authenticate to split-origin browsers, with a regression test in apps/backend/internal/backendapp/middleware_test.go.
• Remaining risk: session redirect classification depends on the backend emitting the WWW-Authenticate: Bearer challenge; same-origin and split-origin paths now both preserve that signal.