feat!: storage-owned PKCE verifier cookie with OAuth state binding

[nicknisi]

Summary

Introduces two tightly-coupled breaking changes against the OAuth sign-in flow:

1. PKCE state binding — the URL state parameter is now a sealed blob that is byte-compared against an HttpOnly wos-auth-verifier cookie before the code is exchanged. Prevents a stolen state from being replayed from a different browser / context.
2. Storage-owned verifier cookie — the verifier cookie is now plumbed through new SessionStorage primitives (getCookie / setCookie / clearCookie). Adapters no longer serialize, read, or delete the cookie manually; the library owns the lifecycle end-to-end.

See MIGRATION.md for the full migration guide.

API changes

New methods (replace the old URL builders)

Old	New
getAuthorizationUrl(...)	createAuthorization(response, ...)
getSignInUrl(...)	createSignIn(response, ...)
getSignUpUrl(...)	createSignUp(response, ...)

All three take a response argument and return { url, response?, headers? }. Storage either mutates response (adapters that override applyHeaders) or emits headers via the headers bag — callers forward whichever is populated.

handleCallback — simpler signature

Before:

await auth.handleCallback(request, response, { code, state, cookieValue });

After:

await auth.handleCallback(request, response, { code, state });

cookieValue is gone — handleCallback reads the verifier via storage.getCookie(request, 'wos-auth-verifier').

On success, result.headers carries a Set-Cookie entry as a string[] with two entries: the session cookie and the verifier-delete cookie. Adapters MUST .append each entry individually — never comma-join into a single header.

The header-bag key is case-insensitive: mergeHeaderBags preserves the adapter's casing, so check headers['Set-Cookie'] ?? headers['set-cookie'].

New: clearPendingVerifier

Used on error paths where handleCallback doesn't run (OAuth error responses, missing code, early bail-outs). Accepts TResponse | undefined — headers-only adapters can pass undefined.

const { headers } = await auth.clearPendingVerifier(response);

New typed errors

• OAuthStateMismatchError — URL state doesn't match the cookie
• PKCECookieMissingError — verifier cookie absent on callback
• (plus the existing SessionEncryptionError)

Cookie details

• HttpOnly, SameSite=Lax (downgraded from Strict so the cookie actually rides the cross-site OAuth redirect back)
• Secure inferred from redirectUri protocol (forced on when SameSite=None)
• Max-Age=600
• Path=/ so the cookie is visible in Chrome DevTools' Application panel from any page (path-scoped cookies are invisible from pages outside the scope, which made PKCE wiring look broken even when working end-to-end). HttpOnly + 10-minute TTL keeps exposure bounded.
• Sealed payload embeds issuedAt; unsealState enforces the 600s TTL independently of the SessionEncryption adapter's ttl handling, with 60s bounded clock-skew tolerance for multi-node deploys.

Removed

• getAuthorizationUrl / getSignInUrl / getSignUpUrl (replaced — see table above)
• decodeState — state is no longer a cleartext return-pathname carrier; use handleCallback's returned returnPathname instead
• serializePKCESetCookie / buildPKCEDeleteCookieHeader / getPKCECookieOptions / PKCECookieOptions / PKCE_COOKIE_NAME from the public surface — storage owns all of this internally

Also in this PR

• Case-insensitive `Set-Cookie` merge — adapters that normalize header keys through `Headers` objects (emitting lowercase `set-cookie`) no longer silently drop one cookie on callback.
• Browser-safe bundling — `AuthKitCore` no longer imports `node:crypto`; state byte-compare uses a web-crypto-compatible constant-time helper so the library bundles cleanly for edge/worker runtimes.
• `CookieSessionStorage` default cookie name aligned with `ConfigurationProvider` at `wos-session` (was `wos_session` in the fallback — divergent from the documented default; not user-visible on the `createAuthService` path, but the inconsistency is fixed).
• Dependency: `valibot` added for runtime schema validation of the unsealed PKCE state payload (defense-in-depth).

