Authentication Flow

Relevant source files

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

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

The @pcstyle/auth SDK provides a unified authentication system for PCSTYLE services, built upon WorkOS AuthKit. It facilitates session management, cross-subdomain authentication via shared cookies, and integration with third-party services like Convex. The system ensures that users are authenticated across the .pcstyle.dev domain before accessing protected routes or resources.

The SDK architecture consists of Next.js middleware for route protection, React hooks for client-side state management, and configuration utilities for backend data providers. It relies on environment variables such as WORKOS_API_KEY, WORKOS_CLIENT_ID, and a shared WORKOS_COOKIE_PASSWORD to maintain security across different applications.
Sources: README.md:1-25, src/types.ts:74-82

Middleware and Route Protection

The authentication flow begins at the edge with Next.js middleware. The createAuthMiddleware function wraps the WorkOS authkitMiddleware to intercept incoming requests and enforce authentication requirements.

Request Lifecycle

When a request is made, the middleware checks if the requested path is defined within publicPaths. If the path is not public, the middleware validates the user's session. Unauthenticated users attempting to access protected paths are redirected to the sign-in portal.

The middleware is typically configured with a matcher to exclude static assets and internal Next.js paths.
Sources: src/middleware.ts:1-40, README.md:31-43

Client-Side Authentication State

Applications consume authentication data through React hooks. These hooks provide access to the current User object and the overall AuthState.

Auth Hooks

• useAuth(): Returns the current AuthState, including the user object, loading status, and a boolean isAuthenticated flag.
• useUser(): A convenience hook that returns the User object directly but throws an error if the user is not authenticated.

Navigation and URLs

The SDK provides helper functions to generate URLs for authentication actions, specifically managing the returnTo state to ensure users are redirected back to their original location after signing in.

Function	Destination	Description
getSignInUrl(returnTo?)	https://auth.pcstyle.dev	Generates a URL with an optional base64 encoded state for redirection.
getSignOutUrl()	https://auth.pcstyle.dev/signout	Directs the user to the global sign-out endpoint.

Sources: src/hooks.ts:47-64

Data Models

The system utilizes two primary user representations: the core identity provided by WorkOS and the application-specific record used within Convex databases.

User Structures

The User interface represents the identity provider's data, while ConvexUser includes database-specific metadata such as internal IDs and roles.

Field	Type	Source	Description
id	string	User	The WorkOS unique identifier.
email	string	Both	User's primary email address.
authId	string	ConvexUser	Mapping to the WorkOS ID.
role	string	ConvexUser	Application-level permission level.

Sources: src/types.ts:4-14, src/types.ts:39-50

Convex Integration

For backend services using Convex, the SDK provides a method to generate a JWT-based authentication configuration. This allows Convex to verify tokens issued by WorkOS using RS256 algorithms and JWKS (JSON Web Key Sets).

JWT Provider Configuration

The configuration includes two custom JWT providers to handle different WorkOS issuer formats, ensuring compatibility with various AuthKit versions.

Summary

The authentication flow in @pcstyle/auth centralizes identity management through a shared domain (auth.pcstyle.dev) and cross-subdomain cookies. By utilizing middleware for proactive protection and specialized hooks for reactive state management, the SDK ensures a consistent security posture across all PCSTYLE services. Integration with Convex further extends this identity flow to the data layer, allowing for secure, verified access to backend resources via JWT.
Sources: README.md:1-15, src/types.ts:74-82, src/index.ts:1-12