docs: document OAuth2 flow state cookies (SameSite=Lax) in cookies.md and security.md

[github-actions]

Summary

When OAuth2Handler was added, its oauth2_state and oauth2_verifier flow cookies were not reflected in the Cookie Helpers reference or the Security Notes page. This PR closes that gap.

Changes

docs/handler/cookies.md

Added a new OAuth2 flow cookies section explaining that OAuth2Handler sets the same SameSite=Lax, HttpOnly, 5-minute TTL state cookies (oauth2_state, oauth2_verifier) as OIDCHandler, and documents the same rationale: the provider redirect is a top-level cross-site navigation that SameSite=Strict would block.

docs/security.md

Updated the Cookie security bullet to name all four flow state cookies (oidc_state, oidc_verifier, oauth2_state, oauth2_verifier) rather than only the OIDC pair, keeping the security guidance accurate for the OAuth2Handler that was added in the previous commit.

Motivation

The prior commit (#204) added full OAuth2Handler documentation (routes, config, status codes, account linking) but missed updating the cross-cutting cookie and security reference pages. A developer reading docs/security.md or docs/handler/cookies.md would see that only OIDC uses SameSite=Lax cookies, leaving them unaware that OAuth2Handler makes the same trade-off.

Verification

• Code references: handler/oauth2.go:109–127 (oauth2_state, oauth2_verifier, SameSite=Lax, 5-min TTL)
• Equivalent OIDC code: handler/oidc.go:88–110 (identical pattern)
• No functional code was changed; documentation only.

Generated by Update Docs · ● 2.2M · ◷

To install this agentic workflow, run

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

Greptile Summary

Documentation-only PR that fills a gap left when OAuth2Handler was introduced: adds an OAuth2 flow cookies section to docs/handler/cookies.md and widens the Cookie security bullet in docs/security.md to name all four flow-state cookies. Both changes are accurate and consistent with handler/oauth2.go (lines 109–127, 143–159, 173).

Confidence Score: 5/5

Safe to merge — documentation only, no functional code changed.

No P0 or P1 findings. All documented claims (SameSite=Lax, HttpOnly, 5-min TTL, clearing order, PKCE server-side verification) are verified against the implementation in handler/oauth2.go. The only outstanding gap (missing OAuth2 PKCE section in security.md) was flagged in a prior review and is a P2 at most.

No files require special attention.

Important Files Changed

Filename	Overview
docs/handler/cookies.md	Adds OAuth2 flow cookies section; content is accurate and consistent with handler/oauth2.go (SameSite=Lax, HttpOnly, 5-min TTL, clearing order).
docs/security.md	Cookie security bullet updated to name all four flow-state cookies; wording is accurate. The pre-existing OIDC PKCE section still has no OAuth2 counterpart (flagged in a prior review).

Sequence Diagram

sequenceDiagram
    participant Browser
    participant App as goauth OAuth2Handler
    participant Provider as OAuth2 Provider

    Browser->>App: GET /oauth2/login
    App->>Browser: Set oauth2_state cookie (SameSite=Lax, HttpOnly, 5 min TTL)
    App->>Browser: Set oauth2_verifier cookie (SameSite=Lax, HttpOnly, 5 min TTL)
    App->>Browser: 302 Redirect to Provider AuthCodeURL with state and S256 PKCE challenge

    Browser->>Provider: GET /authorize (top-level cross-site navigation)
    Provider->>Browser: 302 Redirect to /oauth2/callback with code and state

    Browser->>App: GET /oauth2/callback (cookies sent via SameSite=Lax)
    App->>App: Validate state param vs oauth2_state cookie (CSRF check)
    App->>App: Read verifier from oauth2_verifier cookie
    App->>App: Clear both flow cookies
    App->>Provider: Exchange code plus PKCE verifier server-side
    Provider->>App: Access token
    App->>App: FetchUserInfo and issue JWT session cookies
    App->>Browser: 302 Redirect to login success URL

Loading

Comments Outside Diff (1)

1. docs/security.md, line 23-25 (link)

   Missing OAuth2 PKCE section

   This PR adds the OAuth2 cookie details to the Cookie security section, but docs/security.md still has a dedicated ## OIDC PKCE section with no equivalent for the OAuth2 flow. The OAuth2 handler uses the same S256 PKCE pattern (oauth2.S256ChallengeOption(verifier) in oauth2.go:129) and validates the state parameter on every callback (lines 143–146), so a parallel ## OAuth2 PKCE entry would keep the security reference complete.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: docs/security.md
   Line: 23-25
   
   Comment:
   **Missing OAuth2 PKCE section**
   
   This PR adds the OAuth2 cookie details to the Cookie security section, but `docs/security.md` still has a dedicated `## OIDC PKCE` section with no equivalent for the OAuth2 flow. The OAuth2 handler uses the same S256 PKCE pattern (`oauth2.S256ChallengeOption(verifier)` in `oauth2.go:129`) and validates the state parameter on every callback (lines 143–146), so a parallel `## OAuth2 PKCE` entry would keep the security reference complete.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

_{Reviews (2): Last reviewed commit: "docs: fix OAuth2 cookie-clearing timing ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates cross-cutting documentation to accurately reflect the OAuth2Handler flow cookies and their SameSite trade-offs, aligning Cookie Helpers and Security Notes with the existing implementation.

Changes:

• Document OAuth2 flow state cookies (oauth2_state, oauth2_verifier) in Cookie Helpers, mirroring the OIDC rationale for SameSite=Lax.
• Update Security Notes to include both OIDC and OAuth2 flow state cookies in the cookie security guidance.

Show a summary per file

File	Description
docs/security.md	Expands cookie security guidance to explicitly include OAuth2 flow state cookies alongside OIDC.
docs/handler/cookies.md	Adds an “OAuth2 flow cookies” section describing cookie names and SameSite rationale for OAuth2Handler.

Copilot's findings

Tip

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

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