@acropole/skills 0.0.0-stage → 1.0.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 (90) hide show
  1. package/README.md +180 -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 +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,234 @@
1
+ # orfeu (Python) — guia de uso (FastAPI, Flask, Django, Strawberry)
2
+
3
+ > Escrito para a **API 1.0.0** (versão instalada: `python -c "import importlib.metadata as m;
4
+ > print(m.version('orfeu'))"`). Conceitos comuns às três implementações estão no `SKILL.md` da skill; o que muda
5
+ > em relação ao Node e ao Angular está em [diferencas.md](diferencas.md). Estrutura do serviço FastAPI em si
6
+ > (camadas, banco, configuração): skill `fastapi`. Flask, Django e Strawberry ainda não têm skill de
7
+ > padrões — aqui só a integração com o Orfeu.
8
+
9
+ O orfeu é o cliente Python do autorizador **Argos**. Num serviço, ele:
10
+
11
+ 1. autentica o próprio backend no Argos (`app_id` + `secret`), baixa o JWKS e **sincroniza o catálogo de
12
+ operações** declaradas com `@operation`;
13
+ 2. em cada chamada a uma rota marcada, valida a credencial de quem chama (JWT, token pessoal ou token de
14
+ API), decide a permissão e responde 401/403 sem rodar o handler quando nega;
15
+ 3. grava **um evento de auditoria** por chamada guardada (enviado em lote, em segundo plano) e **uma linha
16
+ de log** estruturada (`logging` padrão);
17
+ 4. mantém a correlação W3C `traceparent` e oferece `orfeu_headers(...)` para repassar contexto a outro serviço.
18
+
19
+ Sem OpenTelemetry e sem dependência de observabilidade: só `httpx` e `PyJWT[crypto]`.
20
+
21
+ Leia sob demanda:
22
+ - [python-api.md](python-api.md) — **todos** os exports públicos (`orfeu`, `orfeu.adapters.*` e submódulos úteis), com
23
+ assinatura, comportamento, erros e status.
24
+ - [python-recipes.md](python-recipes.md) — receitas prontas: app FastAPI protegido, operação com permissão, rota
25
+ pública/opcional, anotar alvo na auditoria, chamada entre serviços propagando trace (como o usuário e como
26
+ o próprio serviço), WebSocket, log JSON, testes com mocks, cliente avulso (script/worker), Strawberry,
27
+ Flask/Django — e a lista de armadilhas.
28
+
29
+ ## 1. Instalação
30
+
31
+ ```bash
32
+ pip install "orfeu[fastapi]" # FastAPI/Starlette (fastapi>=0.111, starlette>=0.37)
33
+ pip install "orfeu[flask]" # ou [django], [strawberry]; sem extra = só o cliente (OrfeuClient)
34
+ ```
35
+
36
+ - **Python ≥ 3.11** (`requires-python = ">=3.11"`; usa `enum.StrEnum`). Testado em 3.11–3.14.
37
+ - Dependências fixas: `httpx>=0.27`, `PyJWT[crypto]>=2.8`. O adapter FastAPI foi testado com FastAPI
38
+ 0.111.0, 0.116.1, 0.137.0 e 0.142.2.
39
+ - Fixe a versão maior no app: `orfeu[fastapi]>=1.0,<2`.
40
+
41
+ ## 2. Configuração
42
+
43
+ A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(...)` dos adapters ou
44
+ `OrfeuClient(...)`), exceto no Django, que lê `settings`.
45
+
46
+ | Parâmetro | Obrigatório | O que é |
47
+ |---|---|---|
48
+ | `authorizer_url` | sim | URL base da API do Argos (a barra final é removida). |
49
+ | `realm_id` | sim | Realm do backend (nome ou UUID). Tokens de outro realm são recusados. |
50
+ | `app_id` | sim | UUID do backend cadastrado no Argos (é o `agent_id` dos logs). |
51
+ | `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
52
+ | `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
53
+ | `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
54
+
55
+ Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
56
+ sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY` e `ORFEU_AUDIT` (opcionais).
57
+
58
+ Nos outros frameworks o app escolhe os nomes das variáveis. Convenção sugerida (a mesma do Django):
59
+ `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET`, `ORFEU_TLS_VERIFY`.
60
+
61
+ ## 3. App FastAPI — o mínimo
62
+
63
+ ```python
64
+ import os
65
+ from fastapi import FastAPI, Request
66
+ from orfeu import Level, Method
67
+ from orfeu.adapters.fastapi import Orfeu, install_envelope, operation
68
+
69
+ app = FastAPI() # com ou sem lifespan= próprio
70
+ install_envelope(app) # todo erro vira {status, message, data: null}
71
+ orfeu = Orfeu(
72
+ app,
73
+ authorizer_url=os.environ["ORFEU_AUTHORIZER_URL"],
74
+ realm_id=os.environ["ORFEU_REALM_ID"],
75
+ app_id=os.environ["ORFEU_APP_ID"],
76
+ secret=os.environ["ORFEU_SECRET"],
77
+ )
78
+
79
+ @app.get("/items")
80
+ @operation(id="items.list", level=Level.PRIVATE, method=Method.READ)
81
+ async def list_items(request: Request):
82
+ user = request.state.user # TokenClaims
83
+ return {"status": 200, "message": "", "data": {"sub": user.sub}}
84
+ ```
85
+
86
+ - `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
87
+ token do app → JWKS → sync das operações → busca das operações com grupos; no shutdown faz o flush da
88
+ auditoria. Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
89
+ - O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
90
+ (`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
91
+ (`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
92
+ - `await orfeu.startup_async()` / `orfeu.startup()` são públicos e idempotentes (testes, scripts). O
93
+ `OrfeuClient` fica em `orfeu.client`.
94
+ - Rotas **sem** `@operation` passam direto, sem autenticação, log ou auditoria.
95
+
96
+ ## 4. Operações: `@operation`, `Level`, `Method`
97
+
98
+ ```python
99
+ @router.post("/forms")
100
+ @operation(id="forms.create", level=Level.PROTECTED, method=Method.WRITE)
101
+ async def create_form(...): ...
102
+ ```
103
+
104
+ - `id`: identificador único da operação, 1..200 caracteres (convenção: `recurso.acao`). A chave real no
105
+ Argos é `(id, method)`: o mesmo `id` com outro `method` é outra operação.
106
+ - `level` (`Level`, `StrEnum` — as strings `"private"` etc. também valem). Significado de cada nível:
107
+ `SKILL.md` §3.
108
+
109
+ - `method` (`Method`): `READ`, `WRITE`, `DELETE`, `STREAM`. Sem `method=`, é inferido pelo **nome da
110
+ função**: `get_`/`list_`/`fetch_`/`read_` → `read`; `delete_`/`remove_`/`destroy_` → `delete`; contém
111
+ `stream`/`subscribe`/`watch`/`listen` → `stream`; o resto → `write`. **Prefira passar `method=`**:
112
+ renomear a função muda a operação.
113
+ - Valor inválido levanta `OrfeuConfigError` **na importação** do módulo.
114
+ - O decorator **não embrulha** a função: só grava `__orfeu_id__`/`__orfeu_method__`/`__orfeu_level__` nela
115
+ e registra num **registro global** do processo. Coloque `@operation` logo abaixo do decorator de rota —
116
+ o objeto que o FastAPI registra precisa carregar esses atributos (ver armadilhas).
117
+ - Quem pode chamar uma operação `protected` (grupos) é configurado **no Argos**, não no código.
118
+
119
+ ## 5. Credenciais e regra de decisão
120
+
121
+ Headers (`x-access-token` → `x-app-token` → `x-api-token`, vale a primeira presente; `Authorization` é
122
+ ignorado) e a regra 401/403 estão no `SKILL.md` §4 — idêntica em FastAPI HTTP/WebSocket, Flask, Django e
123
+ Strawberry. Específico do Python: o JWT precisa ser RS256 com `kid` no header; introspecção com cache de 60 s
124
+ (token inativo: 10 s); tokens de outro realm são sempre recusados (não há `acceptAnyRealm`).
125
+
126
+ O que o handler FastAPI recebe (`request.state` / `websocket.state`):
127
+
128
+ | Caso | `request.state.user` | `request.state.api_token` |
129
+ |---|---|---|
130
+ | usuário (`x-access-token`/`x-app-token`) válido | `TokenClaims` | ausente |
131
+ | `x-api-token` válido | `None` | `ApiTokenClaims(token_id, app_id)` |
132
+ | anônimo (`public`/`optional` sem credencial válida) | **ausente** (`AttributeError`) | ausente |
133
+
134
+ Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`.
135
+
136
+ ## 6. Respostas, erros e status
137
+
138
+ | Situação | Resposta |
139
+ |---|---|
140
+ | sem credencial / credencial inválida | `401` `{"status": 401, "message": "Invalid or missing credentials.", "data": null, "error": "unauthorized", "detail": "..."}` — corpo **genérico**; o motivo real vai só para log/auditoria |
141
+ | sem permissão | `403` `{..., "message": "Insufficient permissions.", "error": "forbidden"}` |
142
+ | rota que a guarda não conseguiu resolver | `500` `error: "route_unresolved"`, handler **não** roda (falha fechada; logger `orfeu.guard`) |
143
+ | WebSocket negado/irresolvível | fecha com **1008** antes do `accept` |
144
+
145
+ Envelope de sucesso/erro do próprio app (`install_envelope(app)`): levante `NotFound("Formulário não
146
+ encontrado.")`, `Conflict(...)`, `BadRequest(...)` etc. na regra de negócio — vira `fail(status, message)`.
147
+ `HTTPException` → `detail` como mensagem; 422 de validação → mensagens unidas por `; `; qualquer outra
148
+ exceção → `500 "Erro inesperado no serviço."` (detalhe só no log `orfeu.envelope`). Sucesso: `ok(data,
149
+ message, status)`; `response_model=Envelope[T]` documenta no OpenAPI.
150
+
151
+ O status final da resposta (inclusive 4xx/5xx gerados pelo envelope) é o que vai para a auditoria como
152
+ `outcome`/`status`, com a `message` do corpo.
153
+
154
+ ## 7. Auditoria
155
+
156
+ Toda chamada guardada vira um evento (quem, o quê, onde, resultado, duração, trace), enviado em lote por
157
+ uma thread daemon (`orfeu-audit`: a cada 1 s ou 200 eventos; buffer de 10 mil; backoff até 60 s em erro;
158
+ 404 do Argos pausa por 10 min). A requisição nunca espera.
159
+
160
+ No handler, acrescente o **alvo** quando ele for conhecido:
161
+
162
+ ```python
163
+ from orfeu import annotate_operation
164
+
165
+ annotate_operation(target_type="form", target_id=form_id, details={"campos": ["titulo"]})
166
+ ```
167
+
168
+ - Só funciona **dentro** de uma chamada guardada; fora dela devolve `False` e não faz nada.
169
+ - `target_id` vira `str`; `details` é mesclado a cada chamada. Limites: `target_type` 100 caracteres,
170
+ `target_id` 200, `details` 4 KB (acima disso vira `{"truncated": true, "original_bytes": n}`).
171
+ - Nunca ponha segredo, token ou dado pessoal sensível em `details`.
172
+ - Flush: automático no shutdown do FastAPI e no `atexit`; `orfeu.client.flush_audit()` força.
173
+ `audit=False` desliga; `AuditOptions(flush_interval=..., batch_size=..., max_buffer=...)` ajusta.
174
+
175
+ ## 8. Trace e chamadas entre serviços
176
+
177
+ Cada chamada guardada tem um `OrfeuTrace`: com `traceparent` W3C válido na entrada, o trace continua
178
+ (`entry=False`, mesmo `trace_id`); sem ele (ou inválido), começa um novo (`entry=True`).
179
+
180
+ Para chamar outro serviço **em nome da requisição atual**, use `orfeu_headers(request)`:
181
+
182
+ ```python
183
+ import httpx
184
+ from orfeu.adapters.fastapi import orfeu_headers
185
+
186
+ async with httpx.AsyncClient() as http:
187
+ r = await http.get(f"{OUTRO_SERVICO}/forms/{form_id}", headers=orfeu_headers(request))
188
+ ```
189
+
190
+ Ele devolve `traceparent` (o evento do outro serviço vira um passo interno da mesma ação),
191
+ `x-route-id`/`x-client-id` recebidos e a credencial **de usuário** (`x-access-token` ou `x-app-token`).
192
+ O `x-api-token` de quem chamou **nunca** é repassado. `credential=False` omite a credencial (para chamar
193
+ como o próprio serviço, com o `x-api-token` dele). Fora de uma chamada guardada devolve `{}`.
194
+
195
+ ## 9. Logs
196
+
197
+ Uma linha por chamada guardada no logger `orfeu.operation` (`INFO "operação executada"` / `ERROR` com a
198
+ mensagem), com os campos como atributos do `LogRecord` (`operation`, `operation_id`, `operation_method`,
199
+ `operation_level`, `agent_id`, `actor_type`, `permission_result`, `duration_ms`, `user`, `token_id`,
200
+ `route_id`, `client_id`, `trace_id`, `span_id`). Outros loggers: `orfeu.audit` (falha de entrega),
201
+ `orfeu.envelope` (exceção convertida em 500), `orfeu.guard` (rota irresolvível). O orfeu não configura
202
+ handlers: ligue `JsonLogFormatter` se quiser uma linha JSON por registro ([python-recipes.md](python-recipes.md) §8).
203
+
204
+ ## 10. Testes
205
+
206
+ Não há módulo de mocks oficial. O padrão (o mesmo da suíte do pacote) é construir o app real e trocar só os
207
+ métodos públicos do `OrfeuClient` que vão à rede:
208
+
209
+ ```python
210
+ from unittest.mock import AsyncMock, MagicMock
211
+ orfeu = Orfeu(app, "http://authorizer.test/api", "realm", "app-id", "secret", audit=False)
212
+ orfeu.client.startup = AsyncMock() # sem rede no lifespan
213
+ orfeu.client.validate_token = AsyncMock(return_value=claims)
214
+ orfeu.client.check_permission = MagicMock(return_value=True)
215
+ ```
216
+
217
+ Detalhes (registro global, `clear_registry()`, capturar eventos de auditoria, logs): [python-recipes.md](python-recipes.md) §9.
218
+
219
+ ## 11. Regras que não podem ser quebradas
220
+
221
+ 1. **Toda rota que não é pública leva `@operation`.** Rota sem ele não tem autenticação nenhuma.
222
+ 2. **`@operation` logo abaixo do decorator de rota**, sobre a função que o framework registra. Um wrapper
223
+ intermediário sem `functools.wraps` apaga os atributos e a rota fica **aberta, sem aviso**.
224
+ 3. **Passe `method=` explícito.** A inferência pelo nome muda se a função for renomeada.
225
+ 4. **Nunca leia `Authorization`/`Bearer`** nem valide token na mão: use `request.state.user`/`api_token`.
226
+ 5. **Em `public`/`optional`, `getattr(request.state, "user", None)`** — o atributo não existe no anônimo.
227
+ 6. **Erros de negócio com as classes do envelope** (`NotFound`, `Conflict`...), não `JSONResponse` montado à mão.
228
+ 7. **Chamada a outro serviço dentro de um handler usa `orfeu_headers(request)`** (ou `credential=False` +
229
+ o `x-api-token` do serviço); nunca repasse o `x-api-token` recebido.
230
+ 8. **`annotate_operation` antes de retornar**, no fluxo do handler (não numa task que roda depois da resposta).
231
+ 9. **Segredo fora do código** e nunca em log, `details` ou mensagem de erro.
232
+
233
+ Mais armadilhas (registro global, operações importadas tarde, grupos alterados no Argos, `from __future__
234
+ import annotations` com `Request`): [python-recipes.md](python-recipes.md) §13.
@@ -0,0 +1,126 @@
1
+ #!/usr/bin/env node
2
+ // Verificador da skill `orfeu`: autenticação/autorização feitas à mão em vez do SDK.
3
+ // node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/orfeu/scripts/checar.mjs)
4
+ // Ignora testes (*.spec.*, *.test.*, test_*.py, *_test.py, pastas test/tests).
5
+ // Exceção: `// acropole-ignore-next-line <regra> -- motivo` (`# ...` no Python) na linha anterior.
6
+ import { executar } from './nucleo.mjs';
7
+
8
+ const JS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
9
+ const ehTeste = (a) => /\.(spec|test)\.[cm]?[jt]sx?$/.test(a.nome) || /^test_.*\.py$|_test\.py$|^conftest\.py$/.test(a.nome) || /(^|\/)(tests?|__tests__|e2e)\//.test(a.relRaiz);
10
+ const ehApp = (a) => !ehTeste(a);
11
+ const ehJs = (a) => JS.includes(a.ext) && ehApp(a);
12
+ const ehPy = (a) => a.ext === '.py' && ehApp(a);
13
+
14
+ function procurar(arq, re, fazer) {
15
+ return [...arq.limpo.matchAll(re)].map((m) => ({ linha: arq.linhaDe(m.index), ...fazer(m) }));
16
+ }
17
+
18
+ /** Índice do `)` que fecha o `(` em `inicio`, ignorando strings. */
19
+ function fechaParen(t, inicio) {
20
+ let prof = 0;
21
+ let aspas = '';
22
+ for (let i = inicio; i < t.length; i++) {
23
+ const ch = t[i];
24
+ if (aspas) {
25
+ if (ch === '\\') i++;
26
+ else if (ch === aspas) aspas = '';
27
+ } else if (ch === '"' || ch === "'" || ch === '`') aspas = ch;
28
+ else if (ch === '(') prof++;
29
+ else if (ch === ')' && --prof === 0) return i;
30
+ }
31
+ return t.length;
32
+ }
33
+
34
+ // Só leitura: atribuição (`headers['Authorization'] = ...`, chamada de saída para terceiro) não conta.
35
+ const AUTH_JS = /\bheaders\s*(?:\.\s*authorization\b|\[\s*['"`]authorization['"`]\s*\])(?!\s*=[^=])|\.\s*(?:get|header)\(\s*['"`]authorization['"`]\s*\)|\b(?:split|replace|startsWith|substring|slice)\(\s*['"`]bearer\b/gi;
36
+ const AUTH_PY = /\bheaders\s*(?:\.get\(\s*['"]authorization['"]|\[\s*['"]authorization['"]\s*\](?!\s*=[^=]))|\bHeader\([^)]*alias\s*=\s*['"]authorization['"]|\bauthorization\s*:\s*[\w\[\]| .]*=\s*Header\(|\b(?:HTTPBearer|OAuth2PasswordBearer)\(|\.(?:split|replace|startswith)\(\s*['"]bearer\b/gi;
37
+
38
+ const regras = [
39
+ {
40
+ id: 'authorization-manual',
41
+ resumo: 'token lido de Authorization/Bearer à mão',
42
+ aceita: (a) => ehJs(a) || ehPy(a),
43
+ checar: (arq) =>
44
+ procurar(arq, arq.ext === '.py' ? AUTH_PY : AUTH_JS, () => ({
45
+ mensagem: 'credencial lida à mão de `Authorization`/`Bearer` — a API do app recebe `x-access-token`, `x-app-token` ou `x-api-token`; `Bearer` só existe entre o SDK e o Argos',
46
+ correcao:
47
+ arq.ext === '.py'
48
+ ? 'proteja a rota com `@operation(...)` e leia `request.state.user` (referências: python.md)'
49
+ : 'proteja com `guard(...)`/`operation(...)` do `@orfeu/node` e use o usuário do contexto (referências: node.md)',
50
+ })),
51
+ },
52
+ {
53
+ id: 'jwt-manual',
54
+ resumo: 'validação de JWT à mão (jwt.verify / jwt.decode do PyJWT)',
55
+ aceita: (a) => ehJs(a) || ehPy(a),
56
+ checar: (arq) =>
57
+ procurar(arq, arq.ext === '.py' ? /\bjwt\.decode\s*\(/g : /\bjwt\.verify\s*\(|\bjwtVerify\s*\(/g, (m) => ({
58
+ mensagem: `\`${m[0].replace(/\s*\($/, '')}\` valida token à mão; o SDK já valida JWT/JWKS e introspecção`,
59
+ correcao: 'use o guard do Orfeu (`@operation`, `guard`, `operation`) e o usuário que ele entrega',
60
+ })),
61
+ },
62
+ {
63
+ id: 'token-em-storage',
64
+ resumo: 'token ou outra credencial guardada em localStorage/sessionStorage',
65
+ aceita: ehJs,
66
+ checar: (arq) =>
67
+ procurar(arq, /\b(localStorage|sessionStorage)\s*(?:\.\s*setItem\(([^)]*)\)|\[\s*(['"`][^'"`]*['"`])\s*\]\s*=(?!=)|\.\s*(\w+)\s*=(?!=))/g, (m) => m)
68
+ .filter((a) => /token|jwt|bearer|credential|access|refresh|senha|password|passwd|secret|api[-_]?key/i.test(a[2] ?? a[3] ?? a[4] ?? ''))
69
+ .map((a) => ({
70
+ linha: a.linha,
71
+ mensagem: `credencial gravada em \`${a[1]}\`: qualquer script da página lê (XSS) e ela vaza entre abas/usuários`,
72
+ correcao: 'não guarde: o `@orfeu/angular` mantém o token só em memória e renova pelo cookie do Argos; outra credencial que precise durar fica em memória, num service `providedIn: root`',
73
+ })),
74
+ },
75
+ {
76
+ id: 'rota-sem-operation',
77
+ resumo: '(Python) rota FastAPI sem @operation num arquivo que já usa @operation',
78
+ aceita: ehPy,
79
+ checar(arq) {
80
+ const t = arq.limpo;
81
+ if (!/from\s+orfeu[\w.]*\s+import\s*\(?[^)]*?\boperation\b/.test(t)) return [];
82
+ const out = [];
83
+ const defs = [...t.matchAll(/^[ \t]*(?:async[ \t]+)?def[ \t]+\w+/gm)].map((m) => m.index);
84
+ for (const m of t.matchAll(/^[ \t]*@\w+\.(?:get|post|put|patch|delete|api_route|websocket)\(/gm)) {
85
+ const def = defs.find((d) => d > m.index);
86
+ if (def === undefined) continue;
87
+ const anterior = defs.filter((d) => d < m.index).pop() ?? 0;
88
+ if (/@operation\s*\(/.test(t.slice(anterior, def))) continue;
89
+ out.push({
90
+ linha: arq.linhaDe(m.index + m[0].search(/@/)),
91
+ mensagem: 'rota sem `@operation`: passa sem autenticação, sem usuário e sem auditoria',
92
+ correcao: 'acrescente `@operation(id="dominio:acao", level=Level.X, method=Method.Y)` logo abaixo do decorator de rota (pública de propósito: `level=Level.PUBLIC`)',
93
+ });
94
+ }
95
+ return out;
96
+ },
97
+ },
98
+ {
99
+ id: 'rota-sem-guard',
100
+ resumo: '(Node) rota Express sem guard() num arquivo que já usa guard do @orfeu/node',
101
+ aceita: ehJs,
102
+ checar(arq) {
103
+ const t = arq.limpo;
104
+ if (!/['"]@orfeu\/node(?:\/[\w-]+)?['"]/.test(t) || !/\bguard\s*\(/.test(t)) return [];
105
+ const out = [];
106
+ for (const m of t.matchAll(/\b(\w*[Rr]outer|app)\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"`]/g)) {
107
+ const abre = m.index + m[0].lastIndexOf('(');
108
+ const chamada = t.slice(abre, fechaParen(t, abre) + 1);
109
+ if (!chamada.includes(',') || /\bguard\s*\(/.test(chamada)) continue;
110
+ out.push({
111
+ linha: arq.linhaDe(m.index),
112
+ mensagem: `\`${m[1]}.${m[2]}(...)\` sem \`guard(...)\`: a rota não é protegida nem auditada`,
113
+ correcao: "ponha `guard('area:recurso:acao', Level.X)` na própria linha da rota (pública de propósito: `Level.PUBLIC`)",
114
+ });
115
+ }
116
+ return out;
117
+ },
118
+ },
119
+ ];
120
+
121
+ process.exitCode = executar({
122
+ skill: 'orfeu',
123
+ descricao: 'Authorization/Bearer e JWT à mão, token em storage, rota FastAPI sem @operation e rota Express sem guard.',
124
+ regras,
125
+ extensoes: [...JS, '.py'],
126
+ });
@@ -0,0 +1,227 @@
1
+ // Núcleo dos verificadores das skills (`skills/<skill>/scripts/checar.mjs`). Sem dependências, só Node ≥ 18.
2
+ // FONTE ÚNICA: este arquivo é copiado para `skills/<skill>/scripts/nucleo.mjs` pelo `npm run sync`
3
+ // (cada skill é instalada sozinha, então leva a própria cópia). Edite aqui, nunca a cópia.
4
+ //
5
+ // Uso (pelo checar.mjs de cada skill): node checar.mjs [caminhos...] [--json]
6
+ // sem caminhos: a pasta atual (ignora node_modules, dist, .angular, .git, venvs e caches).
7
+ // saída: `arquivo:linha regra mensagem → correção`; código de saída 1 se achar algo.
8
+ // Exceção pontual, na linha ANTERIOR, em comentário da linguagem:
9
+ // // acropole-ignore-next-line <regra>[,<regra>] -- motivo
10
+ // Sem motivo depois de `--`, a exceção não vale.
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+
14
+ const PASTAS_IGNORADAS = new Set(['node_modules', 'dist', '.angular', '.git', '.venv', 'venv', '__pycache__', '.pytest_cache', '.mypy_cache', 'coverage', '.nx', '.turbo']);
15
+
16
+ const C_LIKE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.scss', '.less']);
17
+
18
+ /** Troca cada caractere (menos quebras de linha) de `s[a..b)` por espaço. */
19
+ function apagar(chars, a, b) {
20
+ for (let i = a; i < b; i++) if (chars[i] !== '\n') chars[i] = ' ';
21
+ }
22
+
23
+ /** Texto com os comentários apagados (mesmo tamanho, mesmas linhas). Strings ficam. */
24
+ export function semComentarios(texto, ext) {
25
+ const c = texto.split('');
26
+ const n = texto.length;
27
+ if (ext === '.html' || ext === '.htm') {
28
+ for (const m of texto.matchAll(/<!--[\s\S]*?(-->|$)/g)) apagar(c, m.index, m.index + m[0].length);
29
+ return c.join('');
30
+ }
31
+ if (ext === '.py') {
32
+ for (let i = 0; i < n; i++) {
33
+ const ch = texto[i];
34
+ if (ch === '#') {
35
+ const fim = texto.indexOf('\n', i);
36
+ apagar(c, i, fim < 0 ? n : fim);
37
+ i = fim < 0 ? n : fim;
38
+ } else if (ch === '"' || ch === "'") {
39
+ const triplo = texto.startsWith(ch.repeat(3), i);
40
+ const fecha = triplo ? ch.repeat(3) : ch;
41
+ let j = i + fecha.length;
42
+ while (j < n && !texto.startsWith(fecha, j)) {
43
+ if (texto[j] === '\\') j++;
44
+ else if (!triplo && texto[j] === '\n') break;
45
+ j++;
46
+ }
47
+ i = j + fecha.length - 1;
48
+ }
49
+ }
50
+ return c.join('');
51
+ }
52
+ const barraDupla = C_LIKE.has(ext); // .css puro só tem /* */
53
+ for (let i = 0; i < n; i++) {
54
+ const ch = texto[i];
55
+ if (ch === '/' && texto[i + 1] === '*') {
56
+ const fim = texto.indexOf('*/', i + 2);
57
+ const f = fim < 0 ? n : fim + 2;
58
+ apagar(c, i, f);
59
+ i = f - 1;
60
+ } else if (barraDupla && ch === '/' && texto[i + 1] === '/' && texto[i - 1] !== ':') {
61
+ const fim = texto.indexOf('\n', i);
62
+ apagar(c, i, fim < 0 ? n : fim);
63
+ i = fim < 0 ? n : fim;
64
+ } else if (ch === '"' || ch === "'" || ch === '`') {
65
+ let j = i + 1;
66
+ while (j < n && texto[j] !== ch) {
67
+ if (texto[j] === '\\') j++;
68
+ else if (ch !== '`' && texto[j] === '\n') break;
69
+ j++;
70
+ }
71
+ i = j;
72
+ }
73
+ }
74
+ let out = c.join('');
75
+ // Comentário HTML dentro de template inline.
76
+ if (ext === '.ts') out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
77
+ return out;
78
+ }
79
+
80
+ /** Monta o objeto de arquivo que as regras recebem. */
81
+ export function lerArquivo(caminho, rel, raiz = path.dirname(caminho)) {
82
+ const texto = fs.readFileSync(caminho, 'utf8').replace(/\r\n?/g, '\n');
83
+ const ext = path.extname(caminho).toLowerCase();
84
+ const inicios = [0];
85
+ for (let i = 0; i < texto.length; i++) if (texto[i] === '\n') inicios.push(i + 1);
86
+ const linhaDe = (idx) => {
87
+ let lo = 0;
88
+ let hi = inicios.length - 1;
89
+ while (lo < hi) {
90
+ const mid = (lo + hi + 1) >> 1;
91
+ if (inicios[mid] <= idx) lo = mid;
92
+ else hi = mid - 1;
93
+ }
94
+ return lo + 1;
95
+ };
96
+ // relRaiz: relativo ao caminho pedido na linha de comando (para regras que olham pastas, ex.: tests/).
97
+ const relRaiz = path.relative(raiz, caminho).split(path.sep).join('/') || path.basename(caminho);
98
+ return { caminho, rel, relRaiz, ext, nome: path.basename(caminho), texto, limpo: semComentarios(texto, ext), linhaDe };
99
+ }
100
+
101
+ /** Trechos de template HTML: o arquivo `.html` inteiro ou `template: \`...\`` de um `.ts`. `{ texto, inicio }`. */
102
+ export function templates(arq) {
103
+ if (arq.ext === '.html') return [{ texto: arq.limpo, inicio: 0 }];
104
+ if (arq.ext !== '.ts') return [];
105
+ const out = [];
106
+ for (const m of arq.limpo.matchAll(/\btemplate\s*:\s*`/g)) {
107
+ const ini = m.index + m[0].length;
108
+ const fim = arq.limpo.indexOf('`', ini);
109
+ if (fim > ini) out.push({ texto: arq.limpo.slice(ini, fim), inicio: ini });
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /** Trechos de CSS: `.css`/`.scss` inteiros ou `styles: \`...\`` / `styles: [\`...\`]` de um `.ts`. */
115
+ export function estilos(arq) {
116
+ if (arq.ext === '.css' || arq.ext === '.scss' || arq.ext === '.less') return [{ texto: arq.limpo, inicio: 0 }];
117
+ if (arq.ext !== '.ts') return [];
118
+ const out = [];
119
+ for (const m of arq.limpo.matchAll(/\bstyles\s*:\s*\[?/g)) {
120
+ let i = m.index + m[0].length;
121
+ for (;;) {
122
+ while (/[\s,]/.test(arq.limpo[i] ?? '')) i++;
123
+ const q = arq.limpo[i];
124
+ if (q !== '`' && q !== "'" && q !== '"') break;
125
+ const fim = arq.limpo.indexOf(q, i + 1);
126
+ if (fim < 0) break;
127
+ // O conteúdo da string é CSS: apaga os /* */ dele.
128
+ out.push({ texto: semComentarios(arq.limpo.slice(i + 1, fim), '.css'), inicio: i + 1 });
129
+ i = fim + 1;
130
+ if (arq.limpo[m.index + m[0].length - 1] !== '[') break;
131
+ }
132
+ }
133
+ return out;
134
+ }
135
+
136
+ /** Lista os arquivos a verificar: `[{ caminho, raiz }]` (raiz = o caminho pedido que o contém). */
137
+ export function listarArquivos(caminhos, cwd, aceita) {
138
+ const out = new Map();
139
+ let raiz = '';
140
+ const visitar = (p, explicito) => {
141
+ let st;
142
+ try {
143
+ st = fs.statSync(p);
144
+ } catch {
145
+ throw new Error(`caminho não encontrado: ${p}`);
146
+ }
147
+ if (st.isDirectory()) {
148
+ if (!explicito && PASTAS_IGNORADAS.has(path.basename(p))) return;
149
+ if (explicito) raiz = p;
150
+ for (const e of fs.readdirSync(p).sort()) visitar(path.join(p, e), false);
151
+ } else if ((explicito || aceita(p)) && !out.has(p)) out.set(p, explicito ? path.dirname(p) : raiz);
152
+ };
153
+ for (const c of caminhos.length ? caminhos : ['.']) visitar(path.resolve(cwd, c), true);
154
+ return [...out].filter(([p]) => aceita(p)).map(([caminho, r]) => ({ caminho, raiz: r }));
155
+ }
156
+
157
+ const IGNORE = /acropole-ignore-next-line\s+([\w,-]+)(?:\s+--(.*?))?\s*(?:\*\/|-->)?\s*$/;
158
+
159
+ /** Exceção declarada na linha anterior: `{ regras: Set, motivo }` ou null. */
160
+ function excecao(arq, linha) {
161
+ const anterior = arq.texto.split('\n')[linha - 2];
162
+ const m = anterior && anterior.match(IGNORE);
163
+ if (!m) return null;
164
+ return { regras: new Set(m[1].split(',').filter(Boolean)), motivo: (m[2] ?? '').trim() };
165
+ }
166
+
167
+ /**
168
+ * Roda as regras. `regras`: `[{ id, aceita(arq) => bool, checar(arq, ctx) => [{ linha, mensagem, correcao }] }]`.
169
+ * `preparar(arquivos, ctx)` opcional roda antes, com todos os arquivos lidos (ex.: coletar declarações).
170
+ */
171
+ export function verificar({ regras, caminhos = [], cwd = process.cwd(), extensoes, preparar }) {
172
+ const aceita = (p) => extensoes.includes(path.extname(p).toLowerCase()) || extensoes.includes(path.basename(p));
173
+ const arquivos = listarArquivos(caminhos, cwd, aceita).map(({ caminho, raiz }) =>
174
+ lerArquivo(caminho, path.relative(cwd, caminho).split(path.sep).join('/') || path.basename(caminho), raiz),
175
+ );
176
+ const ctx = {};
177
+ if (preparar) preparar(arquivos, ctx);
178
+ const achados = [];
179
+ for (const arq of arquivos) {
180
+ for (const regra of regras) {
181
+ if (regra.aceita && !regra.aceita(arq)) continue;
182
+ for (const a of regra.checar(arq, ctx) ?? []) {
183
+ const exc = excecao(arq, a.linha);
184
+ let correcao = a.correcao;
185
+ if (exc && exc.regras.has(regra.id)) {
186
+ if (exc.motivo) continue;
187
+ correcao += ' (a exceção acropole-ignore-next-line precisa de motivo depois de "--")';
188
+ }
189
+ achados.push({ arquivo: arq.rel, linha: a.linha, regra: regra.id, mensagem: a.mensagem, correcao });
190
+ }
191
+ }
192
+ }
193
+ achados.sort((a, b) => (a.arquivo < b.arquivo ? -1 : a.arquivo > b.arquivo ? 1 : a.linha - b.linha || (a.regra < b.regra ? -1 : 1)));
194
+ // Mesmo achado duas vezes na mesma linha (ex.: duas cores) vira um só por regra+mensagem.
195
+ const unicos = [...new Map(achados.map((a) => [`${a.arquivo}:${a.linha}:${a.regra}:${a.mensagem}`, a])).values()];
196
+ return { arquivos: arquivos.length, achados: unicos };
197
+ }
198
+
199
+ /** Ponto de entrada dos checar.mjs: lê argv, imprime e define o código de saída. */
200
+ export function executar({ skill, descricao, regras, extensoes, preparar, argv = process.argv.slice(2) }) {
201
+ if (argv.includes('--help') || argv.includes('-h')) {
202
+ console.log(`Verificador da skill ${skill}: ${descricao}
203
+
204
+ Uso: node checar.mjs [caminhos...] [--json]
205
+ sem caminhos, verifica a pasta atual (ignora node_modules, dist, .angular...).
206
+ Exceção (linha anterior, em comentário): acropole-ignore-next-line <regra> -- motivo
207
+
208
+ Regras:
209
+ ${regras.map((r) => ` ${r.id.padEnd(28)} ${r.resumo}`).join('\n')}`);
210
+ return 0;
211
+ }
212
+ const json = argv.includes('--json');
213
+ const caminhos = argv.filter((a) => a !== '--json');
214
+ let r;
215
+ try {
216
+ r = verificar({ regras, caminhos, extensoes, preparar });
217
+ } catch (e) {
218
+ console.error(`checar (${skill}): ${e.message}`);
219
+ return 2;
220
+ }
221
+ if (json) console.log(JSON.stringify({ skill, arquivos: r.arquivos, achados: r.achados }, null, 2));
222
+ else {
223
+ for (const a of r.achados) console.log(`${a.arquivo}:${a.linha} ${a.regra} ${a.mensagem} → ${a.correcao}`);
224
+ console.log(r.achados.length ? `\n${r.achados.length} problema(s) em ${r.arquivos} arquivo(s) verificado(s).` : `Nada encontrado (${r.arquivos} arquivo(s) verificado(s)).`);
225
+ }
226
+ return r.achados.length ? 1 : 0;
227
+ }