@acropole/skills 1.7.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +5 -4
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/package.json +1 -1
  4. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
  5. package/skills/angular/SKILL.md +2 -2
  6. package/skills/angular/references/dados.md +3 -3
  7. package/skills/angular/references/estrutura.md +6 -5
  8. package/skills/angular/references/features.md +5 -5
  9. package/skills/angular/references/testes-build.md +1 -1
  10. package/skills/auto-servico/SKILL.md +18 -14
  11. package/skills/express/references/dados.md +4 -1
  12. package/skills/express/references/estrutura.md +2 -1
  13. package/skills/fastapi/references/banco.md +6 -2
  14. package/skills/fastapi/references/estrutura.md +1 -1
  15. package/skills/hefesto/SKILL.md +6 -2
  16. package/skills/orfeu/SKILL.md +43 -13
  17. package/skills/orfeu/references/angular-api.md +39 -13
  18. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  19. package/skills/orfeu/references/angular-recipes.md +25 -12
  20. package/skills/orfeu/references/angular.md +37 -15
  21. package/skills/orfeu/references/diferencas.md +17 -8
  22. package/skills/orfeu/references/node-api.md +41 -9
  23. package/skills/orfeu/references/node-armadilhas.md +16 -2
  24. package/skills/orfeu/references/node-recipes.md +13 -4
  25. package/skills/orfeu/references/node.md +31 -12
  26. package/skills/orfeu/references/python-api.md +41 -16
  27. package/skills/orfeu/references/python-recipes.md +13 -9
  28. package/skills/orfeu/references/python.md +33 -12
  29. package/skills/orfeu/references/react.md +133 -0
  30. package/skills/trismegisto/SKILL.md +42 -29
  31. package/skills/trismegisto/references/angular-api.md +608 -6
  32. package/skills/trismegisto/references/angular-exports.md +479 -791
  33. package/skills/trismegisto/references/angular-recipes.md +13 -7
  34. package/skills/trismegisto/references/angular.md +32 -9
  35. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  36. package/skills/trismegisto/references/catalogo/seletores.json +90 -65
  37. package/skills/trismegisto/references/react-api.md +16864 -0
  38. package/skills/trismegisto/references/react.md +237 -0
  39. package/skills/trismegisto/references/spine-api.md +5565 -1973
  40. package/skills/trismegisto/references/spine-recipes.md +113 -26
  41. package/skills/trismegisto/references/spine.md +95 -33
  42. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -1,7 +1,9 @@
1
1
  # @orfeu/node — guia de uso (Express, Fastify, NestJS, Apollo)
2
2
 
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).
3
+ > Escrito para a **1.7.1** (peça `^1.7.1`; anda junto com `@orfeu/angular`, `@orfeu/react` e `orfeu`). A 1.0.0
4
+ > aceitava `orfeuUser` forjado nas subscriptions do Apollo; a 1.3.0 trouxe as correções da auditoria de segurança
5
+ > (§5); a 1.6.0, a tolerância de relógio; a 1.7.0 fez `public` deixar de validar credencial e criou o `identify`
6
+ > (§5).
5
7
  > Se a versão instalada for outra, confira os nomes de [node-api.md](node-api.md)
6
8
  > contra os `.d.ts` de `node_modules/@orfeu/node/dist/`. Conceitos comuns às três implementações estão no
7
9
  > `SKILL.md` da skill; o que muda em relação ao Python e ao Angular está em [diferencas.md](diferencas.md).
@@ -31,7 +33,7 @@ Leia sob demanda:
31
33
  ## 1. Instalação
32
34
 
33
35
  ```bash
34
- npm install @orfeu/node@^1.4.0
36
+ npm install @orfeu/node@^1.7.1
35
37
  npm install express # se usar @orfeu/node/express
36
38
  npm install fastify # @orfeu/node/fastify
37
39
  npm install @nestjs/common @nestjs/core reflect-metadata rxjs # @orfeu/node/nest
@@ -56,14 +58,15 @@ const client = new OrfeuClient({
56
58
  allowedClients: ['<client_id do front>'], // backend de front próprio: ligue (§5)
57
59
  issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
58
60
  // acceptAnyRealm: false, tlsVerify: true, audit: true, logger: jsonLineLogger,
59
- // permissionsRefresh: true, trustedProxies: DEFAULT_TRUSTED_PROXIES, checkRevocation: false (padrões)
61
+ // permissionsRefresh: true, trustedProxies: DEFAULT_TRUSTED_PROXIES, checkRevocation: false,
62
+ // clockToleranceSec: DEFAULT_CLOCK_TOLERANCE_SEC (30) (padrões)
60
63
  });
61
64
  ```
62
65
 
63
66
  | Opção | Padrão | Efeito |
64
67
  |---|---|---|
65
68
  | `acceptAnyRealm` | `false` | `true` aceita tokens de qualquer realm (busca o JWKS do realm da claim `realm_id`). |
66
- | `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo). |
69
+ | `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo); desde a 1.6 deixa um `console.warn` ao criar o client. |
67
70
  | `audit` | `true` | `false` desliga a auditoria; objeto `{ flushIntervalMs, maxBuffer, batchSize }` ajusta o lote. |
68
71
  | `logger` | `jsonLineLogger` | função `(record) => void` para outro destino; `false` desliga o log de operação. |
69
72
  | `permissionsRefresh` | `true` | revalida o catálogo (grupos liberados) a cada 60 s ±20%; `false` ou `{ enabled, intervalMs, jitter }`. |
