@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.
Files changed (92) hide show
  1. package/README.md +181 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. 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.