Authentication & RBAC

Relevant source files

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

• server/src/routes/auth.ts
• server/src/routes/admin.ts
• server/src/routes/users.ts
• shared/src/validators.ts
• server/src/index.ts
• server/scripts/provision-test-accounts.ts
• client/src/types/index.ts

The Authentication and Role-Based Access Control (RBAC) system in SoulSeer manages user identity, session synchronization, and granular permission enforcement across the platform. It leverages Auth0 for identity management and integrates with an internal PostgreSQL database to maintain application-specific roles and user states.

This system ensures that different user tiers—Clients, Readers, and Admins—can only access endpoints and perform actions relevant to their roles. The backend uses Express middleware to verify JWTs and check role-specific permissions before processing requests.
Sources: server/src/index.ts:101-140, README.md:Tech Stack

Identity Management & Authentication

SoulSeer uses Auth0 as the primary identity provider. When a user authenticates via the frontend, their Auth0 identity is synchronized with the local database to track application-specific data such as account balances and reading history.

User Synchronization Flow

The /api/auth/sync endpoint is responsible for ensuring the internal users table matches the Auth0 profile. On the first login, a new user record is created; on subsequent logins, the record is updated if the full name or profile image has changed.

User Roles

Roles are assigned during synchronization or manual provisioning. The system recognizes three primary roles:

Role	Purpose	Source
client	Standard user who seeks readings and funds their balance.	shared/src/validators.ts:16
reader	Spiritual advisors who provide readings and set per-minute rates.	shared/src/validators.ts:16
admin	Platform controllers with full oversight and reader onboarding capabilities.	shared/src/validators.ts:16

Initial admin status is determined by checking if the user's email exists in a pre-configured adminEmails list.
Sources: server/src/routes/auth.ts:18-21, server/src/routes/auth.ts:35-38

Role-Based Access Control (RBAC)

RBAC is enforced on the server using middleware that intercepts requests based on the user's role stored in the database.

Middleware Implementation

The system uses two primary types of protection:

1. Authentication Guard: requireAuth ensures a valid Auth0 JWT is present.
2. Role Guard: requireRole(role) ensures the authenticated user possesses the required clearance.

Admin Management Capabilities

Admins have elevated permissions to modify user roles and provision reader accounts. The server/src/routes/admin.ts file defines several critical RBAC-protected actions:

• Role Updates: PATCH /api/admin/users/:id/role allows an admin to change any user's role, with a safety check preventing admins from demoting themselves.
• Manual Provisioning: POST /api/admin/create-manual-account uses the auth0ManagementService to create users directly in Auth0 and the internal database.
• Balance Adjustments: POST /api/admin/balance-adjust allows manual credits or debits to user accounts.

Sources: server/src/routes/admin.ts:233-255, server/src/routes/admin.ts:404-469, server/src/routes/admin.ts:258-301

Security and Data Integrity

Account Deletion (Soft-Delete)

When a user deletes their account via DELETE /api/me, the system performs a "soft-delete" to maintain financial records while scrubbing Personal Identifying Information (PII).

• The Auth0 user is deleted via the Management API.
• Internal database fields (email, fullName, bio) are replaced with scrubbed/placeholder values.
• A deletedAt timestamp is set, and the user is forced offline.
• Deletion is blocked if the user has an active reading session.

Sources: server/src/routes/users.ts:245-317

Implementation of Protected Routes

Routes in the application are grouped by access level. The following table summarizes the distribution of routes based on the server/src/index.ts configuration:

Route Path	Protection Level	Middleware Used
/api/auth	Public / Strict Rate Limit	strictLimiter
/api/readers	Public	None (Public view)
/api/me	Authenticated	requireAuth
/api/admin/*	Admin Only	requireAuth, requireRole('admin')
/api/payments/*	Authenticated	requireAuth

Sources: server/src/index.ts:101-140, server/src/routes/admin.ts:37-38

Conclusion

The Authentication and RBAC architecture of SoulSeer provides a secure foundation for a multi-tenant marketplace. By separating identity (Auth0) from application state (Local DB) and enforcing role-based logic at the middleware level, the system ensures data privacy for clients and financial security for readers.
Sources: README.md:Tech Stack, server/src/index.ts:35-70