@@ -71,6 +74,7 @@ const client = new OrfeuClient({
71
74
  | `issuerUrl` | — | URL pública do Argos (`SERVER_URL`): `iss` esperado = `${issuerUrl}/realms/${realm_id}`. Sem a opção, `ORFEU_ISSUER_URL`. |
72
75
  | `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
76
  | `checkRevocation` | `false` | lista de operações sensíveis (ou `true`) conferidas na introspecção do Argos; fail-closed. |
77
+ | `clockToleranceSec` | `30` (`DEFAULT_CLOCK_TOLERANCE_SEC`) | 1.6+: tolerância de relógio, em segundos, no `exp`/`nbf`/`iat` dos JWT (`validateToken`, `validateServiceToken`). Afrouxa: token vencido há menos de 30 s ainda vale; `0` = conferência exata. Valor inválido ou negativo volta ao padrão. |
74
78
 
75
79
  As três variáveis `ORFEU_*` só são lidas **quando a opção não é passada** — e no construtor. Cliente criado no
76
80
  topo de um módulo ESM roda antes do `dotenv.config()` e não as vê em `local`: prefira passar pelas settings do
@@ -119,12 +123,26 @@ Headers de credencial (`x-access-token` → `x-app-token` → `x-api-token`, a p
119
123
  401/403 estão no `SKILL.md` §4 — a regra é a mesma do Python. Específico do Node: introspecção com cache de
120
124
  60 s (token inativo: 10 s); `acceptAnyRealm: true` aceita JWT de outros realms.
121
125
 
126
+ **`public` não valida nada (1.7+)**: o guard libera sem ler `x-access-token`/`x-app-token`/`x-api-token` e sem
127
+ chamar o Argos (um token aleatório em rajada numa rota pública não vira mais introspecção), e o handler não recebe
128
+ `orfeuUser`/`orfeuApiToken`. Log e auditoria saem com `actor_type: public`. Para ter a identidade quando houver:
129
+ - **`optional`** — autoriza: sem credencial roda anônimo; credencial inválida ou vencida dá 401; o usuário precisa
130
+ de ao menos um grupo, o que depende do catálogo de operações (sem ele, `optional` com credencial dá 403);
131
+ - **`identify`** — só identifica, nunca bloqueia e não depende do catálogo nem do `startup()`: credencial válida
132
+ (access → app → api; o `x-api-token` só se concedido para a operação) preenche `orfeuUser`/`orfeuApiToken`;
133
+ inválida, vencida ou Argos fora vira anônimo. Registra a operação como `public` e gera o mesmo log/auditoria,
134
+ com o ator identificado. Quem decide o acesso é o app, depois. É exatamente o `public` até a 1.6:
135
+ `guard(id, Level.PUBLIC, method)` → `identify(id, method)` (Express), `fastify.orfeuIdentify(id, method?)`,
136
+ `@Identify(id, method?)` (Nest), `createIdentify(client)` ou `operation('public', r, { identify: true })`
137
+ (Apollo; `identify` com outro nível lança `OrfeuConfigError`). Receitas em [node-recipes.md](node-recipes.md).
138
+
122
139
  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`,
140
+ `kid` não conferem; falta `exp`, `sub` ou `iss`, ou venceu (com a tolerância de `clockToleranceSec`, 1.6+); o
141
+ `iss` não é o do realm do token (com `issuerUrl`,
124
142
  exatamente `${issuerUrl}/realms/${realm_id}`; sem, uma URL http(s) terminada em `/realms/${realm_id}`); o realm
125
143
  não é o do app (modo estrito); é token **de aplicação** (`type: "app"`, client_credentials); ou `allowedClients`
126
144
  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.
145
+ introspecção) nunca vira 500: 401 nos níveis que validam (`public` não valida; `identify` vira anônimo).
128
146
 
129
147
  **`allowedClients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
130
148
  login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
@@ -144,7 +162,7 @@ para o log.
144
162
 
145
163
  Quem passou fica em `req.orfeuUser` (`TokenClaims`: `sub`, `realmId`, `groups`, `exp`, `raw`) ou
146
164
  `req.orfeuApiToken` (`{ tokenId, appId }`) — no Apollo, `ctx.orfeuUser`/`ctx.orfeuApiToken`; no Nest,
147
- `@OrfeuUser()`.
165
+ `@OrfeuUser()`. Em `public` (1.7+) ficam vazios; em `identify`, preenchidos só com credencial válida.
148
166
 
149
167
  ### Rota máquina-a-máquina: token de serviço (1.4+)
150
168
 
@@ -166,10 +184,10 @@ app.post('/interno/sincronizar', serviceGuard({ allowedApps: [process.env.APP_OR
166
184
 
167
185
  | Framework | Captura (global) | Protege | Usuário |
168
186
  |---|---|---|---|
169
- | Express | `app.use(middleware)` de `orfeu(client)` | `guard(id, level, method?)` por rota | `req.orfeuUser` |
170
- | Fastify | `await fastify.register(orfeuFastifyPlugin, { client })` | `preHandler: fastify.orfeuGuard(id, level, method?)` | `request.orfeuUser` |
171
- | NestJS | `OrfeuModule.forRootAsync(opts)` | `@UseGuards(OrfeuGuard)` + `@Operation(id, level, method?)` no método | `@OrfeuUser()` |
172
- | Apollo | `plugins: [orfeuPlugin(client)]`; WS: `context: orfeuWsContext(client)` | `operation(level, resolver, opts?)` em **todo** campo raiz + `secureResolvers` + `assertSchemaSecured` | `ctx.orfeuUser` |
187
+ | Express | `app.use(middleware)` de `orfeu(client)` | `guard(id, level, method?)` por rota; `identify(id, method?)` (1.7+) | `req.orfeuUser` |
188
+ | Fastify | `await fastify.register(orfeuFastifyPlugin, { client })` | `preHandler: fastify.orfeuGuard(id, level, method?)`; `fastify.orfeuIdentify(id, method?)` (1.7+) | `request.orfeuUser` |
189
+ | NestJS | `OrfeuModule.forRootAsync(opts)` | `@UseGuards(OrfeuGuard)` + `@Operation(id, level, method?)` ou `@Identify(id, method?)` (1.7+) no método | `@OrfeuUser()` |
190
+ | Apollo | `plugins: [orfeuPlugin(client)]`; WS: `context: orfeuWsContext(client)` | `operation(level, resolver, opts?)` em **todo** campo raiz (`{ identify: true }` com `public`, 1.7+) + `secureResolvers` + `assertSchemaSecured`; fora dele, `createGuard`/`createIdentify` | `ctx.orfeuUser` |
173
191
 
174
192
  A captura só lê headers; **quem valida é o guard**. Rota sem guard (ou método Nest sem `@Operation`) não tem
175
193
  usuário e **não é protegida nem auditada**.
@@ -246,6 +264,7 @@ O pacote não publica mocks. Opções (`node-recipes.md` §12):
246
264
 
247
265
  - Não leia `Authorization`/`Bearer`; não valide JWT nem confira grupos à mão: use o guard.
248
266
  - Não deixe rota/resolver de negócio sem guard; não use `PUBLIC` para "resolver depois".
267
+ - Não leia `orfeuUser` numa rota `PUBLIC` (1.7+: sempre vazio): use `OPTIONAL` ou `identify`.
249
268
  - Não declare operações depois do `startup()` (não estarão no catálogo e serão negadas).
250
269
  - Não use texto livre para nível/método: `Level.*`/`Method.*`.
251
270
  - Não repasse credencial com `orfeuHeaders` para fora dos seus serviços.
@@ -1,4 +1,4 @@
1
- # orfeu 1.4.0 — referência da API
1
+ # orfeu 1.7.1 — 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
@@ -6,7 +6,10 @@ são importados do módulo indicado. Marcos: 1.1 — recarga das permissões e `
6
6
  intervalo mínimo de 30 s na busca forçada do JWKS; 1.3.0 — auditoria de segurança (`iss`/`exp`/`sub`
7
7
  obrigatórios, `type: "app"` recusado como usuário, `allowed_clients`, `issuer_url`, `trusted_proxies`,
8
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`).
9
+ (`validate_service_token`, `@service_route`); 1.6.0 — `clock_tolerance_s`, aviso com `tls_verify=False`, OpenAPI
10
+ anotado (`document_operations`), `httpx.AsyncClient` reaproveitado por event loop e caches por token com teto;
11
+ 1.7.0 — `public` não valida credencial e `request.state.user` existe (`None`) sem identidade; 1.7.1 — OpenAPI
12
+ anotado também nas rotas de `include_router` (FastAPI ≥ 0.137). A 1.5.0 não mudou esta lib.
10
13
 
11
14
  Sumário: [1. Adapter FastAPI](#1-orfeuadaptersfastapi) · [2. Operações e modelos](#2-operações-e-modelos) ·
12
15
  [3. OrfeuClient](#3-orfeuclient) · [4. Exceções](#4-exceções) · [5. Envelope](#5-envelope) ·
@@ -18,8 +21,9 @@ Sumário: [1. Adapter FastAPI](#1-orfeuadaptersfastapi) · [2. Operações e mod
18
21
 
19
22
  ## 1. `orfeu.adapters.fastapi`
20
23
 
21
- `__all__ = ["Orfeu", "operation", "Envelope", "install_envelope", "ok", "orfeu_headers"]`. Requer o extra
22
- `fastapi` (importa `starlette`).
24
+ `__all__ = ["Orfeu", "operation", "service_route", "Envelope", "install_envelope", "ok", "orfeu_headers"]`. Requer o
25
+ extra `fastapi` (importa `starlette`). Também importáveis do módulo (fora do `__all__`): `install_openapi_operations`,
26
+ `annotate_openapi_operations` (1.6+) e `WS_POLICY_VIOLATION`.
23
27
 
24
28
  ### `class Orfeu`
25
29
 
@@ -39,11 +43,14 @@ Orfeu(
39
43
  issuer_url: str | None = None, # 1.3+; None → ORFEU_ISSUER_URL
40
44
  trusted_proxies: Iterable[str] | None = None, # 1.3+; None → ORFEU_TRUSTED_PROXIES / DEFAULT_TRUSTED_PROXIES
41
45
  check_revocation: bool | Iterable[str] = False, # 1.3+
46
+ clock_tolerance_s: float = DEFAULT_CLOCK_TOLERANCE_S, # 1.6+ (30.0)
47
+ document_operations: bool = True, # 1.6+, só FastAPI: anota o OpenAPI
42
48
  )
43
49
  ```
44
50
 
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
51
+ Os argumentos keyword-only (menos `document_operations`) são repassados ao `OrfeuClient` (§3), com o mesmo
52
+ significado; Flask e Strawberry aceitam os mesmos. Com `document_operations=True`, chama
53
+ `install_openapi_operations(app)`. Na construção: cria `self.client = OrfeuClient(...)`, embrulha `app.router.lifespan_context` e chama
47
54
  `app.add_middleware(_OrfeuASGIMiddleware, client=self.client)`. Construa **depois** de criar o app e antes
48
55
  de ele começar a servir (o Starlette não aceita `add_middleware` depois do start).
49
56
 
@@ -72,8 +79,10 @@ Middleware (por requisição HTTP e handshake WebSocket):
72
79
  direita do `x-forwarded-for` que não é proxy; nunca o primeiro), grava `scope["state"]["orfeu"]` (lido por
73
80
  `orfeu_headers`), decide (regra canônica) e:
74
81
  - negado → 401/403 em JSON (HTTP) ou close 1008 (WS); log + auditoria;
82
+ - `public` (1.7+): libera sem ler credencial nem chamar o Argos;
75
83
  - permitido → `state.user = TokenClaims` (usuário) **ou** `state.user = None` + `state.api_token =
76
- ApiTokenClaims` (token de API); anônimo não define `state.user`; abre o contexto de
84
+ ApiTokenClaims` (token de API); sem identidade (`public`, `optional` anônimo) `state.user = None` (1.7+;
85
+ antes, ausente); abre o contexto de
77
86
  `annotate_operation`; roda o app capturando o status da resposta; grava log + auditoria com o status
78
87
  real (≥ 400 = falha, com a `message`/`detail` do corpo JSON).
79
88
  - WebSocket: a sessão inteira é **uma** operação; sucesso sem `status`.
@@ -96,10 +105,17 @@ Registra exception handlers que fazem todo erro responder `{"status", "message",
96
105
  Modelo pydantic genérico (`status: int = 200`, `message: str = ""`, `data: T | None = None`) para
97
106
  `response_model=Envelope[MeuSchema]`. É `None` se o pydantic não estiver instalado.
98
107
 
108
+ ### OpenAPI anotado (1.6+)
109
+
110
+ | Função | Comportamento |
111
+ |---|---|
112
+ | `annotate_openapi_operations(app, schema) -> dict` | escreve no `schema` gerado pelo FastAPI o `@operation` de cada rota: `summary` = `<identificador> · <nível>`, uma linha `**Operação:** ...` no início da `description` e `x-orfeu-operation` = `{id, method, level}`; rota de `@service_route` ganha `{service: true}` e o resumo `serviço · <função>`. O `operationId` não muda. Inclui as rotas de `include_router` no FastAPI ≥ 0.137 (1.7.1). Devolve o próprio `schema`. |
113
+ | `install_openapi_operations(app) -> None` | faz o `app.openapi()` passar pela função acima (uma vez; o FastAPI guarda o schema). Idempotente; app sem `openapi` (Starlette puro) fica como está. O `Orfeu(app, ...)` já chama, salvo `document_operations=False`. |
114
+
99
115
  ### Re-exports
100
116
 
101
- `operation` (o mesmo de `orfeu.operation`), `ok` (o mesmo de `orfeu.ok`), `orfeu_headers` (o mesmo de
102
- `orfeu.orfeu_headers`).
117
+ `operation` (o mesmo de `orfeu.operation`), `service_route` (o mesmo de `orfeu.service_route`), `ok` (o mesmo de
118
+ `orfeu.ok`), `orfeu_headers` (o mesmo de `orfeu.orfeu_headers`).
103
119
 
104
120
  ---
105
121
 
@@ -167,7 +183,8 @@ OrfeuClient(authorizer_url: str, realm_id: str, app_id: str, secret: str, *,
167
183
  allowed_clients: Iterable[str] | None = None,
168
184
  issuer_url: str | None = None,
169
185
  trusted_proxies: Iterable[str] | None = None,
170
- check_revocation: bool | Iterable[str] = False)
186
+ check_revocation: bool | Iterable[str] = False,
187
+ clock_tolerance_s: float = DEFAULT_CLOCK_TOLERANCE_S) # 1.6+; DEFAULT_CLOCK_TOLERANCE_S = 30.0 (raiz)
171
188
  ```
172
189
 
173
190
  | Argumento (1.3+) | Variável, sem o argumento | O que faz |
@@ -176,6 +193,12 @@ OrfeuClient(authorizer_url: str, realm_id: str, app_id: str, secret: str, *,
176
193
  | `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
194
  | `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
195
  | `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. |
196
+ | `clock_tolerance_s` (1.6+) | — (Django: `ORFEU_CLOCK_TOLERANCE`) | tolerância de relógio (`leeway` do PyJWT), em segundos, no `exp`/`nbf`/`iat` do `validate_token` e do `validate_service_token`. Padrão 30.0; `0` = conferência exata. |
197
+
198
+ `tls_verify=False` deixa um aviso no log (logger `orfeu`) ao criar o client (1.6+). As chamadas ao Argos
199
+ reaproveitam um `httpx.AsyncClient` por event loop (1.6+); `close()` fecha o do loop corrente, `close_sync()` o do
200
+ loop próprio do `run_sync`. Os caches por token (introspecção, revogação, validate antigo) têm teto de 10 000
201
+ entradas, e chamadas simultâneas com o mesmo token no mesmo loop esperam a mesma ida ao Argos (1.6+).
179
202
 
180
203
  Usado por baixo pelos adapters; use direto em scripts, workers ou frameworks sem adapter.
181
204
 
@@ -194,7 +217,7 @@ Atributos de classe (cache): `JWKS_TTL = 3600.0`, `API_TOKEN_TTL = 30.0` (caminh
194
217
  | `async refresh_operations() -> bool` | revalidação com `If-None-Match`; nunca levanta; `True` em sucesso. | — |
195
218
  | `start_permissions_refresh()` / `stop_permissions_refresh()` | controle manual da recarga (o `startup()` já agenda). | — |
196
219
  | `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. | — |
220
+ | `async close(timeout=3.0)` / `close_sync(timeout=3.0)` | para a recarga e faz o flush da auditoria; desde a 1.6 também fecha o `httpx.AsyncClient` do loop. | — |
198
221
  | `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
222
  | `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) |
200
223
  | `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) |
@@ -344,19 +367,20 @@ na permissão (e só vão para a auditoria se forem GUID).
344
367
 
345
368
  ## 11. Outros adapters
346
369
 
347
- ### `orfeu.adapters.flask` — `__all__ = ["Orfeu", "operation", "orfeu_headers"]`
370
+ ### `orfeu.adapters.flask` — `__all__ = ["Orfeu", "operation", "service_route", "orfeu_headers"]`
348
371
 
349
372
  `Orfeu(app, authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True, ...)` (mesmos
350
373
  keyword-only do FastAPI) — faz o startup
351
374
  **na construção** (síncrono): todas as `@operation` precisam estar importadas antes. Registra
352
375
  `before_request` (guarda), `after_request` (log/auditoria com o status real) e `teardown_request`. Na view:
353
- `g.orfeu_user` (`TokenClaims` ou `None` no anônimo) ou `g.orfeu_api_token`; `orfeu_headers(g)`.
376
+ `g.orfeu_user` (`TokenClaims` ou `None` no anônimo e em `public`) ou `g.orfeu_api_token`; `orfeu_headers(g)`.
354
377
  Negação: `jsonify(...)` 401/403 no mesmo corpo do FastAPI.
355
378
 
356
- ### `orfeu.adapters.django` — `__all__ = ["OrfeuMiddleware", "operation", "orfeu_headers"]`
379
+ ### `orfeu.adapters.django` — `__all__ = ["OrfeuMiddleware", "operation", "service_route", "orfeu_headers"]`
357
380
 
358
381
  `"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
382
+ `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES`, `ORFEU_CHECK_REVOCATION` e, 1.6+,
383
+ `ORFEU_CLOCK_TOLERANCE`). Startup na
360
384
  construção do middleware; guarda em `process_view` (lê `view_func` e `view_func.__wrapped__`). Na view:
361
385
  `request.orfeu_user` / `request.orfeu_api_token`; `orfeu_headers(request)`. WSGI ou ASGI.
362
386
 
@@ -366,7 +390,8 @@ construção do middleware; guarda em `process_view` (lê `view_func` e `view_fu
366
390
  keyword-only do FastAPI):
