Introduction to @pcstyle/auth

Relevant source files

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

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

@pcstyle/auth is a unified authentication SDK designed specifically for PCSTYLE services. It leverages WorkOS AuthKit to provide a consistent authentication experience across various subdomains and platforms within the PCSTYLE ecosystem, supporting Next.js and Convex integrations.

Sources: package.json:3, README.md:3

Core Architecture

The SDK is structured as a multi-entry point package, providing specific utilities for different parts of a modern web stack, including frontend hooks, backend middleware, and database-level authentication configurations.

Entry Points and Distribution

The package is bundled using tsup and exports three primary entry points:

1. Main (.): Exports common types and React hooks for client-side authentication.
2. Middleware (./middleware): Provides Next.js middleware for route protection.
3. Convex (./convex): Provides authentication configuration for Convex backend integration.

Sources: package.json:8-23, tsup.config.ts:4-8, src/index.ts:1-12

Client-Side Authentication

The SDK provides React hooks to interact with the WorkOS authentication state. These hooks wrap the underlying @workos-inc/authkit-nextjs components to provide a simplified interface tailored for PCSTYLE services.

Hooks

• useAuth(): Returns the current session state, including the user object, loading status, and authentication flag.
• useUser(): A convenience hook that returns the user object directly or throws an error if the user is not authenticated.

Sources: src/hooks.ts:18-47

Auth State Model

The authentication state is standardized across the SDK using the AuthState interface.

Property	Type	Description
user	User | null	The WorkOS user object if authenticated.
isLoading	boolean	Indicates if the authentication status is being fetched.
isAuthenticated	boolean	Boolean flag indicating if a valid session exists.

Sources: src/types.ts:14-18, src/hooks.ts:22-26

Middleware and Route Protection

The SDK includes a pre-configured middleware factory to secure Next.js applications. It facilitates cross-subdomain authentication using a shared cookie domain.

Configuration

The createAuthMiddleware function allows developers to define public paths that bypass authentication checks.

Convex Backend Integration

For applications using Convex as a backend, the SDK provides a utility to generate a compatible authentication configuration. This configuration utilizes Custom JWT providers to validate WorkOS tokens within Convex functions.

JWT Provider Configuration

The createConvexAuthConfig function sets up two JWT providers pointing to WorkOS:

• A general WorkOS issuer (https://api.workos.com/).
• A User Management specific issuer (https://api.workos.com/user_management/{clientId}).

Sources: src/convex.ts:10-33

Data Structures

User Object (WorkOS)

Field	Type	Description
id	string	Unique identifier from WorkOS.
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.

Sources: src/types.ts:4-12

Convex User Record

The ConvexUser type defines how user data is structured when stored within the Convex database.

Field	Type	Description
authId	string	The external WorkOS ID.
role	string	User permission role.
email	string	User email.
_id	string	Internal Convex document ID.

Sources: src/types.ts:44-53

Summary

@pcstyle/auth serves as the central authentication authority for the PCSTYLE ecosystem. By wrapping WorkOS AuthKit, it provides a unified set of tools including React hooks for the frontend, Next.js middleware for route security, and backend configurations for Convex. This ensures that user identity is maintained seamlessly across various services and subdomains like auth.pcstyle.dev.

Sources: README.md:1-10, src/hooks.ts:56-65