Autenticação & RBAC

Modelo

• Organization → User (e-mail único por organização) → UserRole → Role → RolePermission → Permission (recurso:ação, ex.: order:create).
• isSuperAdmin concede acesso total dentro da organização (ignora checagem granular).

Fluxo de tokens

• Access token (JWT) — curto (TTL JWT_ACCESS_TTL, padrão 15 min). Claims: sub, orgId, email. Validado a cada request; permissões recarregadas do banco.
• Refresh token (opaco) — aleatório, persistido como sha256 em refresh_tokens, TTL longo (JWT_REFRESH_TTL, padrão 30 dias). Rotacionado a cada refresh (o antigo é revogado). Logout revoga o token.

Endpoints (API NestJS)

Método	Rota	Público	Descrição
POST	/api/auth/login	sim	Autentica; retorna accessToken, refreshToken, expiresIn, user.
POST	/api/auth/refresh	sim	Rotaciona o refresh e emite nova sessão.
POST	/api/auth/logout	não	Revoga o refresh token informado.
GET	/api/auth/me	não	Retorna o usuário autenticado (papéis + permissões).
GET	/health	sim	Liveness/readiness (checa o banco).

Detalhes e schemas na Referência da API (Scalar).

Frontend (Next.js)

O browser nunca vê o token. O login é proxiado por um route handler (/api/auth/login) que chama a API e grava accessToken/refreshToken em cookies httpOnly. O middleware.ts protege as rotas; o layout do dashboard valida a sessão via /api/auth/me.

Proteção de rotas no backend

• JwtAuthGuard global — exige autenticação, exceto rotas marcadas com @Public().
• PermissionsGuard global — @RequirePermissions('order:create') exige a(s) permissão(ões).

@RequirePermissions("order:create")
@Post("orders")
createOrder() { /* ... */ }

Seed inicial

pnpm --filter @sfa/api seed cria a organização padrão, o catálogo de permissões, o papel Administrator (todas as permissões) e o usuário admin. Configurável via variáveis SEED_* no .env.