WisprX Auth & RBAC

- JWT-based authentication is used throughout the platform. - Every token must contain:
  - `sub`: user ID
  - `tenantId`: associated tenant/company (nullable for platform-level users)
  - `role`: role type (ex: SUPER_ADMIN, TENANT_ADMIN, USER)
  - `scope`: either `system` (WisprX Admin Panel) or `tenant` (Client Company Panel)
- Use `@nestjs/passport` with `JwtStrategy` to parse the token from headers. - Optional refresh token support may be added later via a secure dual-token flow.
## Role Scopes & Separation
WisprX has **two levels of role hierarchy**, each with its own permissions:
### 1. System Scope (WisprX Admin Panel)
- `SUPER_ADMIN`: Full access to manage tenants, plans, billing, logs, etc. - `ADMIN`: Operational WisprX team member (support, onboarding, monitoring) - `USER`: Internal users with restricted read-only or support roles.
### 2. Tenant Scope (Client’s Admin Panel)
- `ADMIN`: Manages users, messages, contacts, automations, and settings for their company. - `USER`: Regular operator (agents, support reps, sales reps). - `GUEST`: Optional read-only or restricted permission (e.g., temporary access).
The token’s `scope` must match the requested route context.
## RBAC Enforcement
- Use guards:
  - `JwtAuthGuard`: ensures user is authenticated.
  - `ScopeGuard`: ensures scope matches (system or tenant).
  - `RolesGuard`: ensures user has the right role.
  - `TenantGuard`: ensures user is allowed to access that tenant’s data.
- Decorators:
  - `@Roles('TENANT_ADMIN')`, `@Scopes('system')`, `@CurrentUser()` etc.

## Tenant Isolation
- Every request with scope `tenant` **must include and validate `tenantId`**. - All database operations must be scoped using:
  - `where tenant_id = :tenantId` clauses or Prisma filters.
  - Or implicit filters via global query interceptors.
- **Never allow data cross-tenant** under any condition.
## Route Structure
- System panel routes: `/system/users`, `/system/tenants`, `/system/billing`, etc. - Tenant panel routes: `/crm/contacts`, `/inbox`, `/automations`, etc. - Scope must be strictly enforced per route group.
## Session & Metadata
- Stateless sessions using JWT, optionally persisted in a `sessions` table with:
  - `ip`, `user_agent`, `logged_at`, `revoked` (bool)
- Optionally use Redis for token blacklisting and concurrent session management.
## Testing & Security
- All guards and RBAC logic must have unit and integration tests. - Routes must deny access properly if role or scope is invalid. - Admin routes must be locked from tenant users, and vice-versa. - Never expose raw internal IDs or role logic in public errors.
## Future Expansion (optional)
- Implement fine-grained permissions per module (e.g., canCreateCRM, canViewAutomation). - Add support for custom roles per tenant (enterprise feature).