fix: Improve PKCE cookie missing error message

[devin-ai-integration]

Summary

Replaces the technical PKCECookieMissingError message with a user-friendly, solution-oriented alternative.

Before: "PKCE verifier cookie missing — cannot verify OAuth state. Ensure Set-Cookie headers are propagated on redirects."

After: "Sign-in session could not be verified. Please try signing in again."

The old message exposed internal implementation details (PKCE, OAuth state, Set-Cookie headers) that aren't actionable for end users. The new message covers all failure scenarios (session expiry, proxy stripping cookies, etc.) and directs the user toward the correct resolution without leaking technical specifics.

Link to Devin session: https://app.devin.ai/sessions/a078971ce8c94657a457d1a099232333

[devin-ai-integration]

Original prompt from garen.torikian

SYSTEM:
=== BEGIN THREAD HISTORY (in #docs-and-sdks) ===
Kat Brandt (U0A6AKYK3UJ): Question for ya. <https://work-os.slack.com/archives/C0A9L6W70FL/p1781717750368979?thread_ts=1780039505.992099&amp;amp;cid=C0A9L6W70FL|This customer> , using authkit-nextjs, is experiencing an error when their email verification code expires, which is expected, but I'm wondering if it would be helpful to change up the error message.
The error they're getting is "Error: Auth cookie missing - cannot verify OAuth state. Ensure Set-Cookie headers are propagated on redirects."

The customer says "It looks like authkit is dropping some authentication cookie before navigating to the workos hosted login screen or something like that and then expecting that cookie to exist and when it had expired prior, that error message is displayed."
I don't think that's why this is happening, in talking with Cursor, this is expected behavior. What's happening is the customer is leaving the tab idle for too long, so not only is the email code expiring, but so is the PKCE cookie, but perhaps a better error message could be displayed when we detect “state present, cookie missing” and show something like “Your sign-in session expired. Please try again.” instead of the proxy-oriented message.

Do you agree with this assessment? And is changing the error message something we'd consider?

RoboHawk (U09V0J0LDEF): <https://app.plain.com/workspace/w_01KEZ48Y1GZPN4PXQ41666E911/thread/th_01KSS9YV490YH8Y9AHJ0X0DQ3K/|Related Plain ticket>

Garen Torikian (U0A6717PLA1): i think it's Complicated ™️

looks like this error is thrown <https://github.com/workos/authkit-session/blame/02bdbc92f998b51179930060ac21cf7e84d4e554/src/core/AuthKitCore.ts`#`L197|whenever the cookie can't be verified>.

so expiring sign-in session is one possibility, but not the only possibility. i suppose the message could change to not give such a technical "Ensure Set-Cookie headers are propagated" response and advise on a re-login? wdyt?

Kat Br... (960 chars truncated...)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Greptile Summary

This PR changes a single error message string inside PKCECookieMissingError to be more user-friendly, replacing a developer-oriented diagnostic string with a generic "Sign-in session could not be verified" message. No logic, exports, or tests are altered.

• The error class (PKCECookieMissingError) is part of the public API and its technical meaning is still documented in the method JSDoc and in MIGRATION.md; integrators are expected to catch it and redirect rather than surface the message to users.
• All existing tests assert on the error class name, not the message, so they continue to pass unchanged.

Confidence Score: 5/5

A one-line string change in an error message; no control flow, exports, or test assertions are touched.

The only change is swapping the PKCECookieMissingError message text. The error class name, type hierarchy, and all call sites are untouched. Tests match on the error class name property, not the message, so nothing breaks. The tradeoff of losing diagnostic detail in the message is minor given the JSDoc and migration docs still carry that information.

No files require special attention.

Important Files Changed

Filename	Overview
src/core/AuthKitCore.ts	Single-line change: replaces the PKCECookieMissingError message with a user-friendly string; no logic changes, tests remain valid

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Browser
    participant Adapter
    participant AuthKitCore
    participant WorkOS

    Browser->>Adapter: "GET /callback?code=...&state=..."
    Adapter->>AuthKitCore: "verifyCallbackState({ stateFromUrl, cookieValue })"
    alt cookieValue is missing
        AuthKitCore-->>Adapter: throw PKCECookieMissingError("Sign-in session could not be verified...")
        Adapter-->>Browser: Redirect to sign-in
    else cookieValue present but mismatched
        AuthKitCore-->>Adapter: throw OAuthStateMismatchError
        Adapter-->>Browser: Redirect to sign-in
    else verification passes
        AuthKitCore->>WorkOS: Exchange code for tokens
        WorkOS-->>AuthKitCore: access_token + refresh_token
        AuthKitCore-->>Adapter: session + Set-Cookie headers
        Adapter-->>Browser: 200 OK (session cookie set)
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Browser
    participant Adapter
    participant AuthKitCore
    participant WorkOS

    Browser->>Adapter: "GET /callback?code=...&state=..."
    Adapter->>AuthKitCore: "verifyCallbackState({ stateFromUrl, cookieValue })"
    alt cookieValue is missing
        AuthKitCore-->>Adapter: throw PKCECookieMissingError("Sign-in session could not be verified...")
        Adapter-->>Browser: Redirect to sign-in
    else cookieValue present but mismatched
        AuthKitCore-->>Adapter: throw OAuthStateMismatchError
        Adapter-->>Browser: Redirect to sign-in
    else verification passes
        AuthKitCore->>WorkOS: Exchange code for tokens
        WorkOS-->>AuthKitCore: access_token + refresh_token
        AuthKitCore-->>Adapter: session + Set-Cookie headers
        Adapter-->>Browser: 200 OK (session cookie set)
    end

Loading

_{Reviews (1): Last reviewed commit: "Improve PKCE cookie missing error messag..." | Re-trigger Greptile}

[greptile-apps]

Developer-facing context removed from diagnostic message

PKCECookieMissingError is a publicly exported error class that library integrators are expected to catch and handle (e.g., redirect to sign-in). In a properly implemented adapter the message never reaches end users, so the old phrasing ("Ensure Set-Cookie headers are propagated on redirects") served as actionable debug guidance for developers integrating this SDK. The new message is less useful when someone is actively debugging a proxy/cookie-stripping issue and has not yet caught or read the JSDoc. Worth keeping in mind if the team plans to use this message in telemetry or logging — it will no longer carry the root-cause signal.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[devin-ai-integration]

Acknowledged — this is an intentional tradeoff. The error class name (PKCECookieMissingError) and JSDoc already carry the diagnostic signal for integrators who catch it. The message change targets the case where the error propagates to an end user (e.g., via a framework that surfaces error.message without custom handling). The original proxy-oriented guidance remains documented in MIGRATION.md for anyone debugging cookie-stripping issues.