BREAKING CHANGE: every adapter consumer must update. See `MIGRATION.md`.

[Copilot]

Pull request overview

This PR hardens the OAuth flow by binding the OAuth state parameter to a short-lived PKCE verifier cookie, so callbacks must present both the URL state and the matching cookie before the code exchange proceeds.

Changes:

• Introduces PKCE state sealing/unsealing with TTL enforcement and new typed errors for state mismatch / missing cookie.
• Updates URL-generation APIs to return { url, sealedState, cookieOptions } and updates callback handling to require cookieValue.
• Adds PKCE cookie helpers (options + delete header builder) and updates public exports + docs/tests accordingly.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/service/factory.ts	Exposes new PKCE cookie helper methods on the service factory output.
src/service/factory.spec.ts	Verifies the factory output includes the new helper functions.
src/service/AuthService.ts	Adopts the new URL-generation result shape and enforces cookie-bound callback verification.
src/service/AuthService.spec.ts	Updates tests for the new URL result shape + cookie-bound callback flow and errors.
src/operations/AuthOperations.ts	Switches authorization URL generation to PKCE-backed generateAuthorizationUrl and returns the new triple shape.
src/operations/AuthOperations.spec.ts	Adds assertions for sealed state, cookie options, and PKCE params in the generated URL.
src/index.ts	Exports new PKCE helpers/constants and new error types as part of the public API.
src/core/session/types.ts	Extends SessionEncryption to support optional ttl and adds PKCE-related public types.
src/core/pkce/state.ts	Adds sealed PKCE state format with runtime validation + TTL enforcement.
src/core/pkce/state.spec.ts	Adds coverage for state round-tripping, tamper detection, schema validation, and TTL behavior.
src/core/pkce/pkce.spec.ts	Adds end-to-end PKCE round-trip coverage through generateAuthorizationUrl and verifyCallbackState.
src/core/pkce/index.ts	Creates a PKCE submodule export surface for internal/public consumption.
src/core/pkce/generateAuthorizationUrl.ts	Implements PKCE URL generation returning { url, sealedState, cookieOptions }.
src/core/pkce/cookieOptions.ts	Implements PKCE cookie option derivation + Set-Cookie serialization helper.
src/core/pkce/cookieOptions.spec.ts	Adds unit tests for cookie option derivation and Set-Cookie serialization.
src/core/pkce/constants.ts	Introduces PKCE cookie name and TTL constants.
src/core/errors.ts	Adds OAuthStateMismatchError and PKCECookieMissingError.
src/core/errors.spec.ts	Adds tests validating new error types and inheritance.
src/core/encryption/ironWebcryptoEncryption.ts	Adds TTL support to unsealData (and already supports TTL in sealing).
src/core/encryption/ironWebcryptoEncryption.spec.ts	Adds tests validating TTL enforcement behavior.
src/core/AuthKitCore.ts	Adds verifyCallbackState that checks state vs cookie before decrypting/unsealing.
src/core/AuthKitCore.spec.ts	Adds tests for verifyCallbackState error cases and refresh behaviors.
pnpm-lock.yaml	Locks the new valibot dependency.
package.json	Bumps version to 0.4.0 and adds valibot.
README.md	Documents the new PKCE cookie-bound flow, updated APIs, and adapter responsibilities.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 10 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

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

[greptile-apps]

Greptile Summary

This PR introduces PKCE state binding and storage-owned verifier cookie management for the OAuth sign-in flow. The sealed state blob doubles as both the OAuth state query parameter and the wos-auth-verifier cookie value, enabling a constant-time byte-comparison before decryption — a solid defense against cross-context state replay. The SessionStorage interface now owns the full verifier cookie lifecycle (getCookie/setCookie/clearCookie), and handleCallback emits a string[] Set-Cookie bag with case-insensitive merge handled via mergeHeaderBags.

Confidence Score: 4/5

Safe to merge after addressing the expires serialization gap and confirming JWT claim validation expectations.

