docs(auth): extend OAuth2Handler coverage in store-interfaces and sentinel errors

[github-actions]

Summary

After the generic OAuth2Handler was added (#203), three places in the auth package docs still only mentioned OIDCHandler, even though both handlers share the same underlying store contracts and helpers.

Changes

docs/auth/store-interfaces.md

• CreateOIDCUser race-retry note (line 24): credited OIDCHandler alone, but OAuth2Handler uses the same findOrCreateUser helper (in handler/oauth2_common.go) which has identical retry logic. Updated to say "Both OIDCHandler and OAuth2Handler rely on this...".

• OIDCLinkNonceStore section (line 260): described the store as required only for OIDCHandler account linking. OAuth2Handler requires the same store for its CreateLinkNonce / Link endpoints. Updated to list both handlers explicitly.

docs/auth/index.md

• ErrOIDCSubjectAlreadyLinked sentinel (line 31): stated that the interactive link callback redirects with oidc_link_error=Failed+to+link. The shared handleLinkCallback helper uses a caller-supplied errorParam, so OAuth2Handler redirects with oauth2_link_error=Failed+to+link instead. Updated to name both query-parameter variants.

Verification

All three changes are consistent with the implementation in:

• handler/oauth2.go — OAuth2Handler fields LinkNonces auth.OIDCLinkNonceStore
• handler/oauth2_common.go — findOrCreateUser with ErrEmailExists retry; handleLinkCallback with configurable errorParam
• handler/oauth2_test.go — tests assert oauth2_link_error query parameters

No code changes; documentation only.

Generated by Update Docs · ● 1.3M · ◷

To install this agentic workflow, run

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

Greptile Summary

This PR updates two documentation files to reflect that OAuth2Handler shares the same store contracts and helpers as OIDCHandler, following the introduction of OAuth2Handler in #203.

• docs/auth/store-interfaces.md: The CreateOIDCUser race-retry paragraph is broadened to credit both handlers (both call the shared findOrCreateUser helper), and the OIDCLinkNonceStore section is updated to list both OIDCHandler and OAuth2Handler as consumers of the store, matching OAuth2Handler.LinkNonces auth.OIDCLinkNonceStore.
• docs/auth/index.md: The ErrOIDCSubjectAlreadyLinked table entry now names both oidc_link_error (used by OIDCHandler) and oauth2_link_error (used by OAuth2Handler) as the redirect query parameter, consistent with how handleLinkCallback is called with a configurable errorParam in oauth2.go.

Confidence Score: 5/5

Documentation-only change; all three updated statements are verified accurate against the live implementation.

Every claim in the updated docs maps directly to code: findOrCreateUser in oauth2_common.go is called by both handlers and handles the ErrEmailExists retry; OAuth2Handler.LinkNonces is typed auth.OIDCLinkNonceStore; and handleLinkCallback is invoked with "oauth2_link_error" for OAuth2Handler and a different param for OIDCHandler. No code is touched, so there is no runtime risk.

No files require special attention.

Important Files Changed

Filename	Overview
docs/auth/index.md	Documents both oidc_link_error and oauth2_link_error query params for ErrOIDCSubjectAlreadyLinked; verified accurate against handleLinkCallback usage in oauth2.go.
docs/auth/store-interfaces.md	Extends CreateOIDCUser race-retry note and OIDCLinkNonceStore section to cover OAuth2Handler; both changes are consistent with the shared findOrCreateUser helper and OAuth2Handler.LinkNonces field.

Sequence Diagram

sequenceDiagram
    participant Client
    participant OAuth2Handler
    participant OIDCHandler
    participant findOrCreateUser
    participant handleLinkCallback
    participant UserStore

    Note over OAuth2Handler,OIDCHandler: Shared helpers (oauth2_common.go)

    Client->>OAuth2Handler: Callback (login flow)
    OAuth2Handler->>findOrCreateUser: subject, email, name
    findOrCreateUser->>UserStore: CreateOIDCUser()
    alt ErrEmailExists (race condition)
        UserStore-->>findOrCreateUser: ErrEmailExists
        findOrCreateUser->>UserStore: FindByOIDCSubject / FindByEmail (retry)
        UserStore-->>findOrCreateUser: existing user
    end
    findOrCreateUser-->>OAuth2Handler: "*User"

    Client->>OAuth2Handler: Callback (link flow)
    OAuth2Handler->>handleLinkCallback: "errorParam=oauth2_link_error"
    handleLinkCallback->>UserStore: LinkOIDCSubject()
    alt failure
        handleLinkCallback-->>Client: "redirect /?oauth2_link_error=Failed+to+link"
    else success
        handleLinkCallback-->>Client: "redirect /?oauth2_linked=true"
    end

    Client->>OIDCHandler: Callback (link flow)
    OIDCHandler->>handleLinkCallback: "errorParam=oidc_link_error"
    alt failure
        handleLinkCallback-->>Client: "redirect /?oidc_link_error=Failed+to+link"
    end

Loading

_{Reviews (2): Last reviewed commit: "docs(auth): qualify ErrEmailExists refer..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates auth package documentation to reflect that OAuth2Handler shares the same store contracts and account-linking helpers as OIDCHandler, and to document both handlers’ redirect error query parameters.

Changes:

• Clarify that both OIDCHandler and OAuth2Handler rely on CreateOIDCUser returning auth.ErrEmailExists for race-retry behavior.
• Document that OIDCLinkNonceStore is required for account linking in both handlers.
• Document both oidc_link_error and oauth2_link_error redirect query parameters for interactive link failures.

Show a summary per file

File	Description
docs/auth/store-interfaces.md	Expands store-interface docs to explicitly cover OAuth2Handler (race-retry note, link-nonce store requirement).
docs/auth/index.md	Updates sentinel error documentation to mention both handlers’ link-error redirect query parameters.

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