Segurança, Autenticação e Papéis (RBAC)

Segurança, Autenticação e Controle de Acesso (RBAC)

O Prime Crown possui uma arquitetura de segurança stateless baseada em JSON Web Tokens (JWT), suporte a Biometria (WebAuthn/Passkeys), login de telefone formatado em E.164 e controle estrito de papéis (Role-Based Access Control - RBAC).

---

🔒 1. Hierarquia de Papéis (Roles)

Papel	Permissões no Sistema
ADMIN	Acesso total ao sistema, configurações fiscais, gerenciamento de usuários e impersonação.
MANAGER	Gestão de agendamentos, chat com clientes, alocação de equipes e folha de pagamento.
EMPLOYEE	Acesso restrito ao aplicativo da funcionária (visualizar agenda própria, check-in/out GPS e rotas).
CLIENT	Acesso ao portal do cliente (visualizar limpezas agendadas, faturas e solicitar suporte).

---

🔑 2. Impersonação de Contas (Impersonation Mode)

Os Administradores e Gerentes possuem o recurso de Impersonação, permitindo visualizar exatamente a interface e dados como se fossem o cliente ou a funcionária em questão.

sequenceDiagram
    autonumber
    actor Admin as Administrador
    participant API as Auth API (/api/auth/impersonate)
    participant Auth as AuthContext (Frontend)

    Admin->>API: POST /api/auth/impersonate (targetUserId)
    API->>API: Valida papel ADMIN/MANAGER
    API-->>Auth: Retorna JWT temporário de Impersonação
    Auth->>Auth: Alterna contexto visual para a Role do Target
    Note over Admin, Auth: Admin opera como o usuário sem saber sua senha real
    Admin->>API: POST /api/auth/impersonate (stop: true)
    API-->>Auth: Restaura JWT original do Admin

---

🛡️ 3. E.164 Phone Normalization & WebAuthn

• Identificador E.164: Para evitar duplicidade de contas pelo formato de digitação do telefone (ex: 07123456789 vs +447123456789), a função normalizePhoneIdentifier em src/shared/loginIdentifier.ts converte o número para o padrão internacional estrito E.164 antes de salvar ou autenticar no D1.
• Passkeys / WebAuthn: Suporte a login biométrico por impressão digital ou FaceID nativo em dispositivos móveis e desktops via @simplewebauthn.