@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.
Files changed (92) hide show
  1. package/README.md +181 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. 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.