@workos-inc/authkit-nextjs 2.17.0 → 3.0.0

package/src/pkce.ts

@@ -1,20 +1,22 @@
 import { unsealData } from 'iron-session';
 import { cookies } from 'next/headers';
-import { getCookieOptions } from './cookie.js';
+import * as v from 'valibot';
+import { getPKCECookieOptions } from './cookie.js';
 import { WORKOS_COOKIE_PASSWORD } from './env-variables.js';
+import { State, StateSchema } from './interfaces.js';
 
-export const PKCE_COOKIE_NAME = 'wos-pkce-verifier';
+export const PKCE_COOKIE_NAME = 'wos-auth-verifier';
 const PKCE_COOKIE_MAX_AGE = 600; // 10 minutes
 
 /**
  * Set the PKCE verifier cookie in server action context.
  * In middleware context, callers must set the cookie via Set-Cookie headers instead.
  */
-export async function setPKCECookie(pkceCookieValue: string | undefined): Promise<void> {
-  if (!pkceCookieValue) return;
+export async function setPKCECookie(sealedState: string): Promise<void> {
   const nextCookies = await cookies();
-  const { domain, path, sameSite, secure } = getCookieOptions();
-  nextCookies.set(PKCE_COOKIE_NAME, pkceCookieValue, {
+  const { domain, path, sameSite, secure } = getPKCECookieOptions();
+
+  nextCookies.set(PKCE_COOKIE_NAME, sealedState, {
     domain,
     path,
     sameSite,
@@ -25,18 +27,16 @@ export async function setPKCECookie(pkceCookieValue: string | undefined): Promis
 }
 
 /**
- * Read and unseal the PKCE code verifier from the cookie.
- * Returns undefined if the cookie is missing or corrupted.
+ * Read and unseal the auth cookie containing PKCE code verifier and OAuth state.
+ * Throws if the cookie is not in the required state
  */
-export async function getPKCECodeVerifier(cookieValue: string | undefined): Promise<string | undefined> {
-  if (!cookieValue) return undefined;
-  try {
-    const unsealed = await unsealData<{ codeVerifier: string }>(cookieValue, {
-      password: WORKOS_COOKIE_PASSWORD,
-    });
-    return unsealed.codeVerifier;
-  } catch {
-    // Cookie corrupted or expired — caller will proceed without PKCE
-    return undefined;
-  }
+export async function getStateFromPKCECookieValue(cookieValue: string): Promise<State> {
+  // NOTE: TypeScript compiler won't flag if we Seal different data in than we Unseal
+  // Also, this function is not in a critically-high-performance path, so runtime validation
+  // is an acceptable tradeoff for increased security and type-safety
+  const unsealed = await unsealData(cookieValue, {
+    password: WORKOS_COOKIE_PASSWORD,
+  });
+
+  return v.parse(StateSchema, unsealed);
 }

package/src/session.spec.ts

@@ -1,3 +1,4 @@
+import type { Mock, MockInstance } from 'vitest';
 import { NextRequest, NextResponse } from 'next/server';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
@@ -7,8 +8,14 @@ import { getWorkOS } from './workos.js';
 import * as envVariables from './env-variables.js';
 
 import { jwtVerify } from 'jose';
+
+// Helper to override env variable exports without triggering no-import-assign on the import binding
+function setEnvVar(mod: Record<string, unknown>, key: string, value: unknown) {
+  Object.defineProperty(mod, key, { value, configurable: true });
+}
 import { sealData } from 'iron-session';
 import { User } from '@workos-inc/node';
+import { getStateFromPKCECookieValue } from './pkce.js';
 
 vi.mock('jose', async () => {
   const actual = await vi.importActual<typeof import('jose')>('jose');
@@ -147,14 +154,12 @@ describe('session.ts', () => {
 
       await withAuth({ ensureSignedIn: true });
 
-      // URL-safe base64 encoding
-      const pathname = encodeURIComponent(
-        btoa(JSON.stringify({ returnPathname: '/protected?test=123' }))
-          .replace(/\+/g, '-')
-          .replace(/\//g, '_'),
-      );
+      // The state is now sealed, se we need to unseal it
+      const redirectUrl = new URL((redirect as unknown as Mock).mock.calls[0][0]);
+      const sealedState = redirectUrl.searchParams.get('state')!;
+      const { returnPathname } = await getStateFromPKCECookieValue(sealedState);
 
-      expect(redirect).toHaveBeenCalledWith(expect.stringContaining(pathname));
+      expect(returnPathname).toBe('/protected?test=123');
     });
   });
 
@@ -162,7 +167,7 @@ describe('session.ts', () => {
     it('should throw an error if the redirect URI is not set', async () => {
       const originalWorkosRedirectUri = envVariables.WORKOS_REDIRECT_URI;
 
-      Object.defineProperty(envVariables, 'WORKOS_REDIRECT_URI', { value: '', configurable: true });
+      setEnvVar(envVariables, 'WORKOS_REDIRECT_URI', '');
 
       await expect(async () => {
         await updateSessionMiddleware(
@@ -177,16 +182,13 @@ describe('session.ts', () => {
         );
       }).rejects.toThrow('You must provide a redirect URI in the AuthKit middleware or in the environment variables.');
 
-      Object.defineProperty(envVariables, 'WORKOS_REDIRECT_URI', {
-        value: originalWorkosRedirectUri,
-        configurable: true,
-      });
+      setEnvVar(envVariables, 'WORKOS_REDIRECT_URI', originalWorkosRedirectUri);
     });
 
     it('should throw an error if the cookie password is not set', async () => {
       const originalWorkosCookiePassword = envVariables.WORKOS_COOKIE_PASSWORD;
 
-      Object.defineProperty(envVariables, 'WORKOS_COOKIE_PASSWORD', { value: '', configurable: true });
+      setEnvVar(envVariables, 'WORKOS_COOKIE_PASSWORD', '');
 
       await expect(async () => {
         await updateSessionMiddleware(
@@ -203,16 +205,13 @@ describe('session.ts', () => {
         'You must provide a valid cookie password that is at least 32 characters in the environment variables.',
       );
 
-      Object.defineProperty(envVariables, 'WORKOS_COOKIE_PASSWORD', {
-        value: originalWorkosCookiePassword,
-        configurable: true,
-      });
+      setEnvVar(envVariables, 'WORKOS_COOKIE_PASSWORD', originalWorkosCookiePassword);
     });
 
     it('should throw an error if the cookie password is less than 32 characters', async () => {
       const originalWorkosCookiePassword = envVariables.WORKOS_COOKIE_PASSWORD;
 
-      Object.defineProperty(envVariables, 'WORKOS_COOKIE_PASSWORD', { value: 'short', configurable: true });
+      setEnvVar(envVariables, 'WORKOS_COOKIE_PASSWORD', 'short');
 
       await expect(async () => {
         await updateSessionMiddleware(
@@ -229,10 +228,7 @@ describe('session.ts', () => {
         'You must provide a valid cookie password that is at least 32 characters in the environment variables.',
       );
 
-      Object.defineProperty(envVariables, 'WORKOS_COOKIE_PASSWORD', {
-        value: originalWorkosCookiePassword,
-        configurable: true,
-      });
+      setEnvVar(envVariables, 'WORKOS_COOKIE_PASSWORD', originalWorkosCookiePassword);
     });
 
     it('should return early if there is no session', async () => {

package/src/session.ts

@@ -5,7 +5,7 @@ import { JWTPayload, createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';
 import { cookies, headers } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { NextRequest } from 'next/server';
-import { getCookieOptions, getJwtCookie } from './cookie.js';
+import { getCookieOptions, getJwtCookie, getPKCECookieOptions } from './cookie.js';
 import { WORKOS_CLIENT_ID, WORKOS_COOKIE_NAME, WORKOS_COOKIE_PASSWORD, WORKOS_REDIRECT_URI } from './env-variables.js';
 import { TokenRefreshError, getSessionErrorContext } from './errors.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
@@ -26,10 +26,8 @@ import { parse, tokensToRegexp } from 'path-to-regexp';
 import { handleAuthkitHeaders } from './middleware-helpers.js';
 import { lazy, setCachePreventionHeaders } from './utils.js';
 
-function appendPKCESetCookieHeader(headers: Headers, pkceCookieValue: string | undefined, requestUrl: string): void {
-  if (pkceCookieValue) {
-    headers.append('Set-Cookie', `${PKCE_COOKIE_NAME}=${pkceCookieValue}; ${getCookieOptions(requestUrl, true)}`);
-  }
+function appendPKCESetCookieHeader(headers: Headers, sealedState: string, requestUrl: string): void {
+  headers.append('Set-Cookie', `${PKCE_COOKIE_NAME}=${sealedState}; ${getPKCECookieOptions(requestUrl, true)}`);
 }
 
 const sessionHeaderName = 'x-workos-session';
@@ -209,13 +207,13 @@ async function updateSession(
       console.log('No session found from cookie');
     }
 
-    const { url: authorizationUrl, pkceCookieValue } = await getAuthorizationUrl({
+    const { url: authorizationUrl, sealedState } = await getAuthorizationUrl({
       returnPathname: getReturnPathname(request.url),
       redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
       screenHint: options.screenHint,
     });
 
-    appendPKCESetCookieHeader(newRequestHeaders, pkceCookieValue, request.url);
+    appendPKCESetCookieHeader(newRequestHeaders, sealedState, request.url);
 
     return {
       session: { user: null },
@@ -351,12 +349,12 @@ async function updateSession(
 
     options.onSessionRefreshError?.({ error: e, request });
 
-    const { url: authorizationUrl, pkceCookieValue } = await getAuthorizationUrl({
+    const { url: authorizationUrl, sealedState } = await getAuthorizationUrl({
       returnPathname: getReturnPathname(request.url),
       redirectUri: options.redirectUri || WORKOS_REDIRECT_URI,
     });
 
-    appendPKCESetCookieHeader(newRequestHeaders, pkceCookieValue, request.url);
+    appendPKCESetCookieHeader(newRequestHeaders, sealedState, request.url);
 
     return {
       session: { user: null },
@@ -468,8 +466,8 @@ async function redirectToSignIn() {
 
   const returnPathname = getReturnPathname(url);
 
-  const { url: authkitUrl, pkceCookieValue } = await getAuthorizationUrl({ returnPathname, screenHint });
-  await setPKCECookie(pkceCookieValue);
+  const { url: authkitUrl, sealedState } = await getAuthorizationUrl({ returnPathname, screenHint });
+  await setPKCECookie(sealedState);
   redirect(authkitUrl);
 }
 
@@ -567,7 +565,7 @@ async function getSessionFromHeader(): Promise<Session | undefined> {
 function getReturnPathname(url: string): string {
   const newUrl = new URL(url);
 
-  return `${newUrl.pathname}${newUrl.searchParams.size > 0 ? '?' + newUrl.searchParams.toString() : ''}`;
+  return `${newUrl.pathname}${newUrl.search}`;
 }
 
 function getScreenHint(signUpPaths: string[] | undefined, pathname: string) {