Two P2 findings: serializeCookie silently drops CookieOptions.expires (data-loss for any adapter that sets expires instead of maxAge), and jwtVerify is called without explicit issuer/audience options (violates the team's JWT validation rule). Neither blocks the primary PKCE flow, but both are correctness gaps in new code introduced by this PR.

src/core/session/serializeCookie.ts (missing Expires attribute), src/core/AuthKitCore.ts (iss/aud claim validation)

Important Files Changed

Filename	Overview
src/core/session/serializeCookie.ts	New shared serializer for all Set-Cookie headers. Has a correctness gap: CookieOptions.expires is part of the public interface but is never emitted as an Expires= attribute.
src/core/AuthKitCore.ts	Core auth logic for JWT verification, session encryption/decryption, and the new verifyCallbackState for PKCE state binding. jwtVerify is called without explicit iss/aud options.
src/service/AuthService.ts	Orchestration layer; replaces old URL builders with createAuthorization/createSignIn/createSignUp, adds clearPendingVerifier and bestEffortClearVerifier, and implements the two-cookie Set-Cookie merge in handleCallback. Logic is well-thought-out with error-path cleanup.
src/core/pkce/state.ts	New PKCE state sealing/unsealing with valibot schema validation, dual TTL enforcement (adapter-layer + payload-level issuedAt), and 60s clock-skew tolerance. Implementation is solid.
src/core/pkce/generateAuthorizationUrl.ts	Generates PKCE-bound authorization URLs with two-layer size guards: an early check on caller-supplied state bytes and a post-seal check on the serialized cookie header length.
src/core/session/CookieSessionStorage.ts	Abstract base class now owns the full cookie lifecycle with the new getCookie/setCookie/clearCookie primitives. getCookie is correctly documented to require URL-decoded return values.
package.json	Adds valibot runtime dependency; MIGRATION.md is still absent from the files array (previously flagged as P1).

Sequence Diagram

sequenceDiagram
    participant C as Client/Browser
    participant A as Adapter
    participant S as AuthService
    participant Op as AuthOperations
    participant Enc as Encryption
    participant WOS as WorkOS API

    Note over C,WOS: Sign-in initiation
    C->>A: GET /sign-in
    A->>S: createSignIn(response, options)
    S->>Op: createAuthorization(options)
    Op->>WOS: pkce.generate()
    WOS-->>Op: { codeVerifier, codeChallenge }
    Op->>Enc: sealState({ nonce, codeVerifier, issuedAt, ... })
    Enc-->>Op: sealedState
    Op-->>S: { url, sealedState, cookieOptions }
    S->>S: storage.setCookie(response, wos-auth-verifier, sealedState)
    S-->>A: { url, response?, headers? }
    A->>C: Redirect to url + Set-Cookie: wos-auth-verifier=sealedState

    Note over C,WOS: OAuth callback
    C->>A: GET /callback?code=X&state=sealedState
    A->>S: handleCallback(request, response, { code, state })
    S->>S: storage.getCookie(request, wos-auth-verifier) cookieValue
    S->>S: verifyCallbackState({ stateFromUrl, cookieValue })
    Note right of S: constantTimeEqual(urlBytes, cookieBytes)
    S->>Enc: unsealState(cookieValue)
    Note right of Enc: schema validate + issuedAt TTL check
    Enc-->>S: { codeVerifier, returnPathname, ... }
    S->>WOS: authenticateWithCode({ code, codeVerifier })
    WOS-->>S: { accessToken, refreshToken, user }
    S->>Enc: encryptSession(session)
    S->>S: storage.saveSession(response, encryptedSession)
    S->>S: storage.clearCookie(response, wos-auth-verifier)
    S-->>A: { response?, headers: { Set-Cookie: [sessionCookie, verifierDelete] }, returnPathname }

Loading

_{Reviews (8): Last reviewed commit: "feat(pkce)!: reject oversized sealed sta..." | Re-trigger Greptile}