367
391
  `.extension` (classe `SchemaExtension` para `strawberry.Schema(..., extensions=[orfeu.extension])`),
368
392
  `startup_async()`/`startup()` idempotentes — **chame no lifespan** (não há gancho automático). Cada campo
369
- com `@operation` é uma operação (log + auditoria). No resolver: `info.context["orfeu_user"]`;
393
+ com `@operation` é uma operação (log + auditoria). No resolver: `info.context["orfeu_user"]` (num campo `public`,
394
+ 1.7+, pode ter só o usuário validado por outro campo do documento; o campo `public` não valida);
370
395
  `orfeu_headers(info.context)`. Negação: `OrfeuUnauthorizedError`/`OrfeuForbiddenError` (erro GraphQL com
371
396
  `extensions.code`/`status`). Subscriptions (graphql-ws): credenciais no payload do `connection_init`
372
397
  (`{"x-access-token": "..."}`), etiquetas em `routeId`/`clientId`. Funciona com `execute_sync`.
@@ -1,6 +1,6 @@
1
1
  # orfeu — receitas
2
2
 
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
3
+ Todas para a API 1.7.1. URLs e nomes de variáveis são exemplos; os nomes `ORFEU_*` são convenção do app — a lib
4
4
  só lê sozinha `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL` e `ORFEU_TRUSTED_PROXIES`, e só quando o argumento não é
