docs(oidc): fix Callback error-status note to reflect 400/401/500

[github-actions]

Summary

The blockquote note following the OIDCHandler Link redirect-outcomes table contained an inaccuracy: it stated that pre-link-flow Callback errors are "surfaced as JSON error responses (HTTP 401) rather than redirects". In practice, Callback can return three distinct HTTP status codes, not just 401.

This was identified as an outstanding gap across three previously-opened PRs (#64, #67, #69), none of which have been merged. This PR makes the minimal, targeted fix.

What changed

README.md line 612 — one-word change in the blockquote note:

are surfaced as JSON error responses (HTTP 401) rather than redirects

→ are surfaced as JSON error responses (HTTP 400, 401, or 500 as appropriate) rather than redirects

Why this matters

The note sits immediately before the #### Error responses table that correctly documents all three status codes:

Status	Condition
400 Bad Request	Missing state cookie, invalid state param, missing PKCE verifier cookie, missing authorization_code, or missing sub/email claims
401 Unauthorized	Provider error param, code exchange failure, missing/invalid id_token, or unverified OIDC email
500 Internal Server Error	Claim-parsing failure, user resolution failure, or JWT creation failure

The prose note contradicted its own table. Clients that relied solely on the note (rather than the table) would not handle 400/500 responses from Callback, resulting in silent failures for those error paths.

Verification

Checked against handler/oidc.go Callback function — all writeError call sites:

• 400: missing state cookie, invalid state parameter, missing PKCE verifier cookie, missing authorization code, sub and email claims required
• 401: authentication failed (provider error param), failed to exchange code, missing id_token, invalid id_token, OIDC email must be verified
• 500: failed to parse claims, failed to process user, failed to create session

No code changes; documentation only.

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Update Docs · ● 2.8M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This is a one-word documentation fix that corrects an inaccurate status-code claim in README.md line 612. The blockquote previously stated that pre-link-flow Callback errors are surfaced as HTTP 401; the fix expands this to "HTTP 400, 401, or 500 as appropriate", which is confirmed by the writeError call sites in handler/oidc.go and aligns the note with the Error responses table directly below it.

Confidence Score: 5/5

Safe to merge — documentation-only fix verified against source code.

No code changes; the updated text is confirmed accurate by the writeError call sites in handler/oidc.go and is consistent with the adjacent Error responses table. No logic, security, or API contract is affected.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Single-line doc fix: corrects blockquote note from "HTTP 401" to "HTTP 400, 401, or 500 as appropriate", aligning it with the writeError call sites in handler/oidc.go and the Error responses table immediately below.

Sequence Diagram

sequenceDiagram
    participant Client
    participant OIDCHandler as OIDCHandler (Callback)
    participant Provider as OIDC Provider

    Client->>OIDCHandler: GET /callback?code=...&state=...
    OIDCHandler->>OIDCHandler: Validate state cookie / PKCE verifier
    alt Missing cookie, invalid state, missing code, missing claims
        OIDCHandler-->>Client: 400 Bad Request (JSON)
    end
    OIDCHandler->>Provider: Exchange code for tokens
    alt Provider error param / exchange failure / invalid id_token / unverified email
        OIDCHandler-->>Client: 401 Unauthorized (JSON)
    end
    OIDCHandler->>OIDCHandler: Parse claims, resolve user, create JWT
    alt Claims parse failure / user resolution failure / JWT creation failure
        OIDCHandler-->>Client: 500 Internal Server Error (JSON)
    end
    alt Link flow active
        OIDCHandler-->>Client: Redirect /?oidc_linked=true or /?oidc_link_error=…
    else Normal login
        OIDCHandler-->>Client: 200 OK + JWT
    end

Loading

_{Reviews (1): Last reviewed commit: "docs(oidc): fix Callback error-status no..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR corrects an inaccurate note in the OIDCHandler documentation so it matches the actual Callback handler behavior (JSON error responses can be 400, 401, or 500, not only 401).

Changes:

• Update the OIDCHandler link-flow note to reflect Callback JSON error status codes 400/401/500 instead of only 401.

Show a summary per file

File	Description
README.md	Fixes the OIDCHandler Callback error-status note to align with the documented error table and handler/oidc.go behavior.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 0