Authentication (@wrelik/auth)
Relevant source files
The following files were used as context for generating this wiki page:
The @wrelik/auth package serves as the standardized authentication adapter for the Wrelik ecosystem. Built as a wrapper around Clerk, it provides unified session handling, Role-Based Access Control (RBAC), and multi-tenant (organization) context management. Its primary purpose is to decouple application code from specific vendor SDKs, ensuring that applications interact with a consistent internal API rather than importing third-party libraries directly.
As a core infrastructure package, it enforces discipline by being the sole gateway for authentication logic. This adapter-first architecture allows the project to maintain "explicit boundaries and minimal surface area," making it easier to replace vendors without necessitating a rewrite of the applications themselves.
Sources: README.md:12-14, README.md:37-39, DECISIONS.md:16-19
Core Architecture and Principles
The authentication system is designed around the principle of "Vendor-agnostic adapters." While Clerk is the current underlying provider due to its Next.js support and developer experience, the package abstracts Clerk's types into internal structures like WorkflowSession.
Dependency Management and Enforcement
To prevent "vendor lock-in," the repository uses ESLint rules to strictly forbid applications from importing Clerk SDKs directly. Developers must use @wrelik/auth for all authentication and session requirements.
// Example of restricted imports enforced by @wrelik/eslint-config
{
name: '@clerk/nextjs',
message: 'Please use @wrelik/auth instead.',
}
Sources: packages/eslint-config/index.js:18-21, DECISIONS.md:16-19, README.md:12-14
Session Management
The package defines a standard WorkflowSession interface that acts as the internal representation of an authenticated state. This structure normalizes data from the authentication provider into a format that includes user identification, tenant (organization) context, and assigned roles.
WorkflowSession Data Model
| Field | Type | Description |
|---|---|---|
userId | string | null | The unique identifier of the authenticated user. |
tenantId | string | null | The unique identifier for the current organization or tenant (Clerk's orgId). |
roles | string[] | A collection of roles extracted from the provider's metadata. |
Sources: packages/auth/src/index.ts:4-8
Logic Flow: Provider to Internal Session
The fromClerkAuth function transforms a Clerk authentication object into a WorkflowSession. It specifically looks for roles within the publicMetadata of the session claims.
The diagram shows how external Clerk authentication data is mapped to the internal WorkflowSession structure.
Sources: packages/auth/src/index.ts:10-25, packages/auth/src/index.test.ts:20-30
Authorization and Guard Functions
The package provides several utility functions to enforce authentication and authorization constraints within application logic. These functions throw specific typed errors from @wrelik/errors when requirements are not met.
Guard Utilities
| Function | Requirement | Action on Failure |
|---|---|---|
requireUser | Valid userId must exist | Throws AuthRequiredError |
requireTenant | Valid tenantId must exist | Throws TenantRequiredError |
requireRole | Specific role must be in roles | Throws PermissionDeniedError |
hasRole | Checks for role presence | Returns false |
Sources: packages/auth/src/index.ts:27-52, packages/auth/src/index.test.ts:6-9
Role-Based Access Control (RBAC)
The RBAC implementation relies on the roles array within the WorkflowSession. Roles are typically populated from the publicMetadata of the authentication token.
This sequence illustrates the validation process when an application requests a specific role check.
Sources: packages/auth/src/index.ts:43-52
Technical Specifications
Build and Distribution
The package is built using tsup and targets both CommonJS (CJS) and ES Modules (ESM). It exports two main entry points: the primary index and a specific Next.js entry point.
- Main Entry:
src/index.ts - Next.js Entry:
src/next.ts - Build Script:
tsup src/index.ts src/next.ts --format cjs,esm --dts --clean
Sources: packages/auth/package.json:11-15
Dependencies
The package maintains minimal dependencies to keep the integration boundary clean.
| Dependency | Category | Purpose |
|---|---|---|
@clerk/backend | Internal | Core authentication logic and type definitions. |
@wrelik/errors | Internal | Shared typed application errors. |
@clerk/nextjs | Peer | Client-side and middleware integration for Next.js apps. |
Sources: packages/auth/package.json:19-25
Summary
@wrelik/auth provides a robust, type-safe wrapper around Clerk, fulfilling the project's goal of "adapter-first architecture." By abstracting session management and authorization into a unified API, it enables the Wrelik ecosystem to enforce strict multi-tenant access patterns and RBAC consistently across all applications while maintaining the flexibility to swap authentication providers with minimal friction.