@seedgrid/fe-security 2026.7.1 → 2026.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -0
- package/package.json +1 -1
- package/scaffold/src/app/api/security/session/2fa/resend/route.ts +1 -1
- package/scaffold/src/app/api/security/session/2fa/verify/route.ts +1 -1
- package/scaffold/src/app/security/companies/editors/CompanyEditor.tsx +1 -1
- package/scaffold/src/app/security/roles/editors/RoleEditor.tsx +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# @seedgrid/fe-security
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@seedgrid/fe-security)
|
|
4
|
+
[](https://www.npmjs.com/package/@seedgrid/fe-security)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
|
|
7
|
+
Módulo de segurança do front SeedGrid: autenticação com sessão server-side (Next.js), 2FA, gestão de usuários, roles, permissões e empresas. É o módulo-base dos demais módulos front (`fe-apikeys`, `fe-audit`, `fe-backup`, `fe-billing-*`, `fe-login-tenancy`, `fe-self-enter`, `fe-subdomain-tenancy` declaram `requires: ["security"]`).
|
|
8
|
+
|
|
9
|
+
## Sumário
|
|
10
|
+
|
|
11
|
+
- [O que este pacote contém](#o-que-este-pacote-contém)
|
|
12
|
+
- [Telas entregues pelo scaffold](#telas-entregues-pelo-scaffold)
|
|
13
|
+
- [Instalação](#instalação)
|
|
14
|
+
- [Uso rápido](#uso-rápido)
|
|
15
|
+
- [Permissões](#permissões)
|
|
16
|
+
- [Backend correspondente](#backend-correspondente)
|
|
17
|
+
- [Suporte](#suporte)
|
|
18
|
+
|
|
19
|
+
## O que este pacote contém
|
|
20
|
+
|
|
21
|
+
O pacote tem três camadas:
|
|
22
|
+
|
|
23
|
+
**Lib client-safe** (`@seedgrid/fe-security`) — sem imports de `next/*`, pode entrar em bundle client:
|
|
24
|
+
|
|
25
|
+
- `SecurityPaths` — contrato único dos paths REST (auth, 2FA, users, roles, permissions, companies, me, self-enter), espelho do `RestControllerPath.java` da extensão backend.
|
|
26
|
+
- Helpers de permissão: `normalizePermission`, `hasPermission`, `hasAnyPermission`, `hasAllPermissions`, `buildCrudPermissions`, `createPermissionSet`.
|
|
27
|
+
- DTOs de usuários, roles, permissões, empresas e sessão (`session-contract`, `session-result`, `server-contract`).
|
|
28
|
+
- `securityMessages` — bundle i18n (en, pt-BR, es, fr, pt-PT).
|
|
29
|
+
|
|
30
|
+
**Componentes client** (`@seedgrid/fe-security/client`):
|
|
31
|
+
|
|
32
|
+
- `PermissionProvider` — contexto de permissões do usuário logado.
|
|
33
|
+
- `PickListField`, `StatusBadge` — componentes usados nas telas de CRUD.
|
|
34
|
+
|
|
35
|
+
**Motor server-side** (`@seedgrid/fe-security/server`) — SERVER-ONLY:
|
|
36
|
+
|
|
37
|
+
- `createSecurityServer` — motor de sessão (login, refresh de token, logout, 2FA) com cookie httpOnly; é a fundação sobre a qual os outros módulos compõem os seus engines.
|
|
38
|
+
- Helpers de rota: `toRouteResponse`, respostas Problem+JSON (`toProblem`, `problemResponse`) e helpers de server action.
|
|
39
|
+
|
|
40
|
+
## Telas entregues pelo scaffold
|
|
41
|
+
|
|
42
|
+
O diretório `scaffold/` é copiado para dentro do app gerado pelo SeedGrid CLI (o app é dono do código e pode editar à vontade):
|
|
43
|
+
|
|
44
|
+
| Tela | Rota | O que faz |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| Login | `/auth/login` | Autenticação com e-mail/senha; redireciona pro 2FA quando exigido |
|
|
47
|
+
| Verificação 2FA | `/auth/2fa/verify` | Confirma o código do segundo fator (com reenvio) |
|
|
48
|
+
| Esqueci a senha | `/auth/forgot-password` (+ `confirm`, `success`) | Fluxo completo de recuperação de senha |
|
|
49
|
+
| Boas-vindas | `/auth/welcome` | Primeira entrada / confirmação de e-mail |
|
|
50
|
+
| Usuários | `/security/users` (lista, novo, edição) | CRUD de usuários com avatar, membership por empresa |
|
|
51
|
+
| Roles | `/security/roles` (lista, novo, edição) | CRUD de roles com atribuição de permissões |
|
|
52
|
+
| Empresas | `/security/companies` (lista, novo, edição) | CRUD de empresas (guardado por `CompanyManagementGuard`) |
|
|
53
|
+
| Perfil | `/security/profile` | Dados do próprio usuário |
|
|
54
|
+
| Configuração 2FA | `/security/2fa` | Habilitar/desabilitar segundo fator (TOTP) |
|
|
55
|
+
| Trocar senha | `/users/change-password` | Troca de senha do usuário logado |
|
|
56
|
+
|
|
57
|
+
O scaffold também traz o `AuthProvider`, `RouteGuard` (proteção de rotas), `AppShell` com menu por permissão (`useSecurityAppShellSections`), dashboard de segurança e as rotas-proxy de API (`/api/security/session/*`, avatar de usuário).
|
|
58
|
+
|
|
59
|
+
## Instalação
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pnpm add @seedgrid/fe-security @seedgrid/fe-core @seedgrid/fe-components
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
A forma recomendada de consumir o módulo é via **SeedGrid CLI**, que copia o scaffold, registra navegação/i18n e configura o `module.json` automaticamente.
|
|
66
|
+
|
|
67
|
+
## Uso rápido
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// src/modules/security/server/server-api.ts (server-only)
|
|
71
|
+
import { createSecurityServer } from "@seedgrid/fe-security/server";
|
|
72
|
+
|
|
73
|
+
export const session = createSecurityServer({
|
|
74
|
+
apiBaseUrl: process.env.SEEDGRID_API_BASE_URL!,
|
|
75
|
+
cookies: { /* nomes dos cookies de sessão do app */ },
|
|
76
|
+
serviceToken: process.env.SEEDGRID_REPORT_API_TOKEN, // fallback server-to-server
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
// Qualquer módulo dependente compõe sobre a mesma sessão:
|
|
82
|
+
import { createApiKeysServer } from "@seedgrid/fe-apikeys/server";
|
|
83
|
+
export const apiKeys = createApiKeysServer(session);
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
// Client: checagem de permissão
|
|
88
|
+
import { hasPermission, buildCrudPermissions } from "@seedgrid/fe-security";
|
|
89
|
+
|
|
90
|
+
const USER_PERMISSIONS = buildCrudPermissions("USER"); // USER_READ, USER_CREATE, ...
|
|
91
|
+
if (hasPermission(userPermissions, USER_PERMISSIONS.read)) {
|
|
92
|
+
// renderiza a lista de usuários
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Permissões
|
|
97
|
+
|
|
98
|
+
As telas de CRUD seguem a convenção `RECURSO_AÇÃO`: `USER_*`, `ROLE_*`, `COMPANY_*` (`READ`/`CREATE`/`UPDATE`/`DELETE`). O menu do `AppShell` esconde seções que o usuário não pode acessar e o `RouteGuard` bloqueia acesso direto por URL.
|
|
99
|
+
|
|
100
|
+
## Backend correspondente
|
|
101
|
+
|
|
102
|
+
Este módulo conversa com a extensão Quarkus `seedgrid-quarkus-ext-security`. Os paths de `SecurityPaths` são espelho 1:1 do `RestControllerPath.java` — mudou um path no backend, atualize aqui também.
|
|
103
|
+
|
|
104
|
+
Variável de ambiente exigida pelo scaffold: `SEEDGRID_REPORT_API_TOKEN`.
|
|
105
|
+
|
|
106
|
+
## Suporte
|
|
107
|
+
|
|
108
|
+
- Issues: https://github.com/SeedGrid/seedgrid-fe-components/issues
|
|
109
|
+
- Repositório: https://github.com/SeedGrid/seedgrid-fe-components
|
|
110
|
+
|
|
111
|
+
## Licença
|
|
112
|
+
|
|
113
|
+
MIT
|
package/package.json
CHANGED