@acropole/skills 1.4.1 → 1.6.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 (33) hide show
  1. package/README.md +2 -1
  2. package/package.json +1 -1
  3. package/skills/acropole/SKILL.md +4 -2
  4. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +382 -0
  5. package/skills/auto-servico/SKILL.md +14 -8
  6. package/skills/auto-servico/references/diagnostico.md +2 -1
  7. package/skills/auto-servico/references/tools.md +7 -2
  8. package/skills/hefesto/SKILL.md +11 -5
  9. package/skills/hefesto/references/mcp-diagnostico.md +2 -1
  10. package/skills/hefesto/references/mcp-tools.md +13 -3
  11. package/skills/orfeu/SKILL.md +32 -6
  12. package/skills/orfeu/references/angular-api.md +14 -6
  13. package/skills/orfeu/references/angular-armadilhas.md +17 -2
  14. package/skills/orfeu/references/angular-recipes.md +23 -8
  15. package/skills/orfeu/references/angular.md +16 -7
  16. package/skills/orfeu/references/diferencas.md +13 -6
  17. package/skills/orfeu/references/node-api.md +68 -8
  18. package/skills/orfeu/references/node-armadilhas.md +40 -6
  19. package/skills/orfeu/references/node-recipes.md +26 -12
  20. package/skills/orfeu/references/node.md +66 -12
  21. package/skills/orfeu/references/python-api.md +53 -13
  22. package/skills/orfeu/references/python-recipes.md +22 -22
  23. package/skills/orfeu/references/python.md +68 -10
  24. package/skills/trismegisto/SKILL.md +5 -2
  25. package/skills/trismegisto/references/angular-api.md +43 -4
  26. package/skills/trismegisto/references/angular-exports.md +127 -3
  27. package/skills/trismegisto/references/angular-recipes.md +31 -0
  28. package/skills/trismegisto/references/angular-types.md +2 -1
  29. package/skills/trismegisto/references/catalogo/seletores.json +152 -0
  30. package/skills/trismegisto/references/catalogo/tokens.json +1 -0
  31. package/skills/trismegisto/references/spine-api.md +519 -7
  32. package/skills/trismegisto/references/spine-recipes.md +15 -11
  33. package/skills/trismegisto/references/spine.md +21 -3
@@ -1,7 +1,7 @@
1
- # Receitas — @orfeu/node 1.0.1
1
+ # Receitas — @orfeu/node 1.4.0
2
2
 
3
- Todas usam a API real da 1.0.1 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
4
- `REALM_ID`, `APP_ID`, `APP_SECRET` — use os nomes que o projeto já tem.
3
+ Todas usam a API real da 1.4.0 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
4
+ `REALM_ID`, `APP_ID`, `APP_SECRET`, `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL` — use os nomes que o projeto já tem.
5
5
 
6
6
  ## 1. Express
7
7
 
@@ -10,11 +10,18 @@ import express from 'express';
10
10
  import { Level, Method, OrfeuClient, annotateOperation, getRegistry } from '@orfeu/node';
11
11
  import { orfeu } from '@orfeu/node/express';
12
12
 
13
+ const lista = (v?: string) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
14
+ const allowedClients = lista(process.env.ORFEU_ALLOWED_CLIENTS);
15
+
16
+ // Crie o client DEPOIS de carregar o ambiente (dotenv): as opções abaixo são lidas aqui.
13
17
  const client = new OrfeuClient({
14
18
  authorizerUrl: process.env.AUTHORIZER_URL!,
15
19
  realmId: process.env.REALM_ID!,
16
20
  appId: process.env.APP_ID!,
17
21
  secret: process.env.APP_SECRET!,
22
+ allowedClients: allowedClients.length ? allowedClients : undefined, // [] desligaria
23
+ issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
24
+ checkRevocation: ['clientes:delete'], // operações sensíveis
18
25
  });
19
26
  const { middleware, guard } = orfeu(client);
20
27
 
@@ -146,7 +153,7 @@ export class ClientesController {
146
153
  módulo do app. Métodos sem `@Operation` continuam **abertos** — confira todos.
147
154
  - `OrfeuClient` é injetável (`constructor(private readonly orfeu: OrfeuClient) {}`) para `checkPermission`,
148
155
  `flushAudit` etc.
149
- - Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy` (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1). Antes, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
156
+ - Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy`.
150
157
 
151
158
  ## 4. Apollo Server (HTTP + WebSocket)
152
159
 
@@ -195,6 +202,8 @@ await client.startup(); // secureResolvers já registrou as operações n
195
202
 
196
203
  const apollo = new ApolloServer<OrfeuContext>({ schema, plugins: [orfeuPlugin(client)] });
197
204
  const { url } = await startStandaloneServer(apollo, { listen: { port: 4000 }, context: async () => ({}) });
205
+ // Subscription não pública termina com um 401 (UNAUTHENTICATED) no exp do token (~10 min no Argos):
206
+ // o cliente reconecta com o token novo e reassina.
198
207
 
199
208
  // subscriptions: o graphql-ws executa o schema sem os plugins do Apollo — o contexto precisa do orfeuWsContext
200
209
  const httpServer = createServer();
@@ -416,8 +425,8 @@ client.lastPermissionsSyncAt; // Date | null — último sucesso
416
425
  client.permissionsStale; // true após 5 intervalos sem sucesso (bom para o /health, sem derrubar)
417
426
  ```
418
427
 
419
- Versão anterior a essa: as permissões só eram lidas no `startup()` — recarregue com `fetchOperations()` num
420
- `setInterval` (`unref()`), chamando `authenticate()` antes de repetir quando der 401 (o token do serviço vence).
428
+ >>>>
429
+
421
430
 
422
431
  ## 11. Encerramento sem perder eventos
423
432
 
@@ -432,8 +441,8 @@ for (const signal of ['SIGTERM', 'SIGINT'] as const) {
432
441
  ```
433
442
 
434
443
  Em container sem init, o processo Node é o PID 1 e só termina no SIGTERM se tratar o sinal (como acima).
435
- `close()` existe a partir de `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; antes, `flushAudit()` (não havia recarga para parar). Fastify (`fastify.close()`),
436
- Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o encerramento do client sozinhos.
444
+ Fastify (`fastify.close()`), Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o
445
+ encerramento do client sozinhos.
437
446
 
438
447
  ## 12. Testes
439
448
 
@@ -492,11 +501,14 @@ export async function startFakeArgos(opts: { realm?: string; appId?: string; sec
492
501
  await new Promise<void>((resolve) => server.listen(0, 'localhost', resolve));
493
502
  const { port } = server.address() as AddressInfo;
494
503
 
504
+ const url = `http://localhost:${port}`;
505
+
495
506
  return {
496
- url: `http://localhost:${port}`, realm, appId, secret, audits,
497
- signUser: (sub: string, groups: string[] = []) =>
498
- new SignJWT({ groups, realm_id: realm }).setProtectedHeader({ alg: 'RS256', kid: 'k1' })
499
- .setSubject(sub).setIssuedAt().setExpirationTime('1h').sign(privateKey),
507
+ url, realm, appId, secret, audits,
508
+ // 1.3+: exp, sub e iss obrigatórios; iss = <url>/realms/<realm>; client_id conta com allowedClients
509
+ signUser: (sub: string, groups: string[] = [], clientId = 'front-de-teste') =>
510
+ new SignJWT({ groups, realm_id: realm, client_id: clientId }).setProtectedHeader({ alg: 'RS256', kid: 'k1' })
511
+ .setSubject(sub).setIssuer(`${url}/realms/${realm}`).setIssuedAt().setExpirationTime('1h').sign(privateKey),
500
512
  close: () => new Promise<void>((resolve) => server.close(() => resolve())),
501
513
  };
502
514
  }
