@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.
- package/README.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +4 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +382 -0
- package/skills/auto-servico/SKILL.md +14 -8
- package/skills/auto-servico/references/diagnostico.md +2 -1
- package/skills/auto-servico/references/tools.md +7 -2
- package/skills/hefesto/SKILL.md +11 -5
- package/skills/hefesto/references/mcp-diagnostico.md +2 -1
- package/skills/hefesto/references/mcp-tools.md +13 -3
- package/skills/orfeu/SKILL.md +32 -6
- package/skills/orfeu/references/angular-api.md +14 -6
- package/skills/orfeu/references/angular-armadilhas.md +17 -2
- package/skills/orfeu/references/angular-recipes.md +23 -8
- package/skills/orfeu/references/angular.md +16 -7
- package/skills/orfeu/references/diferencas.md +13 -6
- package/skills/orfeu/references/node-api.md +68 -8
- package/skills/orfeu/references/node-armadilhas.md +40 -6
- package/skills/orfeu/references/node-recipes.md +26 -12
- package/skills/orfeu/references/node.md +66 -12
- package/skills/orfeu/references/python-api.md +53 -13
- package/skills/orfeu/references/python-recipes.md +22 -22
- package/skills/orfeu/references/python.md +68 -10
- package/skills/trismegisto/SKILL.md +5 -2
- package/skills/trismegisto/references/angular-api.md +43 -4
- package/skills/trismegisto/references/angular-exports.md +127 -3
- package/skills/trismegisto/references/angular-recipes.md +31 -0
- package/skills/trismegisto/references/angular-types.md +2 -1
- package/skills/trismegisto/references/catalogo/seletores.json +152 -0
- package/skills/trismegisto/references/catalogo/tokens.json +1 -0
- package/skills/trismegisto/references/spine-api.md +519 -7
- package/skills/trismegisto/references/spine-recipes.md +15 -11
- package/skills/trismegisto/references/spine.md +21 -3
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
# Receitas — @orfeu/node 1.0
|
|
1
|
+
# Receitas — @orfeu/node 1.4.0
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.0
|
|
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
|
|
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
|
-
|
|
420
|
-
|
|
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()`
|
|
436
|
-
|
|
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
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
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
|
|
4
|
-
> Apollo
|
|
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.
|
|
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
|
-
|
|
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
|
|
82
|
-
uma operação no Argos
|
|
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
|
|
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.
|
|
165
|
-
sair (`node-recipes.md` §11). `client.pendingAudit` mostra
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
|
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
|
|
168
|
-
| `async
|
|
169
|
-
| `
|
|
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)`
|
|
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
|
|
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.
|
|
4
|
-
|
|
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
|
|
113
|
-
|
|
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
|
|
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.
|
|
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 |
|