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).