@@ -539,3 +551,5 @@ it('401 sem credencial, 403 sem grupo, 204 com grupo', async () => {
539
551
  - `jose` vem com o `@orfeu/node`, mas declare-o como `devDependency` do app se o teste o importa.
540
552
  - `authorizerUrl` do simulado não tem `/api`: o SDK monta `<authorizerUrl>/realms/<realm>/…`.
541
553
  - `clearRegistry()` antes de cada arquivo que declara rotas: o registro global é do processo.
554
+ - Teste do `allowedClients`: `new OrfeuClient({ ..., allowedClients: ['front-de-teste'] })` e um token com
555
+ `signUser(sub, groups, 'outro-front')` → 401. Token sem `iss`/`exp`/`sub` ou com `type: 'app'` → 401.
@@ -1,7 +1,8 @@
1
1
  # @orfeu/node — guia de uso (Express, Fastify, NestJS, Apollo)
2
2
 
3
- > Escrito para a **1.0.1** (peça `^1.0.1`: a 1.0.0 aceitava `orfeuUser` forjado nas subscriptions do
4
- > Apollo). Se a versão instalada for outra, confira os nomes de [node-api.md](node-api.md)
3
+ > Escrito para a **1.4.0** (peça `^1.4.0`; anda junto com `@orfeu/angular` e `orfeu`). A 1.0.0 aceitava
4
+ > `orfeuUser` forjado nas subscriptions do Apollo; a 1.3.0 trouxe as correções da auditoria de segurança (§5).
5
+ > Se a versão instalada for outra, confira os nomes de [node-api.md](node-api.md)
5
6
  > contra os `.d.ts` de `node_modules/@orfeu/node/dist/`. Conceitos comuns às três implementações estão no
6
7
  > `SKILL.md` da skill; o que muda em relação ao Python e ao Angular está em [diferencas.md](diferencas.md).
7
8
  > Estrutura do servidor em si: skills `express` (Express) e `apollo` (GraphQL). Fastify e
@@ -30,7 +31,7 @@ Leia sob demanda:
30
31
  ## 1. Instalação
31
32
 
32
33
  ```bash
33
- npm install @orfeu/node@^1.1.1
34
+ npm install @orfeu/node@^1.4.0
34
35
  npm install express # se usar @orfeu/node/express
35
36
  npm install fastify # @orfeu/node/fastify
36
37
  npm install @nestjs/common @nestjs/core reflect-metadata rxjs # @orfeu/node/nest
@@ -52,7 +53,10 @@ const client = new OrfeuClient({
52
53
  realmId: process.env.REALM_ID!, // realm "de casa" do serviço (nome ou UUID)
53
54
  appId: process.env.APP_ID!, // UUID do serviço cadastrado no Argos
54
55
  secret: process.env.APP_SECRET!, // segredo do serviço: variável de ambiente, nunca no código
55
- // acceptAnyRealm: false, tlsVerify: true, audit: true, logger: jsonLineLogger (padrões)
56
+ allowedClients: ['<client_id do front>'], // backend de front próprio: ligue (§5)
57
+ issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
58
+ // acceptAnyRealm: false, tlsVerify: true, audit: true, logger: jsonLineLogger,
59
+ // permissionsRefresh: true, trustedProxies: DEFAULT_TRUSTED_PROXIES, checkRevocation: false (padrões)
56
60
  });
57
61
  ```
58
62
 
@@ -62,6 +66,15 @@ const client = new OrfeuClient({
62
66
  | `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo). |
63
67
  | `audit` | `true` | `false` desliga a auditoria; objeto `{ flushIntervalMs, maxBuffer, batchSize }` ajusta o lote. |
64
68
  | `logger` | `jsonLineLogger` | função `(record) => void` para outro destino; `false` desliga o log de operação. |
69
+ | `permissionsRefresh` | `true` | revalida o catálogo (grupos liberados) a cada 60 s ±20%; `false` ou `{ enabled, intervalMs, jitter }`. |
70
+ | `allowedClients` | desligado | `client_id`s aceitos no token de usuário (`x-access-token`, `x-app-token`); fora da lista → 401. Sem a opção, lê `ORFEU_ALLOWED_CLIENTS` (vírgula). |
71
+ | `issuerUrl` | — | URL pública do Argos (`SERVER_URL`): `iss` esperado = `${issuerUrl}/realms/${realm_id}`. Sem a opção, `ORFEU_ISSUER_URL`. |
72
+ | `trustedProxies` | `DEFAULT_TRUSTED_PROXIES` | proxies cujo `x-forwarded-for` vale para o IP da auditoria (loopback + redes privadas). Sem a opção, `ORFEU_TRUSTED_PROXIES`; `[]` = nenhum. |
73
+ | `checkRevocation` | `false` | lista de operações sensíveis (ou `true`) conferidas na introspecção do Argos; fail-closed. |
74
+
75
+ As três variáveis `ORFEU_*` só são lidas **quando a opção não é passada** — e no construtor. Cliente criado no
76
+ topo de um módulo ESM roda antes do `dotenv.config()` e não as vê em `local`: prefira passar pelas settings do
77
+ app. `allowedClients: []` desliga e ignora a variável.
65
78
 
66
79
  ## 3. Ordem de subida (obrigatória)
67
80
 
@@ -78,8 +91,8 @@ new OrfeuClient(opts)
78
91
  - `OrfeuClient.create(opts)` faz "copiar o registro + startup" de uma vez (use depois de declarar as rotas).
79
92
  - `OrfeuModule.forRootAsync(opts)` (Nest) faz tudo sozinho.
80
93
  - No Apollo, `secureResolvers(client, …)` já registra no client: chame-o **antes** do `startup()`.
81
- - As permissões (`allowed_groups`) são lidas **só** no `startup()` (ou em `fetchOperations()`): mudar grupos de
82
- uma operação no Argos não vale para um serviço já no ar até recarregar (`node-recipes.md` §10).
94
+ - As permissões (`allowed_groups`) são revalidadas sozinhas a cada ~60 s depois do `startup()` (1.1+,
95
+ `permissionsRefresh`): mudar grupos de uma operação no Argos vale em até ~1 min (`node-recipes.md` §10).
83
96
 
84
97
  ## 4. Operações: identificador, nível e método
85
98
 
@@ -106,6 +119,23 @@ Headers de credencial (`x-access-token` → `x-app-token` → `x-api-token`, a p
106
119
  401/403 estão no `SKILL.md` §4 — a regra é a mesma do Python. Específico do Node: introspecção com cache de
107
120
  60 s (token inativo: 10 s); `acceptAnyRealm: true` aceita JWT de outros realms.
108
121
 
122
+ O `x-access-token` é recusado (401 `Invalid token.`) quando (1.3+): o algoritmo não é `RS256`, a assinatura ou o
123
+ `kid` não conferem; falta `exp`, `sub` ou `iss`, ou venceu; o `iss` não é o do realm do token (com `issuerUrl`,
124
+ exatamente `${issuerUrl}/realms/${realm_id}`; sem, uma URL http(s) terminada em `/realms/${realm_id}`); o realm
125
+ não é o do app (modo estrito); é token **de aplicação** (`type: "app"`, client_credentials); ou `allowedClients`
126
+ está ligado e o `client_id`/`azp` não está na lista. Falha ao falar com o Argos (JWKS, `/apps/token`,
127
+ introspecção) nunca vira 500: anônimo em `public`, 401 nos outros níveis.
128
+
129
+ **`allowedClients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
130
+ login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
131
+ Ligue em todo backend que atende o front do próprio app (valor = `client_id` do front, o `clientId` do
132
+ environment do Angular); serviço chamado por gateways de vários apps lista os fronts de todos. Não ligue no
133
+ que atende qualquer app do realm de propósito (admin do Argos, auto-serviço).
134
+
135
+ **Revogação**: a validação local não enxerga revogação — um access token revogado vale até o `exp` (até 10 min
136
+ no Argos). Para operações sensíveis, `checkRevocation: ['pedidos:delete']` confere na introspecção RFC 7662
137
+ (cache 10 s/60 s, Argos fora → 401); `true` confere em toda validação.
138
+
109
139
  Respostas: Express/Fastify `401 { error: 'unauthorized', detail }` / `403 { error: 'forbidden', detail:
110
140
  'Insufficient permissions.' }`; Nest `UnauthorizedException`/`ForbiddenException`; Apollo `GraphQLError` com
111
141
  `extensions.code` 401/403 (ou o valor de `onForbidden` no 403). Textos sempre genéricos (`Access token
@@ -116,6 +146,22 @@ Quem passou fica em `req.orfeuUser` (`TokenClaims`: `sub`, `realmId`, `groups`,
116
146
  `req.orfeuApiToken` (`{ tokenId, appId }`) — no Apollo, `ctx.orfeuUser`/`ctx.orfeuApiToken`; no Nest,
117
147
  `@OrfeuUser()`.
118
148
 
149
+ ### Rota máquina-a-máquina: token de serviço (1.4+)
150
+
151
+ Desde a 1.3 o token client_credentials de uma aplicação (`type: "app"`) **não vale como usuário**: rota que outra
152
+ aplicação chamava com ele por um `guard()` de operação passou a dar 401 (e suíte com o Orfeu mockado não pega). Use
153
+ o token de serviço: `serviceGuard({ allowedApps: ['<app_id>'] })` (Express), `fastify.orfeuServiceGuard(opts)`,
154
+ `@ServiceRoute(opts)` + `@OrfeuService()` (Nest) ou `client.validateServiceToken(token, opts)` (Apollo, no `context`).
155
+ O realm de verificação nunca vem do token (`realmFor`); `allowedClients` não se aplica. Detalhes em
156
+ [node-api.md](node-api.md).
157
+
158
+ ```ts
159
+ const { middleware, guard, serviceGuard } = orfeu(client);
160
+ app.post('/interno/sincronizar', serviceGuard({ allowedApps: [process.env.APP_ORIGEM_ID!] }), (req, res) => {
161
+ res.json({ de: req.orfeuService!.appId });
162
+ });
163
+ ```
164
+
119
165
  ## 6. Adapters (resumo — código em [node-recipes.md](node-recipes.md))
120
166
 
121
167
  | Framework | Captura (global) | Protege | Usuário |
@@ -131,7 +177,10 @@ usuário e **não é protegida nem auditada**.
131
177
  ## 7. Trace e chamadas a outros serviços
132
178
 
133
179
  O modelo (`entry`, `trace_id`/`span_id`, um evento por serviço) está no `SKILL.md` §5. O IP do cliente só é
134
- gravado em eventos `entry: true` (`x-forwarded-for`, depois `x-real-ip`, depois o socket).
180
+ gravado em eventos `entry: true`, e nunca do **primeiro** `x-forwarded-for` (1.3+): conexão direta de fora de
181
+ `trustedProxies` usa o IP do socket; vinda de proxy confiável, a entrada mais à direita do `x-forwarded-for` que
182
+ não é proxy; sem ele, `x-real-ip`. O padrão confia em loopback e redes privadas (Caddy, ingress); se usuários
183
+ chegam por rede privada **sem** proxy, configure `trustedProxies` só com os proxies.
135
184
 
136
185
  Para chamar outro serviço **seu** em nome da requisição atual:
137
186
 
@@ -161,8 +210,9 @@ são verificados nem usados para permissão; na auditoria só entram se forem GU
161
210
  - **Alvo**: dentro do handler/resolver, `annotateOperation({ target_type, target_id, details })` acrescenta o
162
211
  que foi afetado ao evento desta operação (`details` ≤ 4 KB, sem segredos). Fora de uma operação protegida,
163
212
  devolve `false` e não faz nada.
164
- - **Encerramento**: o SDK não registra handler de sinal. No SIGTERM do app, `await client.flushAudit()` antes de
165
- sair (`node-recipes.md` §11). `client.pendingAudit` mostra quantos eventos esperam envio.
213
+ - **Encerramento**: o SDK não registra handler de sinal. No SIGTERM do app, `await client.close()` antes de
214
+ sair — para a recarga das permissões e faz o flush (`node-recipes.md` §11). `client.pendingAudit` mostra
215
+ quantos eventos esperam envio.
166
216
  - Log de operação: uma linha JSON por chamada protegida no stdout (`logger: 'orfeu.operation'`, `operation`,
167
217
  `operation_id`, `actor_type`, `permission_result`, `duration_ms`, `trace_id`, `span_id`…). Troque o destino
168
218
  com `logger: (record) => …` ou desligue com `logger: false`.
@@ -175,7 +225,7 @@ são verificados nem usados para permissão; na auditoria só entram se forem GU
175
225
  | `OrfeuAuthError` | `authenticate()` recusado (appId/secret errados) ou sem `access_token`; `syncOperations`/`fetchOperations` sem token do serviço |
176
226
  | `OrfeuSyncError` | `POST /apps/operations/sync` falhou |
177
227
  | `OrfeuError` | base de todas; também a falha de `GET /apps/operations` |
178
- | `OrfeuTokenError` | `validateToken`/`validateAppToken` com token inválido; falha de rede na introspecção |
228
+ | `OrfeuTokenError` | `validateToken`/`validateAppToken` com token inválido ou recusado (sem `iss`/`exp`/`sub`, `type: "app"`, client fora do `allowedClients`, revogado com `checkRevocation`); falha ao falar com o Argos (JWKS, introspecção, `/apps/token` ao introspectar) |
179
229
  | `OrfeuForbiddenError` | 403 no `createGuard` do Apollo |
180
230
 
181
231
  Nos adapters, erros de credencial **não** lançam: viram 401/403. Exceções do seu handler seguem o fluxo
@@ -187,7 +237,9 @@ O pacote não publica mocks. Opções (`node-recipes.md` §12):
187
237
  - testar o handler isolado, preenchendo `req.orfeuUser` à mão (Express/Fastify; no Apollo, resolver que passa
188
238
  pelo `secureResolvers` precisa do contexto montado com `trustUser`);
189
239
  - teste de integração contra um **Argos simulado** (servidor HTTP local com os endpoints que o SDK usa e
190
- tokens assinados com `jose`), com `audit: false` e `logger: false` se não forem o foco;
240
+ tokens assinados com `jose`), com `audit: false` e `logger: false` se não forem o foco. Desde a 1.3, o
241
+ token fake precisa de `exp`, `sub` e `iss` (`<url>/realms/<realm_id>`), `RS256`, sem `type: "app"`, e o
242
+ `client_id` da lista quando `allowedClients` está ligado;
191
243
  - `clearRegistry()` entre testes que declaram operações diferentes.
192
244
 
193
245
  ## 11. Não faça
@@ -201,4 +253,6 @@ O pacote não publica mocks. Opções (`node-recipes.md` §12):
201
253
  `orfeuWsContext` (allowlist em node-recipes.md §4).
202
254
  - Não mande `traceparent` do navegador nem invente um: o SDK gera.
203
255
  - Não ponha segredos/PII desnecessária em `annotateOperation({ details })`.
204
- - Não encerre o processo sem `await client.flushAudit()`.
256
+ - Não encerre o processo sem `await client.close()`.
257
+ - Não passe `allowedClients: []` achando que "usa a variável": a lista vazia desliga. Não derive `issuerUrl` do
258
+ `authorizerUrl`.
@@ -1,8 +1,12 @@
1
- # orfeu 1.0.0 — referência da API
1
+ # orfeu 1.4.0 — referência da API
2
2
 
3
3
  Conferida contra o código do pacote (`orfeu/__init__.py` `__all__`, `orfeu/adapters/*.py` `__all__` e os
4
4
  módulos). "Raiz" = `from orfeu import ...`. Itens marcados *(submódulo)* não estão no `__all__` da raiz e
5
- são importados do módulo indicado.
5
+ são importados do módulo indicado. Marcos: 1.1 — recarga das permissões e `close()`; 1.2 — `accept_any_realm` e
6
+ intervalo mínimo de 30 s na busca forçada do JWKS; 1.3.0 — auditoria de segurança (`iss`/`exp`/`sub`
7
+ obrigatórios, `type: "app"` recusado como usuário, `allowed_clients`, `issuer_url`, `trusted_proxies`,
8
+ `check_revocation`, Argos fora → 401 em vez de 500, IP da auditoria); 1.4.0 — token de serviço
9
+ (`validate_service_token`, `@service_route`).
6
10
 
7
11
  Sumário: [1. Adapter FastAPI](#1-orfeuadaptersfastapi) · [2. Operações e modelos](#2-operações-e-modelos) ·
8
12
  [3. OrfeuClient](#3-orfeuclient) · [4. Exceções](#4-exceções) · [5. Envelope](#5-envelope) ·
@@ -29,10 +33,17 @@ Orfeu(
29
33
  *,
30
34
  tls_verify: bool = True,
31
35
  audit: bool | AuditOptions = True,
36
+ permissions_refresh: bool | PermissionsRefreshOptions = True,
37
+ accept_any_realm: bool = False, # 1.2+
38
+ allowed_clients: Iterable[str] | None = None, # 1.3+; None → ORFEU_ALLOWED_CLIENTS; [] desliga
39
+ issuer_url: str | None = None, # 1.3+; None → ORFEU_ISSUER_URL
40
+ trusted_proxies: Iterable[str] | None = None, # 1.3+; None → ORFEU_TRUSTED_PROXIES / DEFAULT_TRUSTED_PROXIES
41
+ check_revocation: bool | Iterable[str] = False, # 1.3+
32
42
  )
33
43
  ```
34
44
 
35
- Na construção: cria `self.client = OrfeuClient(...)`, embrulha `app.router.lifespan_context` e chama
45
+ Os argumentos keyword-only são repassados ao `OrfeuClient` (§3), com o mesmo significado; Flask e Strawberry
46
+ aceitam os mesmos. Na construção: cria `self.client = OrfeuClient(...)`, embrulha `app.router.lifespan_context` e chama
36
47
  `app.add_middleware(_OrfeuASGIMiddleware, client=self.client)`. Construa **depois** de criar o app e antes
37
48
  de ele começar a servir (o Starlette não aceita `add_middleware` depois do start).
38
49
 
@@ -44,7 +55,8 @@ de ele começar a servir (o Starlette não aceita `add_middleware` depois do sta
44
55
  | `_startup()` | alias antigo de `startup_async` (não use em código novo). |
45
56
 
46
57
  Lifespan: `startup_async()` → lifespan original do app (`lifespan=` ou `on_startup`/`on_shutdown`) →
47
- `client.flush_audit()` numa thread (no shutdown, mesmo se o lifespan do app levantar). Se o
58
+ `shutdown_async()` (para a recarga das permissões e faz o flush da auditoria; no shutdown, mesmo se o lifespan
59
+ do app levantar). Se o
48
60
  `startup_async()` falhar, a exceção sobe e o app não inicia.
49
61
 
50
62
  Middleware (por requisição HTTP e handshake WebSocket):
@@ -56,7 +68,8 @@ Middleware (por requisição HTTP e handshake WebSocket):
56
68
  um endpoint `@operation`, a resposta HTTP é trocada por 500 / o `accept` do WS é recusado, log CRITICAL
57
69
  em `orfeu.guard`).
58
70
  3. Endpoint com `@operation` → monta o contexto (credenciais, `traceparent`, `x-route-id`, `x-client-id`,
59
- IP do cliente via `x-forwarded-for`/`x-real-ip`/socket), grava `scope["state"]["orfeu"]` (lido por
71
+ IP do cliente — 1.3+: socket fora de `trusted_proxies` → IP do socket; de proxy confiável → entrada mais à
72
+ direita do `x-forwarded-for` que não é proxy; nunca o primeiro), grava `scope["state"]["orfeu"]` (lido por
60
73
  `orfeu_headers`), decide (regra canônica) e:
61
74
  - negado → 401/403 em JSON (HTTP) ou close 1008 (WS); log + auditoria;
62
75
  - permitido → `state.user = TokenClaims` (usuário) **ou** `state.user = None` + `state.api_token =
@@ -148,9 +161,22 @@ pelo Argos por operação.
148
161
 
149
162
  ```python
150
163
  OrfeuClient(authorizer_url: str, realm_id: str, app_id: str, secret: str, *,
151
- tls_verify: bool = True, audit: bool | AuditOptions = True)
164
+ tls_verify: bool = True, audit: bool | AuditOptions = True,
165
+ permissions_refresh: bool | PermissionsRefreshOptions = True,
166
+ accept_any_realm: bool = False,
167
+ allowed_clients: Iterable[str] | None = None,
168
+ issuer_url: str | None = None,
169
+ trusted_proxies: Iterable[str] | None = None,
170
+ check_revocation: bool | Iterable[str] = False)
152
171
  ```
153
172
 
173
+ | Argumento (1.3+) | Variável, sem o argumento | O que faz |
174
+ |---|---|---|
175
+ | `allowed_clients` | `ORFEU_ALLOWED_CLIENTS` (vírgula) | `client_id`s aceitos no token de usuário (`x-access-token`, `x-app-token`); `client_id`/`azp` fora da lista ou ausentes → 401. Sem diferenciar maiúsculas. Padrão desligado; `[]` desliga e ignora a variável. |
176
+ | `issuer_url` | `ORFEU_ISSUER_URL` | URL pública do Argos (`SERVER_URL`): `iss` esperado = `{issuer_url}/realms/{realm_id}`. Ausente: `iss` http(s) terminado em `/realms/{realm_id}`. Nunca derive do `authorizer_url`. |
177
+ | `trusted_proxies` | `ORFEU_TRUSTED_PROXIES` (vírgula) | proxies cujo `x-forwarded-for` vale para o IP da auditoria; padrão `orfeu.trace.DEFAULT_TRUSTED_PROXIES` (loopback + redes privadas); `[]` = nenhum. |
178
+ | `check_revocation` | — (Django: `ORFEU_CHECK_REVOCATION`) | `True` ou lista de operações sensíveis: confere o `x-access-token` na introspecção RFC 7662, cache 10 s (ativo) / 60 s (inativo), fail-closed. |
179
+
154
180
  Usado por baixo pelos adapters; use direto em scripts, workers ou frameworks sem adapter.
155
181
 
156
182
  Atributos de classe (cache): `JWKS_TTL = 3600.0`, `API_TOKEN_TTL = 30.0` (caminho legado),
@@ -164,15 +190,23 @@ Atributos de classe (cache): `JWKS_TTL = 3600.0`, `API_TOKEN_TTL = 30.0` (caminh
164
190
  | `async authenticate()` | `POST {url}/realms/{realm}/apps/token` com `app_id`/`secret`; guarda o token do app. | `OrfeuAuthError` (rede, HTTP ≠ 200, sem `access_token`) |
165
191
  | `async fetch_jwks()` | baixa e guarda o JWKS do realm. | `OrfeuError` |
166
192
  | `async sync_operations()` | envia o catálogo registrado ao Argos. | `OrfeuSyncError`; `OrfeuAuthError` sem token |
167
- | `async fetch_operations()` | baixa as operações do backend com `allowed_groups` e `operation_id`. **Só roda no startup**; chame de novo para recarregar grupos sem reiniciar. | `OrfeuError`; `OrfeuAuthError` sem token |
168
- | `async validate_token(token) -> TokenClaims` | JWT RS256: exige `kid`, recarrega JWKS se vencido (1 h) ou `kid` desconhecido, verifica `exp` e realm. | `OrfeuTokenError` |
169
- | `async validate_app_token(token) -> TokenClaims` | introspecção (cache por hash do token); exige `type == "app"` e mesmo realm. | `OrfeuTokenError` (inválido, revogado, outro realm, Argos sem introspecção, rede/HTTP) |
193
+ | `async fetch_operations() -> bool` | baixa as operações do backend com `allowed_groups` e `operation_id`; reautentica uma vez no 401; `True` quando o catálogo mudou. A recarga periódica (1.1+) chama sozinha. | `OrfeuError`; `OrfeuAuthError` sem token |
194
+ | `async refresh_operations() -> bool` | revalidação com `If-None-Match`; nunca levanta; `True` em sucesso. | — |
195
+ | `start_permissions_refresh()` / `stop_permissions_refresh()` | controle manual da recarga (o `startup()` já agenda). | — |
196
+ | `permissions_stale` / `last_permissions_sync_at` / `permissions_refresh_running` (props.) | estado da recarga (`stale` = 5 intervalos sem sucesso; bom para o `/health`). | — |
197
+ | `async close(timeout=3.0)` / `close_sync(timeout=3.0)` | para a recarga e faz o flush da auditoria. | — |
198
+ | `async validate_token(token) -> TokenClaims` | JWT **só RS256**: exige `kid`; recarrega JWKS se vencido (1 h) ou `kid` desconhecido (busca forçada no máximo a cada 30 s por realm, 1.2+); exige `exp`, `sub` e `iss` (1.3+) e realm do app (ou qualquer, com `accept_any_realm`); `iss` do realm do token (exato com `issuer_url`); recusa `type: "app"` e `client_id`/`azp` fora do `allowed_clients`; com `check_revocation=True`, confere a revogação. JWKS indisponível também vira `OrfeuTokenError` (1.3+). | `OrfeuTokenError` |
199
+ | `async validate_app_token(token) -> TokenClaims` | introspecção (cache por hash do token); exige `type == "app"` e mesmo realm; `client_id` dentro do `allowed_clients`. | `OrfeuTokenError` (inválido, revogado, outro realm, client fora da lista, Argos sem introspecção, `/apps/token` recusando, rede/HTTP) |
170
200
  | `async validate_api_token(token, identifier, method) -> ApiTokenClaims \| None` | introspecção; `None` se inválido ou se a operação não foi concedida ao token. Argos sem introspecção (404) → endpoint legado de validação. | `OrfeuTokenError` (rede/HTTP do Argos) |
171
201
  | `check_permission(claims, identifier, method) -> bool` | operação desconhecida → `False`; `public` → `True`; `private`/`optional` → tem algum grupo; `protected` → interseção com `allowed_groups`. Síncrono, sem rede. | — |
172
202
  | `operation_uuid(identifier, method) -> str \| None` | UUID no Argos depois do `fetch_operations`. | — |
173
203
  | `record_audit(event: dict)` | enfileira um evento (no-op com auditoria desligada). | — |
174
204
  | `flush_audit(timeout: float = 3.0)` | envia o que está na fila. | — |
175
205
  | `pending_audit` (prop.) | eventos aguardando envio. | — |
206
+ | `is_trusted_proxy` (atributo, 1.3+) | o matcher montado de `trusted_proxies`. | — |
207
+ | `requires_revocation_check(identifier) -> bool` (1.3+) | `check_revocation` cobre esta operação? | — |
208
+ | `async assert_access_token_active(token)` (1.3+) | introspecção RFC 7662 do `x-access-token`; inativo ou Argos fora → erro (fail-closed). | `OrfeuTokenError` |
209
+ | `async validate_service_token(token, *, allowed_apps=None, realm_for=None, check_revocation=None) -> ServiceTokenClaims` (1.4+) | token de serviço (client_credentials, `type: "app"`), mesmas regras do `validateServiceToken` do Node: realm de verificação nunca do token (`realm_for`, síncrona ou `async`; `None` = app desconhecida), `allowed_apps`; `allowed_clients` não se aplica. Devolve `ServiceTokenClaims(app_id, realm_id, exp, raw, client_id=None)`. Rotas: `@service_route(...)` (`orfeu.service_route`). | `OrfeuTokenError` (401) |
176
210
  | `run_sync(coro, timeout: float \| None = 30.0)` | roda uma corrotina do cliente a partir de código síncrono, num loop dedicado (thread daemon `orfeu-loop`), nunca `asyncio.run()` por chamada. Funciona com loop rodando. | o que a corrotina levantar; `TimeoutError` |
177
211
 
178
212
  O token do app é renovado automaticamente quando a introspecção ou o envio da auditoria recebem 401.
@@ -262,6 +296,8 @@ Raiz: `TRACEPARENT_HEADER = "traceparent"`, `OrfeuTrace`, `parse_traceparent`, `
262
296
  | `parse_traceparent(value) -> tuple[str, str] \| None` | `(trace_id, span_id)`; `None` se inválido: maiúsculas, versão `ff`, ids zerados, campos extras na versão `00`. Versões futuras lidas pelos 4 primeiros campos. |
263
297
  | `resolve_trace(incoming) -> OrfeuTrace` | válido → continua (`entry=False`, mesmo `trace_id`, `parent_span_id` = span recebido, `span_id` novo, só o bit *sampled* propagado); senão → trace novo (`entry=True`, flags `01`). |
264
298
  | `format_traceparent(t) -> str` | `"00-{trace_id}-{span_id}-{flags}"`, para mandar adiante. |
299
+ | `DEFAULT_TRUSTED_PROXIES`, `trusted_proxy_matcher(entries)`, `normalize_ip(ip)` *(submódulo `orfeu.trace`, 1.3+)* | lista padrão (loopback + redes privadas) e o matcher usado pelo `trusted_proxies`. |
300
+ | `client_ip_of(..., is_trusted_proxy=None)` *(submódulo `orfeu.trace`)* | IP do cliente para a auditoria; 1.3+ recebe o matcher e nunca usa o primeiro `x-forwarded-for`. |
265
301
 
266
302
  ---
267
303
 
@@ -310,7 +346,8 @@ na permissão (e só vão para a auditoria se forem GUID).
310
346
 
311
347
  ### `orfeu.adapters.flask` — `__all__ = ["Orfeu", "operation", "orfeu_headers"]`
312
348
 
313
- `Orfeu(app, authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True)` — faz o startup
349
+ `Orfeu(app, authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True, ...)` (mesmos
350
+ keyword-only do FastAPI) — faz o startup
314
351
  **na construção** (síncrono): todas as `@operation` precisam estar importadas antes. Registra
315
352
  `before_request` (guarda), `after_request` (log/auditoria com o status real) e `teardown_request`. Na view:
316
353
  `g.orfeu_user` (`TokenClaims` ou `None` no anônimo) ou `g.orfeu_api_token`; `orfeu_headers(g)`.
@@ -318,13 +355,15 @@ Negação: `jsonify(...)` 401/403 no mesmo corpo do FastAPI.
318
355
 
319
356
  ### `orfeu.adapters.django` — `__all__ = ["OrfeuMiddleware", "operation", "orfeu_headers"]`
320
357
 
321
- `"orfeu.adapters.django.OrfeuMiddleware"` em `MIDDLEWARE`; settings de [python.md](python.md) §2. Startup na
358
+ `"orfeu.adapters.django.OrfeuMiddleware"` em `MIDDLEWARE`; settings de [python.md](python.md) §2 (inclusive
359
+ `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES`, `ORFEU_CHECK_REVOCATION`). Startup na
322
360
  construção do middleware; guarda em `process_view` (lê `view_func` e `view_func.__wrapped__`). Na view:
323
361
  `request.orfeu_user` / `request.orfeu_api_token`; `orfeu_headers(request)`. WSGI ou ASGI.
324
362
 
325
363
  ### `orfeu.adapters.strawberry` — `__all__ = ["Orfeu", "operation", "orfeu_headers"]`
326
364
 
327
- `Orfeu(authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True)` (sem `app`):
365
+ `Orfeu(authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True, ...)` (sem `app`; mesmos
366
+ keyword-only do FastAPI):
328
367
  `.extension` (classe `SchemaExtension` para `strawberry.Schema(..., extensions=[orfeu.extension])`),
329
368
  `startup_async()`/`startup()` idempotentes — **chame no lifespan** (não há gancho automático). Cada campo
330
369
  com `@operation` é uma operação (log + auditoria). No resolver: `info.context["orfeu_user"]`;
@@ -341,6 +380,7 @@ Não são API estável, mas aparecem em testes:
341
380
  - `orfeu.middleware.Credentials(api="", access="", app="")` e `extract_credentials(get)` — leitura dos 3
342
381
  headers (valores com `strip()`; só espaço = ausente).
343
382
  - `orfeu.guard`: `UNAUTHORIZED_MESSAGE = "Invalid or missing credentials."`,
344
- `FORBIDDEN_MESSAGE = "Insufficient permissions."`, `decide(client, creds, identifier, method, level)`.
383
+ `FORBIDDEN_MESSAGE = "Insufficient permissions."`, `decide(client, creds, identifier, method, level)`,
384
+ `needs_revocation_check` e `enforce_revocation` (1.3+).
345
385
  - `orfeu.audit.AuditSink(transport, options)` — troque `orfeu.client._audit_sink` por um sink com
346
386
  `transport=lambda batch: lista.extend(batch) or 202` para capturar eventos.
@@ -1,7 +1,8 @@
1
1
  # orfeu — receitas
2
2
 
3
- Todas para a API 1.0.0. URLs e nomes de variáveis são exemplos; os nomes `ORFEU_*` são convenção do app
4
- (a lib não lê ambiente).
3
+ Todas para a API 1.4.0. URLs e nomes de variáveis são exemplos; os nomes `ORFEU_*` são convenção do app — a lib
4
+ só lê sozinha `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL` e `ORFEU_TRUSTED_PROXIES`, e só quando o argumento não é
5
+ passado.
5
6
 
6
7
  Sumário: §1 app FastAPI protegido · §2 operação com permissão (`protected`) · §3 rota pública e opcional ·
7
8
  §4 anotar o alvo na auditoria · §5 chamar outro serviço em nome do usuário · §6 chamar outro serviço como o
@@ -31,7 +32,15 @@ def orfeu_config() -> dict:
31
32
  "app_id": os.environ["ORFEU_APP_ID"],
32
33
  "secret": os.environ["ORFEU_SECRET"],
33
34
  "tls_verify": os.environ.get("ORFEU_TLS_VERIFY", "true").lower() != "false",
35
+ # 1.3+: backend do front do próprio app → só tokens desse client (lista vazia = None, nunca [])
36
+ "allowed_clients": _lista(os.environ.get("ORFEU_ALLOWED_CLIENTS")) or None,
37
+ "issuer_url": os.environ.get("ORFEU_ISSUER_URL") or None, # issuer da discovery sem /realms/<realm>
38
+ "check_revocation": ["forms.delete"], # operações sensíveis
34
39
  }
40
+
41
+
42
+ def _lista(valor: str | None) -> list[str]:
43
+ return [p.strip() for p in (valor or "").split(",") if p.strip()]
35
44
  ```
36
45
 
37
46
  `app/forms/router.py`:
@@ -109,24 +118,9 @@ async def create_form(payload: FormIn, request: Request):
109
118
  - Usuário válido fora desses grupos → **403** `"Insufficient permissions."` sem rodar o handler.
110
119
  - Um `x-api-token` só passa se a operação `forms.create`/`write` foi concedida a esse token neste backend
111
120
  (senão 401).
112
- - Os grupos permitidos são lidos **no startup**. Depois de mudar os grupos no Argos, reinicie o serviço — ou
113
- recarregue periodicamente:
114
-
115
- ```python
116
- import asyncio, logging
117
- from orfeu import OrfeuError
118
-
119
- async def refresh_operations(orfeu, every: float = 300.0) -> None:
120
- while True:
121
- await asyncio.sleep(every)
122
- try:
123
- await orfeu.client.authenticate() # o token do app expira; fetch_operations não renova sozinho
124
- await orfeu.client.fetch_operations()
125
- except OrfeuError:
126
- logging.getLogger(__name__).warning("falha ao recarregar operações", exc_info=True)
127
- ```
128
-
129
- (dispare com `asyncio.create_task(refresh_operations(orfeu))` no seu lifespan e cancele no shutdown.)
121
+ - Os grupos permitidos são revalidados sozinhos a cada ~60 s depois do startup (`permissions_refresh`, ligado
122
+ por padrão): liberar ou revogar um grupo no Argos vale em até ~1 min, sem reiniciar. `orfeu.client.permissions_stale`
123
+ serve para o `/health`.
130
124
 
131
125
  Precisa de uma regra além dos grupos (ex.: só o dono edita)? Faça no handler e levante `Forbidden(...)` do
132
126
  envelope — é uma regra de negócio, não da guarda:
@@ -464,7 +458,13 @@ precisam estar importadas (via `urls.py`) quando o middleware é construído.
464
458
  |---|---|---|
465
459
  | Rota responde sem pedir credencial | sem `@operation`, ou um decorator entre a rota e `@operation` sem `functools.wraps` apagou os atributos | `@operation` logo abaixo de `@router.get(...)`; wrappers com `functools.wraps` |
466
460
  | App não sobe: `OrfeuConfigError: No operations registered` | nenhum módulo com `@operation` importado antes do lifespan | importe os routers no `main` antes de servir |
467
- | 403 numa operação recém-criada, mesmo com grupo certo | módulo importado **depois** do startup (fora do sync), ou grupos alterados no Argos depois do boot | importe tudo antes do startup; reinicie ou recarregue (§2) |
461
+ | 403 numa operação recém-criada, mesmo com grupo certo | módulo importado **depois** do startup (fora do sync), ou grupos liberados há menos de ~1 min | importe tudo antes do startup; espere a recarga (§2) ou confira `permissions_stale` |
462
+ | 401 com token válido depois de atualizar para a 1.3 | `issuer_url` errado (derivado do `authorizer_url` interno); `allowed_clients` sem o `client_id` do front que chamou; token fake de teste sem `iss`/`exp`/`sub` ou com `type: "app"` | `issuer` da discovery sem `/realms/<realm>`; liste os fronts que chamam; assine o fake com as três claims |
463
+ | Rota chamada por outra aplicação virou 401 na 1.3 | o token client_credentials (`type: "app"`) não vale mais como usuário | `@service_route(...)` da 1.4 (python.md §5); no fake, recuse `type: "app"` no `validate_token` |
464
+ | `ORFEU_ALLOWED_CLIENTS` no ambiente e nada muda | o app passa `allowed_clients=[]` (lista vazia das settings), que desliga e ignora a variável | passe `None` quando a lista estiver vazia |
465
+ | 401 (não mais 500) com o Argos fora | 1.3: falha de JWKS/`/apps/token` vira token não validado (anônimo em `public`) | é o esperado; monitore a taxa de 401 e a saúde do Argos |
466
+ | 401 numa operação sensível com o Argos fora | `check_revocation` é fail-closed | só nas operações sensíveis, não `True` |
467
+ | IP da auditoria mudou | 1.3 não usa mais o primeiro `x-forwarded-for` | proxies fora de loopback/redes privadas → `trusted_proxies` |
468
468
  | `AttributeError: 'State' object has no attribute 'user'` | leitura direta de `request.state.user` em `public`/`optional` anônimo | `getattr(request.state, "user", None)` |
469
469
  | `request.state.user` é `None` numa rota `private` | chamada com `x-api-token` (backend) | leia `request.state.api_token` nesse caso |
470
470
  | 401 mesmo mandando `Authorization: Bearer ...` | o orfeu não lê `Authorization` | mande em `x-access-token` (JWT) / `x-app-token` / `x-api-token` |
@@ -473,7 +473,7 @@ precisam estar importadas (via `urls.py`) quando o middleware é construído.
473
473
  | `request` virou parâmetro de query (422) | `from __future__ import annotations` + `Request` importado dentro de função | importe `Request` no topo do módulo |
474
474
  | Evento de auditoria sem alvo | `annotate_operation` chamado numa task/thread iniciada depois da resposta, ou fora de `@operation` | chame no fluxo do handler, antes de retornar |
475
475
  | `route_id`/`client_id` não aparecem na auditoria | `x-route-id`/`x-client-id` não estão em formato GUID | mande o id GUID (no log eles aparecem como vieram) |
476
- | Eventos perdidos ao encerrar | processo morto sem shutdown gracioso | deixe o lifespan terminar; em scripts, `client.flush_audit()` |
476
+ | Eventos perdidos ao encerrar | processo morto sem shutdown gracioso | deixe o lifespan terminar; em scripts, `await client.close()` (ou `close_sync()`) |
477
477
  | 500 `route_unresolved` | a guarda não conseguiu reproduzir o roteamento (internos do FastAPI mudaram) | é falha fechada de propósito; atualize o orfeu e veja o logger `orfeu.guard` |
478
478
  | Testes vazando operações entre si | registro global de `@operation` | `orfeu.decorators.clear_registry()` ao montar cada app de teste |
479
479
  | `tls_verify=False` em produção | atalho de desenvolvimento esquecido | use certificado válido; o parâmetro só afeta chamadas ao Argos, mas ainda assim desliga a verificação |