B2BCall-dialer/docs/AUTHENTICATION.md

Autenticação e RBAC

Implementado em packages/auth, sobre o schema criado pela migration auth_and_rbac (packages/database/prisma/schema.prisma).

Login (agente.md secao 148)

• Senha: Argon2id via @node-rs/argon2 (binário pré-compilado, sem node-gyp), parâmetros padrão OWASP (memoryCost 19 MiB, timeCost 2, parallelism 1).
• login() sempre roda verify() contra um hash Argon2id fixo mesmo quando o e-mail não existe, e devolve o mesmo erro genérico (InvalidCredentialsError) em qualquer caso de falha — mitiga user-enumeration por diferença de tempo de resposta ou mensagem.
• Access token: JWT (HS256, jose), TTL 12 horas (era 15 minutos até a PHASE 69 — pedido do usuário: turno de agente de call center não pode cair no meio, o refresh silencioso do middleware existe mas 15min forçava ele rodar a cada poucos minutos), claims { sub, sessionId, tenantId? }.
• Refresh token: string opaca aleatória (32 bytes), nunca JWT. Só o SHA-256 fica salvo em sessions.refresh_token_hash — posse do token original é a prova de identidade.
• Refresh rotation: cada uso de refreshSession() troca o hash guardado na mesma linha de sessions; o token anterior para de bater com qualquer hash no banco imediatamente.
• Logout / revogação: sessions.revoked_at — idempotente.
• mustChangePassword no User: setado true no Platform Super Admin inicial (seed); a aplicação (quando existir a camada HTTP) deve forçar troca de senha antes de liberar qualquer outra rota quando essa flag estiver ativa.

Resolução de tenant (agente.md secao 31)

Login não recebe nem decide tenant_id. O fluxo é:

1. login() autentica só por e-mail/senha — devolve tokens sem tenant.
2. listUserTenants(userId) devolve os tenants aos quais o usuário pertence (via tenant_memberships), usando withUserContext — a única exceção documentada de RLS "olhar os próprios dados sem tenant ainda escolhido" (ver docs/TENANT_ISOLATION.md).
3. setActiveTenant(sessionId, userId, tenantId) valida a membership de novo (nunca confia em tenantId vindo do cliente sem checar) e emite um novo access token já com tenantId nas claims.

RBAC (agente.md secoes 142-145)

Tabelas: roles, permissions, role_permissions, user_roles.

• Role.scope: PLATFORM (vale em qualquer tenant, UserRole.tenantId = null) ou TENANT (vale só no tenant especificado em UserRole.tenantId).
• userHasPermission(userId, permissionKey, tenantId?): junta roles PLATFORM do usuário com as roles TENANT do tenant informado, e checa se alguma delas carrega a permission. Chamado explicitamente pela camada de serviço — não depende de RLS (ver próxima seção).
• Seed (packages/auth/src/seed.ts, agente.md secao 200) cria o catálogo de permissions e 4 roles de sistema: platform_super_admin (PLATFORM, todas as permissions), tenant_admin, supervisor, agent (TENANT, mapeamento inicial documentado no próprio seed — ajustar quando existir UI de RBAC).

Por que roles/permissions/user_roles/sessions/audit_logs NÃO têm RLS

Diferente das tabelas de negócio tenant-scoped (extensions, agents, campaigns, calls, ...), essas tabelas são infraestrutura de autenticação/autorização, tocadas exclusivamente pelo código confiável de packages/auth, que já resolve o filtro de tenant explicitamente em cada query (userHasPermission, setActiveTenant, etc.). Isso é a camada "RBAC + object authorization" da defesa em profundidade da seção 32 do agente.md — complementar à RLS, não substituída por ela. Se no futuro essas tabelas passarem a ser expostas por queries genéricas (ex.: um endpoint de admin que aceita filtros arbitrários), revisitar essa decisão e considerar RLS ali também.

Platform Super Admin inicial (agente.md secao 199)

O seed cria admin@b2bcall.local com senha aleatória de 24 bytes, salva uma única vez em FIRST_LOGIN.txt (permissão 600, fora do Git) com mustChangePassword = true. Rodar de novo o seed não recria o admin se já existir um usuário com role platform_super_admin.

Camada HTTP (apps/api)

NestJS sobre Fastify (agente.md secao 12). Rotas em apps/api/src/auth:

POST /auth/login           { email, password } -> { accessToken, refreshToken, sessionId, mustChangePassword }
POST /auth/refresh         { refreshToken }     -> { accessToken, refreshToken }
POST /auth/logout          (autenticado)        -> 204
GET  /auth/tenants         (autenticado)        -> [{ tenantId, code, name, status }]
POST /auth/select-tenant   (autenticado) { tenantId } -> { accessToken }
POST /auth/change-password (autenticado) { currentPassword, newPassword } -> 204

• JwtAuthGuard (apps/api/src/common/guards) valida o access token e injeta request.user (claims do JWT); @CurrentUser() expõe isso no controller.
• DomainExceptionFilter traduz os erros de packages/auth (InvalidCredentialsError → 401, InvalidRefreshTokenError → 401, NotATenantMemberError → 403) sem vazar stack trace.
• LoginRateLimitGuard conta tentativas de login por IP e por e-mail via Redis (INCR+EXPIRE, 5/minuto — agente.md secao 149), funcionando corretamente com múltiplas instâncias da API (ao contrário de um contador em memória local).
• helmet + cors restritivo (CORS_ORIGIN via env, false por padrão — nega tudo até ser configurado) + rate limit global de 300/min como defesa extra (agente.md secao 182).
• GET /health, /health/live, /health/ready (agente.md secao 187) — ready checa Postgres e Redis de verdade.
• API escuta só em 127.0.0.1:3000 (API_PORT) — nunca exposta direto, fica atrás do nginx quando ele existir.

Pegadinha de rede corrigida durante os testes: REDIS_HOST=redis / POSTGRES_HOST=postgres no .env são os nomes de serviço do Docker Compose — só resolvem de dentro da rede Docker. Como apps/api roda direto no host (ainda não containerizada), ela usa REDIS_URL/APP_DATABASE_URL (@localhost) em vez disso. Quando b2bcall-api virar um serviço Docker na mesma rede, essas URLs precisam trocar para os hostnames internos.

O que falta

• Password reset (link expirável por e-mail) — precisa de um provedor de e-mail/SMTP, fora do escopo desta fase.
• Reuse detection de refresh token roubado (família de tokens) — não implementado; a rotação simples (secao 148) já está feita, a detecção de reuso é um hardening adicional a avaliar depois.
• Progressive blocking (backoff exponencial) no login — hoje é só janela fixa de 5/minuto.
• Enforcement server-side de mustChangePassword bloqueando outras rotas (hoje só o client precisa respeitar a flag) — revisitar quando existirem rotas de negócio de verdade para proteger.