@workos-inc/authkit-nextjs 3.0.0-beta.1 → 3.0.1

package/src/interfaces.ts

@@ -1,5 +1,6 @@
 import type { AuthenticationResponse, OauthTokens, User } from '@workos-inc/node';
 import { type NextRequest } from 'next/server';
+import * as v from 'valibot';
 
 export interface HandleAuthOptions {
   returnPathname?: string;
@@ -61,6 +62,20 @@ export interface AccessToken {
   feature_flags?: string[];
 }
 
+export const StateSchema = v.object({
+  nonce: v.string(),
+  customState: v.optional(v.string()),
+  returnPathname: v.optional(v.string()),
+  codeVerifier: v.string(),
+});
+
+export type State = v.InferOutput<typeof StateSchema>;
+
+export interface GetAuthURLResult {
+  url: string;
+  sealedState: string;
+}
+
 export interface GetAuthURLOptions {
   screenHint?: 'sign-up' | 'sign-in';
   returnPathname?: string;

package/src/jwt.ts

@@ -2,16 +2,16 @@
  * JWT (JSON Web Token) Interface Definitions
  */
 export interface JWTHeader {
-  'alg': string;
-  'typ'?: string | undefined;
-  'cty'?: string | undefined;
-  'crit'?: Array<string | Exclude<keyof JWTHeader, 'crit'>> | undefined;
-  'kid'?: string | undefined;
-  'jku'?: string | undefined;
-  'x5u'?: string | string[] | undefined;
+  alg: string;
+  typ?: string | undefined;
+  cty?: string | undefined;
+  crit?: Array<string | Exclude<keyof JWTHeader, 'crit'>> | undefined;
+  kid?: string | undefined;
+  jku?: string | undefined;
+  x5u?: string | string[] | undefined;
   'x5t#S256'?: string | undefined;
-  'x5t'?: string | undefined;
-  'x5c'?: string | string[] | undefined;
+  x5t?: string | undefined;
+  x5c?: string | string[] | undefined;
 }
 /**
  * JWT Payload Interface

package/src/middleware-helpers.spec.ts

@@ -0,0 +1,238 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  handleAuthkitHeaders,
+  handleAuthkitProxy,
+  partitionAuthkitHeaders,
+  applyResponseHeaders,
+  isAuthkitRequestHeader,
+  AUTHKIT_REQUEST_HEADERS,
+} from './middleware-helpers.js';
+
+describe('middleware-helpers', () => {
+  function createMockRequest(url = 'https://example.com/test', method = 'GET'): NextRequest {
+    return new NextRequest(url, { method });
+  }
+
+  function createAuthkitHeaders(): Headers {
+    const headers = new Headers();
+    headers.set('x-workos-middleware', 'true');
+    headers.set('x-workos-session', 'encrypted-session-data');
+    headers.set('x-url', 'https://example.com/test');
+    headers.set('set-cookie', 'wos-session=abc123; Path=/; HttpOnly');
+    headers.set('cache-control', 'private, no-cache');
+    headers.set('vary', 'Cookie');
+    return headers;
+  }
+
+  describe('isAuthkitRequestHeader', () => {
+    it('should recognize known headers and x-workos-* pattern', () => {
+      expect(isAuthkitRequestHeader('x-workos-middleware')).toBe(true);
+      expect(isAuthkitRequestHeader('x-workos-session')).toBe(true);
+      expect(isAuthkitRequestHeader('x-url')).toBe(true);
+      expect(isAuthkitRequestHeader('x-workos-future-header')).toBe(true);
+      // Case insensitive
+      expect(isAuthkitRequestHeader('X-WorkOS-Session')).toBe(true);
+    });
+
+    it('should reject non-authkit headers', () => {
+      expect(isAuthkitRequestHeader('set-cookie')).toBe(false);
+      expect(isAuthkitRequestHeader('content-type')).toBe(false);
+      expect(isAuthkitRequestHeader('x-custom-header')).toBe(false);
+    });
+  });
+
+  describe('partitionAuthkitHeaders', () => {
+    it('should split headers into request-only and response headers', () => {
+      const request = createMockRequest();
+      const authkitHeaders = createAuthkitHeaders();
+
+      const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      // Request headers contain internal authkit headers
+      expect(requestHeaders.get('x-workos-session')).toBe('encrypted-session-data');
+      expect(requestHeaders.get('x-workos-middleware')).toBe('true');
+
+      // Response headers contain browser-safe headers only
+      expect(responseHeaders.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+      expect(responseHeaders.get('cache-control')).toBe('private, no-cache');
+      expect(responseHeaders.get('vary')).toBe('Cookie');
+
+      // Internal headers NOT in response
+      expect(responseHeaders.get('x-workos-session')).toBeNull();
+      expect(responseHeaders.get('x-workos-middleware')).toBeNull();
+    });
+
+    it('should preserve original request headers while adding authkit headers', () => {
+      const request = createMockRequest();
+      request.headers.set('authorization', 'Bearer token');
+      request.headers.set('x-custom', 'value');
+
+      const { requestHeaders } = partitionAuthkitHeaders(request, createAuthkitHeaders());
+
+      expect(requestHeaders.get('authorization')).toBe('Bearer token');
+      expect(requestHeaders.get('x-custom')).toBe('value');
+      expect(requestHeaders.get('x-workos-session')).toBe('encrypted-session-data');
+    });
+
+    it('should filter response headers to allowlist only', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('set-cookie', 'session=abc');
+      authkitHeaders.set('x-dangerous-header', 'leaked');
+      authkitHeaders.set('location', 'https://evil.com');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('set-cookie')).toBe('session=abc');
+      expect(responseHeaders.get('x-dangerous-header')).toBeNull();
+      expect(responseHeaders.get('location')).toBeNull();
+    });
+
+    it('should handle multiple Set-Cookie headers correctly', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.append('set-cookie', 'cookie1=value1');
+      authkitHeaders.append('set-cookie', 'cookie2=value2');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.getSetCookie()).toHaveLength(2);
+    });
+
+    it('should auto-add cache-control: no-store when cookies present without cache-control', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('set-cookie', 'session=abc');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('cache-control')).toBe('no-store');
+    });
+
+    it('should deduplicate and merge Vary header values', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.append('vary', 'Cookie');
+      authkitHeaders.append('vary', 'Cookie, Accept');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('vary')).toBe('Cookie, Accept');
+    });
+
+    it('should forward x-middleware-cache header', () => {
+      const request = createMockRequest();
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('x-middleware-cache', 'no-cache');
+
+      const { responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(responseHeaders.get('x-middleware-cache')).toBe('no-cache');
+    });
+
+    it('should strip client-injected x-workos-* headers and use trusted values', () => {
+      const request = createMockRequest();
+      request.headers.set('x-workos-session', 'malicious-session');
+      request.headers.set('x-workos-admin-bypass', 'true');
+
+      const authkitHeaders = new Headers();
+      authkitHeaders.set('x-workos-session', 'real-session');
+
+      const { requestHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+
+      expect(requestHeaders.get('x-workos-session')).toBe('real-session');
+      expect(requestHeaders.get('x-workos-admin-bypass')).toBeNull();
+    });
+  });
+
+  describe('handleAuthkitHeaders', () => {
+    it('should return NextResponse with response headers applied', () => {
+      const request = createMockRequest();
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders());
+
+      expect(response).toBeInstanceOf(NextResponse);
+      expect(response.status).toBe(200);
+      expect(response.headers.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+      expect(response.headers.get('vary')).toBe('Cookie');
+
+      // Internal headers NOT leaked
+      for (const header of AUTHKIT_REQUEST_HEADERS) {
+        expect(response.headers.get(header)).toBeNull();
+      }
+    });
+
+    it('should redirect with normalized absolute URL', () => {
+      const request = createMockRequest('https://example.com/page');
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders(), {
+        redirect: '/login',
+      });
+
+      expect(response.status).toBe(307);
+      expect(response.headers.get('location')).toBe('https://example.com/login');
+      expect(response.headers.get('set-cookie')).toBe('wos-session=abc123; Path=/; HttpOnly');
+    });
+
+    it('should use 307 for GET and 303 for POST redirects by default', () => {
+      const getRequest = createMockRequest('https://example.com/test', 'GET');
+      const postRequest = createMockRequest('https://example.com/test', 'POST');
+      const headers = createAuthkitHeaders();
+
+      const getResponse = handleAuthkitHeaders(getRequest, headers, { redirect: '/login' });
+      const postResponse = handleAuthkitHeaders(postRequest, headers, { redirect: '/login' });
+
+      expect(getResponse.status).toBe(307);
+      expect(postResponse.status).toBe(303);
+    });
+
+    it('should allow overriding redirect status', () => {
+      const request = createMockRequest();
+      const response = handleAuthkitHeaders(request, createAuthkitHeaders(), {
+        redirect: '/login',
+        redirectStatus: 302,
+      });
+
+      expect(response.status).toBe(302);
+    });
+
+    it('should throw clear error on invalid redirect URL', () => {
+      const request = createMockRequest();
+
+      expect(() =>
+        handleAuthkitHeaders(request, createAuthkitHeaders(), {
+          redirect: 'http://[invalid',
+        }),
+      ).toThrow('Invalid redirect URL: "http://[invalid". Must be a valid absolute or relative URL.');
+    });
+
+    it('should treat empty/undefined redirect as no redirect', () => {
+      const request = createMockRequest();
+      const headers = createAuthkitHeaders();
+
+      expect(handleAuthkitHeaders(request, headers, { redirect: '' }).status).toBe(200);
+      expect(handleAuthkitHeaders(request, headers, { redirect: undefined }).status).toBe(200);
+    });
+  });
+
+  describe('applyResponseHeaders', () => {
+    it('should merge headers onto existing response', () => {
+      const response = NextResponse.next();
+      response.headers.set('vary', 'Accept');
+      response.headers.set('set-cookie', 'existing=value');
+
+      const headers = new Headers();
+      headers.set('vary', 'Cookie');
+      headers.set('set-cookie', 'new=value');
+
+      applyResponseHeaders(response, headers);
+
+      expect(response.headers.get('vary')).toBe('Accept, Cookie');
+      expect(response.headers.getSetCookie()).toHaveLength(2);
+    });
+  });
+
+  describe('handleAuthkitHeaders (deprecated alias)', () => {
+    it('should be the same function reference as handleAuthkitProxy', () => {
+      expect(handleAuthkitHeaders).toBe(handleAuthkitProxy);
+    });
+  });
+});

package/src/middleware-helpers.ts

@@ -0,0 +1,134 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/** Internal AuthKit headers - forwarded to downstream requests but never sent to browser. */
+export const AUTHKIT_REQUEST_HEADERS = [
+  'x-workos-middleware',
+  'x-url',
+  'x-redirect-uri',
+  'x-sign-up-paths',
+  'x-workos-session',
+] as const;
+
+export type AuthkitRequestHeader = (typeof AUTHKIT_REQUEST_HEADERS)[number];
+
+const ALLOWED_RESPONSE_HEADERS: readonly string[] = [
+  'set-cookie',
+  'cache-control',
+  'vary',
+  'www-authenticate',
+  'proxy-authenticate',
+  'link',
+  'x-middleware-cache',
+];
+
+const MULTI_VALUE_HEADERS: readonly string[] = ['set-cookie', 'www-authenticate', 'proxy-authenticate', 'link'];
+
+export function isAuthkitRequestHeader(name: string): boolean {
+  const lower = name.toLowerCase();
+  return (AUTHKIT_REQUEST_HEADERS as readonly string[]).includes(lower) || lower.startsWith('x-workos-');
+}
+
+function setHeader(headers: Headers, name: string, value: string): void {
+  const lower = name.toLowerCase();
+  if (MULTI_VALUE_HEADERS.includes(lower)) {
+    headers.append(name, value);
+  } else if (lower === 'vary') {
+    const existing = headers.get(name);
+    const merged = new Set([
+      ...(existing ? existing.split(',').map((v) => v.trim()) : []),
+      ...value.split(',').map((v) => v.trim()),
+    ]);
+    headers.set(name, [...merged].join(', '));
+  } else {
+    headers.set(name, value);
+  }
+}
+
+export interface AuthkitHeadersResult {
+  requestHeaders: Headers;
+  responseHeaders: Headers;
+}
+
+/**
+ * Partitions AuthKit headers into request headers (for withAuth) and response headers (for browser).
+ */
+export function partitionAuthkitHeaders(request: NextRequest, authkitHeaders: Headers): AuthkitHeadersResult {
+  const headers = new Headers(authkitHeaders);
+  const requestHeaders = new Headers(request.headers);
+
+  // Snapshot keys before iterating, since we delete headers during the loop
+  const requestHeaderKeys = Array.from(requestHeaders.keys());
+  for (const name of requestHeaderKeys) {
+    if (isAuthkitRequestHeader(name)) {
+      requestHeaders.delete(name);
+    }
+  }
+  for (const headerName of AUTHKIT_REQUEST_HEADERS) {
+    const value = headers.get(headerName);
+    if (value != null) {
+      requestHeaders.set(headerName, value);
+    }
+  }
+
+  // Build response headers from allowlist only
+  const responseHeaders = new Headers();
+  for (const [name, value] of headers) {
+    const lower = name.toLowerCase();
+    if (!isAuthkitRequestHeader(lower) && ALLOWED_RESPONSE_HEADERS.includes(lower)) {
+      setHeader(responseHeaders, name, value);
+    }
+  }
+
+  // Auto-add cache-control when setting cookies
+  if (responseHeaders.has('set-cookie') && !responseHeaders.has('cache-control')) {
+    responseHeaders.set('cache-control', 'no-store');
+  }
+
+  return { requestHeaders, responseHeaders };
+}
+
+export function applyResponseHeaders(response: NextResponse, responseHeaders: Headers): NextResponse {
+  for (const [name, value] of responseHeaders) {
+    setHeader(response.headers, name, value);
+  }
+  return response;
+}
+
+export type AuthkitRedirectStatus = 302 | 303 | 307 | 308;
+
+export interface HandleAuthkitHeadersOptions {
+  /** URL to redirect to (relative or absolute). */
+  redirect?: string | URL;
+
+  /** Redirect status code. @default 307 for GET/HEAD, 303 for POST/PUT/DELETE */
+  redirectStatus?: AuthkitRedirectStatus;
+}
+
+/**
+ * Creates a NextResponse with properly merged AuthKit headers.
+ */
+export function handleAuthkitProxy(
+  request: NextRequest,
+  authkitHeaders: Headers,
+  options: HandleAuthkitHeadersOptions = {},
+): NextResponse {
+  const { requestHeaders, responseHeaders } = partitionAuthkitHeaders(request, authkitHeaders);
+  const { redirect, redirectStatus } = options;
+
+  if (redirect != null && redirect !== '') {
+    let redirectUrl: URL;
+    try {
+      redirectUrl = redirect instanceof URL ? redirect : new URL(redirect, request.url);
+    } catch {
+      throw new Error(`Invalid redirect URL: "${redirect}". Must be a valid absolute or relative URL.`);
+    }
+    const method = request.method.toUpperCase();
+    const status = redirectStatus ?? (method === 'GET' || method === 'HEAD' ? 307 : 303);
+    return applyResponseHeaders(NextResponse.redirect(redirectUrl, status), responseHeaders);
+  }
+
+  return applyResponseHeaders(NextResponse.next({ request: { headers: requestHeaders } }), responseHeaders);
+}
+
+/** @deprecated Use `handleAuthkitProxy` instead. */
+export const handleAuthkitHeaders: typeof handleAuthkitProxy = handleAuthkitProxy;

package/src/middleware.spec.ts

@@ -0,0 +1,25 @@
+import { authkitMiddleware, authkitProxy } from './middleware.js';
+
+describe('middleware', () => {
+  describe('authkitProxy', () => {
+    it('should return a middleware function when called with no options', () => {
+      const middleware = authkitProxy();
+      expect(typeof middleware).toBe('function');
+    });
+
+    it('should accept the same options as authkitMiddleware', () => {
+      const middleware = authkitProxy({
+        debug: true,
+        middlewareAuth: { enabled: true, unauthenticatedPaths: ['/public'] },
+        signUpPaths: ['/sign-up'],
+      });
+      expect(typeof middleware).toBe('function');
+    });
+  });
+
+  describe('authkitMiddleware (deprecated alias)', () => {
+    it('should be the same function reference as authkitProxy', () => {
+      expect(authkitMiddleware).toBe(authkitProxy);
+    });
+  });
+});

package/src/middleware.ts

@@ -3,7 +3,7 @@ import { updateSessionMiddleware, updateSession } from './session.js';
 import { AuthkitMiddlewareOptions, AuthkitOptions, AuthkitResponse } from './interfaces.js';
 import { WORKOS_REDIRECT_URI } from './env-variables.js';
 
-export function authkitMiddleware({
+export function authkitProxy({
   debug = false,
   middlewareAuth = { enabled: false, unauthenticatedPaths: [] },
   redirectUri = WORKOS_REDIRECT_URI,
@@ -15,6 +15,9 @@ export function authkitMiddleware({
   };
 }
 
+/** @deprecated Use `authkitProxy` instead. */
+export const authkitMiddleware: typeof authkitProxy = authkitProxy;
+
 export async function authkit(request: NextRequest, options: AuthkitOptions = {}): Promise<AuthkitResponse> {
   return await updateSession(request, options);
 }

package/src/pkce.spec.ts

@@ -0,0 +1,146 @@
+import { sealData } from 'iron-session';
+import { getStateFromPKCECookieValue, getPKCECookieNameForState } from './pkce.js';
+
+const PASSWORD = process.env.WORKOS_COOKIE_PASSWORD!;
+
+describe('getPKCECookieNameForState', () => {
+  it('should derive a cookie name prefixed with the base name', () => {
+    const state = 'any-string-at-all';
+
+    expect(getPKCECookieNameForState(state)).toMatch(/^wos-auth-verifier-[0-9a-f]{8}$/);
+  });
+
+  it('should produce different names for different states', () => {
+    const stateA = 'first-sealed-state-value';
+    const stateB = 'second-sealed-state-value';
+
+    expect(getPKCECookieNameForState(stateA)).not.toBe(getPKCECookieNameForState(stateB));
+  });
+
+  it('should be deterministic for the same input', () => {
+    const state = 'some-sealed-state';
+
+    expect(getPKCECookieNameForState(state)).toBe(getPKCECookieNameForState(state));
+  });
+});
+
+describe('setPKCECookie SameSite override', () => {
+  const mockSet = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    vi.doMock('next/headers', () => ({
+      cookies: async () => ({ set: mockSet, get: vi.fn(), getAll: vi.fn(), delete: vi.fn() }),
+      headers: async () => ({ get: vi.fn(), set: vi.fn(), delete: vi.fn() }),
+    }));
+    vi.doMock('./env-variables', async (importOriginal) => {
+      return { ...(await importOriginal<typeof import('./env-variables')>()) };
+    });
+  });
+
+  it('should downgrade strict to lax', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'strict' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      getPKCECookieNameForState('sealed-state'),
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+
+  it('should preserve none for iframe/cross-origin flows', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'none' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      getPKCECookieNameForState('sealed-state'),
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'none' }),
+    );
+  });
+
+  it('should downgrade mixed-case Strict to lax', async () => {
+    const envVars = await import('./env-variables');
+    Object.defineProperty(envVars, 'WORKOS_COOKIE_SAMESITE', { value: 'Strict' });
+
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      getPKCECookieNameForState('sealed-state'),
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+
+  it('should default to lax when no SameSite configured', async () => {
+    const { setPKCECookie } = await import('./pkce');
+    await setPKCECookie('sealed-state');
+
+    expect(mockSet).toHaveBeenCalledWith(
+      getPKCECookieNameForState('sealed-state'),
+      'sealed-state',
+      expect.objectContaining({ sameSite: 'lax' }),
+    );
+  });
+});
+
+describe('getStateFromPKCECookieValue', () => {
+  it('should unseal and validate a valid state', async () => {
+    const sealed = await sealData(
+      { nonce: 'test-nonce', codeVerifier: 'verifier-abc', returnPathname: '/dashboard', customState: 'custom' },
+      { password: PASSWORD },
+    );
+
+    const state = await getStateFromPKCECookieValue(sealed);
+
+    expect(state.nonce).toBe('test-nonce');
+    expect(state.returnPathname).toBe('/dashboard');
+    expect(state.customState).toBe('custom');
+  });
+
+  it('should unseal state with codeVerifier', async () => {
+    const sealed = await sealData({ nonce: 'test-nonce', codeVerifier: 'verifier-123' }, { password: PASSWORD });
+
+    const state = await getStateFromPKCECookieValue(sealed);
+
+    expect(state.nonce).toBe('test-nonce');
+    expect(state.codeVerifier).toBe('verifier-123');
+  });
+
+  it('should throw when codeVerifier is missing', async () => {
+    const sealed = await sealData({ nonce: 'test-nonce', returnPathname: '/dashboard' }, { password: PASSWORD });
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+
+  it('should throw when nonce is missing', async () => {
+    const sealed = await sealData(
+      { codeVerifier: 'verifier-abc', returnPathname: '/dashboard' },
+      { password: PASSWORD },
+    );
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+
+  it('should throw when sealed data is corrupted', async () => {
+    await expect(getStateFromPKCECookieValue('not-a-valid-sealed-value')).rejects.toThrow();
+  });
+
+  it('should throw when sealed with a different password', async () => {
+    const sealed = await sealData(
+      { nonce: 'test-nonce', codeVerifier: 'verifier-abc' },
+      { password: 'a-different-password-that-is-32-chars!' },
+    );
+
+    await expect(getStateFromPKCECookieValue(sealed)).rejects.toThrow();
+  });
+});

package/src/pkce.ts

@@ -0,0 +1,59 @@
+import fnv1a from '@sindresorhus/fnv1a';
+import { unsealData } from 'iron-session';
+import { cookies } from 'next/headers';
+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-auth-verifier';
+
+/**
+ * Short, deterministic hex fingerprint of an arbitrary string.
+ * Used to give each PKCE flow its own cookie name without depending
+ * on the internal format of the sealed state value
+ */
+function shortHash(input: string): string {
+  // fnv1a returns a BigInt — use 32-bit variant so it fits safely in a Number
+  const hash = Number(fnv1a(input, { size: 32 }));
+
+  // Hex-encode and pad to a fixed 8-char width
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * Derive a flow-specific cookie name so concurrent auth flows don't overwrite
+ * each other's PKCE cookies. Uses an FNV-1a hash of the full sealed state
+ */
+export function getPKCECookieNameForState(state: string): string {
+  return `${PKCE_COOKIE_NAME}-${shortHash(state)}`;
+}
+
+/**
+ * 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(sealedState: string): Promise<void> {
+  const nextCookies = await cookies();
+  const options = getPKCECookieOptions();
+
+  nextCookies.set(getPKCECookieNameForState(sealedState), sealedState, {
+    ...options,
+    httpOnly: true,
+  });
+}
+
+/**
+ * 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 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);
+}