Role Validation & User Types
Relevant source files
The following files were used as context for generating this wiki page:
Role validation and user type management form the core authorization logic in the CellarNode authentication system. This system ensures that users accessing specific dashboards possess the appropriate UserType and roles, preventing unauthorized access across different portals such as those for importers, producers, or administrators.
The architecture relies on a combination of type definitions, utility functions for server-side or logic-level validation, and React components for client-side enforcement and user feedback.
Sources: src/types.ts, src/auth-guard.ts, src/react/unauthorized.tsx
User Type Definitions
The system defines a strict set of user types that categorize the entities interacting with the dashboards. These types are used throughout the registration, login, and validation flows to ensure data integrity and proper access control.
| Type | Description |
|---|---|
importer | Users representing importing organizations. |
producer | Users representing production entities. |
admin | Internal administrative users with elevated privileges. |
Sources: src/types.ts:3-9, src/types.ts:74
Data Structures
The AuthUser interface is the primary data structure containing authorization metadata.
export interface AuthUser {
id: string;
email: string;
name: string;
phone?: string;
userType: "importer" | "producer" | "admin";
orgId: string | null;
roles: string[];
createdAt: string;
}
Sources: src/types.ts:1-10
Validation Logic
The primary mechanism for checking a user's permission level is the validateUserType function. This utility performs a direct comparison between the userType property of an authenticated user and the expected type required for a specific resource or action.
This logic is used to guard routes and API actions, ensuring that a "producer" cannot access an "importer" dashboard, even with a valid session.
Sources: src/auth-guard.ts:3-5, tests/auth-guard.test.ts:16-29
React Integration & UI Enforcement
The React layer enforces role validation during the authentication process and provides a dedicated UI for handling authorization failures.
Login-time Validation
During the OTP verification process, the LoginForm component validates the returned user's type against the userType prop passed to the component. If a mismatch is detected, the session is cleared and an error is displayed.
Sources: src/react/login-form.tsx:164-173
Handling Unauthorized Access
The UnauthorizedPage component provides a "Wrong Portal" view. It is designed to be "portal-aware," meaning it can detect if a user is authenticated but simply on the wrong dashboard, and then suggest the correct URL via DashboardLink objects.
| Field | Type | Description |
|---|---|---|
expectedRole | string | The role required by the current dashboard. |
authenticatedUserType | string | The actual type of the logged-in user. |
dashboardLinks | DashboardLink[] | A map of user types to their respective dashboard URLs. |
Sources: src/react/unauthorized.tsx:7-14, src/types.ts:76-80
Registration Constraints
User types are also enforced at the point of account creation. The RegisterForm and the RegisterInput interface limit registration to specific business types, excluding administrative roles from public registration flows.
export interface RegisterInput {
name: string;
email: string;
phone?: string;
userType: "importer" | "producer";
}
Sources: src/types.ts:12-17, src/react/register-form.tsx:39-44
Summary
The Role Validation & User Types system provides a consistent authorization framework across the CellarNode ecosystem. By combining strict TypeScript interfaces, central validation utilities, and portal-aware UI components, the project ensures that users are confined to their appropriate functional domains while providing clear navigation paths if they attempt to access restricted portals.
Sources: src/index.ts:1-24, src/auth-guard.ts:1-5