5
5
  passado.
6
6
 
@@ -137,9 +137,8 @@ if form.owner != request.state.user.sub:
137
137
  ```python
138
138
  @router.get("/public/{slug}")
139
139
  @operation(id="forms.public_get", level=Level.PUBLIC, method=Method.READ)
140
- async def public_form(slug: str, request: Request):
141
- user = getattr(request.state, "user", None) # pode não existir
142
- return ok(await service.public_view(slug, viewer=user.sub if user else None))
140
+ async def public_form(slug: str):
141
+ return ok(await service.public_view(slug)) # 1.7+: public nunca tem usuário
143
142
 
144
143
 
145
144
  @router.get("/feed")
@@ -149,11 +148,12 @@ async def feed(request: Request):
149
148
  return ok(await service.feed(personal_for=user.sub if user else None))
150
149
  ```
151
150
 
152
- - `PUBLIC`: nunca bloqueia; credencial inválida é ignorada (roda anônimo).
151
+ - `PUBLIC` (1.7+): nunca bloqueia e **não lê credencial nenhuma** nem chama o Argos; `request.state.user` é
152
+ sempre `None`. Até a 1.6 a credencial válida chegava ao handler: rota pública que personaliza pelo usuário
153
+ vira `OPTIONAL` (o Python não tem o `identify` do Node).
153
154
  - `OPTIONAL`: sem credencial roda anônimo; com credencial **inválida** → 401; com credencial válida exige
