Server-Side Authentication

Relevant source files

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

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

Server-side authentication in the @pcstyle/auth SDK provides a unified mechanism for securing PCSTYLE services using WorkOS AuthKit. It primarily handles identity verification at the edge via Next.js middleware and provides backend configuration for third-party services like Convex. The system ensures that users are authenticated before reaching protected routes and manages session consistency across different subdomains.

The architecture relies on a shared cookie domain (.pcstyle.dev) and environment-specific keys to synchronize authentication states between the frontend, the server-side middleware, and backend data providers.
Sources: README.md:1-12, src/types.ts:71-76

Middleware Architecture

The server-side authentication flow is initiated through a specialized Next.js middleware. This middleware intercepts incoming requests to determine if the user has a valid session. It uses the authkitMiddleware from WorkOS to validate tokens and manage redirection for unauthenticated requests.

Authentication Flow

The following diagram illustrates how the middleware processes a request and determines access based on the configured public paths.

The middleware uses AuthMiddlewareOptions to define which paths should bypass authentication checks.
Sources: src/middleware.ts:24-32, src/types.ts:33-49

Middleware Configuration

Developers can configure the middleware by specifying publicPaths. By default, the middleware is pre-configured with a recommended matcher for Next.js to exclude static assets and internal paths.

Option	Type	Description
publicPaths	string[]	Paths that do not require authentication.
redirectUri	string	Custom redirect URI for OAuth callbacks (Default: https://auth.pcstyle.dev/callback).
signInUrl	string	The primary sign-in URL.

Sources: src/middleware.ts:40-42, src/types.ts:36-48

Convex Backend Integration

For server-side logic residing in Convex, the SDK provides a specialized configuration generator. This allows Convex to verify JWTs issued by WorkOS, enabling secure data access within Convex functions.

JWT Provider Configuration

The createConvexAuthConfig function generates a configuration object containing two providers. Both utilize the RS256 algorithm and fetch public keys from WorkOS JWKS endpoints.

Convex Config Structure

The configuration requires a WORKOS_CLIENT_ID to construct the appropriate issuer and JWKS URLs.

// Example configuration generated for Convex
{
    providers: [
        {
            type: 'customJwt',
            issuer: 'https://api.workos.com/',
            algorithm: 'RS256',
            applicationID: clientId,
            jwks: `https://api.workos.com/sso/jwks/${clientId}`,
        },
        // ...additional provider for user management
    ]
}

Sources: src/convex.ts:16-32

Data Models and Types

The server-side system operates on several key data structures representing the user and the session state.

User Object

The User type represents the core identity data returned from WorkOS.

Field	Type	Description
id	string	Unique identifier for the user.
email	string	User's email address.
firstName	string | null	User's given name.
lastName	string | null	User's family name.
profilePictureUrl	string | null	URL to the user's avatar.

Sources: src/types.ts:4-12

Convex User Record

When users are persisted in the Convex database, they follow the ConvexUser interface, which includes metadata like roles and timestamps.
Sources: src/types.ts:54-63

Server-Side Environment Requirements

For server-side authentication to function correctly across the pcstyle.dev ecosystem, specific environment variables must be configured on the hosting server.

Variable	Importance	Description
WORKOS_API_KEY	Required	Secret key for backend WorkOS communication.
WORKOS_CLIENT_ID	Required	Identifies the application in WorkOS and Convex.
WORKOS_COOKIE_PASSWORD	Critical	32+ character password for encrypting session cookies.
WORKOS_COOKIE_DOMAIN	Recommended	Set to .pcstyle.dev for cross-subdomain sessions.

Sources: README.md:14-20

Summary

Server-side authentication in this project is a multi-layered system involving Next.js middleware for route protection and Convex configuration for secure backend data access. By standardizing on WorkOS AuthKit and shared cookie domains, it provides a seamless "Single Sign-On" experience across all PCSTYLE subdomains while maintaining strict access control at the edge.
Sources: README.md:1-5, src/index.ts:1-12