Testing the Auth Guard

Relevant source files

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

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

Testing the Auth Guard involves verifying the logic used to protect routes and resources based on user types and authentication states. In the @cellarnode/auth ecosystem, the guard mechanism primarily focuses on validating the UserType of an authenticated user against required permissions for specific dashboard contexts. Sources: src/auth-guard.ts, tests/auth-guard.test.ts

The testing suite ensures that users are correctly identified as authorized or unauthorized, facilitating proper redirection to login or specialized unauthorized pages when a type mismatch occurs. Sources: src/react/unauthorized.tsx, tests/auth-guard.test.ts

Core Validation Logic

The primary utility for guarding routes is the validateUserType function. This function performs a strict equality check between the userType property of an AuthUser object and an expected UserType string. Sources: src/auth-guard.ts:3-5

AuthUser Data Structure

The AuthUser interface defines the user object passed to the guard. It contains identity, organizational context, and the critical userType field used for authorization. Sources: src/types.ts:1-10

Field	Type	Description
id	string	Unique identifier for the user
email	string	User email address
userType	"importer" | "producer" | "admin"	The role used for guard validation
orgId	string | null	Associated organization identifier
roles	string[]	Additional permission strings

Sources: src/types.ts:1-10

Validation Testing Strategy

Tests for the Auth Guard utilize vitest to verify that the validation logic behaves correctly under various scenarios. The test suite uses a factory function makeUser to generate mock user objects with specific userType values for comparison. Sources: tests/auth-guard.test.ts:4-13

Positive and Negative Assertions

The validation tests confirm two primary states:

1. Authorized Access: Returns true when the user's type (e.g., "producer") matches the requirement.
2. Unauthorized Access: Returns false when the user's type (e.g., "admin") does not match the specific requirement (e.g., "producer").

The diagram shows the decision logic implemented in the validation utility. Sources: src/auth-guard.ts:3-5, tests/auth-guard.test.ts:15-26

Integration with Client-Side Components

The results of the Auth Guard logic directly influence the UI via the UnauthorizedPage. This component handles two specific unauthorized states identified during testing and development:

Wrong Portal Detection

If a user is authenticated but possesses a different userType than what the current dashboard requires, the system identifies a "Wrong Portal" scenario. The UnauthorizedPage can use a list of DashboardLink objects to suggest the correct URL for the user's actual type. Sources: src/react/unauthorized.tsx:16-43

Access Denied Fallback

When no matching dashboard link is available or the user is completely unauthorized for the requested context, the system falls back to a generic "Access Denied" state. Sources: src/react/unauthorized.tsx:46-65

The sequence illustrates how a guard failure triggers the unauthorized UI flow. Sources: src/auth-guard.ts, src/react/unauthorized.tsx

Test Case Summary

Test Scenario	Input UserType	Expected Requirement	Result
Matching Producer	"producer"	"producer"	true
Matching Importer	"importer"	"importer"	true
Mismatched Role	"admin"	"producer"	false
Reversed Roles	"importer"	"producer"	false

Sources: tests/auth-guard.test.ts:16-25

Conclusion

Testing the Auth Guard ensures that the validateUserType logic remains a reliable gatekeeper for CellarNode dashboards. By strictly enforcing UserType checks, the system prevents unauthorized access and provides clear navigational feedback to users who attempt to access the incorrect dashboard portal. Sources: src/auth-guard.ts, src/react/unauthorized.tsx