@acropole/skills 0.0.0-stage → 1.1.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 +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# @orfeu/node — guia de uso (Express, Fastify, NestJS, Apollo)
|
|
2
|
+
|
|
3
|
+
> Escrito para a **1.0.1** (peça `^1.0.1`: a 1.0.0 aceitava `orfeuUser` forjado nas subscriptions do
|
|
4
|
+
> Apollo). Se a versão instalada for outra, confira os nomes de [node-api.md](node-api.md)
|
|
5
|
+
> contra os `.d.ts` de `node_modules/@orfeu/node/dist/`. Conceitos comuns às três implementações estão no
|
|
6
|
+
> `SKILL.md` da skill; o que muda em relação ao Python e ao Angular está em [diferencas.md](diferencas.md).
|
|
7
|
+
> Estrutura do servidor em si: skills `express` (Express) e `apollo` (GraphQL). Fastify e
|
|
8
|
+
> NestJS ainda não têm skill de padrões — aqui só a integração com o Orfeu.
|
|
9
|
+
|
|
10
|
+
O `@orfeu/node` é o cliente Node do **Argos** (autorizador OIDC + RBAC). Num serviço ele:
|
|
11
|
+
1. autentica o próprio serviço no Argos (`appId` + `secret`);
|
|
12
|
+
2. **registra o catálogo de operações** do serviço (cada rota/resolver protegido é uma operação com
|
|
13
|
+
identificador, método e nível) e busca no Argos quais grupos podem executar cada uma;
|
|
14
|
+
3. em cada chamada, valida a credencial de quem chama (JWT pelo JWKS do realm, ou token opaco por
|
|
15
|
+
introspecção) e decide **401/403/permitido** — a mesma regra em todos os adapters;
|
|
16
|
+
4. grava **um evento de auditoria por chamada protegida** (em lote, fora do caminho da requisição) e uma linha
|
|
17
|
+
de log JSON;
|
|
18
|
+
5. propaga o contexto (credencial, `traceparent`, `x-route-id`, `x-client-id`) quando o serviço chama outro.
|
|
19
|
+
|
|
20
|
+
**Não escreva nada disso à mão.** Não existe telemetria embutida: a correlação entre serviços é só pelo
|
|
21
|
+
header W3C `traceparent`.
|
|
22
|
+
|
|
23
|
+
Leia sob demanda:
|
|
24
|
+
- [node-api.md](node-api.md) — todos os exports dos 5 pontos de import, com assinatura e comportamento.
|
|
25
|
+
- [node-recipes.md](node-recipes.md) — receitas: Express, Fastify, NestJS, Apollo (HTTP + WebSocket), BFF
|
|
26
|
+
chamando backend, anotação de auditoria, operação fora de um adapter, logger próprio, subida resiliente,
|
|
27
|
+
recarregar permissões, encerramento, testes com um Argos simulado.
|
|
28
|
+
- [node-armadilhas.md](node-armadilhas.md) — erros comuns (403 para todo mundo, operação sem nível, eventos perdidos…).
|
|
29
|
+
|
|
30
|
+
## 1. Instalação
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm install @orfeu/node@^1.0.1
|
|
34
|
+
npm install express # se usar @orfeu/node/express
|
|
35
|
+
npm install fastify # @orfeu/node/fastify
|
|
36
|
+
npm install @nestjs/common @nestjs/core reflect-metadata rxjs # @orfeu/node/nest
|
|
37
|
+
npm install @apollo/server graphql # @orfeu/node/apollo
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- Node **20.18.1+** (dependência `undici` 7). ESM e CommonJS. Dependências próprias: `jose`, `undici`,
|
|
41
|
+
`fastify-plugin`. Os frameworks são peers **opcionais**: instale só o que usa.
|
|
42
|
+
- Pontos de import: `@orfeu/node` (núcleo), `@orfeu/node/express`, `@orfeu/node/fastify`,
|
|
43
|
+
`@orfeu/node/nest`, `@orfeu/node/apollo`. O registro global de operações é único entre eles (inclusive em CJS).
|
|
44
|
+
|
|
45
|
+
## 2. Configuração
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { OrfeuClient } from '@orfeu/node';
|
|
49
|
+
|
|
50
|
+
const client = new OrfeuClient({
|
|
51
|
+
authorizerUrl: process.env.AUTHORIZER_URL!, // URL base do Argos COM o prefixo da API (…/api)
|
|
52
|
+
realmId: process.env.REALM_ID!, // realm "de casa" do serviço (nome ou UUID)
|
|
53
|
+
appId: process.env.APP_ID!, // UUID do serviço cadastrado no Argos
|
|
54
|
+
secret: process.env.APP_SECRET!, // segredo do serviço: variável de ambiente, nunca no código
|
|
55
|
+
// acceptAnyRealm: false, tlsVerify: true, audit: true, logger: jsonLineLogger (padrões)
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
| Opção | Padrão | Efeito |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `acceptAnyRealm` | `false` | `true` aceita tokens de qualquer realm (busca o JWKS do realm da claim `realm_id`). |
|
|
62
|
+
| `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo). |
|
|
63
|
+
| `audit` | `true` | `false` desliga a auditoria; objeto `{ flushIntervalMs, maxBuffer, batchSize }` ajusta o lote. |
|
|
64
|
+
| `logger` | `jsonLineLogger` | função `(record) => void` para outro destino; `false` desliga o log de operação. |
|
|
65
|
+
|
|
66
|
+
## 3. Ordem de subida (obrigatória)
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
new OrfeuClient(opts)
|
|
70
|
+
→ declarar as rotas/resolvers protegidos (guard(), @Operation, operation()+secureResolvers) — cada declaração registra a operação
|
|
71
|
+
→ copiar o registro para o client: for (const op of getRegistry()) client.registerOperation(op)
|
|
72
|
+
→ await client.startup() // POST /apps/token → POST /apps/operations/sync → GET /apps/operations (+ JWKS sob demanda)
|
|
73
|
+
→ começar a ouvir (listen)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
- `startup()` lança `OrfeuConfigError` se nenhuma operação foi registrada, `OrfeuAuthError` se `appId`/`secret`
|
|
77
|
+
forem recusados, `OrfeuSyncError` se o sync falhar, `OrfeuError` se a busca das operações falhar.
|
|
78
|
+
- `OrfeuClient.create(opts)` faz "copiar o registro + startup" de uma vez (use depois de declarar as rotas).
|
|
79
|
+
- `OrfeuModule.forRootAsync(opts)` (Nest) faz tudo sozinho.
|
|
80
|
+
- No Apollo, `secureResolvers(client, …)` já registra no client: chame-o **antes** do `startup()`.
|
|
81
|
+
- As permissões (`allowed_groups`) são lidas **só** no `startup()` (ou em `fetchOperations()`): mudar grupos de
|
|
82
|
+
uma operação no Argos não vale para um serviço já no ar até recarregar (`node-recipes.md` §10).
|
|
83
|
+
|
|
84
|
+
## 4. Operações: identificador, nível e método
|
|
85
|
+
|
|
86
|
+
Uma operação = `identifier` + `method` + `level`. Use **sempre** as constantes:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { Level, Method } from '@orfeu/node';
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
O significado de cada `Level` (`PUBLIC`, `OPTIONAL`, `PRIVATE`, `PROTECTED`) está no `SKILL.md` §3.
|
|
93
|
+
|
|
94
|
+
`Method.READ`, `Method.WRITE`, `Method.DELETE`, `Method.STREAM`. Sem método explícito ele é inferido pelo
|
|
95
|
+
último segmento do id (`tasks:list` → `read`; `tasks:delete` → `delete`; `…subscribe`/`watch`/`stream`/`listen`
|
|
96
|
+
→ `stream`; o resto → `write`). No Apollo: Query → `read`, Mutation → `delete` se o campo começa com
|
|
97
|
+
`delete`/`remove`/`destroy`, senão `write`, Subscription → `stream`.
|
|
98
|
+
|
|
99
|
+
Convenção de id: `recurso:ação` (`clientes:list`, `clientes:create`). O mesmo id com métodos diferentes são
|
|
100
|
+
operações diferentes. Valor de nível/método fora do conjunto → erro de compilação, e `OrfeuConfigError` na
|
|
101
|
+
subida em JS. Id vazio é recusado; id com mais de 200 caracteres é aceito com aviso (a auditoria corta).
|
|
102
|
+
|
|
103
|
+
## 5. Regra de autorização (igual em todos os adapters)
|
|
104
|
+
|
|
105
|
+
Headers de credencial (`x-access-token` → `x-app-token` → `x-api-token`, a primeira presente vale) e a tabela
|
|
106
|
+
401/403 estão no `SKILL.md` §4 — a regra é a mesma do Python. Específico do Node: introspecção com cache de
|
|
107
|
+
60 s (token inativo: 10 s); `acceptAnyRealm: true` aceita JWT de outros realms.
|
|
108
|
+
|
|
109
|
+
Respostas: Express/Fastify `401 { error: 'unauthorized', detail }` / `403 { error: 'forbidden', detail:
|
|
110
|
+
'Insufficient permissions.' }`; Nest `UnauthorizedException`/`ForbiddenException`; Apollo `GraphQLError` com
|
|
111
|
+
`extensions.code` 401/403 (ou o valor de `onForbidden` no 403). Textos sempre genéricos (`Access token
|
|
112
|
+
required.`, `Invalid token.`, `Invalid, expired, revoked or unauthorized api token.`); o motivo detalhado só vai
|
|
113
|
+
para o log.
|
|
114
|
+
|
|
115
|
+
Quem passou fica em `req.orfeuUser` (`TokenClaims`: `sub`, `realmId`, `groups`, `exp`, `raw`) ou
|
|
116
|
+
`req.orfeuApiToken` (`{ tokenId, appId }`) — no Apollo, `ctx.orfeuUser`/`ctx.orfeuApiToken`; no Nest,
|
|
117
|
+
`@OrfeuUser()`.
|
|
118
|
+
|
|
119
|
+
## 6. Adapters (resumo — código em [node-recipes.md](node-recipes.md))
|
|
120
|
+
|
|
121
|
+
| Framework | Captura (global) | Protege | Usuário |
|
|
122
|
+
|---|---|---|---|
|
|
123
|
+
| Express | `app.use(middleware)` de `orfeu(client)` | `guard(id, level, method?)` por rota | `req.orfeuUser` |
|
|
124
|
+
| Fastify | `await fastify.register(orfeuFastifyPlugin, { client })` | `preHandler: fastify.orfeuGuard(id, level, method?)` | `request.orfeuUser` |
|
|
125
|
+
| NestJS | `OrfeuModule.forRootAsync(opts)` | `@UseGuards(OrfeuGuard)` + `@Operation(id, level, method?)` no método | `@OrfeuUser()` |
|
|
126
|
+
| Apollo | `plugins: [orfeuPlugin(client)]`; WS: `context: orfeuWsContext(client)` | `operation(level, resolver, opts?)` em **todo** campo raiz + `secureResolvers` + `assertSchemaSecured` | `ctx.orfeuUser` |
|
|
127
|
+
|
|
128
|
+
A captura só lê headers; **quem valida é o guard**. Rota sem guard (ou método Nest sem `@Operation`) não tem
|
|
129
|
+
usuário e **não é protegida nem auditada**.
|
|
130
|
+
|
|
131
|
+
## 7. Trace e chamadas a outros serviços
|
|
132
|
+
|
|
133
|
+
O modelo (`entry`, `trace_id`/`span_id`, um evento por serviço) está no `SKILL.md` §5. O IP do cliente só é
|
|
134
|
+
gravado em eventos `entry: true` (`x-forwarded-for`, depois `x-real-ip`, depois o socket).
|
|
135
|
+
|
|
136
|
+
Para chamar outro serviço **seu** em nome da requisição atual:
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
import { orfeuHeaders } from '@orfeu/node';
|
|
140
|
+
await fetch(`${BACKEND}/clientes`, { headers: { ...orfeuHeaders(req), 'content-type': 'application/json' } });
|
|
141
|
+
// Apollo: orfeuHeaders(ctx)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`orfeuHeaders` devolve: a credencial recebida (`x-access-token` ou `x-app-token` — **nunca** `x-api-token`),
|
|
145
|
+
`traceparent` deste passo (`00-<trace_id>-<span_id deste serviço>-<flags>`), `x-route-id` e `x-client-id`.
|
|
146
|
+
`orfeuHeaders(req, { credential: false })` omite a credencial (o backend verá a chamada como anônima — use
|
|
147
|
+
quando o serviço chama com credencial própria, ex. `x-api-token` do serviço).
|
|
148
|
+
**Nunca** use `orfeuHeaders` em chamadas para terceiros: repassaria o token do usuário.
|
|
149
|
+
|
|
150
|
+
`x-route-id` (id da tela, vindo do front) e `x-client-id` (id do app front) são etiquetas de correlação: não
|
|
151
|
+
são verificados nem usados para permissão; na auditoria só entram se forem GUIDs.
|
|
152
|
+
|
|
153
|
+
## 8. Auditoria e log
|
|
154
|
+
|
|
155
|
+
- Cada chamada protegida vira um evento enviado em lote para `POST /realms/{realm}/audit/events` do Argos: a
|
|
156
|
+
cada 1 s ou 200 eventos (≤ 90 KB), buffer de 10 mil (cheio → descarta primeiro leituras bem-sucedidas),
|
|
157
|
+
backoff até 60 s em 5xx/rede, pausa de 10 min se o Argos não tiver o endpoint (404). A requisição nunca
|
|
158
|
+
espera a auditoria; falha de auditoria nunca derruba a requisição.
|
|
159
|
+
- `outcome`: `denied` (401/403), `failure` (status ≥ 400 ou exceção; no Apollo, também resultado
|
|
160
|
+
`{ status >= 400 }`), `success`.
|
|
161
|
+
- **Alvo**: dentro do handler/resolver, `annotateOperation({ target_type, target_id, details })` acrescenta o
|
|
162
|
+
que foi afetado ao evento desta operação (`details` ≤ 4 KB, sem segredos). Fora de uma operação protegida,
|
|
163
|
+
devolve `false` e não faz nada.
|
|
164
|
+
- **Encerramento**: o SDK não registra handler de sinal. No SIGTERM do app, `await client.flushAudit()` antes de
|
|
165
|
+
sair (`node-recipes.md` §11). `client.pendingAudit` mostra quantos eventos esperam envio.
|
|
166
|
+
- Log de operação: uma linha JSON por chamada protegida no stdout (`logger: 'orfeu.operation'`, `operation`,
|
|
167
|
+
`operation_id`, `actor_type`, `permission_result`, `duration_ms`, `trace_id`, `span_id`…). Troque o destino
|
|
168
|
+
com `logger: (record) => …` ou desligue com `logger: false`.
|
|
169
|
+
|
|
170
|
+
## 9. Erros que o SDK lança
|
|
171
|
+
|
|
172
|
+
| Classe (`@orfeu/node`) | Quando |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `OrfeuConfigError` | nível/método inválido, id vazio, `startup()` sem operações, `operation()` reaproveitando a mesma função, campo GraphQL sem `operation()`, schema com campo não protegido |
|
|
175
|
+
| `OrfeuAuthError` | `authenticate()` recusado (appId/secret errados) ou sem `access_token`; `syncOperations`/`fetchOperations` sem token do serviço |
|
|
176
|
+
| `OrfeuSyncError` | `POST /apps/operations/sync` falhou |
|
|
177
|
+
| `OrfeuError` | base de todas; também a falha de `GET /apps/operations` |
|
|
178
|
+
| `OrfeuTokenError` | `validateToken`/`validateAppToken` com token inválido; falha de rede na introspecção |
|
|
179
|
+
| `OrfeuForbiddenError` | 403 no `createGuard` do Apollo |
|
|
180
|
+
|
|
181
|
+
Nos adapters, erros de credencial **não** lançam: viram 401/403. Exceções do seu handler seguem o fluxo
|
|
182
|
+
normal do framework (e o evento sai como `failure`).
|
|
183
|
+
|
|
184
|
+
## 10. Testes
|
|
185
|
+
|
|
186
|
+
O pacote não publica mocks. Opções (`node-recipes.md` §12):
|
|
187
|
+
- testar o handler isolado, preenchendo `req.orfeuUser` à mão (Express/Fastify; no Apollo, resolver que passa
|
|
188
|
+
pelo `secureResolvers` precisa do contexto montado com `trustUser`);
|
|
189
|
+
- teste de integração contra um **Argos simulado** (servidor HTTP local com os endpoints que o SDK usa e
|
|
190
|
+
tokens assinados com `jose`), com `audit: false` e `logger: false` se não forem o foco;
|
|
191
|
+
- `clearRegistry()` entre testes que declaram operações diferentes.
|
|
192
|
+
|
|
193
|
+
## 11. Não faça
|
|
194
|
+
|
|
195
|
+
- Não leia `Authorization`/`Bearer`; não valide JWT nem confira grupos à mão: use o guard.
|
|
196
|
+
- Não deixe rota/resolver de negócio sem guard; não use `PUBLIC` para "resolver depois".
|
|
197
|
+
- Não declare operações depois do `startup()` (não estarão no catálogo e serão negadas).
|
|
198
|
+
- Não use texto livre para nível/método: `Level.*`/`Method.*`.
|
|
199
|
+
- Não repasse credencial com `orfeuHeaders` para fora dos seus serviços.
|
|
200
|
+
- Apollo: não grave `ctx.orfeuUser` à mão (use `trustUser`) e não espalhe `connectionParams` no `extra` do
|
|
201
|
+
`orfeuWsContext` (allowlist em node-recipes.md §4).
|
|
202
|
+
- Não mande `traceparent` do navegador nem invente um: o SDK gera.
|
|
203
|
+
- Não ponha segredos/PII desnecessária em `annotateOperation({ details })`.
|
|
204
|
+
- Não encerre o processo sem `await client.flushAudit()`.
|
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
# orfeu 1.0.0 — referência da API
|
|
2
|
+
|
|
3
|
+
Conferida contra o código do pacote (`orfeu/__init__.py` `__all__`, `orfeu/adapters/*.py` `__all__` e os
|
|
4
|
+
módulos). "Raiz" = `from orfeu import ...`. Itens marcados *(submódulo)* não estão no `__all__` da raiz e
|
|
5
|
+
são importados do módulo indicado.
|
|
6
|
+
|
|
7
|
+
Sumário: [1. Adapter FastAPI](#1-orfeuadaptersfastapi) · [2. Operações e modelos](#2-operações-e-modelos) ·
|
|
8
|
+
[3. OrfeuClient](#3-orfeuclient) · [4. Exceções](#4-exceções) · [5. Envelope](#5-envelope) ·
|
|
9
|
+
[6. Auditoria](#6-auditoria) · [7. Trace](#7-trace) · [8. Repasse de contexto](#8-repasse-de-contexto) ·
|
|
10
|
+
[9. Logs](#9-logs) · [10. Constantes de header](#10-constantes-de-header) · [11. Outros adapters](#11-outros-adapters) ·
|
|
11
|
+
[12. Internos úteis em teste](#12-internos-úteis-em-teste)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. `orfeu.adapters.fastapi`
|
|
16
|
+
|
|
17
|
+
`__all__ = ["Orfeu", "operation", "Envelope", "install_envelope", "ok", "orfeu_headers"]`. Requer o extra
|
|
18
|
+
`fastapi` (importa `starlette`).
|
|
19
|
+
|
|
20
|
+
### `class Orfeu`
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
Orfeu(
|
|
24
|
+
app, # FastAPI ou qualquer app Starlette
|
|
25
|
+
authorizer_url: str,
|
|
26
|
+
realm_id: str,
|
|
27
|
+
app_id: str,
|
|
28
|
+
secret: str,
|
|
29
|
+
*,
|
|
30
|
+
tls_verify: bool = True,
|
|
31
|
+
audit: bool | AuditOptions = True,
|
|
32
|
+
)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Na construção: cria `self.client = OrfeuClient(...)`, embrulha `app.router.lifespan_context` e chama
|
|
36
|
+
`app.add_middleware(_OrfeuASGIMiddleware, client=self.client)`. Construa **depois** de criar o app e antes
|
|
37
|
+
de ele começar a servir (o Starlette não aceita `add_middleware` depois do start).
|
|
38
|
+
|
|
39
|
+
| Membro | Comportamento |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `client: OrfeuClient` | o cliente usado pela guarda (para `flush_audit()`, `pending_audit`, mocks em teste). |
|
|
42
|
+
| `async startup_async() -> None` | copia o registro global de `@operation` para o cliente e roda `client.startup()`. Idempotente (marca iniciado só no sucesso). Já é chamado pelo lifespan. |
|
|
43
|
+
| `startup() -> None` | versão síncrona, roda no loop próprio do cliente (seguro com loop rodando). |
|
|
44
|
+
| `_startup()` | alias antigo de `startup_async` (não use em código novo). |
|
|
45
|
+
|
|
46
|
+
Lifespan: `startup_async()` → lifespan original do app (`lifespan=` ou `on_startup`/`on_shutdown`) →
|
|
47
|
+
`client.flush_audit()` numa thread (no shutdown, mesmo se o lifespan do app levantar). Se o
|
|
48
|
+
`startup_async()` falhar, a exceção sobe e o app não inicia.
|
|
49
|
+
|
|
50
|
+
Middleware (por requisição HTTP e handshake WebSocket):
|
|
51
|
+
|
|
52
|
+
1. Resolve a rota exatamente como o roteador vai despachar (`include_router` com prefixo, routers aninhados,
|
|
53
|
+
`Mount`, `Host`, path params). Falhou ao resolver → HTTP 500 `route_unresolved` / WS fecha 1008, sem
|
|
54
|
+
rodar o handler.
|
|
55
|
+
2. Endpoint sem `__orfeu_id__` → passa direto (com rede de segurança: se o roteador acabar despachando para
|
|
56
|
+
um endpoint `@operation`, a resposta HTTP é trocada por 500 / o `accept` do WS é recusado, log CRITICAL
|
|
57
|
+
em `orfeu.guard`).
|
|
58
|
+
3. Endpoint com `@operation` → monta o contexto (credenciais, `traceparent`, `x-route-id`, `x-client-id`,
|
|
59
|
+
IP do cliente via `x-forwarded-for`/`x-real-ip`/socket), grava `scope["state"]["orfeu"]` (lido por
|
|
60
|
+
`orfeu_headers`), decide (regra canônica) e:
|
|
61
|
+
- negado → 401/403 em JSON (HTTP) ou close 1008 (WS); log + auditoria;
|
|
62
|
+
- permitido → `state.user = TokenClaims` (usuário) **ou** `state.user = None` + `state.api_token =
|
|
63
|
+
ApiTokenClaims` (token de API); anônimo não define `state.user`; abre o contexto de
|
|
64
|
+
`annotate_operation`; roda o app capturando o status da resposta; grava log + auditoria com o status
|
|
65
|
+
real (≥ 400 = falha, com a `message`/`detail` do corpo JSON).
|
|
66
|
+
- WebSocket: a sessão inteira é **uma** operação; sucesso sem `status`.
|
|
67
|
+
|
|
68
|
+
Constante: `WS_POLICY_VIOLATION = 1008` *(submódulo `orfeu.adapters.fastapi`)*.
|
|
69
|
+
|
|
70
|
+
### `install_envelope(app) -> None`
|
|
71
|
+
|
|
72
|
+
Registra exception handlers que fazem todo erro responder `{"status", "message", "data": null}`:
|
|
73
|
+
|
|
74
|
+
| Exceção | Resposta |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `EnvelopeError` e subclasses | `exc.status`, `exc.message` |
|
|
77
|
+
| `starlette.exceptions.HTTPException` (inclui a do FastAPI) | `status_code`, `detail_text(detail)`, preserva `headers` |
|
|
78
|
+
| `RequestValidationError` | 422, mensagens do pydantic `"campo: msg"` unidas por `; ` (ou `"Requisição inválida."`) |
|
|
79
|
+
| `Exception` | 500 `"Erro inesperado no serviço."`; stack no logger `orfeu.envelope` |
|
|
80
|
+
|
|
81
|
+
### `Envelope[T]`
|
|
82
|
+
|
|
83
|
+
Modelo pydantic genérico (`status: int = 200`, `message: str = ""`, `data: T | None = None`) para
|
|
84
|
+
`response_model=Envelope[MeuSchema]`. É `None` se o pydantic não estiver instalado.
|
|
85
|
+
|
|
86
|
+
### Re-exports
|
|
87
|
+
|
|
88
|
+
`operation` (o mesmo de `orfeu.operation`), `ok` (o mesmo de `orfeu.ok`), `orfeu_headers` (o mesmo de
|
|
89
|
+
`orfeu.orfeu_headers`).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 2. Operações e modelos
|
|
94
|
+
|
|
95
|
+
### `operation(id, level, *, method=None)` (raiz e adapters)
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
operation(id: str, level: Level | str, *, method: Method | str | None = None) -> Callable
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Decorator declarativo: **não embrulha** a função. Valida (`OrfeuConfigError` na importação se `id` não tiver
|
|
102
|
+
1..200 caracteres ou `method`/`level` forem inválidos), registra um `OperationDescriptor(identifier=id,
|
|
103
|
+
method, level, description=func.__doc__)` no registro global (sem duplicar `(id, method)`; o primeiro
|
|
104
|
+
vence) e grava `func.__orfeu_id__`, `func.__orfeu_method__`, `func.__orfeu_level__` (strings).
|
|
105
|
+
|
|
106
|
+
Inferência de `method` quando omitido (pelo `func.__name__`, minúsculo, nesta ordem): começa com
|
|
107
|
+
`get_`/`list_`/`fetch_`/`read_` → `read`; começa com `delete_`/`remove_`/`destroy_` → `delete`; contém
|
|
108
|
+
`stream`/`subscribe`/`watch`/`listen` → `stream`; senão `write`.
|
|
109
|
+
|
|
110
|
+
`orfeu.decorators.get_registry() -> list[OperationDescriptor]` (cópia) e
|
|
111
|
+
`orfeu.decorators.clear_registry() -> None` *(submódulo)*: leitura e limpeza do registro global (testes).
|
|
112
|
+
|
|
113
|
+
### `class Level(StrEnum)` / `class Method(StrEnum)` (raiz)
|
|
114
|
+
|
|
115
|
+
| `Level` | valor | | `Method` | valor |
|
|
116
|
+
|---|---|---|---|---|
|
|
117
|
+
| `PUBLIC` | `"public"` | | `READ` | `"read"` |
|
|
118
|
+
| `OPTIONAL` | `"optional"` | | `WRITE` | `"write"` |
|
|
119
|
+
| `PRIVATE` | `"private"` | | `DELETE` | `"delete"` |
|
|
120
|
+
| `PROTECTED` | `"protected"` | | `STREAM` | `"stream"` |
|
|
121
|
+
|
|
122
|
+
`Level.PRIVATE == "private"` é `True`. Qualquer outro valor é recusado no registro.
|
|
123
|
+
|
|
124
|
+
### `@dataclass OperationDescriptor` (raiz)
|
|
125
|
+
|
|
126
|
+
`identifier: str`, `method: Method | str`, `level: Level | str`, `protocol: str | None = None`,
|
|
127
|
+
`native_ref: str | None = None`, `description: str | None = None`. `to_dict()` → payload do sync.
|
|
128
|
+
Usado com `OrfeuClient.register_operation` quando não há decorator.
|
|
129
|
+
|
|
130
|
+
### `@dataclass OperationWithGroups` (raiz)
|
|
131
|
+
|
|
132
|
+
`identifier`, `method`, `level`, `allowed_groups: list[str]`, `operation_id: str | None` (UUID no Argos).
|
|
133
|
+
É o que `fetch_operations()` carrega e o que `check_permission` consulta.
|
|
134
|
+
|
|
135
|
+
### `@dataclass TokenClaims` (raiz)
|
|
136
|
+
|
|
137
|
+
`sub: str`, `realm_id: str`, `groups: list[str]`, `exp: int`, `raw: dict` (payload completo). Para um
|
|
138
|
+
`x-app-token`, `raw["token_type"] == "app_token"` e `raw["token_id"]` traz o id do token.
|
|
139
|
+
|
|
140
|
+
### `@dataclass ApiTokenClaims` *(submódulo `orfeu.models`)*
|
|
141
|
+
|
|
142
|
+
`token_id: str`, `app_id: str` (backend dono do token). Sem grupos: a permissão do token de API é decidida
|
|
143
|
+
pelo Argos por operação.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 3. `OrfeuClient`
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
OrfeuClient(authorizer_url: str, realm_id: str, app_id: str, secret: str, *,
|
|
151
|
+
tls_verify: bool = True, audit: bool | AuditOptions = True)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Usado por baixo pelos adapters; use direto em scripts, workers ou frameworks sem adapter.
|
|
155
|
+
|
|
156
|
+
Atributos de classe (cache): `JWKS_TTL = 3600.0`, `API_TOKEN_TTL = 30.0` (caminho legado),
|
|
157
|
+
`INTROSPECTION_TTL = 60.0`, `INTROSPECTION_INACTIVE_TTL = 10.0` (segundos).
|
|
158
|
+
|
|
159
|
+
| Método / propriedade | Comportamento | Erros |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| `app_id` (prop.) | o `app_id` deste backend. | — |
|
|
162
|
+
| `register_operation(op: OperationDescriptor)` | registra antes do `startup`; `(identifier, method)` repetido é ignorado. | `OrfeuConfigError` (valor inválido) |
|
|
163
|
+
| `async startup()` | `authenticate()` → `fetch_jwks()` → `sync_operations()` → `fetch_operations()`. | `OrfeuConfigError` se nada registrado; os erros abaixo |
|
|
164
|
+
| `async authenticate()` | `POST {url}/realms/{realm}/apps/token` com `app_id`/`secret`; guarda o token do app. | `OrfeuAuthError` (rede, HTTP ≠ 200, sem `access_token`) |
|
|
165
|
+
| `async fetch_jwks()` | baixa e guarda o JWKS do realm. | `OrfeuError` |
|
|
166
|
+
| `async sync_operations()` | envia o catálogo registrado ao Argos. | `OrfeuSyncError`; `OrfeuAuthError` sem token |
|
|
167
|
+
| `async fetch_operations()` | baixa as operações do backend com `allowed_groups` e `operation_id`. **Só roda no startup**; chame de novo para recarregar grupos sem reiniciar. | `OrfeuError`; `OrfeuAuthError` sem token |
|
|
168
|
+
| `async validate_token(token) -> TokenClaims` | JWT RS256: exige `kid`, recarrega JWKS se vencido (1 h) ou `kid` desconhecido, verifica `exp` e realm. | `OrfeuTokenError` |
|
|
169
|
+
| `async validate_app_token(token) -> TokenClaims` | introspecção (cache por hash do token); exige `type == "app"` e mesmo realm. | `OrfeuTokenError` (inválido, revogado, outro realm, Argos sem introspecção, rede/HTTP) |
|
|
170
|
+
| `async validate_api_token(token, identifier, method) -> ApiTokenClaims \| None` | introspecção; `None` se inválido ou se a operação não foi concedida ao token. Argos sem introspecção (404) → endpoint legado de validação. | `OrfeuTokenError` (rede/HTTP do Argos) |
|
|
171
|
+
| `check_permission(claims, identifier, method) -> bool` | operação desconhecida → `False`; `public` → `True`; `private`/`optional` → tem algum grupo; `protected` → interseção com `allowed_groups`. Síncrono, sem rede. | — |
|
|
172
|
+
| `operation_uuid(identifier, method) -> str \| None` | UUID no Argos depois do `fetch_operations`. | — |
|
|
173
|
+
| `record_audit(event: dict)` | enfileira um evento (no-op com auditoria desligada). | — |
|
|
174
|
+
| `flush_audit(timeout: float = 3.0)` | envia o que está na fila. | — |
|
|
175
|
+
| `pending_audit` (prop.) | eventos aguardando envio. | — |
|
|
176
|
+
| `run_sync(coro, timeout: float \| None = 30.0)` | roda uma corrotina do cliente a partir de código síncrono, num loop dedicado (thread daemon `orfeu-loop`), nunca `asyncio.run()` por chamada. Funciona com loop rodando. | o que a corrotina levantar; `TimeoutError` |
|
|
177
|
+
|
|
178
|
+
O token do app é renovado automaticamente quando a introspecção ou o envio da auditoria recebem 401.
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 4. Exceções (raiz)
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
OrfeuError(Exception)
|
|
186
|
+
├── OrfeuAuthError credenciais do backend recusadas / sem token do app
|
|
187
|
+
├── OrfeuTokenError token de quem chama inválido/expirado/outro realm; erro do Argos na introspecção
|
|
188
|
+
├── OrfeuSyncError falha no sync do catálogo
|
|
189
|
+
├── OrfeuConfigError nenhuma operação registrada; id/method/level inválido
|
|
190
|
+
├── OrfeuUnauthorizedError (também PermissionError) status=401, code="UNAUTHENTICATED"
|
|
191
|
+
└── OrfeuForbiddenError (também PermissionError) status=403, code="FORBIDDEN"
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`OrfeuUnauthorizedError`/`OrfeuForbiddenError` têm `.message` e `.extensions = {"code", "status"}`; são
|
|
195
|
+
levantadas pelo adapter Strawberry (no FastAPI/Flask/Django a negação é uma resposta HTTP, não exceção no
|
|
196
|
+
handler). Os adapters capturam `OrfeuTokenError` e convertem em 401 — o handler nunca a vê.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 5. Envelope
|
|
201
|
+
|
|
202
|
+
Raiz: `ok`, `fail`, `EnvelopeError`, `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `Conflict`,
|
|
203
|
+
`Unprocessable`, `Unavailable`. Submódulo `orfeu.envelope`: `EnvelopeDict`, `detail_text`.
|
|
204
|
+
|
|
205
|
+
| Função / classe | Assinatura / valor |
|
|
206
|
+
|---|---|
|
|
207
|
+
| `ok(data=None, message="", status=200)` | `{"status": status, "message": message, "data": data}` |
|
|
208
|
+
| `fail(status, message)` | `{"status": status, "message": message, "data": None}` |
|
|
209
|
+
| `EnvelopeError(message, status=None)` | `.message`, `.status` (padrão 500; `status=` sobrescreve) |
|
|
210
|
+
| `BadRequest` 400 · `Unauthorized` 401 · `Forbidden` 403 · `NotFound` 404 · `Conflict` 409 · `Unprocessable` 422 · `Unavailable` 503 | subclasses com `status` fixo |
|
|
211
|
+
| `detail_text(detail) -> str` | `str` → igual; lista de erros pydantic → `"loc: msg; ..."` (sem `body`/`query`/`path` no `loc`); dict → `message`/`detail` |
|
|
212
|
+
|
|
213
|
+
`Unauthorized`/`Forbidden` do envelope são erros **de negócio** levantados pelo app; não têm relação com a
|
|
214
|
+
guarda (a guarda responde 401/403 antes do handler).
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 6. Auditoria
|
|
219
|
+
|
|
220
|
+
### `annotate_operation(*, target_type=None, target_id=None, details=None) -> bool` (raiz)
|
|
221
|
+
|
|
222
|
+
Acrescenta ao evento da operação em andamento (via `ContextVar`): `target_type: str`, `target_id: str | int`
|
|
223
|
+
(convertido para `str`), `details: dict` (mesclado ao anterior). Devolve `False` fora de uma chamada
|
|
224
|
+
guardada. Limites aplicados na montagem do evento: `target_type` 100, `target_id` 200, `details` 4 KB
|
|
225
|
+
(acima → `{"truncated": true, "original_bytes": n}`; não serializável → `{"unserializable": true}`).
|
|
226
|
+
|
|
227
|
+
### `@dataclass AuditOptions` (raiz)
|
|
228
|
+
|
|
229
|
+
`enabled: bool = True`, `flush_interval: float = 1.0` (s), `max_buffer: int = 10_000`, `batch_size: int = 200`.
|
|
230
|
+
Lotes também limitados a ~90 KB.
|
|
231
|
+
|
|
232
|
+
Entrega (`orfeu.audit.AuditSink`, thread `orfeu-audit`): 2xx ok; 5xx/rede/401/408/429 → volta à fila com
|
|
233
|
+
backoff exponencial até 60 s; 404 → descarta a fila e pausa 10 min; outro 4xx → descarta o lote. Buffer
|
|
234
|
+
cheio → descarta primeiro uma **leitura bem-sucedida**. Avisos (no máximo 1 por minuto) no logger
|
|
235
|
+
`orfeu.audit` com prefixo `[orfeu]`. `atexit` tenta um último flush (3 s).
|
|
236
|
+
|
|
237
|
+
### Evento (`build_audit_event(...)`, raiz)
|
|
238
|
+
|
|
239
|
+
Campos: `event_id`, `occurred_at` (início, ISO UTC), `duration_ms`, `trace_id`, `span_id`,
|
|
240
|
+
`parent_span_id?`, `entry`, `actor_type` (`user`/`app_token`/`api_token`/`public`/`unauthenticated`),
|
|
241
|
+
`sdk` (`python/<versão>`), `service_instance` (`host:pid`), `operation {identifier, method, level}`,
|
|
242
|
+
`permission_result` (`allowed`/`forbidden`/`unauthorized`/`public`), `outcome`
|
|
243
|
+
(`success`/`failure`/`denied`), e quando disponíveis: `user_id`, `token_id`, `client_id`, `route_id`
|
|
244
|
+
(só se tiverem formato GUID — senão omitidos), `client_ip` (só no evento de entrada e se for IP),
|
|
245
|
+
`target_type`, `target_id`, `details`, `status`, `message` (≤ 500).
|
|
246
|
+
|
|
247
|
+
`build_audit_event` e `record_operation(client, *, operation_id, actor_type, permission_result,
|
|
248
|
+
duration_ms, success, method=None, level=None, trace=None, ...)` são as peças que os adapters usam;
|
|
249
|
+
`record_operation` emite o log e enfileira o evento, nunca levanta. Use-os só para integrar um framework sem
|
|
250
|
+
adapter.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## 7. Trace
|
|
255
|
+
|
|
256
|
+
Raiz: `TRACEPARENT_HEADER = "traceparent"`, `OrfeuTrace`, `parse_traceparent`, `format_traceparent`,
|
|
257
|
+
`resolve_trace`.
|
|
258
|
+
|
|
259
|
+
| Item | Comportamento |
|
|
260
|
+
|---|---|
|
|
261
|
+
| `@dataclass(frozen) OrfeuTrace(trace_id, span_id, entry, parent_span_id=None, flags="01")` | contexto de uma chamada. |
|
|
262
|
+
| `parse_traceparent(value) -> tuple[str, str] \| None` | `(trace_id, span_id)`; `None` se inválido: maiúsculas, versão `ff`, ids zerados, campos extras na versão `00`. Versões futuras lidas pelos 4 primeiros campos. |
|
|
263
|
+
| `resolve_trace(incoming) -> OrfeuTrace` | válido → continua (`entry=False`, mesmo `trace_id`, `parent_span_id` = span recebido, `span_id` novo, só o bit *sampled* propagado); senão → trace novo (`entry=True`, flags `01`). |
|
|
264
|
+
| `format_traceparent(t) -> str` | `"00-{trace_id}-{span_id}-{flags}"`, para mandar adiante. |
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## 8. Repasse de contexto
|
|
269
|
+
|
|
270
|
+
### `orfeu_headers(source, *, credential=True) -> dict[str, str]` (raiz e adapters)
|
|
271
|
+
|
|
272
|
+
`source`: `Request`/`WebSocket` (FastAPI/Starlette), `request` (Django), `flask.g` (Flask) ou
|
|
273
|
+
`info.context` (Strawberry). Devolve, quando existirem: a credencial de usuário recebida
|
|
274
|
+
(`x-access-token` **ou** `x-app-token`; nunca `x-api-token`), `traceparent` (o span da chamada atual vira o
|
|
275
|
+
pai do próximo serviço), `x-route-id`, `x-client-id`. `credential=False` omite a credencial. Fora de chamada
|
|
276
|
+
guardada → `{}`.
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## 9. Logs
|
|
281
|
+
|
|
282
|
+
Raiz: `JsonLogFormatter`, `OPERATION_LOG_FIELDS`, `emit_operation_log`, `resolve_actor_type`,
|
|
283
|
+
`resolve_token_id`.
|
|
284
|
+
|
|
285
|
+
| Item | Comportamento |
|
|
286
|
+
|---|---|
|
|
287
|
+
| logger `orfeu.operation` | 1 registro por chamada guardada: `INFO "operação executada"` ou `ERROR <mensagem>`. |
|
|
288
|
+
| `OPERATION_LOG_FIELDS` | `("operation", "operation_id", "operation_method", "operation_level", "agent_id", "actor_type", "permission_result", "duration_ms", "user", "token_id", "route_id", "client_id", "trace_id", "span_id")` — atributos do `LogRecord`, opcionais só quando conhecidos. |
|
|
289
|
+
| `JsonLogFormatter()` | `logging.Formatter`: `{"timestamp", "level", "logger", "message", ...campos, "exc_info"?}` numa linha. |
|
|
290
|
+
| `emit_operation_log(*, operation_id, app_id, actor_type, permission_result, duration_ms, success, user=None, token_id=None, route_id=None, client_id=None, error_message=None, trace_id=None, span_id=None, method=None, level=None, operation_uuid=None)` | emite o registro. O **argumento** `operation_id` é o identificador (vira o campo `operation`); o campo `operation_id` é o UUID (`operation_uuid`). |
|
|
291
|
+
| `resolve_actor_type(claims, level, api_token=None)` | `api_token` → `"api_token"`; claims de app-token → `"app_token"`; claims → `"user"`; sem nada → `"public"` em `public`/`optional`, senão `"unauthenticated"`. |
|
|
292
|
+
| `resolve_token_id(claims, api_token=None)` | id do token opaco (api ou app), ou `None`. |
|
|
293
|
+
|
|
294
|
+
Outros loggers: `orfeu.audit`, `orfeu.envelope`, `orfeu.guard`.
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## 10. Constantes de header (raiz)
|
|
299
|
+
|
|
300
|
+
`ACCESS_TOKEN_HEADER = "x-access-token"`, `APP_TOKEN_HEADER = "x-app-token"`,
|
|
301
|
+
`API_TOKEN_HEADER = "x-api-token"`, `ROUTE_ID_HEADER = "x-route-id"`, `CLIENT_ID_HEADER = "x-client-id"`,
|
|
302
|
+
`TRACEPARENT_HEADER = "traceparent"`.
|
|
303
|
+
|
|
304
|
+
`x-route-id`/`x-client-id` são etiquetas de correlação mandadas pela interface; nunca verificadas nem usadas
|
|
305
|
+
na permissão (e só vão para a auditoria se forem GUID).
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## 11. Outros adapters
|
|
310
|
+
|
|
311
|
+
### `orfeu.adapters.flask` — `__all__ = ["Orfeu", "operation", "orfeu_headers"]`
|
|
312
|
+
|
|
313
|
+
`Orfeu(app, authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True)` — faz o startup
|
|
314
|
+
**na construção** (síncrono): todas as `@operation` precisam estar importadas antes. Registra
|
|
315
|
+
`before_request` (guarda), `after_request` (log/auditoria com o status real) e `teardown_request`. Na view:
|
|
316
|
+
`g.orfeu_user` (`TokenClaims` ou `None` no anônimo) ou `g.orfeu_api_token`; `orfeu_headers(g)`.
|
|
317
|
+
Negação: `jsonify(...)` 401/403 no mesmo corpo do FastAPI.
|
|
318
|
+
|
|
319
|
+
### `orfeu.adapters.django` — `__all__ = ["OrfeuMiddleware", "operation", "orfeu_headers"]`
|
|
320
|
+
|
|
321
|
+
`"orfeu.adapters.django.OrfeuMiddleware"` em `MIDDLEWARE`; settings de [python.md](python.md) §2. Startup na
|
|
322
|
+
construção do middleware; guarda em `process_view` (lê `view_func` e `view_func.__wrapped__`). Na view:
|
|
323
|
+
`request.orfeu_user` / `request.orfeu_api_token`; `orfeu_headers(request)`. WSGI ou ASGI.
|
|
324
|
+
|
|
325
|
+
### `orfeu.adapters.strawberry` — `__all__ = ["Orfeu", "operation", "orfeu_headers"]`
|
|
326
|
+
|
|
327
|
+
`Orfeu(authorizer_url, realm_id, app_id, secret, *, tls_verify=True, audit=True)` (sem `app`):
|
|
328
|
+
`.extension` (classe `SchemaExtension` para `strawberry.Schema(..., extensions=[orfeu.extension])`),
|
|
329
|
+
`startup_async()`/`startup()` idempotentes — **chame no lifespan** (não há gancho automático). Cada campo
|
|
330
|
+
com `@operation` é uma operação (log + auditoria). No resolver: `info.context["orfeu_user"]`;
|
|
331
|
+
`orfeu_headers(info.context)`. Negação: `OrfeuUnauthorizedError`/`OrfeuForbiddenError` (erro GraphQL com
|
|
332
|
+
`extensions.code`/`status`). Subscriptions (graphql-ws): credenciais no payload do `connection_init`
|
|
333
|
+
(`{"x-access-token": "..."}`), etiquetas em `routeId`/`clientId`. Funciona com `execute_sync`.
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## 12. Internos úteis em teste
|
|
338
|
+
|
|
339
|
+
Não são API estável, mas aparecem em testes:
|
|
340
|
+
|
|
341
|
+
- `orfeu.middleware.Credentials(api="", access="", app="")` e `extract_credentials(get)` — leitura dos 3
|
|
342
|
+
headers (valores com `strip()`; só espaço = ausente).
|
|
343
|
+
- `orfeu.guard`: `UNAUTHORIZED_MESSAGE = "Invalid or missing credentials."`,
|
|
344
|
+
`FORBIDDEN_MESSAGE = "Insufficient permissions."`, `decide(client, creds, identifier, method, level)`.
|
|
345
|
+
- `orfeu.audit.AuditSink(transport, options)` — troque `orfeu.client._audit_sink` por um sink com
|
|
346
|
+
`transport=lambda batch: lista.extend(batch) or 202` para capturar eventos.
|