Security Best Practices

The @pcstyle/auth SDK provides a unified security layer for PCSTYLE services, leveraging WorkOS AuthKit for robust identity management. It ensures secure authentication across subdomains and provides standardized mechanisms for protecting routes, managing user sessions, and integrating with external data platforms like Convex.

The security architecture relies on a combination of Next.js middleware for request interception, client-side hooks for state management, and environment-driven configurations to maintain a secure perimeter around protected resources.

Sources: README.md:1-5, package.json:1-5

Cross-Subdomain Authentication

A critical security requirement for PCSTYLE services is maintaining a consistent session across various subdomains (e.g., app.pcstyle.dev, auth.pcstyle.dev). This is achieved through strict cookie domain synchronization and shared secrets.

The project requires a WORKOS_COOKIE_PASSWORD that must be at least 32 characters and must be identical across all applications within the *.pcstyle.dev domain to allow seamless, secure handoffs between services.

Sources: README.md:15-18, src/types.ts:70-75

Auth Configuration Defaults

Sources: src/types.ts:77-80

Route Protection via Middleware

The primary defense mechanism for server-side resources is the authentication middleware. It intercepts incoming requests to determine if they should be allowed based on the user's authentication status and the path's public/private designation.

The middleware is configured with a default matcher that excludes static assets and internal Next.js paths while protecting all other routes by default.

Sources: src/middleware.ts:20-43, README.md:21-33

Secure Client-Side State Management

The SDK provides React hooks to safely access authentication state. These hooks interact with the AuthKitProvider to expose user data and loading states while preventing common pitfalls like accessing null user objects in protected contexts.

Safe Access Hooks

• useAuth(): Provides user, isLoading, and isAuthenticated. It safely returns null for the user if not logged in.
• useUser(): A strict hook that throws an error if called outside an authenticated context, ensuring that developers do not proceed with null user references.

Sources: src/hooks.ts:16-52, src/types.ts:21-25

External System Integration (Convex)

For backend data integrity, the SDK provides a secure JWT-based configuration for Convex. This ensures that database queries are only executed for users with valid tokens issued by WorkOS.

The configuration utilizes RS256 as the signing algorithm and retrieves public keys from the WorkOS JWKS endpoint, ensuring that the application never handles sensitive private keys for token verification.

Sources: src/convex.ts:12-32, README.md:73-77

Environment Variable Security

Security relies on the proper configuration of environment variables. The SDK enforces the presence of these variables during initialization, particularly for sensitive integrations like Convex.

Sources: README.md:10-18, src/convex.ts:13-15

Conclusion

Security in the PCSTYLE ecosystem is built on a foundation of centralized authentication and decentralized enforcement. By mandating middleware for route protection, utilizing strict JWT verification for backend services, and enforcing domain-wide cookie standards, the SDK provides a robust framework that minimizes the risk of unauthorized access while maintaining a seamless user experience across the service portfolio.

Sources: src/middleware.ts:20-25, src/convex.ts:20-30, README.md:1-5