@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.
@@ -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 |
@@ -1,7 +1,8 @@
1
1
  # orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
2
2
 
3
- > Escrito para a **API 1.0.0** (versão instalada: `python -c "import importlib.metadata as m;
4
- > print(m.version('orfeu'))"`). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
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
- - Fixe a versão maior no app: `orfeu[fastapi]>=1.0,<2`.
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 lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(...)` dos adapters ou
44
- `OrfeuClient(...)`), exceto no Django, que lê `settings`.
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 (`@orfeu/node` ≥ 1.1 / `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`. |
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` e `ORFEU_AUDIT` (opcionais).
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, com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1, agenda a recarga
89
- periódica delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
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 sempre recusados (não há `acceptAnyRealm`).
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.0.1`); as 0.9.x foram retiradas do registry.
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.0.1)
44
+ ## 2. Instalação (2.1.2)
42
45
 
43
46
  ```bash
44
47
  # sem shell pronto