Role-Based Access Control (RBAC)

Relevant source files

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

• RBAC_GUIDE.md
• lib/rbac.ts
• migrations/003-rbac-and-auth.sql
• RBAC_SYSTEM_ARCHITECTURE.md
• RBAC_IMPLEMENTATION_SUMMARY.md
• RBAC_DELIVERY_SUMMARY.md
• RBAC_QUICK_START.md

Introduction

BankChase implements a robust Role-Based Access Control (RBAC) system designed to secure retail banking operations through strict user isolation and granular permission management. The system is built on a hybrid security model that combines API-level middleware checks with database-level Row Level Security (RLS) to ensure that users can only access data relevant to their specific roles and identities. Sources: RBAC_SYSTEM_ARCHITECTURE.md:233-270, RBAC_DELIVERY_SUMMARY.md:15-25

The primary goal of the RBAC implementation is to provide a multi-layered defense mechanism, protecting sensitive financial data from unauthorized access or lateral movement. By categorizing users into distinct roles—Customer, Admin, and Auditor—the system enforces a principle of least privilege across all service endpoints. Sources: RBAC_SYSTEM_ARCHITECTURE.md:272-310, RBAC_GUIDE.md:6-10

Architecture and Security Layers

The security architecture is organized into eight distinct layers, providing independent protection even if one layer is bypassed. Sources: RBAC_SYSTEM_ARCHITECTURE.md:272-310

Multi-Layer Security Model

1. Application Layer: Permission checks via RBAC matrix at the API entry point.
2. SQL Filtering: Mandatory WHERE user_id = $1 filters on all customer-facing queries to prevent cross-user data leaks.
3. Database RLS: PostgreSQL policies that verify auth.uid() = user_id at the engine level.
4. Transport Security: Encryption via HTTPS/TLS 1.3.
5. Token Security: JWT tokens signed with HS256 and stored in httpOnly secure cookies.
6. Password Security: Bcrypt hashing with 10 salt rounds.
7. 2FA Security: 6-digit verification codes with 5-minute expiration.
8. Audit Logging: Immutable trails of all administrative actions.

Sources: RBAC_SYSTEM_ARCHITECTURE.md:274-308, RBAC_IMPLEMENTATION_SUMMARY.md:104-120

System Request Flow

The following diagram illustrates how a request is processed through the RBAC verification layers:

Role Definitions and Permissions

The system utilizes three primary roles, each with defined access scopes and capabilities. Sources: RBAC_GUIDE.md:12-35, RBAC_DELIVERY_SUMMARY.md:29-50

Role	Scope	Key Capabilities
Customer	Self-Only	View own profile, accounts, transactions, and initiate transfers.
Admin	Full System	Manage users, update roles, delete accounts, and view audit logs.
Auditor	Read-Only	Access audit logs, login history, and transaction history for compliance.

Permission Enforcement Logic

Permissions are defined in lib/rbac.ts and enforced through helper functions such as checkPermission() and canAccessResource(). Sources: lib/rbac.ts, RBAC_IMPLEMENTATION_SUMMARY.md:32-41

// Example of permission checking logic derived from system utilities
if (isAdmin(user)) {
  // Execute admin-level logic
}

if (checkPermission(user, 'read', 'accounts')) {
  // User can read accounts based on role matrix
}

Sources: RBAC_GUIDE.md:60-75, lib/rbac.ts

Database Schema and RLS

The database schema, defined in migrations/003-rbac-and-auth.sql, incorporates specific tables for identity, authentication, and auditing. Sources: migrations/003-rbac-and-auth.sql:1-148

Key Tables

• users: Stores profiles and the assigned role (customer, admin, auditor).
• accounts: Contains financial details, featuring a zero-balance guarantee on creation.
• admin_audit_logs: An immutable table recording admin actions, including IP address and user agent.
• login_history: Tracks successful and failed login attempts with device metadata.

Sources: RBAC_IMPLEMENTATION_SUMMARY.md:18-30, RBAC_DELIVERY_SUMMARY.md:105-120

Row Level Security (RLS) Implementation

RLS policies provide a final layer of defense at the database level. For example, the users and accounts tables are restricted so that non-admin users can only view rows where the user_id matches their authenticated auth.uid(). Sources: migrations/003-rbac-and-auth.sql:120-140, RBAC_SYSTEM_ARCHITECTURE.md:288-294

Authentication and 2FA Workflow

The RBAC system is tightly integrated with a secure authentication flow that includes mandatory Two-Factor Authentication (2FA) for login. Sources: RBAC_QUICK_START.md:30-60, RBAC_IMPLEMENTATION_SUMMARY.md:55-80

Login Sequence

1. Initial Auth: User submits email/password; the system verifies the Bcrypt hash.
2. 2FA Generation: A 6-digit code is generated and stored in the two_factor_codes table with a 5-minute TTL.
3. Verification: The user submits the code to the /api/auth/verify-2fa endpoint.
4. JWT Issuance: Upon successful verification, the system marks the code as used and issues a signed JWT token valid for 7 days.

Sources: RBAC_SYSTEM_ARCHITECTURE.md:115-180, RBAC_DELIVERY_SUMMARY.md:158-170

Sequence Diagram: Authentication and 2FA

Audit and Compliance

The system ensures administrative accountability through an immutable audit logging mechanism. Every action performed by an admin or auditor role is recorded in the admin_audit_logs table. Sources: RBAC_DELIVERY_SUMMARY.md:52-65, RBAC_IMPLEMENTATION_SUMMARY.md:94-102

Audit Log Contents

• Admin Metadata: ID of the administrator performing the action.
• Action Context: Action type (e.g., UPDATE_USER_ROLE), target resource, and specific parameters in JSON format.
• Network Metadata: The source IP address and user agent of the administrator.
• Immutability: The database schema is configured to prevent the deletion or modification of these logs to maintain a clean forensic trail.

Sources: RBAC_SYSTEM_ARCHITECTURE.md:200-230, RBAC_DELIVERY_SUMMARY.md:175-185

Conclusion

Role-Based Access Control in BankChase provides a foundational security framework that isolates customer data while enabling necessary oversight through administrative and auditor roles. By leveraging 8 layers of security, including database RLS and mandatory 2FA, the system mitigates risks associated with data breaches and unauthorized lateral movement within the application. Sources: RBAC_IMPLEMENTATION_SUMMARY.md:4-15, RBAC_DELIVERY_SUMMARY.md:245-260