Cross-Domain Cookie Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/middleware.ts
• src/types.ts
• src/hooks.ts
• src/convex.ts

The Cross-Domain Cookie Strategy in the @pcstyle/auth SDK is designed to provide a unified authentication experience across multiple PCSTYLE subdomains. By utilizing WorkOS AuthKit and specific cookie configurations, the system ensures that a user authenticated on one subdomain (e.g., auth.pcstyle.dev) remains authenticated across others (e.g., app.pcstyle.dev), provided they share a common root domain.

This strategy relies on synchronized environment variables, middleware enforcement, and standardized domain configurations to maintain session persistence and security. It centralizes authentication logic while allowing individual services to remain decoupled.
Sources: README.md:10-20, src/types.ts:70-80

Core Architecture and Configuration

The cross-domain strategy is anchored by the WORKOS_COOKIE_DOMAIN and WORKOS_COOKIE_PASSWORD environment variables. These must be identical across all participating services to allow the browser to share and decrypt the session cookie.

Configuration Requirements

Variable	Description	Requirement
WORKOS_COOKIE_DOMAIN	The shared root domain for cookies.	Must start with a dot (e.g., .pcstyle.dev).
WORKOS_COOKIE_PASSWORD	Secret used to encrypt/decrypt cookies.	Must be 32+ characters and identical across services.
WORKOS_CLIENT_ID	Identifier for the WorkOS application.	Used for JWT validation and Convex integration.

Sources: README.md:10-20, src/types.ts:77-80

Domain Defaults

The SDK provides default configurations to ensure consistency across the PCSTYLE ecosystem:

• Default Auth Domain: https://auth.pcstyle.dev
• Default Cookie Domain: .pcstyle.dev

Sources: src/types.ts:76-81

Authentication Flow

The authentication flow utilizes a centralized authentication server. When a user is unauthenticated on a specific service, the middleware or client-side hooks redirect them to the primary auth domain.

Redirection Logic

The getSignInUrl helper facilitates this flow by constructing a URL that points to the centralized auth domain, optionally including a base64-encoded state to handle the return path after successful authentication.
Sources: src/hooks.ts:60-66

Implementation Components

Middleware Protection

The createAuthMiddleware function wraps the @workos-inc/authkit-nextjs middleware. It is responsible for intercepting requests and verifying the existence of a valid session cookie before allowing access to non-public paths.

export function createAuthMiddleware(options?: AuthMiddlewareOptions) {
    return authkitMiddleware({
        middlewareAuth: {
            enabled: true,
            unauthenticatedPaths: options?.publicPaths ?? [],
        },
    });
}

Sources: src/middleware.ts:24-32

Client-Side Integration

The useAuth and useUser hooks provide a reactive interface for the session state managed via the cross-domain cookie.

Convex Integration

For backend services using Convex, the strategy extends to JWT validation. The createConvexAuthConfig function generates a configuration that allows Convex to verify tokens issued by WorkOS, ensuring the cross-domain identity is respected at the data layer.
Sources: src/convex.ts:11-34

Security Considerations

The strategy relies on the following security measures:

1. Cookie Encryption: The WORKOS_COOKIE_PASSWORD ensures that while the cookie is shared across subdomains, it cannot be tampered with by the client.
2. Path Matching: The matcherConfig in the middleware prevents sensitive auth logic from running on static assets or internal Next.js paths.
3. Strict Contexts: The useUser hook throws an error if called outside an authenticated context, preventing accidental access to null user data.

Sources: README.md:16-19, src/middleware.ts:40-45, src/hooks.ts:44-50

The Cross-Domain Cookie Strategy enables a seamless SSO-like experience across the PCSTYLE platform by standardizing how subdomains interact with shared session data and centralized authentication services.