@acropole/skills 1.4.1 → 1.5.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/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
|
@@ -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 |
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
|
|
2
2
|
|
|
3
|
-
> Escrito para a **
|
|
4
|
-
> print(m.version('orfeu'))"`).
|
|
3
|
+
> Escrito para a **1.4.0** (anda junto com `@orfeu/node` e `@orfeu/angular`; versão instalada:
|
|
4
|
+
> `python -c "import importlib.metadata as m; print(m.version('orfeu'))"`). A 1.3.0 trouxe as correções da
|
|
5
|
+
> auditoria de segurança (§5). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
|
|
5
6
|
> em relação ao Node e ao Angular está em [diferencas.md](diferencas.md). Estrutura do serviço FastAPI em si
|
|
6
7
|
> (camadas, banco, configuração): skill `fastapi`. Flask, Django e Strawberry ainda não têm skill de
|
|
7
8
|
> padrões — aqui só a integração com o Orfeu.
|
|
@@ -36,12 +37,14 @@ pip install "orfeu[flask]" # ou [django], [strawberry]; sem extra = s
|
|
|
36
37
|
- **Python ≥ 3.11** (`requires-python = ">=3.11"`; usa `enum.StrEnum`). Testado em 3.11–3.14.
|
|
37
38
|
- Dependências fixas: `httpx>=0.27`, `PyJWT[crypto]>=2.8`. O adapter FastAPI foi testado com FastAPI
|
|
38
39
|
0.111.0, 0.116.1, 0.137.0 e 0.142.2.
|
|
39
|
-
-
|
|
40
|
+
- No `requirements.txt` do app, versão exata: `orfeu[fastapi]==1.4.0` (mesma versão das libs `@orfeu/*` do app).
|
|
40
41
|
|
|
41
42
|
## 2. Configuração
|
|
42
43
|
|
|
43
|
-
A
|
|
44
|
-
|
|
44
|
+
A configuração entra pelo construtor (`Orfeu(...)` dos adapters ou `OrfeuClient(...)`); o Django lê `settings`.
|
|
45
|
+
Exceção (1.3+): sem o argumento, `allowed_clients`, `issuer_url` e `trusted_proxies` leem `ORFEU_ALLOWED_CLIENTS`,
|
|
46
|
+
`ORFEU_ISSUER_URL` e `ORFEU_TRUSTED_PROXIES` do ambiente. Prefira passar pelas settings do app; um argumento
|
|
47
|
+
passado vence a variável, e `allowed_clients=[]` **desliga** (passe `None` quando a lista estiver vazia).
|
|
45
48
|
|
|
46
49
|
| Parâmetro | Obrigatório | O que é |
|
|
47
50
|
|---|---|---|
|
|
@@ -51,10 +54,17 @@ A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(..
|
|
|
51
54
|
| `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
|
|
52
55
|
| `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
|
|
53
56
|
| `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
|
|
54
|
-
| `permissions_refresh` | não, só por nome (
|
|
57
|
+
| `permissions_refresh` | não, só por nome (`orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
|
|
58
|
+
| `accept_any_realm` | não, só por nome (`orfeu` ≥ 1.2) | `False` (padrão). `True` aceita `x-access-token`/`x-app-token` de qualquer realm, buscando o JWKS do realm do token (limites em [diferencas.md](diferencas.md)). Django: `ORFEU_ACCEPT_ANY_REALM`. |
|
|
59
|
+
| `allowed_clients` | não, só por nome (1.3+) | `client_id`s aceitos no token de usuário (`x-access-token` e `x-app-token`); `client_id`/`azp` fora da lista → 401. Sem o argumento, `ORFEU_ALLOWED_CLIENTS` (vírgula). Padrão desligado. |
|
|
60
|
+
| `issuer_url` | não, só por nome (1.3+) | URL pública do Argos (`SERVER_URL`): `iss` esperado = `{issuer_url}/realms/{realm_id}`. Sem o argumento, `ORFEU_ISSUER_URL`. |
|
|
61
|
+
| `trusted_proxies` | não, só por nome (1.3+) | proxies cujo `x-forwarded-for` vale para o IP da auditoria. Padrão `orfeu.trace.DEFAULT_TRUSTED_PROXIES` (loopback + redes privadas); sem o argumento, `ORFEU_TRUSTED_PROXIES`; `[]` = nenhum. |
|
|
62
|
+
| `check_revocation` | não, só por nome (1.3+) | `False` (padrão), lista de operações sensíveis ou `True`: confere o `x-access-token` na introspecção RFC 7662 do Argos (cache 10 s/60 s, fail-closed). Django: `ORFEU_CHECK_REVOCATION`. |
|
|
55
63
|
|
|
56
64
|
Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
|
|
57
|
-
sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY
|
|
65
|
+
sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY`, `ORFEU_AUDIT`, `ORFEU_PERMISSIONS_REFRESH`,
|
|
66
|
+
`ORFEU_ACCEPT_ANY_REALM`, `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES` e
|
|
67
|
+
`ORFEU_CHECK_REVOCATION` (opcionais).
|
|
58
68
|
|
|
59
69
|
Nos outros frameworks o app escolhe os nomes das variáveis. Convenção sugerida (a mesma do Django):
|
|
60
70
|
`ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET`, `ORFEU_TLS_VERIFY`.
|
|
@@ -75,6 +85,8 @@ orfeu = Orfeu(
|
|
|
75
85
|
realm_id=os.environ["ORFEU_REALM_ID"],
|
|
76
86
|
app_id=os.environ["ORFEU_APP_ID"],
|
|
77
87
|
secret=os.environ["ORFEU_SECRET"],
|
|
88
|
+
allowed_clients=["<client_id do front>"], # backend de front próprio: ligue (§5)
|
|
89
|
+
issuer_url=os.environ.get("ORFEU_ISSUER_URL") or None,
|
|
78
90
|
)
|
|
79
91
|
|
|
80
92
|
@app.get("/items")
|
|
@@ -85,8 +97,9 @@ async def list_items(request: Request):
|
|
|
85
97
|
```
|
|
86
98
|
|
|
87
99
|
- `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
|
|
88
|
-
token do app → JWKS → sync das operações → busca das operações com grupos (e
|
|
89
|
-
|
|
100
|
+
token do app → JWKS → sync das operações → busca das operações com grupos (e agenda a recarga periódica
|
|
101
|
+
delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e
|
|
102
|
+
com `on_startup`. Não chame nada no seu lifespan.
|
|
90
103
|
- O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
|
|
91
104
|
(`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
|
|
92
105
|
(`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
|
|
@@ -122,7 +135,27 @@ async def create_form(...): ...
|
|
|
122
135
|
Headers (`x-access-token` → `x-app-token` → `x-api-token`, vale a primeira presente; `Authorization` é
|
|
123
136
|
ignorado) e a regra 401/403 estão no `SKILL.md` §4 — idêntica em FastAPI HTTP/WebSocket, Flask, Django e
|
|
124
137
|
Strawberry. Específico do Python: o JWT precisa ser RS256 com `kid` no header; introspecção com cache de 60 s
|
|
125
|
-
(token inativo: 10 s); tokens de outro realm são
|
|
138
|
+
(token inativo: 10 s); tokens de outro realm são recusados, salvo `accept_any_realm=True` (1.2+). Busca forçada
|
|
139
|
+
do JWKS (por `kid` desconhecido) no máximo uma vez a cada 30 s por realm: chave recém-rotacionada pode levar até
|
|
140
|
+
30 s para ser aceita.
|
|
141
|
+
|
|
142
|
+
O `x-access-token` é recusado (401) quando (1.3+): algoritmo diferente de `RS256`; assinatura ou `kid` não
|
|
143
|
+
conferem; falta `exp`, `sub` ou `iss`, ou venceu; o `iss` não é o do realm do token (com `issuer_url`, exatamente
|
|
144
|
+
`{issuer_url}/realms/{realm_id}`; sem, uma URL http(s) terminada em `/realms/{realm_id}` — o `authorizer_url`
|
|
145
|
+
costuma ser endereço interno e não serve); o realm não é o do app; é token **de aplicação** (`type: "app"`,
|
|
146
|
+
client_credentials); ou `allowed_clients` está ligado e o `client_id`/`azp` não está na lista.
|
|
147
|
+
|
|
148
|
+
**Argos fora não vira 500** (1.3+): JWKS indisponível ou `/apps/token` recusando ao introspectar tratam o token
|
|
149
|
+
como não validado — `public` segue anônimo, `private`/`protected`/`optional` respondem 401. Alerta que olhava 500
|
|
150
|
+
não pega mais isso: monitore a taxa de 401 e a saúde do Argos.
|
|
151
|
+
|
|
152
|
+
**`allowed_clients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
|
|
153
|
+
login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
|
|
154
|
+
Ligue em todo backend que atende o front do próprio app (valor = `client_id` do front); serviço chamado por
|
|
155
|
+
gateways de vários apps lista os fronts de todos; não ligue no que atende qualquer app do realm de propósito.
|
|
156
|
+
|
|
157
|
+
**Revogação**: a validação local não enxerga revogação — um access token revogado vale até o `exp` (até 10 min
|
|
158
|
+
no Argos). Operações sensíveis: `check_revocation=["pedidos.delete"]` (introspecção RFC 7662, fail-closed).
|
|
126
159
|
|
|
127
160
|
O que o handler FastAPI recebe (`request.state` / `websocket.state`):
|
|
128
161
|
|
|
@@ -139,6 +172,25 @@ Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`
|
|
|
139
172
|
`user.raw.get("preferred_username") or user.raw.get("email") or user.sub`. `user.get(...)` lança
|
|
140
173
|
`AttributeError: 'TokenClaims' object has no attribute 'get'` (500 na rota).
|
|
141
174
|
|
|
175
|
+
### Rota máquina-a-máquina: token de serviço (1.4+)
|
|
176
|
+
|
|
177
|
+
Desde a 1.3 o token client_credentials de uma aplicação (`type: "app"`) não vale como usuário: rota que outra
|
|
178
|
+
aplicação chamava com ele via `@operation` passou a dar 401 (e teste com o `validate_token` mockado não pega). Use:
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from orfeu import service_route
|
|
182
|
+
|
|
183
|
+
@router.post("/interno/sincronizar")
|
|
184
|
+
@service_route(allowed_apps=[settings.app_origem_id]) # não combine com @operation
|
|
185
|
+
async def sincronizar(request: Request):
|
|
186
|
+
return ok({"de": request.state.service.app_id})
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Vale em FastAPI (HTTP e WebSocket, `request.state.service`), Flask (`g.orfeu_service`) e Django
|
|
190
|
+
(`request.orfeu_service`); no Strawberry, chame `await client.validate_service_token(token, ...)` no contexto. O
|
|
191
|
+
realm de verificação nunca vem do token (`realm_for`); `allowed_clients` não se aplica; a rota não entra no catálogo
|
|
192
|
+
nem na auditoria de operação. Detalhes em [python-api.md](python-api.md) §3.
|
|
193
|
+
|
|
142
194
|
## 6. Respostas, erros e status
|
|
143
195
|
|
|
144
196
|
| Situação | Resposta |
|
|
@@ -183,6 +235,10 @@ annotate_operation(target_type="form", target_id=form_id, details={"campos": ["t
|
|
|
183
235
|
Cada chamada guardada tem um `OrfeuTrace`: com `traceparent` W3C válido na entrada, o trace continua
|
|
184
236
|
(`entry=False`, mesmo `trace_id`); sem ele (ou inválido), começa um novo (`entry=True`).
|
|
185
237
|
|
|
238
|
+
IP do cliente na auditoria (1.3+): o primeiro `x-forwarded-for` nunca é usado. Conexão direta de fora de
|
|
239
|
+
`trusted_proxies` → IP do socket; de proxy confiável → a entrada mais à direita do `x-forwarded-for` que não é
|
|
240
|
+
proxy. Usuários na rede privada sem proxy: configure `trusted_proxies` só com os proxies.
|
|
241
|
+
|
|
186
242
|
Para chamar outro serviço **em nome da requisição atual**, use `orfeu_headers(request)`:
|
|
187
243
|
|
|
188
244
|
```python
|
|
@@ -221,6 +277,8 @@ orfeu.client.check_permission = MagicMock(return_value=True)
|
|
|
221
277
|
```
|
|
222
278
|
|
|
223
279
|
Detalhes (registro global, `clear_registry()`, capturar eventos de auditoria, logs): [python-recipes.md](python-recipes.md) §9.
|
|
280
|
+
Teste que assina JWT de verdade (sem mock do `validate_token`): desde a 1.3 o token precisa de `exp`, `sub` e
|
|
281
|
+
`iss` (`<url>/realms/<realm_id>`), sem `type: "app"`, e do `client_id` da lista quando `allowed_clients` está ligado.
|
|
224
282
|
|
|
225
283
|
## 11. Regras que não podem ser quebradas
|
|
226
284
|
|
|
@@ -25,7 +25,10 @@ Divisão de trabalho entre as skills:
|
|
|
25
25
|
## 1. Pacotes
|
|
26
26
|
|
|
27
27
|
Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular ← (maps, charts, spine)`. Todos na
|
|
28
|
-
**mesma versão** (`^2.
|
|
28
|
+
**mesma versão** (`^2.1.2`); as 0.9.x foram retiradas do registry.
|
|
29
|
+
|
|
30
|
+
> **Atualizando um app** (vindo da 1.x ou da 2.0.x)? Siga o guia da skill `acropole`:
|
|
31
|
+
> [../acropole/references/fluxos/atualizar-libs-2026-10.md](../acropole/references/fluxos/atualizar-libs-2026-10.md) — quebras da 2.0, o que a 2.1 muda no app e os contornos de CSS a remover.
|
|
29
32
|
|
|
30
33
|
| Pacote | Para quê |
|
|
31
34
|
|---|---|
|
|
@@ -38,7 +41,7 @@ Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular
|
|
|
38
41
|
| `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores, GeoJSON) com mapas base embutidos |
|
|
39
42
|
| `@trismegisto/spine` | o **shell pronto**: cabeçalho, menu lateral vindo do servidor de autorização (Argos), workspace em abas, barra da página, login/callback, modal/painel/toast por serviço, configurações, tour, auditoria, cliente GraphQL. O app entrega só as telas |
|
|
40
43
|
|
|
41
|
-
## 2. Instalação (2.
|
|
44
|
+
## 2. Instalação (2.1.2)
|
|
42
45
|
|
|
43
46
|
```bash
|
|
44
47
|
# sem shell pronto
|