Convex Database Integration

Relevant source files

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

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

The Convex Database Integration module within the @pcstyle/auth SDK provides a streamlined way to authenticate users in Convex backend functions using WorkOS AuthKit. It bridges the gap between Next.js frontend authentication and Convex's server-side logic by configuring custom JWT providers.

This integration ensures that identity tokens generated by WorkOS are correctly validated by the Convex platform, allowing developers to utilize authenticated user data within their database queries and mutations. Sources: README.md:57-61, src/convex.ts:1-12

Authentication Configuration

The core of the integration is the createConvexAuthConfig function. This utility generates the necessary configuration object for Convex to recognize WorkOS as a trusted JWT issuer. It specifically configures two provider entries to handle different aspects of the WorkOS authentication flow, including standard SSO and user management. Sources: src/convex.ts:13-37

JWT Provider Structure

The configuration uses the customJwt type and points to the WorkOS JSON Web Key Sets (JWKS) to verify the authenticity of incoming tokens. Sources: src/convex.ts:22-35

This diagram illustrates how the generated configuration allows the Convex backend to validate WorkOS JWT tokens using the JWKS endpoint. Sources: src/convex.ts:22-35

Data Models and Types

The integration defines specific data structures to ensure type safety when dealing with user records within the Convex environment. Sources: src/types.ts:44-54

Field	Type	Description
_id	string	Convex internal record ID
authId	string	The unique identifier from WorkOS
email	string	User's primary email address
name	string (Optional)	Full name of the user
avatarUrl	string (Optional)	URL to the user's profile image
role	string	User authorization role
createdAt	number	Unix timestamp of record creation
updatedAt	number	Unix timestamp of last update

Sources: src/types.ts:44-54

Integration Workflow

The integration follows a standard flow where the client authenticates via the SDK hooks, and the resulting session is propagated to Convex. Sources: src/hooks.ts:18-30, README.md:60-61

The sequence shows the transition from frontend authentication state managed by useAuth to backend authorization in Convex. Sources: src/hooks.ts:18-30, src/convex.ts:13-37

Implementation Details

Configuration Generation

The createConvexAuthConfig function requires a WORKOS_CLIENT_ID. If this environment variable is missing during initialization, the SDK throws an error to prevent insecure or failing authentication attempts. Sources: src/convex.ts:14-16

Export Strategy

The SDK provides multiple ways to consume the Convex configuration:

• Direct Function: createConvexAuthConfig(clientId) for manual setup. Sources: src/convex.ts:13
• Default Export: A pre-invoked version using process.env.WORKOS_CLIENT_ID. Sources: src/convex.ts:42
• Subpath Export: Accessible via @pcstyle/auth/convex as defined in the package configuration. Sources: package.json:23-27

Middleware Interaction

While the Convex integration handles database-level security, the createAuthMiddleware in src/middleware.ts ensures that the Next.js routes hosting the application are protected before any database calls are initiated. Sources: src/middleware.ts:22-28

Summary

The Convex Database Integration provides the essential security handshake between the PCSTYLE authentication layer and the Convex backend. By standardizing the customJwt provider configuration and providing shared TypeScript interfaces, it ensures that user identity is consistent and verifiable across the entire stack, from Next.js middleware to database mutations. Sources: src/convex.ts:1-42, src/types.ts:44-54