Middleware Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
The @pcstyle/auth middleware provides a unified authentication layer for PCSTYLE services, built upon the WorkOS AuthKit for Next.js. Its primary role is to intercept incoming requests, verify authentication state, and manage access to protected routes across different subdomains within the pcstyle.dev ecosystem.
By utilizing a pre-configured middleware factory, developers can ensure consistent session handling and cross-subdomain cookie persistence, which is critical for the "unified" experience described in the project goals.
Sources: README.md:3-5, src/middleware.ts:1-5
Core Middleware Architecture
The middleware is structured as a wrapper around @workos-inc/authkit-nextjs. It exposes a factory function, createAuthMiddleware, which consumes a specific set of configuration options to determine which paths should remain accessible to unauthenticated users.
Execution Flow
When a request enters the Next.js application, the middleware evaluates whether the requested path matches the exclusion criteria defined in the matcher and whether the path is explicitly marked as public.
The diagram above illustrates the decision logic applied to every request based on the middleware configuration.
Sources: src/middleware.ts:17-43, README.md:29-37
Configuration Interface
The behavior of the middleware is governed by the AuthMiddlewareOptions interface. This interface allows developers to customize the security perimeter of their application.
AuthMiddlewareOptions Properties
| Property | Type | Default | Description |
|---|---|---|---|
publicPaths | string[] | [] | A list of route patterns that do not require an active session. |
redirectUri | string | 'https://auth.pcstyle.dev/callback' | The URI where users are sent after a successful OAuth authentication. |
signInUrl | string | 'https://auth.pcstyle.dev' | The primary login page for the PCSTYLE ecosystem. |
Sources: src/types.ts:25-45, src/middleware.ts:26-30
Recommended Matcher Configuration
To prevent the middleware from intercepting internal Next.js assets, static files, or favicons, a specific matcher configuration is recommended. This ensures optimal performance by only running authentication logic on actual page or API routes.
export const matcherConfig = {
matcher: ['/((?!_next|static|favicon.ico|.*\\..*).*)'],
};
Sources: src/middleware.ts:40-43
Cross-Subdomain Authentication
A critical aspect of the middleware configuration is the environmental setup required for cross-subdomain support. The middleware relies on a shared cookie domain to ensure that a user logged into one PCSTYLE service remains logged into others.
Environmental Requirements
The underlying system requires specific environment variables to function correctly alongside the middleware:
WORKOS_COOKIE_DOMAIN: Must be set to.pcstyle.devto allow cookies to be shared across subdomains.WORKOS_COOKIE_PASSWORD: Must be a consistent 32+ character password across all services to decrypt session cookies.
Sources: README.md:12-20, src/types.ts:63-71
Implementation Details
The createAuthMiddleware function translates the PCSTYLE-specific options into the format expected by the WorkOS AuthKit.
export function createAuthMiddleware(options?: AuthMiddlewareOptions) {
return authkitMiddleware({
middlewareAuth: {
enabled: true,
unauthenticatedPaths: options?.publicPaths ?? [],
},
});
}
In this implementation, publicPaths are mapped directly to unauthenticatedPaths, enabling the "middlewareAuth" feature of the underlying provider.
Sources: src/middleware.ts:25-32
Summary
The middleware configuration in @pcstyle/auth serves as the primary gatekeeper for PCSTYLE services. By configuring publicPaths and utilizing the standard matcherConfig, developers can balance security with accessibility. The system is designed to work seamlessly with the auth.pcstyle.dev domain, facilitating a centralized identity management experience through shared cookie domains and standardized redirect URIs.