AuthState Interfaces

Relevant source files

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

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

The @pcstyle/auth SDK provides a unified set of interfaces and types to manage authentication state across PCSTYLE services. By wrapping WorkOS AuthKit, it standardizes how user data, session status, and loading states are handled in both client-side React components and server-side configurations.

This system ensures type safety when accessing user profiles and provides a consistent structure for middleware and third-party integrations, such as Convex.

Sources: README.md:3-5, src/types.ts:1-25

Core Data Structures

The primary data structures define the shape of the user profile and the current session state.

User Interface

The User interface represents the authenticated entity as provided by the WorkOS AuthKit. It contains essential identity and metadata fields.

Field	Type	Description
id	string	Unique identifier for the user
email	string	User's primary email address
firstName	string | null	User's first name
lastName	string | null	User's last name
profilePictureUrl	string | null	URL to the user's profile image
createdAt	string	ISO timestamp of account creation
updatedAt	string	ISO timestamp of last update

Sources: src/types.ts:4-12

AuthState Interface

The AuthState interface is the standard return type for authentication hooks, encapsulating the user profile alongside lifecycle flags.

Field	Type	Description
user	User | null	The user object if authenticated, otherwise null
isLoading	boolean	Indicates if the authentication status is being fetched
isAuthenticated	boolean	Boolean flag derived from the presence of a user

Sources: src/types.ts:17-21

State Relationships and Flow

The following diagram illustrates how the AuthState is composed and consumed by application hooks.

The relationship between the user profile data and the session state used by React hooks.
Sources: src/types.ts:4-21, src/hooks.ts:19-45

Hook Implementation Logic

The SDK provides hooks that transform raw WorkOS data into the structured AuthState.

useAuth()

This hook consumes the underlying useWorkOSAuth hook and maps its properties to the AuthState interface. It ensures that the isAuthenticated property is a strict boolean based on the existence of the user object.

Sources: src/hooks.ts:19-27

useUser()

A convenience hook that enforces authentication. It consumes useAuth() and throws a runtime error if the state is unauthenticated, ensuring that subsequent code can safely access the User object without null checks.

Sources: src/hooks.ts:39-47

The logic flow for deriving state in the useAuth and useUser hooks.
Sources: src/hooks.ts:19-47

Integration Interfaces

Middleware Configuration

The AuthMiddlewareOptions interface defines how the authentication state is protected at the edge.

Option	Type	Default	Description
publicPaths	string[]	[]	Paths that bypass authentication
redirectUri	string	https://auth.pcstyle.dev/callback	OAuth callback destination
signInUrl	string	https://auth.pcstyle.dev	The primary sign-in endpoint

Sources: src/types.ts:26-44, src/middleware.ts:21-27

Convex Auth Integration

For backend services using Convex, the SDK provides createConvexAuthConfig to bridge the AuthState via JWT providers. It configures two providers: one for standard WorkOS API issuer and another for User Management issuer.

The dual-provider configuration used to validate authentication state in Convex.
Sources: src/convex.ts:14-34

Summary

The AuthState interfaces provide a robust foundation for handling user identity within the PCSTYLE ecosystem. By abstracting the complexities of WorkOS AuthKit into clean, type-safe interfaces like User and AuthState, the SDK enables developers to implement protected routes and user-aware components with minimal boilerplate.

Sources: README.md:50-70, src/index.ts:1-10