Route Protection with Auth Guard

Relevant source files

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

• src/auth-guard.ts
• src/types.ts
• src/react/unauthorized.tsx
• src/react/login-form.tsx
• tests/auth-guard.test.ts
• src/auth-client.ts

Route protection in the CellarNode authentication system ensures that only users with the correct credentials and specific account types can access protected dashboards. The system combines logic-based validation with React-based UI feedback to handle unauthorized access gracefully.

The core of this system revolves around verifying the userType of an authenticated user against the required role for a specific route. If a mismatch is detected, the system provides either a "Wrong Portal" redirection view or an "Access Denied" notification.

Sources: src/auth-guard.ts, src/react/unauthorized.tsx:8-13, src/react/login-form.tsx:189-198

Core Validation Logic

The primary mechanism for route protection is the validateUserType function. This function compares the userType property of an authenticated AuthUser object against a required UserType.

export function validateUserType(user: AuthUser, expected: UserType): boolean {
  return user.userType === expected;
}

Sources: src/auth-guard.ts:3-5

Supported User Types

The system categorizes users into three distinct types which are used for route guarding:

• importer: Users associated with importing operations.
• producer: Users associated with production/supply operations.
• admin: Administrative users with elevated access.

Sources: src/types.ts:1-10, src/types.ts:114

Authentication Flow and Role Enforcement

The enforcement of route protection occurs at two primary stages: during the login process and during subsequent authenticated requests.

1. Enforcement during Login

The LoginForm component enforces role restrictions immediately upon OTP verification. If a user successfully authenticates but their userType does not match the portal's required userType, the login is rejected, the access token is cleared, and an error is displayed.

The logic ensures that a producer cannot sign into an importer-specific dashboard.
Sources: src/react/login-form.tsx:189-198

2. Enforcement during Request Interception

The AuthClient handles 401 Unauthorized responses by attempting a token refresh. If the refresh fails or the user is no longer authorized, the onAuthFailure callback is triggered, typically redirecting the user back to the login page.

Sources: src/auth-client.ts:63-75

Unauthorized Access UI

When a user attempts to access a protected route without the correct role, the UnauthorizedPage component provides visual feedback.

Portal Redirection Logic

The system is "portal-aware." If a user is logged in as an importer but tries to access a producer dashboard, the UI identifies the mismatch and provides a direct link to the correct dashboard based on the provided dashboardLinks.

Component Property	Type	Description
expectedRole	string	The role required by the current route.
authenticatedUserType	string	The actual role of the logged-in user.
dashboardLinks	DashboardLink[]	Array of available portals for redirection.
onNavigateLogin	() => void	Callback to return to the login screen.

Sources: src/react/unauthorized.tsx:8-15, src/types.ts:116-120

Access Denied Scenarios

The UnauthorizedPage handles two distinct states:

1. Wrong Portal: The user is authenticated but on the wrong dashboard. A link to the correct portal is shown.
2. Access Denied: A generic fallback for when the user does not have access and no alternative portal is defined.

Summary of Guard Components

The following table summarizes the key components involved in protecting routes and handling unauthorized states.

Component / Function	File Path	Primary Responsibility
validateUserType	src/auth-guard.ts	Pure function to check if a user's type matches requirements.
UnauthorizedPage	src/react/unauthorized.tsx	React component for displaying access denied or portal redirection UI.
LoginForm	src/react/login-form.tsx	Enforces userType checks immediately after successful OTP verification.
AuthClient	src/auth-client.ts	Intercepts authentication failures and triggers logout/redirection.
AuthError	src/types.ts	Custom error class used to propagate authorization failures with specific codes.

Sources: src/auth-guard.ts, src/react/unauthorized.tsx, src/react/login-form.tsx, src/auth-client.ts, src/types.ts:40-51