@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.
- package/README.md +5 -4
- package/agents/revisor-orfeu.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
- package/skills/angular/SKILL.md +2 -2
- package/skills/angular/references/dados.md +3 -3
- package/skills/angular/references/estrutura.md +6 -5
- package/skills/angular/references/features.md +5 -5
- package/skills/angular/references/testes-build.md +1 -1
- package/skills/auto-servico/SKILL.md +18 -14
- package/skills/express/references/dados.md +4 -1
- package/skills/express/references/estrutura.md +2 -1
- package/skills/fastapi/references/banco.md +6 -2
- package/skills/fastapi/references/estrutura.md +1 -1
- package/skills/hefesto/SKILL.md +6 -2
- package/skills/orfeu/SKILL.md +43 -13
- package/skills/orfeu/references/angular-api.md +39 -13
- package/skills/orfeu/references/angular-armadilhas.md +18 -1
- package/skills/orfeu/references/angular-recipes.md +25 -12
- package/skills/orfeu/references/angular.md +37 -15
- package/skills/orfeu/references/diferencas.md +17 -8
- package/skills/orfeu/references/node-api.md +41 -9
- package/skills/orfeu/references/node-armadilhas.md +16 -2
- package/skills/orfeu/references/node-recipes.md +13 -4
- package/skills/orfeu/references/node.md +31 -12
- package/skills/orfeu/references/python-api.md +41 -16
- package/skills/orfeu/references/python-recipes.md +13 -9
- package/skills/orfeu/references/python.md +33 -12
- package/skills/orfeu/references/react.md +133 -0
- package/skills/trismegisto/SKILL.md +42 -29
- package/skills/trismegisto/references/angular-api.md +608 -6
- package/skills/trismegisto/references/angular-exports.md +479 -791
- package/skills/trismegisto/references/angular-recipes.md +13 -7
- package/skills/trismegisto/references/angular.md +32 -9
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +90 -65
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5565 -1973
- package/skills/trismegisto/references/spine-recipes.md +113 -26
- package/skills/trismegisto/references/spine.md +95 -33
- 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
|
-
> `orfeuUser` forjado nas subscriptions do Apollo; a 1.3.0 trouxe as correções da auditoria de segurança
|
|
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.
|
|
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
|
|
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
|
|
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:
|
|
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.
|
|
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
|
|
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
|
|
46
|
-
aceitam os mesmos.
|
|
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);
|
|
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`), `
|
|
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`
|
|
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.
|
|
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
|
|
141
|
-
|
|
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
|
|
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
|
|
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 (
|
|
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.
|
|
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)
|
|
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.
|
|
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
|
|
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
|
|
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 — `
|
|
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
|
-
|
|
|
180
|
+
| `public` (1.7+: sempre, com ou sem credencial) ou `optional` sem credencial | `None` (até a 1.6, **ausente**: `AttributeError`) | ausente |
|
|
167
181
|
|
|
168
|
-
|
|
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 `
|
|
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).
|