154
155
  ao menos um grupo (igual a `PRIVATE`).
155
- - Rotas públicas também geram log e auditoria (com `actor_type` `public` ou o ator real, se veio credencial
156
- válida).
156
+ - Rotas públicas também geram log e auditoria, sempre com `actor_type` `public`.
157
157
 
158
158
  ## §4. Anotar o alvo na auditoria
159
159
 
@@ -462,10 +462,14 @@ precisam estar importadas (via `urls.py`) quando o middleware é construído.
462
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
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
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 |
465
+ | 401 (não mais 500) com o Argos fora | 1.3: falha de JWKS/`/apps/token` vira token não validado (`public` não valida, segue anônimo) | é o esperado; monitore a taxa de 401 e a saúde do Argos |
466
+ | Rota `public` perdeu o usuário depois de atualizar para a 1.7 | desde a 1.7.0 `public` não lê credencial: `request.state.user`/`g.orfeu_user`/`request.orfeu_user` são `None` | troque o nível para `optional` (credencial inválida passa a dar 401) |
467
+ | Token vencido há poucos segundos ainda passa | 1.6: `clock_tolerance_s` (padrão 30 s) | esperado; `clock_tolerance_s=0` para a conferência exata |
468
+ | `/docs` com `<id> · <nível>` no lugar do resumo da rota | 1.6: OpenAPI anotado pelo `Orfeu(app, ...)` | é o esperado; `document_operations=False` desliga (o `operationId` não muda) |
469
+ | Rotas de `include_router` sem anotação no `/docs` | FastAPI ≥ 0.137 com `orfeu` 1.6/1.7.0 | `orfeu` 1.7.1 |
466
470
  | 401 numa operação sensível com o Argos fora | `check_revocation` é fail-closed | só nas operações sensíveis, não `True` |
467
471
  | IP da auditoria mudou | 1.3 não usa mais o primeiro `x-forwarded-for` | proxies fora de loopback/redes privadas → `trusted_proxies` |
468
- | `AttributeError: 'State' object has no attribute 'user'` | leitura direta de `request.state.user` em `public`/`optional` anônimo | `getattr(request.state, "user", None)` |
472
+ | `AttributeError: 'State' object has no attribute 'user'` | `orfeu` < 1.7: leitura direta de `request.state.user` em `public`/`optional` anônimo | atualize para a 1.7.1 (o atributo passa a existir, `None`) ou `getattr(request.state, "user", None)` |
469
473
  | `request.state.user` é `None` numa rota `private` | chamada com `x-api-token` (backend) | leia `request.state.api_token` nesse caso |
470
474
  | 401 mesmo mandando `Authorization: Bearer ...` | o orfeu não lê `Authorization` | mande em `x-access-token` (JWT) / `x-app-token` / `x-api-token` |
471
475
  | 401 em `optional` | credencial presente e inválida nunca vira anônima | não mande credencial vencida; trate o 401 no cliente |
@@ -1,8 +1,10 @@
1
1
  # orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
2
2
 
