docs(oauth2): document shared PKCE redirect for Login and Link

[github-actions]

PR #325 refactored OAuth2Handler.Login and OAuth2Handler.Link to share a single redirectToProvider helper. Both endpoints now set identical oauth2_state and oauth2_verifier HttpOnly cookies (SameSite=Lax, 5-minute TTL) before redirecting the browser to the provider.

The existing docs described PKCE protection for Login but were silent on Link. This PR closes that gap.

Changes

• docs/handler/oauth2.md — Routes section: Added a note explaining that Login and Link share the same redirect mechanism (state + PKCE verifier cookies) and that Callback validates both cookies for either flow.
• Response types table: Updated the Link row to mention that it sets state and PKCE verifier cookies (consistent with Login).
• Account linking section: Updated to reference PKCE alongside the HMAC-signed state, and cross-references Login's cookie behaviour so readers understand Callback validates them identically.

Testing

Documentation-only change; no code logic altered. Verify by reading handler/oauth2.go (Login, Link, redirectToProvider) against the updated doc.

Generated by Update Docs · ● 1.3M · ◷

Add this agentic workflows to your repo

To install this agentic workflow, run

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

Greptile Summary

This documentation-only PR updates docs/handler/oauth2.md to accurately reflect that Login and Link share a single redirectToProvider helper and therefore both set identical oauth2_state and oauth2_verifier HttpOnly cookies before redirecting to the provider.

• Updated the Response types table so both the Login and Link rows mention that they set state and PKCE verifier cookies, eliminating the prior inconsistency where only Link mentioned them.
• Expanded the Account linking section to reference PKCE alongside the HMAC-signed state, and added a cross-reference noting that Callback validates the cookies identically for both flows.

Confidence Score: 5/5

Documentation-only change with no code modifications; all updated prose accurately mirrors the implementation in handler/oauth2.go.

Every changed passage was verified against the actual Go source: both Login and Link call the shared redirectToProvider helper that sets oauth2_state and oauth2_verifier cookies, Callback validates them identically before diverging on link vs login logic, and the HMAC-signed state distinction is already captured in the pre-existing cookie table. No logic, configuration, or behaviour was altered.

No files require special attention.

Important Files Changed

Filename	Overview
docs/handler/oauth2.md	Accurate documentation update; all three changed passages reflect the actual behaviour in handler/oauth2.go — both Login and Link call redirectToProvider, which sets oauth2_state and oauth2_verifier HttpOnly cookies, and Callback reads both cookies identically before diverging on link vs login logic.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant Handler as OAuth2Handler
    participant Provider as OAuth2 Provider

    Note over Browser,Provider: Login flow
    Browser->>Handler: GET /auth/github/login
    Handler-->>Browser: 302 + Set-Cookie: oauth2_state, oauth2_verifier
    Browser->>Provider: Redirect to provider AuthCodeURL
    Provider-->>Browser: "302 back to /auth/github/callback?code=&state="
    Browser->>Handler: "GET /callback (with state & verifier cookies)"
    Handler->>Handler: "validate state cookie == query param state"
    Handler->>Handler: PKCE exchange with verifier cookie
    Handler->>Handler: clear oauth2_state and oauth2_verifier cookies
    Handler-->>Browser: "302 /?oauth2_login=1 + JWT cookie"

    Note over Browser,Provider: Link flow (same redirect mechanism)
    Browser->>Handler: "GET /auth/github/link?nonce=<nonce>"
    Handler->>Handler: consume nonce, look up user, sign state (HMAC)
    Handler-->>Browser: 302 + Set-Cookie: oauth2_state (HMAC-signed), oauth2_verifier
    Browser->>Provider: Redirect to provider AuthCodeURL
    Provider-->>Browser: "302 back to /auth/github/callback?code=&state="
    Browser->>Handler: GET /callback (with cookies)
    Handler->>Handler: validate state cookie, PKCE exchange (identical to Login)
    Handler->>Handler: "parseLinkState -> extract userID from HMAC state"
    Handler->>Handler: "handleLinkCallback -> link subject"
    Handler-->>Browser: "302 /?oauth2_linked=true"

Loading

_{Reviews (3): Last reviewed commit: "Merge origin/main: expand PKCE/CSRF cook..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates the OAuth2 handler documentation to reflect that both OAuth2Handler.Login and OAuth2Handler.Link use the same PKCE+state cookie redirect mechanism, and that Callback validates the same cookies for either flow.

Changes:

• Documented that both Login and Link set oauth2_state and oauth2_verifier HttpOnly cookies with SameSite=Lax and a 5-minute TTL before redirecting to the provider.
• Updated the response types table to note that Link sets the same state+PKCE verifier cookies as Login.
• Expanded the account-linking section to explicitly mention PKCE alongside the HMAC-signed state, and that Callback validates the cookies identically for both flows.

Show a summary per file

File	Description
docs/handler/oauth2.md	Clarifies shared Login/Link redirect behavior (state + PKCE verifier cookies) and aligns the Link documentation with Callback validation 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