@acropole/skills 0.0.0-stage → 1.1.0
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 +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Estrutura, bootstrap, build e configuração
|
|
2
|
+
|
|
3
|
+
## Árvore de pastas (servidor REST)
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
server/
|
|
7
|
+
package.json
|
|
8
|
+
tsconfig.json
|
|
9
|
+
scripts/ # utilitários fora do app (smoke tests, seeds pontuais)
|
|
10
|
+
src/
|
|
11
|
+
index.ts # carrega config e chama o builder; erro de env = exit(1)
|
|
12
|
+
config/
|
|
13
|
+
index.ts # dotenv/dotenvx + schema zod -> export config / EnvConfig
|
|
14
|
+
openapi.ts # spec servida por swagger-ui em <prefixo>/docs
|
|
15
|
+
environments/.env.<amb> # um por ambiente (local, dev, homol, prod) — nunca em texto puro no git
|
|
16
|
+
database/
|
|
17
|
+
connection.ts # export const db = knex(config)
|
|
18
|
+
db.pg.config.ts # client, connection, pool
|
|
19
|
+
migrations/ # SQL versionado (ver dados.md)
|
|
20
|
+
core/
|
|
21
|
+
index.ts # startup de dependências (Orfeu, cache), Server.start, shutdown
|
|
22
|
+
server/index.ts # cria o app Express, middlewares, monta routers, listen
|
|
23
|
+
server/http.server.ts # http.createServer(app) (necessário p/ WebSocket e close())
|
|
24
|
+
middlewares/ # request-id, logger, error, security-headers, rate-limit, validation...
|
|
25
|
+
auth/ # instância do OrfeuClient + wrapper guard()
|
|
26
|
+
database/ # helpers genéricos (upsert portátil, conversão JSON)
|
|
27
|
+
modules/ # logger, cache (redis), crypto, upload
|
|
28
|
+
app/
|
|
29
|
+
routes/
|
|
30
|
+
router.ts # /health, /docs, montagem dos namespaces
|
|
31
|
+
<area>/index.ts # agrega sub-routers da área
|
|
32
|
+
<area>/<recurso>/index.ts # wiring: método + path + guard + validate + handler
|
|
33
|
+
<area>/<recurso>/<recurso>.controller.ts
|
|
34
|
+
<area>/<recurso>/<recurso>.validators.ts # schemas zod { body, params, query }
|
|
35
|
+
services/<dominio>/*.service.ts # regra de negócio, integrações externas
|
|
36
|
+
modules/database/<schema>/<recurso>/
|
|
37
|
+
<recurso>.entity.ts # classe com campos camelCase
|
|
38
|
+
<recurso>.mapper.ts # row snake_case -> entity
|
|
39
|
+
<recurso>.repository.ts # queries Knex (métodos estáticos)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Regras:
|
|
43
|
+
|
|
44
|
+
- **Controller não escreve SQL.** Se a mesma consulta aparece em dois controllers, vira método de
|
|
45
|
+
repositório. Regra que envolve mais de um repositório ou integração externa vai para `services/`.
|
|
46
|
+
- Controllers e repositórios com **métodos estáticos** (`static async list(req, res)`) são o padrão
|
|
47
|
+
dos projetos; sem container de DI. Funciona bem, desde que o estado compartilhado (db, cache,
|
|
48
|
+
client do Orfeu) seja módulo singleton.
|
|
49
|
+
- Serialização de saída num helper do controller (`serializeX(entity)`) quando a API expõe snake_case
|
|
50
|
+
e o domínio é camelCase. Escolha **um** casing por API e mantenha.
|
|
51
|
+
- Namespaces de rota por público: `/admin/*` (painel), `/me/*` (recursos do próprio usuário),
|
|
52
|
+
`/service/*` (máquina a máquina), cada um com seu guard no ponto de montagem.
|
|
53
|
+
|
|
54
|
+
## Bootstrap
|
|
55
|
+
|
|
56
|
+
Sequência: `index.ts` → `config` (valida env) → `core/index.ts` (dependências) → `Server.start`.
|
|
57
|
+
|
|
58
|
+
- Dependências que a API precisa para responder corretamente (banco, `orfeuClient.startup()`, cache)
|
|
59
|
+
sobem **antes** do `listen`. Aquecer caches usados por middleware (ex.: lista de origens do CORS)
|
|
60
|
+
também, para a primeira requisição não pagar a query.
|
|
61
|
+
- Se uma dependência externa pode ficar indisponível por um tempo (o servidor de autorização, por
|
|
62
|
+
exemplo), o padrão aceito é subir mesmo assim **negando** as operações protegidas e tentar de novo em
|
|
63
|
+
segundo plano (`setTimeout(retry, 30_000).unref()`). Nunca "modo degradado" que libera tudo.
|
|
64
|
+
- `guard()` registra a operação no import do router; por isso `startup()` do Orfeu deve rodar depois
|
|
65
|
+
que os routers foram importados (o import de `./server` no topo de `core/index.ts` já garante).
|
|
66
|
+
|
|
67
|
+
## TypeScript e build
|
|
68
|
+
|
|
69
|
+
Há dois estilos nos projetos:
|
|
70
|
+
|
|
71
|
+
| | Servidores REST | Gateways GraphQL |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| Express | 5.x | 4.x |
|
|
74
|
+
| Módulos | CommonJS (`"module": "CommonJS"`) | ESM (`"type": "module"`, imports com `.js`) |
|
|
75
|
+
| Dev | `nodemon` + `ts-node -r tsconfig-paths/register` | `tsx watch` |
|
|
76
|
+
| Build | `tsc` → `dist/` | `tsc` ou `esbuild --bundle --packages=external` |
|
|
77
|
+
| Aliases | `baseUrl: "src"` + `paths` (`src/*`) | imports relativos |
|
|
78
|
+
| Env | `@dotenvx/dotenvx` (arquivos cifrados) + zod | `dotenv` + `process.env` cru |
|
|
79
|
+
|
|
80
|
+
**Recomendado para serviço novo:** Express 5, ESM, `tsx watch` em dev, `tsc` (ou esbuild) no build,
|
|
81
|
+
`strict: true`, imports relativos ou `paths` resolvidos no build (sem depender de
|
|
82
|
+
`tsconfig-paths` em runtime), config validada por zod. Se usar `tsconfig-paths` em runtime com
|
|
83
|
+
`baseUrl: "src"`, o container precisa de `TS_NODE_BASEURL=./dist`.
|
|
84
|
+
|
|
85
|
+
`tsconfig` mínimo usado:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"compilerOptions": {
|
|
90
|
+
"target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
|
|
91
|
+
"outDir": "dist", "strict": true, "esModuleInterop": true, "resolveJsonModule": true
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Scripts por ambiente com `cross-env NODE_ENV=<amb>`; o arquivo `.env.<amb>` é escolhido pelo
|
|
97
|
+
`NODE_ENV`. Em produção, `node dist/index.js` (nunca `nodemon`/`ts-node`).
|
|
98
|
+
|
|
99
|
+
## Configuração por ambiente
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
import dotenvx from '@dotenvx/dotenvx';
|
|
103
|
+
import { z } from 'zod';
|
|
104
|
+
|
|
105
|
+
dotenvx.config({ path: `src/config/environments/.env.${process.env.NODE_ENV}`, quiet: true });
|
|
106
|
+
|
|
107
|
+
const envSchema = z.object({
|
|
108
|
+
API_PREFIX: z.string().min(1),
|
|
109
|
+
PORT: z.string().transform(Number).optional().default(3000),
|
|
110
|
+
DB_HOST: z.string(), DB_PORT: z.string().transform(Number), DB_USER: z.string(),
|
|
111
|
+
DB_PASSWORD: z.string(), DB_DATABASE: z.string(),
|
|
112
|
+
DB_POOL_MIN: z.string().transform(Number).optional().default(2),
|
|
113
|
+
DB_POOL_MAX: z.string().transform(Number).optional().default(10),
|
|
114
|
+
AUTHORIZER_URL: z.url(), REALM_ID: z.string().min(1),
|
|
115
|
+
APP_ID: z.string().min(1), APP_SECRET: z.string().min(1),
|
|
116
|
+
AUTH_TLS_VERIFY: z.string().transform(v => v !== 'false').optional().default(true),
|
|
117
|
+
UI_STATIC_PATH: z.string().optional(),
|
|
118
|
+
UI_BASE_PATH: z.string().optional(),
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
const parsed = envSchema.safeParse(process.env);
|
|
122
|
+
if (!parsed.success) {
|
|
123
|
+
throw Error(`Invalid environment variables:\n${JSON.stringify(parsed.error.flatten().fieldErrors, null, 2)}`);
|
|
124
|
+
}
|
|
125
|
+
export type EnvConfig = z.infer<typeof envSchema>;
|
|
126
|
+
export const config: EnvConfig = parsed.data;
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Variáveis recorrentes (só nomes): `API_PREFIX`, `PORT`/`AGENT_PORT`, `DB_*`, `REDIS_*`,
|
|
130
|
+
`AUTHORIZER_URL`/`AUTH_SERVER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTH_TLS_VERIFY`,
|
|
131
|
+
`SMTP_*`, `UI_STATIC_PATH`, `UI_BASE_PATH`, `GRAPHQL_PATH`, `GRAPHQL_INTROSPECTION`.
|
|
132
|
+
|
|
133
|
+
- `AUTH_TLS_VERIFY=false` existe só para ambiente com certificado autoassinado; é opção **escopada ao
|
|
134
|
+
client do Orfeu**, nunca `NODE_TLS_REJECT_UNAUTHORIZED=0` global. Desligada, loga um aviso na subida e
|
|
135
|
+
aparece como `tls_verify: false` no `/health`. Prefira `NODE_EXTRA_CA_CERTS` com a CA do ambiente.
|
|
136
|
+
- `API_DOCS` (opcional): liga/desliga o Swagger; sem ela, só em `NODE_ENV=local`.
|
|
137
|
+
- `@types/node` na major do Node da imagem (`node:22` → `^22`).
|
|
138
|
+
- Booleans de env: compare com string (`v !== 'false'`), não `Boolean(v)` (`"false"` é truthy).
|
|
139
|
+
- Arquivos `.env` cifrados (dotenvx) podem ir ao repositório; a chave de decifrar fica fora dele.
|
|
140
|
+
Arquivo de `.env` em texto puro nunca é versionado.
|
|
141
|
+
|
|
142
|
+
## Servir a SPA pelo mesmo processo
|
|
143
|
+
|
|
144
|
+
Padrão usado quando a UI Angular é empacotada na mesma imagem:
|
|
145
|
+
|
|
146
|
+
- `UI_STATIC_PATH` definido → `express.static` + fallback para `index.html`.
|
|
147
|
+
- `UI_BASE_PATH` (ex.: `/painel`) → monta estáticos, fallback **e** a API também sob
|
|
148
|
+
`${UI_BASE_PATH}${API_PREFIX}`, para bater com o `--base-href` do build atrás de proxy por caminho.
|
|
149
|
+
- Em dev, sem `UI_STATIC_PATH`: a UI roda no `ng serve` e a origem dela precisa estar liberada no CORS.
|
|
150
|
+
|
|
151
|
+
## Divergências encontradas
|
|
152
|
+
|
|
153
|
+
- Express 4 vs 5 e CJS vs ESM (tabela acima).
|
|
154
|
+
- Config validada (zod) vs `process.env` cru — prefira zod.
|
|
155
|
+
- Shutdown: presente em alguns serviços, ausente em outros — sempre implemente.
|
|
156
|
+
- Rastreamento: alguns usam `traceparent` do Orfeu, um gateway usa header próprio de trace
|
|
157
|
+
(`x-trace-id`). Use o do Orfeu (W3C `traceparent`).
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# Middlewares
|
|
2
|
+
|
|
3
|
+
## Ordem (servidor REST que também pode servir a SPA)
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
app.set('trust proxy', true); // 1. atrás de proxy TLS: req.protocol/req.ip corretos
|
|
7
|
+
app.use(requestId); // 2. id de correlação antes de qualquer log
|
|
8
|
+
app.use(requestLogger); // 3. loga no 'finish' (status e duração reais)
|
|
9
|
+
app.use(express.json({ limit: '10mb' })); // 4. parsers — UM json(), já com o limite
|
|
10
|
+
app.use(express.urlencoded({ extended: true }));
|
|
11
|
+
app.use((req, _res, next) => { if (req.body === undefined) req.body = {}; next(); }); // Express 5: sem parser = undefined
|
|
12
|
+
app.use(securityHeaders(servesUi)); // 5. HSTS, CSP, nosniff...
|
|
13
|
+
app.use(cookieParser()); // 6. cookies (sessão/refresh)
|
|
14
|
+
if (UI_STATIC_PATH) app.use(UI_BASE_PATH || '/', express.static(UI_STATIC_PATH)); // 7. estáticos
|
|
15
|
+
app.use(API_PREFIX, corsMiddleware, blockForeignWrites, router, apiNotFound); // 8. CORS só na API; 404 JSON
|
|
16
|
+
if (UI_STATIC_PATH) app.get(`${UI_BASE_PATH}/*splat`, sendIndexHtml); // 9. fallback SPA
|
|
17
|
+
app.use(handleErrors); // 10. sempre o último
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`apiNotFound` responde `404 { error: 'not_found' }` para rota de API que nenhum handler atendeu — sem ele a
|
|
21
|
+
requisição segue e cai no fallback da SPA (`index.html` com 200). Os routers recebem `applyUuidParams`
|
|
22
|
+
(rotas-erros.md).
|
|
23
|
+
|
|
24
|
+
Gateway GraphQL (Express 4 + Apollo), tudo no mesmo `app.use(path, …)`:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
app.use(graphqlPath,
|
|
28
|
+
compression(), // respostas grandes de JSON comprimem 70–85%
|
|
29
|
+
cors<cors.CorsRequest>(),
|
|
30
|
+
express.json(),
|
|
31
|
+
expressMiddleware(apollo, { context: async ({ req }) => ({ req, App: modules }) }),
|
|
32
|
+
);
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Montagem do Apollo, plugins e contexto: apollo.
|
|
36
|
+
|
|
37
|
+
## Request id / correlação
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
export function requestId(req: Request, res: Response, next: NextFunction) {
|
|
41
|
+
const id = (req.headers['x-request-id'] as string) || randomUUID();
|
|
42
|
+
req.requestId = id; // declare na augmentação de Express.Request
|
|
43
|
+
res.setHeader('X-Request-Id', id);
|
|
44
|
+
next();
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- `x-request-id` identifica **a requisição** neste serviço (logs). A correlação **entre serviços** é o
|
|
49
|
+
`traceparent` (W3C) gerenciado pelo Orfeu — não invente um header de trace próprio (um gateway que
|
|
50
|
+
fez isso precisou de lógica de origem/propagação paralela). Ver orfeu.
|
|
51
|
+
- Declare campos novos de `req` por augmentação, não com `(req as any)`:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
declare global {
|
|
55
|
+
namespace Express { interface Request { requestId?: string; serviceApp?: AppEntity } }
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Logger de requisição
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
export function requestLogger(req: Request, res: Response, next: NextFunction) {
|
|
63
|
+
const start = Date.now();
|
|
64
|
+
res.on('finish', () => Logger.info('request', {
|
|
65
|
+
requestId: req.requestId, method: req.method, url: req.originalUrl,
|
|
66
|
+
status: res.statusCode, ms: Date.now() - start,
|
|
67
|
+
}));
|
|
68
|
+
next();
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Não logue headers nem body (tokens, senhas). `originalUrl` pode conter query com dado sensível em
|
|
73
|
+
fluxos OAuth — nesses endpoints, logue só o path.
|
|
74
|
+
|
|
75
|
+
## CORS
|
|
76
|
+
|
|
77
|
+
- **Nunca global** quando o processo serve a SPA: `<script type="module" crossorigin>` manda `Origin`
|
|
78
|
+
até em same-origin e o CORS derrubava os próprios bundles com 500.
|
|
79
|
+
- Allowlist **dinâmica** (origens dos clients cadastrados no banco) com cache curto (TTL ~30 s) no
|
|
80
|
+
repositório — um cadastro novo vale sem reiniciar.
|
|
81
|
+
- Permita same-origin explicitamente: o navegador manda `Origin` em POST/PUT/DELETE same-origin; atrás
|
|
82
|
+
de balanceador a origem pública não está na allowlist.
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
|
|
86
|
+
|
|
87
|
+
async function originAllowed(req: Request, origin: string): Promise<boolean> {
|
|
88
|
+
if (uiOrigin && origin === uiOrigin) return true; // ng serve em dev
|
|
89
|
+
if (isSameOrigin(req, origin)) return true; // compara com X-Forwarded-Host / Host
|
|
90
|
+
try { return (await OriginsRepository.origins()).includes(origin); }
|
|
91
|
+
catch { return false; } // banco fora: recusa, não derruba
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// Origem recusada: segue SEM o header Access-Control-Allow-Origin (o navegador bloqueia a leitura).
|
|
95
|
+
// Nunca `cb(new Error(...))`: isso vira 500 no error handler.
|
|
96
|
+
const corsMiddleware = cors((req, cb) => {
|
|
97
|
+
const origin = req.headers.origin;
|
|
98
|
+
if (!origin) return cb(null, { origin: false }); // curl, server-to-server: CORS não se aplica
|
|
99
|
+
originAllowed(req, origin).then((ok) => cb(null, { origin: ok, credentials: true }));
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
// Sem o header o navegador não LÊ a resposta, mas a requisição já EXECUTOU. Para método que muda estado,
|
|
103
|
+
// barre antes do router.
|
|
104
|
+
const blockForeignWrites: RequestHandler = async (req, res, next) => {
|
|
105
|
+
const origin = req.headers.origin;
|
|
106
|
+
if (!origin || SAFE_METHODS.has(req.method) || await originAllowed(req, origin)) return next();
|
|
107
|
+
res.status(403).json({ error: 'origin_not_allowed', detail: 'Origem não permitida.' });
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
app.use(API_PREFIX, corsMiddleware, blockForeignWrites, router);
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- Origem não permitida: resposta **sem** o header de CORS (nunca 500); `POST`/`PUT`/`PATCH`/`DELETE` dessa
|
|
114
|
+
origem recebem **403** antes de chegar ao handler.
|
|
115
|
+
- Falha ao consultar a allowlist recusa a origem; não derruba a requisição.
|
|
116
|
+
Gateways que só recebem tráfego do proxy/front usam `cors()` aberto — aceitável quando a autorização
|
|
117
|
+
é por token em header (não cookie).
|
|
118
|
+
|
|
119
|
+
## Security headers
|
|
120
|
+
|
|
121
|
+
Sempre: `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`,
|
|
122
|
+
`Referrer-Policy: strict-origin-when-cross-origin`, `Permissions-Policy` restritiva e CSP.
|
|
123
|
+
|
|
124
|
+
- API pura: `default-src 'none'; frame-ancestors <origens permitidas ou 'none'>`.
|
|
125
|
+
- Servindo SPA: `default-src 'self'`, `style-src 'self' 'unsafe-inline'` (CSS crítico inline do
|
|
126
|
+
Angular), `img-src 'self' data:`, `connect-src 'self' <servidor de autorização>`, e hashes para os
|
|
127
|
+
scripts inline fixos que o build gera (não use `'unsafe-inline'` em `script-src`).
|
|
128
|
+
- Rota de docs (swagger) define o próprio CSP.
|
|
129
|
+
- Middleware que consulta banco para montar header **não pode** derrubar a resposta:
|
|
130
|
+
`.catch(() => [])` e caia no valor mais restritivo.
|
|
131
|
+
|
|
132
|
+
## Rate limit
|
|
133
|
+
|
|
134
|
+
Contador em Redis com `INCR` + `EXPIRE` atômicos (script Lua), chave por IP + rota + tenant:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
const loginRateLimit = rateLimit({
|
|
138
|
+
windowMs: 60_000, max: 10,
|
|
139
|
+
keyGenerator: req => `rl:login:${req.ip}:${req.params.realmId}`,
|
|
140
|
+
});
|
|
141
|
+
router.post('/login', loginRateLimit, validate(loginSchema), AuthController.login);
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Responde `429 { error: 'too_many_requests' }` com `X-RateLimit-Limit`, `X-RateLimit-Remaining` e
|
|
145
|
+
`Retry-After`. Use em login, recuperação de senha e qualquer endpoint que permita enumeração.
|
|
146
|
+
`req.ip` só é confiável com `trust proxy` configurado.
|
|
147
|
+
|
|
148
|
+
## Autenticação e autorização (Orfeu)
|
|
149
|
+
|
|
150
|
+
Detalhes do SDK, níveis, métodos e headers: **orfeu**. A parte Express:
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
// core/auth/orfeu.client.ts
|
|
154
|
+
export const orfeuClient = new OrfeuClient({
|
|
155
|
+
authorizerUrl: config.AUTHORIZER_URL, realmId: config.REALM_ID,
|
|
156
|
+
appId: config.APP_ID, secret: config.APP_SECRET, tlsVerify: config.AUTH_TLS_VERIFY,
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
// core/auth/guard.ts
|
|
160
|
+
import { orfeu } from '@orfeu/node/express';
|
|
161
|
+
import { detectMethod, Level, Method } from '@orfeu/node';
|
|
162
|
+
const sdk = orfeu(orfeuClient);
|
|
163
|
+
export const orfeuMiddleware = sdk.middleware; // só captura credencial + trace
|
|
164
|
+
export function guard(identifier: string, level: Level, method?: Method) {
|
|
165
|
+
orfeuClient.registerOperation({ identifier, method: method ?? detectMethod(identifier), level });
|
|
166
|
+
return sdk.guard(identifier, level, method); // valida token e checa permissão
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// app/routes/router.ts
|
|
170
|
+
router.use('/admin', orfeuMiddleware, admin); // middleware no namespace
|
|
171
|
+
// app/routes/admin/groups/index.ts
|
|
172
|
+
router.get('/', guard('admin:groups:list', Level.PROTECTED), GroupsController.list);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
- **Uma instância** de `OrfeuClient` por política (ex.: uma estrita ao próprio tenant, outra com
|
|
176
|
+
`acceptAnyRealm` para rotas que aceitam qualquer tenant), compartilhada por todos os routers.
|
|
177
|
+
- Duas rotas podem declarar a mesma operação de propósito (listar e detalhar sob a mesma leitura);
|
|
178
|
+
o registro deduplica por identificador + método.
|
|
179
|
+
- Rota que aceita qualquer usuário autenticado mas precisa de `req.orfeuUser`: guard `Level.PUBLIC`
|
|
180
|
+
(valida se houver credencial, nunca bloqueia) + um middleware seu que responde 401 se faltar.
|
|
181
|
+
Escolha o `Method` pelo verbo HTTP (GET/HEAD → READ, DELETE → DELETE, resto → WRITE) para a
|
|
182
|
+
auditoria registrar certo.
|
|
183
|
+
- Usuário autenticado em `req.orfeuUser` (`sub`, `groups`, `raw` com as claims).
|
|
184
|
+
|
|
185
|
+
## Middlewares de escopo próprios
|
|
186
|
+
|
|
187
|
+
Padrões reais que complementam o guard:
|
|
188
|
+
|
|
189
|
+
- **Escopo de client/tenant** (`/clients/:clientId/*`): confere que o usuário tem acesso àquele
|
|
190
|
+
client (consulta de vínculo grupo ↔ client) e, se exigido, um papel ativo no token. 401 sem usuário,
|
|
191
|
+
403 sem vínculo.
|
|
192
|
+
- **Máquina a máquina** (`/service/*`): aceita só token de aplicação (`client_credentials`), busca a
|
|
193
|
+
aplicação, exige `enabled` e o grant; o tenant usado dali em diante vem do **registro** da aplicação,
|
|
194
|
+
nunca de parâmetro enviado pelo cliente.
|
|
195
|
+
- **Recursos do próprio usuário** (`/me/*`): sem permissão por operação; cada consulta filtra pelo
|
|
196
|
+
`sub` do token.
|
|
197
|
+
|
|
198
|
+
Todos respondem no formato `{ error, detail }` e são montados no ponto de entrada do namespace.
|
|
199
|
+
|
|
200
|
+
## Upload
|
|
201
|
+
|
|
202
|
+
- Multipart com `multer` (`memoryStorage`, `limits.fileSize`) + validação de mimetype/extensão.
|
|
203
|
+
- **Erros do multer são do cliente**: eles não têm `status` e caem no error handler como 500. Embrulhe o
|
|
204
|
+
middleware e traduza: `LIMIT_FILE_SIZE` → **413** `file_too_large`; outro `MulterError` (campo
|
|
205
|
+
inesperado, arquivos demais) → **400** `invalid_upload`; recusa do `fileFilter` (erro próprio) → **400**
|
|
206
|
+
`invalid_mimetype` — sempre com `detail`:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
const withUploadErrors = (handler: RequestHandler): RequestHandler => (req, res, next) =>
|
|
210
|
+
handler(req, res, (err?: unknown) => {
|
|
211
|
+
if (!err) return next();
|
|
212
|
+
if (err instanceof InvalidMimetypeError) return res.status(400).json({ error: 'invalid_mimetype', detail: 'Formato não permitido (PNG, JPEG, WebP ou SVG).' });
|
|
213
|
+
if (err instanceof multer.MulterError) {
|
|
214
|
+
return err.code === 'LIMIT_FILE_SIZE'
|
|
215
|
+
? res.status(413).json({ error: 'file_too_large', detail: `Arquivo acima de ${MAX_UPLOAD_MB} MB.` })
|
|
216
|
+
: res.status(400).json({ error: 'invalid_upload', detail: err.message });
|
|
217
|
+
}
|
|
218
|
+
next(err);
|
|
219
|
+
});
|
|
220
|
+
export const uploadImage = { single: (field: string) => withUploadErrors(multerImage.single(field)) };
|
|
221
|
+
```
|
|
222
|
+
- O `mimetype` do multer é o que o cliente declarou: confira os bytes iniciais (assinatura do arquivo)
|
|
223
|
+
antes de gravar.
|
|
224
|
+
- Em gateway que só repassa o arquivo: `express.raw({ type: () => true, limit: '20mb' })` e
|
|
225
|
+
reenvie o corpo com o `content-type` original (preserva o boundary) — o serviço de destino valida.
|
|
226
|
+
- Arquivos pequenos de configuração (logos) podem ir como data URI no banco — evita disco local e
|
|
227
|
+
funciona com várias réplicas.
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
# Rotas REST: URL, validação, respostas, erros e paginação
|
|
2
|
+
|
|
3
|
+
## Convenção de URL
|
|
4
|
+
|
|
5
|
+
- Tudo sob um prefixo configurável (`API_PREFIX`, ex.: `/api`): `app.use(API_PREFIX, cors, router)`.
|
|
6
|
+
- Recursos no plural, kebab-case: `/group-types`, `/web-routes`, `/groups/:groupId/members/:userId`.
|
|
7
|
+
- Parâmetros de rota em camelCase com sufixo `Id` (`:groupId`, `:clientId`); campos de body/query em
|
|
8
|
+
snake_case (`realm_id`, `project_id`, `next_cursor`).
|
|
9
|
+
- Sub-router com `Router({ mergeParams: true })` sempre que o pai tiver parâmetro
|
|
10
|
+
(`/realms/:realmId/...`), senão `req.params.realmId` chega `undefined`.
|
|
11
|
+
- Tenant/escopo na URL (`/realms/:realmId/...`) validado **uma vez** por middleware no ponto de montagem
|
|
12
|
+
(`router.use('/realms/:realmId', realmChecker)`), retornando 404 `realm_not_found`.
|
|
13
|
+
- Verbos: `GET` lista/detalhe, `POST` cria (201) ou ação (`/password/recover`, `/operations/sync`),
|
|
14
|
+
`PUT` atualiza (200 com o recurso), `DELETE` remove (204). Vínculos N:N como sub-recurso:
|
|
15
|
+
`POST /groups/:id/members` + `DELETE /groups/:id/members/:userId`.
|
|
16
|
+
|
|
17
|
+
## Validação de entrada (zod)
|
|
18
|
+
|
|
19
|
+
Schema por rota em `<recurso>.validators.ts`, com as partes da requisição:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
export const createGroupSchema = z.object({
|
|
23
|
+
body: z.object({
|
|
24
|
+
realm_id: z.string().uuid(),
|
|
25
|
+
type_id: z.string().uuid(),
|
|
26
|
+
name: z.string().min(1).max(200),
|
|
27
|
+
description: z.string().max(2000).optional(),
|
|
28
|
+
}),
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Middleware recomendado — responde com o motivo e **substitui** as partes validadas pelo resultado
|
|
33
|
+
(coerções, defaults e remoção de campos desconhecidos passam a valer no controller):
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import type { RequestHandler } from 'express';
|
|
37
|
+
import { z, ZodType } from 'zod';
|
|
38
|
+
|
|
39
|
+
export const validate = (schema: ZodType): RequestHandler => (req, res, next) => {
|
|
40
|
+
const result = schema.safeParse({ body: req.body, params: req.params, query: req.query });
|
|
41
|
+
if (!result.success) {
|
|
42
|
+
return res.status(400).json({
|
|
43
|
+
error: 'invalid_request',
|
|
44
|
+
detail: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
const data = result.data as { body?: unknown; params?: any; query?: any };
|
|
48
|
+
if (data.body !== undefined) req.body = data.body;
|
|
49
|
+
if (data.params) Object.assign(req.params, data.params);
|
|
50
|
+
if (data.query) res.locals.query = data.query; // Express 5: req.query é getter, não reatribua
|
|
51
|
+
next();
|
|
52
|
+
};
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Divergências encontradas: um serviço valida com zod mas descarta o resultado e responde só
|
|
56
|
+
`{ error: 'invalid_request' }` sem detalhe; outro valida à mão no controller
|
|
57
|
+
(`if (!name) return res.status(400)...`). Use o middleware acima; validação manual só para regra que
|
|
58
|
+
depende de banco (ex.: "o grupo pertence ao mesmo tenant do projeto").
|
|
59
|
+
|
|
60
|
+
Query string: sempre normalize e limite (`Math.min(100, Math.max(1, parseInt(q.limit) || 20))`);
|
|
61
|
+
parâmetro inválido explícito → 400, não silêncio.
|
|
62
|
+
|
|
63
|
+
### Parâmetros de rota que são UUID: validação central
|
|
64
|
+
|
|
65
|
+
Id que não é UUID chegando cru no `where` vira erro de cast no banco ("invalid input syntax for type
|
|
66
|
+
uuid") e responde **500**. Valide num lugar só, antes de qualquer handler, e responda **400**:
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; // aceita maiúsculas
|
|
70
|
+
export const isUuid = (v: unknown): v is string => typeof v === 'string' && UUID_RE.test(v);
|
|
71
|
+
|
|
72
|
+
// Lista EXPLÍCITA: param novo entra aqui ou em NON_UUID_PARAMS (com o motivo), nunca fica de fora.
|
|
73
|
+
export const UUID_PARAMS = ['clientId', 'groupId', 'userId', 'tokenId'] as const;
|
|
74
|
+
export const NON_UUID_PARAMS = ['kind'] as const; // enum validado no controller
|
|
75
|
+
|
|
76
|
+
export function applyUuidParams(...routers: Router[]) {
|
|
77
|
+
for (const router of routers) {
|
|
78
|
+
for (const name of UUID_PARAMS) {
|
|
79
|
+
router.param(name, (_req, res, next, value) => isUuid(value) ? next()
|
|
80
|
+
: res.status(400).json({ error: 'invalid_id', detail: `O parâmetro ${name} precisa ser um UUID válido.` }));
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- `router.param` só vale para as rotas do **próprio** router: aplique em todo router que declara esses
|
|
87
|
+
params (inclusive sub-routers com `mergeParams`).
|
|
88
|
+
- Um teste que percorre as rotas registradas e falha se algum `:param` não estiver em nenhuma das duas
|
|
89
|
+
listas impede o esquecimento.
|
|
90
|
+
- Id de UUID que vem no **corpo** ou na query (`group_id`, `operation_ids[]`) passa pelo mesmo `isUuid`
|
|
91
|
+
(ou `z.string().uuid()` no schema).
|
|
92
|
+
|
|
93
|
+
### PUT/PATCH com corpo vazio
|
|
94
|
+
|
|
95
|
+
No Express 5, `req.body` fica `undefined` quando nenhum parser casou (sem corpo ou sem `Content-Type`): o
|
|
96
|
+
`const { name } = req.body` do controller vira `TypeError` e 500. Normalize para `{}` logo depois dos
|
|
97
|
+
parsers e, em PUT/PATCH, recuse corpo sem campo nenhum com **400**:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
app.use((req, _res, next) => { if (req.body === undefined) req.body = {}; next(); });
|
|
101
|
+
|
|
102
|
+
export const requireBody: RequestHandler = (req, res, next) => {
|
|
103
|
+
const body = req.body;
|
|
104
|
+
if (body && typeof body === 'object' && !Array.isArray(body) && Object.keys(body).length > 0) return next();
|
|
105
|
+
res.status(400).json({ error: 'empty_body', detail: 'Informe ao menos um campo para atualizar.' });
|
|
106
|
+
};
|
|
107
|
+
router.patch('/:groupId', guard('admin:groups:update', Level.PROTECTED), requireBody, validate(updateGroupSchema), GroupsController.update);
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Com zod, o mesmo efeito no schema: `body: z.object({...}).partial().refine((b) => Object.keys(b).length > 0, 'corpo vazio')`.
|
|
111
|
+
|
|
112
|
+
### Ordenação: allowlist em `Map`, não em objeto literal
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
// ERRADO: SORT_COLUMNS['constructor'] é a função Object, e passa como "coluna" válida
|
|
116
|
+
const SORT_COLUMNS = { name: 'name', created: 'created_at' };
|
|
117
|
+
const column = SORT_COLUMNS[req.query.sort as string] ?? 'name';
|
|
118
|
+
|
|
119
|
+
// CERTO
|
|
120
|
+
const SORT_COLUMNS: ReadonlyMap<string, string> = new Map([['name', 'name'], ['created', 'created_at']]);
|
|
121
|
+
const column = SORT_COLUMNS.get(String(req.query.sort)) ?? 'name';
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Objeto literal herda chaves do `Object.prototype` (`constructor`, `toString`, `__proto__`): `obj[x]` e
|
|
125
|
+
`x in obj` aceitam essas chaves. Use `Map`/`Set`, ou confira com `Object.hasOwn(obj, x)` antes de ler. Vale
|
|
126
|
+
para toda allowlist indexada por valor do cliente (ordenação, filtro, nome de coluna, tipo). O verificador da
|
|
127
|
+
skill acusa o caso de ordenação (`ordenacao-objeto-literal`).
|
|
128
|
+
|
|
129
|
+
## Formato de resposta
|
|
130
|
+
|
|
131
|
+
Os servidores REST respondem **o recurso direto**, sem envelope:
|
|
132
|
+
|
|
133
|
+
```jsonc
|
|
134
|
+
// GET /groups/:id 200
|
|
135
|
+
{ "id": "…", "name": "…", "enabled": true, "created_at": "…", "type": { "id": "…", "name": "…" } }
|
|
136
|
+
|
|
137
|
+
// GET /groups?page=1&limit=20 200 (offset)
|
|
138
|
+
{ "groups": [ … ], "total": 42, "page": 1, "limit": 20 }
|
|
139
|
+
|
|
140
|
+
// GET /audit/events?limit=50&cursor=… 200 (cursor)
|
|
141
|
+
{ "items": [ … ], "next_cursor": "eyJ0Ijoi…" } // null na última página
|
|
142
|
+
|
|
143
|
+
// POST /groups 201 corpo = recurso criado
|
|
144
|
+
// PUT /groups/:id 200 corpo = recurso atualizado
|
|
145
|
+
// DELETE / vínculo / ação sem retorno 204 sem corpo
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
O envelope `{ status, message, data }` é o contrato dos **resolvers GraphQL** (e dos serviços FastAPI
|
|
149
|
+
que eles repassam) — ver apollo. Se o seu servidor Express é consumido só por um gateway que
|
|
150
|
+
repassa esse envelope, siga o contrato do gateway; caso contrário, recurso direto.
|
|
151
|
+
|
|
152
|
+
## Formato de erro
|
|
153
|
+
|
|
154
|
+
Recomendado (é também o formato de 401/403 do Orfeu, então o cliente trata tudo igual):
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{ "error": "group_project_realm_mismatch", "detail": "Esse grupo não pertence ao mesmo tenant do projeto." }
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
- `error`: código estável em snake_case, que o front pode testar.
|
|
161
|
+
- `detail`: frase para humano (pt-BR), opcional.
|
|
162
|
+
|
|
163
|
+
| Status | Quando | `error` típico |
|
|
164
|
+
| --- | --- | --- |
|
|
165
|
+
| 400 | entrada inválida, regra de consistência | `invalid_request`, `invalid_cursor`, `<regra>_mismatch` |
|
|
166
|
+
| 401 | sem credencial / token inválido ou expirado | `unauthorized`, `token_expired`, `token_invalid` |
|
|
167
|
+
| 403 | autenticado sem permissão / escopo errado | `forbidden` |
|
|
168
|
+
| 404 | recurso ou tenant inexistente (ou fora do escopo do chamador) | `not_found`, `realm_not_found` |
|
|
169
|
+
| 409 | duplicidade, limite atingido | `already_exists`, `token_limit` |
|
|
170
|
+
| 413 | corpo acima do limite | (do body-parser) |
|
|
171
|
+
| 429 | rate limit | `too_many_requests` + `Retry-After` |
|
|
172
|
+
| 500 | erro não tratado (error handler) | `internal_error` |
|
|
173
|
+
| 503 | dependência fora (banco, cache, serviço) | `<dep>_unavailable` |
|
|
174
|
+
|
|
175
|
+
Divergências encontradas: `error` às vezes é código (`"forbidden"`), às vezes frase
|
|
176
|
+
(`"Grupo não encontrado"`), e o error handler global responde `{ message }`. Padronize em
|
|
177
|
+
`{ error, detail }` também no handler global:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
export class HttpError extends Error {
|
|
181
|
+
constructor(public status: number, public code: string, detail?: string) { super(detail ?? code); }
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
export const handleErrors: ErrorRequestHandler = (err, req, res, _next) => {
|
|
185
|
+
const status = err instanceof HttpError ? err.status : (err.status ?? err.statusCode ?? 500);
|
|
186
|
+
if (status >= 500) Logger.error('Unhandled error', { requestId: req.requestId, message: err.message, stack: err.stack });
|
|
187
|
+
if (res.headersSent) return;
|
|
188
|
+
res.status(status).json(status >= 500
|
|
189
|
+
? { error: 'internal_error', detail: 'Erro interno no servidor' } // não vaze err.message de 500
|
|
190
|
+
: { error: err instanceof HttpError ? err.code : 'invalid_request', detail: err.message });
|
|
191
|
+
};
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Com Express 5, o controller pode simplesmente `throw new HttpError(404, 'not_found', 'Grupo não encontrado')`.
|
|
195
|
+
Um padrão real útil: classe de erro de domínio (`QueryError(status, code, message)`) lançada pelos
|
|
196
|
+
parsers de filtro e convertida no controller/handler.
|
|
197
|
+
|
|
198
|
+
Regras de escopo: filtro explícito por algo fora do escopo do chamador → **403** (ele pediu o que não
|
|
199
|
+
pode ver); detalhe de recurso fora do escopo → **404** (não revela existência).
|
|
200
|
+
|
|
201
|
+
### Rotas escopadas por um recurso pai (IDOR)
|
|
202
|
+
|
|
203
|
+
Rota montada sob um recurso pai (`/clients/:clientId/groups/:groupId`, `/realms/:realmId/users/:userId`)
|
|
204
|
+
precisa conferir que **todo** id da URL e do corpo pertence àquele pai. O middleware de escopo do pai só
|
|
205
|
+
prova que o chamador pode mexer no `clientId`; sem a conferência, `PUT /clients/<meu>/groups/<de outro>`
|
|
206
|
+
altera o grupo de outro client (IDOR — referência direta a objeto sem checar posse).
|
|
207
|
+
|
|
208
|
+
- Busque o filho **pelo par** (`WHERE group_id = ? AND client_id = ?`), nunca só pelo id.
|
|
209
|
+
- Recurso que existe mas é de outro escopo responde **404 igual ao inexistente** (`not_found`), sem revelar
|
|
210
|
+
que existe. 403 só quando o chamador pediu explicitamente algo fora do escopo dele (filtro).
|
|
211
|
+
- Ids no corpo (vínculos, listas `*_ids`, `parent_id`, `type_id`) também: confira todos de uma vez e
|
|
212
|
+
responda 404 se algum não for do escopo.
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
// repositório: o escopo faz parte da chave
|
|
216
|
+
findInClient: (groupId: string, clientId: string, trx = db) =>
|
|
217
|
+
trx('groups').where({ group_id: groupId, client_id: clientId }).first(),
|
|
218
|
+
|
|
219
|
+
async countInClient(ids: string[], clientId: string, trx = db) {
|
|
220
|
+
const [{ n }] = await trx('groups').whereIn('group_id', ids).andWhere({ client_id: clientId }).count({ n: '*' });
|
|
221
|
+
return Number(n);
|
|
222
|
+
},
|
|
223
|
+
|
|
224
|
+
// controller
|
|
225
|
+
const group = await GroupRepository.findInClient(req.params.groupId, req.params.clientId);
|
|
226
|
+
if (!group) throw new HttpError(404, 'not_found', 'Grupo não encontrado');
|
|
227
|
+
const ids = [...new Set(req.body.group_ids as string[])];
|
|
228
|
+
if (await GroupRepository.countInClient(ids, req.params.clientId) !== ids.length) {
|
|
229
|
+
throw new HttpError(404, 'not_found', 'Grupo não encontrado');
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Teste de integração para cada rota escopada: id de **outro** pai na URL e no corpo → 404, e nada muda no banco.
|
|
234
|
+
|
|
235
|
+
## Paginação
|
|
236
|
+
|
|
237
|
+
### Offset (telas administrativas, tabelas pequenas)
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
const page = Math.max(1, parseInt(req.query.page as string) || 1);
|
|
241
|
+
const limit = Math.min(100, Math.max(1, parseInt(req.query.limit as string) || 20));
|
|
242
|
+
const offset = (page - 1) * limit;
|
|
243
|
+
const [items, total] = await Promise.all([Repo.findAll({ limit, offset }), Repo.count()]);
|
|
244
|
+
res.json({ groups: items.map(serialize), total, page, limit });
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Ordenação sempre determinística (inclua uma coluna única no `ORDER BY`).
|
|
248
|
+
|
|
249
|
+
### Cursor / keyset (logs, auditoria, feeds — volume grande, ordem por tempo)
|
|
250
|
+
|
|
251
|
+
- Cursor **opaco**: `base64url(JSON.stringify({ t, id }))` do último item.
|
|
252
|
+
- Consulta: `WHERE (occurred_at, id) < (?, ?) ORDER BY occurred_at DESC, id DESC LIMIT limit + 1`;
|
|
253
|
+
se vier `limit + 1` linhas há próxima página.
|
|
254
|
+
- Guarde o timestamp **com microssegundos** (texto ISO vindo do banco) — com milissegundos o keyset
|
|
255
|
+
pula ou repete itens no mesmo ms.
|
|
256
|
+
- Cursor malformado → 400 `invalid_cursor`. `limit` com padrão e teto.
|
|
257
|
+
|
|
258
|
+
```ts
|
|
259
|
+
export const encodeCursor = (c: { t: string; id: string }) =>
|
|
260
|
+
Buffer.from(JSON.stringify(c), 'utf8').toString('base64url');
|
|
261
|
+
|
|
262
|
+
export function decodeCursor(raw: string) {
|
|
263
|
+
try {
|
|
264
|
+
const c = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
|
|
265
|
+
if (typeof c.t === 'string' && typeof c.id === 'string' && !Number.isNaN(new Date(c.t).getTime())) return c;
|
|
266
|
+
} catch { /* cai no erro */ }
|
|
267
|
+
throw new HttpError(400, 'invalid_cursor', 'cursor inválido');
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
## Documentação
|
|
272
|
+
|
|
273
|
+
OpenAPI em `src/config/openapi.ts` servido por `swagger-ui-express` em `<prefixo>/docs`, com um CSP
|
|
274
|
+
próprio para essa rota (o CSP global da API é `default-src 'none'`). **Só monte a rota com `config.API_DOCS`**:
|
|
275
|
+
o mapa da API não fica exposto sem autenticação nos ambientes publicados.
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
// config/index.ts (zod): sem API_DOCS, liga só em NODE_ENV=local (o container roda com outro NODE_ENV)
|
|
279
|
+
API_DOCS: z.enum(['true', 'false']).optional()
|
|
280
|
+
.transform((v) => (v === undefined ? process.env.NODE_ENV === 'local' : v === 'true')),
|
|
281
|
+
|
|
282
|
+
// router.ts
|
|
283
|
+
if (config.API_DOCS) router.use('/docs', cspDaDocumentacao, swaggerUi.serve, swaggerUi.setup(openApiSpec));
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Teste do config: `NODE_ENV=dev`/`test` → `false`; `local` → `true`; `API_DOCS` força nos dois sentidos.
|