3
- > Escrito para a **1.4.0** (anda junto com `@orfeu/node` e `@orfeu/angular`; versão instalada:
3
+ > Escrito para a **1.7.1** (anda junto com `@orfeu/node`, `@orfeu/angular` e `@orfeu/react`; versão instalada:
4
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
+ > auditoria de segurança (§5); a 1.6.0, a tolerância de relógio, o OpenAPI anotado e o `httpx.AsyncClient`
6
+ > reaproveitado; a 1.7.0 fez `public` deixar de validar credencial (§5); a 1.7.1 corrigiu o OpenAPI com
7
+ > `include_router` no FastAPI ≥ 0.137. Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
6
8
  > em relação ao Node e ao Angular está em [diferencas.md](diferencas.md). Estrutura do serviço FastAPI em si
7
9
  > (camadas, banco, configuração): skill `fastapi`. Flask, Django e Strawberry ainda não têm skill de
8
10
  > padrões — aqui só a integração com o Orfeu.
@@ -37,7 +39,7 @@ pip install "orfeu[flask]" # ou [django], [strawberry]; sem extra = s
37
39
  - **Python ≥ 3.11** (`requires-python = ">=3.11"`; usa `enum.StrEnum`). Testado em 3.11–3.14.
38
40
  - Dependências fixas: `httpx>=0.27`, `PyJWT[crypto]>=2.8`. O adapter FastAPI foi testado com FastAPI
39
41
  0.111.0, 0.116.1, 0.137.0 e 0.142.2.
40
- - No `requirements.txt` do app, versão exata: `orfeu[fastapi]==1.4.0` (mesma versão das libs `@orfeu/*` do app).
42
+ - No `requirements.txt` do app, versão exata: `orfeu[fastapi]==1.7.1` (mesma versão das libs `@orfeu/*` do app).
41
43
 
42
44
  ## 2. Configuração
43
45
 
@@ -52,7 +54,7 @@ passado vence a variável, e `allowed_clients=[]` **desliga** (passe `None` quan
52
54
  | `realm_id` | sim | Realm do backend (nome ou UUID). Tokens de outro realm são recusados. |
53
55
  | `app_id` | sim | UUID do backend cadastrado no Argos (é o `agent_id` dos logs). |
54
56
  | `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
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. |
57
+ | `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. Desde a 1.6 deixa um aviso no log (logger `orfeu`). |
56
58
  | `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
57
59
  | `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
60
  | `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`. |
@@ -60,11 +62,13 @@ passado vence a variável, e `allowed_clients=[]` **desliga** (passe `None` quan
60
62
  | `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
63
  | `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
64
  | `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`. |
65
+ | `clock_tolerance_s` | não, só por nome (1.6+) | `30.0` (`DEFAULT_CLOCK_TOLERANCE_S`): tolerância de relógio (`leeway` do PyJWT) no `exp`/`nbf`/`iat` do `validate_token` e do `validate_service_token`. **Afrouxa**: token vencido há menos de 30 s ainda vale; `0` = conferência exata. Em `OrfeuClient` e nos adapters FastAPI, Flask e Strawberry; Django: `ORFEU_CLOCK_TOLERANCE`. |
66
+ | `document_operations` | não, só por nome (1.6+, só FastAPI) | `True` (padrão): o OpenAPI (`/docs`, `/openapi.json`) mostra em cada rota o `@operation` — `summary` `<id> · <nível>`, uma linha na descrição com identificador, método e nível, e a extensão `x-orfeu-operation` (`{id, method, level}`; rota de serviço: `{service: true}`). O `operationId` não muda. `False` desliga. |
63
67
 
64
68
  Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
65
69
  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).
70
+ `ORFEU_ACCEPT_ANY_REALM`, `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES`,
71
+ `ORFEU_CHECK_REVOCATION` e `ORFEU_CLOCK_TOLERANCE` (1.6+, segundos) (opcionais).
68
72
 
69
73
  Nos outros frameworks o app escolhe os nomes das variáveis. Convenção sugerida (a mesma do Django):
70
74
  `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET`, `ORFEU_TLS_VERIFY`.
@@ -140,14 +144,24 @@ do JWKS (por `kid` desconhecido) no máximo uma vez a cada 30 s por realm: chave
140
144
  30 s para ser aceita.
141
145
 
142
146
  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
147
+ conferem; falta `exp`, `sub` ou `iss`, ou venceu (com a tolerância de `clock_tolerance_s`, 1.6+); o `iss` não é o
148
+ do realm do token (com `issuer_url`, exatamente
144
149
  `{issuer_url}/realms/{realm_id}`; sem, uma URL http(s) terminada em `/realms/{realm_id}` — o `authorizer_url`
145
150
  costuma ser endereço interno e não serve); o realm não é o do app; é token **de aplicação** (`type: "app"`,
146
151
  client_credentials); ou `allowed_clients` está ligado e o `client_id`/`azp` não está na lista.
147
152
 
148
153
  **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.
154
+ como não validado — `private`/`protected`/`optional` respondem 401 (`public` não valida nada). Alerta que olhava
155
+ 500 não pega mais isso: monitore a taxa de 401 e a saúde do Argos.
156
+
157
+ **`public` não valida nada (1.7+)** (FastAPI HTTP e WebSocket, Django, Flask e Strawberry): a guarda libera sem ler
158
+ `x-access-token`/`x-app-token`/`x-api-token` e sem chamar o Argos, e o handler roda sem identidade
159
+ (`request.state.user`, `request.orfeu_user` e `g.orfeu_user` = `None`; sem `*_api_token`). Log e auditoria saem com
160
+ `actor_type: public`. **Rota pública que lê a identidade troca para `optional`**: sem credencial roda anônimo; com
161
+ credencial, ela precisa ser válida (inválida ou vencida dá 401) e o usuário precisa de ao menos um grupo (depende
162
+ do catálogo de operações). O `orfeu` Python **não tem** o `identify` do `@orfeu/node`. No Strawberry o contexto é
163
+ do documento: `info.context["orfeu_user"]` pode ter o usuário validado por outro campo, mas o campo `public` não o
164
+ valida.
151
165
 
152
166
  **`allowed_clients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
153
167
  login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
@@ -163,9 +177,10 @@ O que o handler FastAPI recebe (`request.state` / `websocket.state`):
163
177
  |---|---|---|
164
178
  | usuário (`x-access-token`/`x-app-token`) válido | `TokenClaims` | ausente |
165
179
  | `x-api-token` válido | `None` | `ApiTokenClaims(token_id, app_id)` |
166
- | anônimo (`public`/`optional` sem credencial válida) | **ausente** (`AttributeError`) | ausente |
180
+ | `public` (1.7+: sempre, com ou sem credencial) ou `optional` sem credencial | `None` (até a 1.6, **ausente**: `AttributeError`) | ausente |
167
181
 
168
- Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`.
182
+ Desde a 1.7 `request.state.user` sempre existe; `getattr(request.state, "user", None)` continua funcionando e é o
183
+ jeito seguro em código que ainda roda com versões anteriores.
169
184
 
170
185
  `TokenClaims` é um **objeto** (dataclass), não um `dict`: `user.sub`, `user.realm_id`, `user.groups`, `user.exp` e
171
186
  `user.raw` (o JWT decodificado inteiro). Nome/e-mail do usuário estão em `raw`:
@@ -206,6 +221,11 @@ encontrado.")`, `Conflict(...)`, `BadRequest(...)` etc. na regra de negócio —
206
221
  exceção → `500 "Erro inesperado no serviço."` (detalhe só no log `orfeu.envelope`). Sucesso: `ok(data,
207
222
  message, status)`; `response_model=Envelope[T]` documenta no OpenAPI.
208
223
 
224
+ **OpenAPI** (1.6+): o `Orfeu(app, ...)` anota o schema com o `@operation` de cada rota (`document_operations=True`,
225
+ padrão): no `/docs`, cada linha mostra `<identificador> · <nível>`. Para um app montado sem o adapter, ou para
226
+ anotar um schema próprio, `install_openapi_operations(app)` e `annotate_openapi_operations(app, schema)` (em
227
+ `orfeu.adapters.fastapi`). Rotas de `include_router` no FastAPI ≥ 0.137 só aparecem anotadas a partir da 1.7.1.
228
+
209
229
  O status final da resposta (inclusive 4xx/5xx gerados pelo envelope) é o que vai para a auditoria como
210
230
  `outcome`/`status`, com a `message` do corpo.
211
231
 
@@ -287,7 +307,8 @@ Teste que assina JWT de verdade (sem mock do `validate_token`): desde a 1.3 o to
287
307
  intermediário sem `functools.wraps` apaga os atributos e a rota fica **aberta, sem aviso**.
288
308
  3. **Passe `method=` explícito.** A inferência pelo nome muda se a função for renomeada.
289
309
  4. **Nunca leia `Authorization`/`Bearer`** nem valide token na mão: use `request.state.user`/`api_token`.
290
- 5. **Em `public`/`optional`, `getattr(request.state, "user", None)`** — o atributo não existe no anônimo.
310
+ 5. **Em `optional`, `getattr(request.state, "user", None)`** — `None` no anônimo (até a 1.6 o atributo nem existia).
311
+ Em `public` (1.7+) **não há usuário nunca**: para ler a identidade, use `optional`.
291
312
  6. **Erros de negócio com as classes do envelope** (`NotFound`, `Conflict`...), não `JSONResponse` montado à mão.
292
313
  7. **Chamada a outro serviço dentro de um handler usa `orfeu_headers(request)`** (ou `credential=False` +
293
314
  o `x-api-token` do serviço); nunca repasse o `x-api-token` recebido.
@@ -0,0 +1,133 @@
1
+ # `@orfeu/react` — login e sessão no front React
2
+
3
+ Porte do `@orfeu/angular` para **React 19 + React Router v7 (modo data)**, versão **1.7.1**. Mesmo protocolo (OIDC
4
+ Authorization Code + PKCE contra o Argos), mesmas chaves de armazenamento, mensagens entre abas, códigos de recusa e
5
+ tempos — um teste de paridade no pacote compara as duas libs. Mesmo princípio: **a sessão nunca cai sozinha**; ela só
6
+ termina por `logout()` (ou pelo logout de outra aba). Token só em memória, refresh pelo cookie do Argos.
7
+
8
+ Shell pronto sobre ele: `@trismegisto/react/spine` (skill `trismegisto`, no `references/react.md` §5 dela). Angular: `angular.md`.
9
+
10
+ ## 1. Instalação
11
+
12
+ ```bash
13
+ npm install @orfeu/react@^1.7.1 react-router
14
+ ```
15
+
16
+ - **Pela faixa** (`^1.7.1`), como as outras libs do Orfeu: o npm também tem um `0.0.0-stage` provisório, que nunca
17
+ deve entrar no app. Confira no `package.json` que ficou `"@orfeu/react": "^1.7.1"`.
18
+ - Peers: `react >=19`, `react-dom >=19`, `react-router >=7`. Só ESM.
19
+ - **Uma cópia só** no app (`npm ls @orfeu/react`): o `@trismegisto/react/spine` e o app precisam do mesmo `AuthClient`.
20
+
21
+ ## 2. Pontos de import
22
+
23
+ | Import | Conteúdo |
24
+ |---|---|
25
+ | `@orfeu/react` | `createAuthClient`, `AuthClient`, `OrfeuProvider`, `useAuthClient`, hooks (`useAuth`, `useAuthSelector`, `useAuthEvent`, `useView`, `useRealmApps`, `useAuthFetch`), `createAuthFetch`, `OrfeuAuthError`, `OrfeuHttpError`, `classifyRefreshError`, `ViewStore`, `emptyView`; tipos `AuthConfig`, `AuthOptions`, `AuthState`, `Badge`, `ConnectionState`, `UserProfile`, `Route`, `View`, `AppDef`… |
26
+ | `@orfeu/react/router` | `authMiddleware`, `requireAuth`, `callbackLoader`, `RequireAuth`, `isAuthOffline`, tipo `AuthRouteErrorData` |
27
+ | `@orfeu/react/util` | `decodeJwt`, `generatePkcePair`, `generateCodeVerifier`, `generateCodeChallenge`, `base64UrlEncode` (`isJwtExpired` está depreciado) |
28
+
29
+ ## 3. Bootstrap
30
+
31
+ ```tsx
32
+ // auth.ts — um client por app, criado fora do React
33
+ import { createAuthClient } from '@orfeu/react';
34
+ export const auth = createAuthClient({
35
+ authority: '', // '' = mesma origem da UI (atrás do proxy)
36
+ realmId: 'meu-realm',
37
+ clientId: 'meu-client-id',
38
+ redirectUrl: `${location.origin}/callback`, // absoluta
39
+ scope: 'openid profile',
40
+ });
41
+
42
+ // main.tsx
43
+ import { createBrowserRouter, RouterProvider } from 'react-router';
44
+ import { OrfeuProvider } from '@orfeu/react';
45
+ import { authMiddleware, callbackLoader } from '@orfeu/react/router';
46
+ import { auth } from './auth';
47
+
48
+ const router = createBrowserRouter([
49
+ { path: '/callback', loader: callbackLoader(auth), errorElement: <ErroDeLogin /> },
50
+ { path: '/logoff', element: <Saiu /> },
51
+ {
52
+ path: '/',
53
+ middleware: [authMiddleware(auth)], // ou loader: requireAuth(auth) em CADA rota com dados
54
+ element: <Layout />,
55
+ errorElement: <ErroRaiz />, // isAuthOffline(useRouteError()) → "sem conexão"
56
+ children: [{ path: 'clientes/:id', element: <Cliente />, loader: clienteLoader }],
57
+ },
58
+ ], { future: { v8_middleware: true } });
59
+ auth.connectRouter(router); // logo depois do createBrowserRouter
60
+
61
+ createRoot(document.getElementById('root')!).render(
62
+ <OrfeuProvider client={auth}><RouterProvider router={router} /></OrfeuProvider>,
63
+ );
64
+ ```
65
+
66
+ - `createAuthClient(config, options?)`: `AuthOptions` tem `eagerInit` (padrão `true`), `autoReauthorize` (padrão
67
+ `true`), `initInIframe`, `expiryLog` (padrão: fora de produção), `fetch`, `navigate`, `currentUrl`, `basename`
68
+ (o `connectRouter` preenche), `isServer`.
69
+ - Com o `@trismegisto/react/spine`, **não** monte essas rotas: `createSpineRoutes({ auth, components })` já cria
70
+ `/login`, `/callback` (com o `callbackLoader`), `/logoff`, `/blocked` e o layout protegido.
71
+
72
+ ## 4. Guarda de rota (`@orfeu/react/router`)
73
+
74
+ | Peça | Quando |
75
+ |---|---|
76
+ | `authMiddleware(client)` | recomendado: decide antes de qualquer loader; exige `future.v8_middleware` |
77
+ | `requireAuth(client, loader?)` | sem a flag; precisa estar em **cada** rota com dados (os loaders de uma navegação rodam em paralelo) |
78
+ | `callbackLoader(client)` | a rota do `redirectUrl`; troca o `code` uma vez só (seguro com StrictMode/revalidação) e sai com `replace` |
79
+ | `<RequireAuth fallback?>` | modo declarativo (sem data router) |
80
+ | `isAuthOffline(error)` | o erro 503 que a guarda lança quando não há sessão e o Argos está inalcançável |
81
+
82
+ Sem sessão: `redirectDocument` para o `/authorize` do Argos, guardando a URL pedida (volta para ela depois do
83
+ callback). Com sessão, mesmo com o token vencido: libera e dispara a renovação. Com o Argos fora e sem sessão: 503
84
+ no `errorElement` (`isAuthOffline`), e a lib navega para a URL pedida quando a sessão volta. Diferente do
85
+ `PrivateGuard` do Angular, um loader não "cancela" a navegação: trate o 503 no `errorElement`.
86
+
87
+ ## 5. Estado para a UI (hooks)
88
+
89
+ ```tsx
90
+ const { authenticated, profile, badge, badges, connectionState, reauthorizationRequired,
91
+ logout, authorize, switchBadge, getValidToken } = useAuth();
92
+ const conectado = useAuthSelector((s) => s.connectionState === 'online'); // valor primitivo ou referência do snapshot
93
+ useAuthEvent('logoutFailed', () => toast.error('Não foi possível sair agora.'));
94
+ const { view } = useView(); // /view do Argos: routes, apps
95
+ const apps = useRealmApps();
96
+ ```
97
+
98
+ - `connectionState`: `online`, `reconnecting`, `offline`, `reauthorizing`. Banner de conexão: `offline`/`reconnecting`
99
+ → aviso; `reauthorizationRequired` → botão "Entrar novamente" que chama `authorize(urlAtual)` (sem logout).
100
+ - `logout()` devolve `Promise<boolean>`: `false` = o Argos falhou, a sessão continua e `logoutFailed` foi emitido;
101
+ avise a pessoa (o `@trismegisto/react/spine` já faz isso).
102
+ - As claims (`profile`, `badge`) servem para **exibir**, nunca para decidir permissão: quem decide é o backend.
103
+
104
+ ## 6. Chamadas às APIs do app (`createAuthFetch` / `useAuthFetch`)
105
+
106
+ ```tsx
107
+ const apiFetch = useAuthFetch({ attachTo: ['/api/'] }); // ou createAuthFetch(auth, {...}) fora do React
108
+ const resp = await apiFetch('/api/pedidos', { headers: { 'x-access-token': auth.getToken() ?? '' } });
109
+ ```
110
+
111
+ - Faz o que o `OrfeuTokenInterceptor` do Angular faz: requisição que leva o token da sessão (em qualquer header) e
112
+ sairia com ele vencido espera a renovação e troca o token.
113
+ - `attachTo` anexa `Authorization: Bearer` **só** às URLs listadas (padrão: nenhuma). Os backends do Orfeu leem o
114
+ token em **`x-access-token`** (nunca em `Authorization`): mande-o nesse header, como no Angular.
115
+ - `retryOnUnauthorized` (padrão `true`) repete um 401 **uma vez** e só se o token mudou no meio; nunca desloga.
116
+
117
+ ## 7. Testes no app
118
+
119
+ Crie o client com `fetch` e `navigate` falsos (`createAuthClient(cfg, { fetch: fakeFetch, navigate: vi.fn(),
120
+ eagerInit: false })`) e use o `createMemoryRouter` do React Router com as mesmas rotas. O shell do Trismegisto tem
121
+ um dublê para os specs dele (não exportado ao app).
122
+
123
+ ## 8. Armadilhas
124
+
125
+ 1. **Versão fora da faixa** (`0.0.0-stage`, o provisório do npm): use `^1.7.1`.
126
+ 2. **`connectRouter` esquecido**: o login volta para a URL errada e o `basename` não é respeitado.
127
+ 3. **`requireAuth` só na rota pai**: os loaders filhos rodam em paralelo e buscam dados sem sessão; use o middleware
128
+ ou ponha em cada rota com dados.
129
+ 4. **Token em `localStorage`/`sessionStorage`** ou em estado global persistido: nunca. Leia com `getToken()` /
130
+ `getValidToken()` na hora da chamada.
131
+ 5. **`logout()` por erro de rede, 401 ou token vencido**: não. A lib já está renovando; a sessão só cai por ação da
132
+ pessoa.
133
+ 6. **Duas cópias** (`npm ls @orfeu/react`): o shell e o app ficariam com clients diferentes (sessão dupla).