Middleware Implementation

Relevant source files

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

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

The middleware implementation in the @pcstyle/auth SDK provides a unified authentication layer for PCSTYLE services. It leverages the WorkOS AuthKit to intercept incoming requests, validate session states, and enforce access control based on pre-defined public paths. This ensures that all subdomains within the pcstyle.dev ecosystem share a consistent authentication context.

The middleware is designed as a wrapper around @workos-inc/authkit-nextjs, offering a pre-configured setup that simplifies integration across various Next.js projects. It handles the complexities of session management and redirection while allowing developers to specify exceptions for public endpoints.
Sources: README.md:3-8, src/middleware.ts:1-12

Core Configuration and Logic

The primary entry point for the middleware is the createAuthMiddleware function. This function abstracts the configuration of the WorkOS authkitMiddleware by mapping custom options to the internal middleware settings.

Middleware Options

The middleware behavior is controlled via the AuthMiddlewareOptions interface. This allows for fine-grained control over which paths require authentication and where users are redirected during the auth flow.

Option	Type	Description	Default
publicPaths	string[]	Paths that bypass authentication checks (e.g., health checks).	[]
redirectUri	string	The callback URI for OAuth completion.	https://auth.pcstyle.dev/callback
signInUrl	string	The primary entry point for unauthenticated users.	https://auth.pcstyle.dev

Sources: src/types.ts:25-45, src/middleware.ts:24-30

Processing Flow

The following diagram illustrates how the middleware processes an incoming request based on the provided configuration.

The middleware uses a Next.js matcher to filter requests and then checks the unauthenticatedPaths (derived from publicPaths) to decide whether to enforce a session check.
Sources: src/middleware.ts:24-44, README.md:21-31

Implementation Details

The implementation is split between the configuration factory and the exported matcher settings required by Next.js.

Factory Function

The createAuthMiddleware function initializes the authkitMiddleware with middlewareAuth enabled. It specifically sets the unauthenticatedPaths property using the publicPaths provided in the options.
Sources: src/middleware.ts:24-32

export function createAuthMiddleware(options?: AuthMiddlewareOptions) {
    return authkitMiddleware({
        middlewareAuth: {
            enabled: true,
            unauthenticatedPaths: options?.publicPaths ?? [],
        },
    });
}

Sources: src/middleware.ts:24-32

Matcher Configuration

To optimize performance, the SDK provides a matcherConfig that excludes static assets, Next.js internals, and files with extensions from being processed by the middleware.

export const matcherConfig = {
    matcher: ['/((?!_next|static|favicon.ico|.*\\..*).*)'],
};

Sources: src/middleware.ts:44-46

Integration with Hooks and Providers

The middleware works in tandem with client-side hooks and providers to ensure a seamless user experience. While the middleware handles server-side protection, the useAuth hook provides the UI with the current session state.

The useAuth hook retrieves the user, isLoading, and isAuthenticated state, which is initially established by the middleware's cookie management.
Sources: src/hooks.ts:18-30, README.md:52-64

Summary

The middleware implementation in @pcstyle/auth serves as the gatekeeper for PCSTYLE services. By centralizing the authentication logic through createAuthMiddleware and providing a standardized matcherConfig, it ensures that all applications within the ecosystem maintain high security standards with minimal configuration overhead. The integration with WorkOS AuthKit allows for robust session handling across subdomains using a shared cookie domain.
Sources: src/middleware.ts:1-46, src/types.ts:60-65, package.json:23-27