Identity & Authentication System

Relevant source files

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

• AUTH_SYSTEM.md
• lib/rbac.ts
• RBAC_INDEX.md
• RBAC_IMPLEMENTATION_SUMMARY.md
• docs/RBAC_ARCHITECTURE.md
• migrations/003-rbac-and-auth.sql

The Identity & Authentication System in BankChase is a multi-layered security framework designed to manage user identities, verify credentials, and enforce granular access controls. It integrates traditional email/password authentication with Two-Factor Authentication (2FA), Role-Based Access Control (RBAC), and comprehensive audit logging to ensure production-grade security for banking operations.

The system is built on a hybrid architecture utilizing PostgreSQL for structured identity data and compliance trails, and Clerk for session orchestration in specific modules. It employs an 8-layer security approach, including SQL parameterized queries, SHA256 token hashing, and Row-Level Security (RLS) to prevent unauthorized data access.
Sources: RBAC_INDEX.md:104-124, RBAC_IMPLEMENTATION_SUMMARY.md:126-140, AUTH_SYSTEM.md:4-16

Authentication Architecture & Workflow

The authentication flow follows a sequential verification process, moving from initial credential validation to secondary factor verification before a final session token is issued.

Primary Authentication Flow

Users authenticate using email and password credentials. Passwords are secured using Bcrypt hashing with 10 rounds to prevent credential theft. Upon successful primary validation, the system generates a 6-digit 2FA code with a 5-minute expiration window.
Sources: RBAC_IMPLEMENTATION_SUMMARY.md:37-52, AUTH_SYSTEM.md:120-135

Two-Factor Authentication (2FA)

2FA is enforced as a mandatory step for login completion. The system generates single-use codes that are stored in the database with a reference to the user ID and an expiration timestamp.
Sources: RBAC_DELIVERY_SUMMARY.md:88-95, RBAC_IMPLEMENTATION_SUMMARY.md:54-61

Role-Based Access Control (RBAC)

BankChase implements a three-tier role system to enforce the principle of least privilege. Permissions are defined in a matrix that dictates access to specific API routes and resources.

Role Definitions

Role	Access Level	Permissions
Customer	Restricted	View/update own profile, view own accounts, initiate own transfers.
Admin	Full Access	Manage all users, update roles, delete accounts, view audit logs.
Auditor	Read-Only	View audit logs and transaction history for compliance; no data modification.
Sources: RBAC_IMPLEMENTATION_SUMMARY.md:144-162, RBAC_DELIVERY_SUMMARY.md:34-53

Permission Enforcement

Authorization is checked at both the API level and the database level using Row-Level Security (RLS). The lib/rbac.ts utility provides helper functions like checkPermission() and canAccessResource() to verify that the userId associated with a JWT token matches the resource being requested.
Sources: lib/rbac.ts:1-25, RBAC_IMPLEMENTATION_SUMMARY.md:25-33

Data Models & Schema

The identity system relies on a set of PostgreSQL tables defined in the 003-rbac-and-auth.sql migration. These tables support authentication persistence, security challenges, and forensic tracking.

Core Identity Tables

Table	Description	Key Fields
users	Primary user identity records	id, email, password_hash, role
accounts	Banking accounts linked to users	id, user_id, balance, account_number
two_factor_codes	Temporary 2FA storage	user_id, code, expires_at, used
password_resets	Secure recovery tokens	user_id, token_hash, expires_at
admin_audit_logs	Immutable action records	admin_id, action_type, ip_address
login_history	Tracking of all login attempts	user_id, ip_address, device_name, success
Sources: migrations/003-rbac-and-auth.sql:1-60, RBAC_IMPLEMENTATION_SUMMARY.md:8-23

Security Implementation Details

Session Management

Sessions are managed via JWT tokens signed with HS256. These tokens are stored in httpOnly cookies, making them inaccessible to client-side scripts and mitigating XSS-based session hijacking.
Sources: RBAC_IMPLEMENTATION_SUMMARY.md:133-138, AUTH_SYSTEM.md:138-146

Audit and Forensic Logging

The system maintains an immutable audit trail of all administrative actions. Every role change, user deletion, or sensitive configuration update is logged with the administrator's IP address and user agent.
Sources: RBAC_IMPLEMENTATION_SUMMARY.md:18-20, RBAC_DELIVERY_SUMMARY.md:55-63

Password Recovery

Password resets utilize 32-byte cryptographically secure random tokens. These tokens are hashed using SHA256 before being stored in the database. When a user provides the token, the system hashes the input and compares it against the stored hash to verify the request.
Sources: RBAC_IMPLEMENTATION_SUMMARY.md:63-78, RBAC_DELIVERY_SUMMARY.md:113-120

Conclusion

The Identity & Authentication System provides the foundational security layer for the BankChase application. By combining Bcrypt password hashing, mandatory 2FA, a structured RBAC permission matrix, and database-level Row-Level Security, the system ensures that user identities are protected and data remains isolated. The addition of immutable audit logs and detailed login history further supports compliance and forensic requirements essential for a banking environment.
Sources: RBAC_INDEX.md:150-165, RBAC_DELIVERY_SUMMARY.md:210-230