Dependencies & External Integrations

Relevant source files

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

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

The @pcstyle/auth package serves as a unified authentication SDK designed specifically for PCSTYLE services. Its primary purpose is to provide a consistent authentication layer by abstracting the complexities of WorkOS AuthKit and providing native integrations for Next.js and Convex.

The architecture relies heavily on external peer dependencies to manage session state, user identity, and secure routing across multiple subdomains within the pcstyle.dev ecosystem.

Sources: package.json:1-5, README.md:1-5, src/types.ts:77-85

Primary Dependencies

The SDK is built upon several core technologies that must be present in the host environment. These are defined as peer dependencies to ensure version compatibility and prevent duplicate installations in the consumer's bundle.

Dependency	Version	Purpose
@workos-inc/authkit-nextjs	^2.13.0	Core authentication logic and Next.js primitives
next	>=14.0.0	Framework support for Middleware and Server Components
react	>=18.0.0	UI primitives for Client Component hooks

Sources: package.json:28-32

WorkOS Integration

WorkOS AuthKit is the central identity provider for the SDK. The integration handles user management, session persistence via cookies, and OAuth flows.

Authentication Flow

The following diagram illustrates how the SDK interacts with WorkOS to establish an authenticated session.

Configuration Requirements

Successful integration with WorkOS requires specific environment variables to manage the secure handshake and cross-subdomain cookie sharing.

Variable	Description	Source
WORKOS_API_KEY	Secret key for backend API calls	README.md:17
WORKOS_CLIENT_ID	Public identifier for the AuthKit application	README.md:18
WORKOS_COOKIE_PASSWORD	32+ character string for encrypting session cookies	README.md:19
WORKOS_COOKIE_DOMAIN	Domain for cross-subdomain auth (e.g., .pcstyle.dev)	README.md:20

Convex Integration

The SDK provides a specialized entry point for Convex backend services. This integration allows Convex to verify JWTs issued by WorkOS, enabling secure database access based on the user's identity.

The createConvexAuthConfig function configures two custom JWT providers to handle both standard WorkOS SSO and User Management issuers.

export function createConvexAuthConfig(clientId: string | undefined) {
    if (!clientId) {
        throw new Error('WORKOS_CLIENT_ID is required for Convex auth config');
    }

    return {
        providers: [
            {
                type: 'customJwt' as const,
                issuer: 'https://api.workos.com/',
                algorithm: 'RS256' as const,
                applicationID: clientId,
                jwks: `https://api.workos.com/sso/jwks/${clientId}`,
            },
            {
                type: 'customJwt' as const,
                issuer: `https://api.workos.com/user_management/${clientId}`,
                algorithm: 'RS256' as const,
                jwks: `https://api.workos.com/sso/jwks/${clientId}`,
                applicationID: clientId,
            },
        ],
    };
}

Sources: src/convex.ts:11-37, package.json:20-23

Middleware & Routing

The SDK wraps WorkOS middleware to provide a pre-configured solution for PCSTYLE services, specifically managing public path exclusions and redirect logic.

AuthMiddlewareOptions

Field	Type	Description
publicPaths	string[]	Array of routes that bypass authentication checks
redirectUri	string	Custom OAuth callback URI
signInUrl	string	The central login entry point

Sources: src/types.ts:25-44

Request Lifecycle

The middleware is typically configured with a standard Next.js matcher to intercept all routes except internal assets and static files.

Client-Side Hooks

The SDK integrates with the React context provided by AuthKitProvider to expose authentication state to client components.

useAuth()

A wrapper around the base WorkOS hook that standardizes the return type into an AuthState object.

• user: The User object or null.
• isLoading: Boolean indicating if the session is being fetched.
• isAuthenticated: Boolean derived from the presence of a user object.

Sources: src/hooks.ts:17-29, src/types.ts:16-21

useUser()

A strict version of the auth hook that throws an error if called outside of an authenticated context, ensuring type safety for protected components.
Sources: src/hooks.ts:39-49

Summary

The @pcstyle/auth SDK acts as a bridge between PCSTYLE applications and the WorkOS identity platform. By enforcing specific peer dependencies and providing pre-configured middleware and Convex integrations, it ensures that authentication is handled consistently across all subdomains in the pcstyle.dev ecosystem. The reliance on external providers like WorkOS allows the SDK to focus on providing a developer-friendly API through custom React hooks and specialized backend configuration utilities.