@acropole/skills 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +14 -11
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
  7. package/skills/angular/SKILL.md +4 -3
  8. package/skills/angular/references/armadilhas.md +3 -3
  9. package/skills/angular/references/dados.md +3 -3
  10. package/skills/angular/references/estrutura.md +6 -5
  11. package/skills/angular/references/features.md +5 -5
  12. package/skills/angular/references/testes-build.md +1 -1
  13. package/skills/auto-servico/SKILL.md +18 -14
  14. package/skills/auto-servico/references/roteiros.md +1 -1
  15. package/skills/auto-servico/references/tools.md +1 -1
  16. package/skills/express/references/dados.md +4 -1
  17. package/skills/express/references/estrutura.md +2 -1
  18. package/skills/fastapi/references/banco.md +6 -2
  19. package/skills/fastapi/references/estrutura.md +1 -1
  20. package/skills/hefesto/SKILL.md +13 -6
  21. package/skills/hefesto/references/diagnostico.md +1 -0
  22. package/skills/hefesto/references/mcp-roteiros.md +48 -7
  23. package/skills/orfeu/SKILL.md +43 -13
  24. package/skills/orfeu/references/angular-api.md +39 -13
  25. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  26. package/skills/orfeu/references/angular-recipes.md +25 -12
  27. package/skills/orfeu/references/angular.md +37 -15
  28. package/skills/orfeu/references/diferencas.md +17 -8
  29. package/skills/orfeu/references/node-api.md +41 -9
  30. package/skills/orfeu/references/node-armadilhas.md +16 -2
  31. package/skills/orfeu/references/node-recipes.md +13 -4
  32. package/skills/orfeu/references/node.md +31 -12
  33. package/skills/orfeu/references/python-api.md +41 -16
  34. package/skills/orfeu/references/python-recipes.md +13 -9
  35. package/skills/orfeu/references/python.md +33 -12
  36. package/skills/orfeu/references/react.md +133 -0
  37. package/skills/orquestracao/SKILL.md +3 -1
  38. package/skills/orquestracao/scripts/coord.sh +10 -2
  39. package/skills/trismegisto/SKILL.md +89 -35
  40. package/skills/trismegisto/references/angular-api.md +4548 -344
  41. package/skills/trismegisto/references/angular-exports.md +8275 -2579
  42. package/skills/trismegisto/references/angular-recipes.md +327 -6
  43. package/skills/trismegisto/references/angular-types.md +92 -0
  44. package/skills/trismegisto/references/angular.md +96 -16
  45. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  46. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  47. package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
  48. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  49. package/skills/trismegisto/references/react-api.md +16864 -0
  50. package/skills/trismegisto/references/react.md +237 -0
  51. package/skills/trismegisto/references/spine-api.md +5904 -1361
  52. package/skills/trismegisto/references/spine-recipes.md +140 -46
  53. package/skills/trismegisto/references/spine.md +121 -49
  54. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -24,9 +24,11 @@ def connect_to_db(app, settings) -> None:
24
24
  )
25
25
  engine = create_engine(
26
26
  url,
27
- pool_size=settings.min_connection_count,
28
- max_overflow=settings.max_connection_count,
27
+ pool_size=settings.min_connection_count, # 2: no máximo 2 conexões paradas no pool
28
+ max_overflow=settings.max_connection_count, # 8: o excedente fecha ao voltar
29
29
  pool_timeout=30, pool_recycle=1800, pool_pre_ping=True,
30
+ # o Postgres fecha a conexão parada há DB_IDLE_SESSION_TIMEOUT_S (300), fora de transação; o pre_ping repõe
31
+ connect_args={"options": f"-c idle_session_timeout={settings.db_idle_session_timeout_s * 1000}"},
30
32
  )
31
33
  with engine.connect() as conn: # falha cedo: o app não sobe sem banco
32
34
  conn.execute(text("SELECT 1"))
@@ -42,6 +44,8 @@ def close_db_connections(app) -> None:
42
44
 
43
45
  - Use `URL.create(...)` — nunca monte a URL por f-string (senha com `@`/`:` quebra).
44
46
  - Atenção ao nome: `max_overflow` é o **excedente** sobre `pool_size`, não o máximo total.
47
+ - Conexão parada não fica presa no banco: o SQLAlchemy não tem tempo de ociosidade, e quem fecha é o Postgres
48
+ (`idle_session_timeout`, mandado na conexão). Nunca corta consulta nem transação aberta. Padrão: 2 + 8 e 300 s.
45
49
 
46
50
  Dependência por requisição (`app/shared/dependencies.py`):
47
51
 
@@ -266,7 +266,7 @@ Nomes de variáveis usados (sem valores):
266
266
  |---|---|
267
267
  | Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
268
268
  | Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
269
- | Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
269
+ | Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT` (2), `MAX_CONNECTION_COUNT` (8), `DB_IDLE_SESSION_TIMEOUT_S` (300) |
270
270
  | Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), `REDIS_CLIENT_NAME` (nome das conexões, padrão `<app>-server`; ver integracoes.md), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
271
271
  | Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
272
272
 
@@ -145,10 +145,14 @@ vê e opera as aplicações dos grupos dela (Desenvolvedor/Administrador: todas)
145
145
  token de aplicação pessoal (`x-app-token`, criado logado no Hefesto, em variável de ambiente, nunca no git):
146
146
 
147
147
  ```json
148
- { "mcpServers": { "hefesto": { "type": "http", "url": "https://<host>/hefesto/mcp",
149
- "headers": { "x-app-token": "${HEFESTO_TOKEN}", "x-mcp-scopes": "deploy.*" } } } }
148
+ { "mcpServers": { "hefesto-prod": { "type": "http", "url": "https://<host>/hefesto/mcp",
149
+ "headers": { "x-app-token": "${HEFESTO_TOKEN_PROD}", "x-mcp-scopes": "deploy.*" } } } }
150
150
  ```
151
151
 
152
+ Nome da entrada: `hefesto-<ambiente>` (o ambiente do Hefesto onde o token foi criado), como gera *Configurações ›
153
+ Sessões › Conectar um agente de IA*; assim `hefesto-homol` e `hefesto-prod` convivem no mesmo agente. O auto-serviço
154
+ do Hefesto, oferecido ao Administrador, sai como `argos-hefesto-<ambiente>` (skill auto-servico).
155
+
152
156
  Sem `x-mcp-scopes` a conexão é só de consulta (`deploy.*.read`); para deploy e variáveis, peça a escrita no header
153
157
  (`deploy.*`, ou só `deploy.requests.write`). deployApp, redeployApp, cancelRequest, approveRequest, rejectRequest,
154
158
  rollbackApp e setEnvironmentVars só executam com `confirm: true`: sem ele, respondem `VALIDATION_ERROR` com `details.confirmation_required` e não fazem
@@ -156,12 +160,15 @@ nada. O agente trabalha assim:
156
160
 
157
161
  1. `getContext` → `listApps(search)` → `getApp(app_id)`: por ambiente, o repositório e os workers (servidor, status,
158
162
  versão em execução). Todo id sai daí; nunca suposição.
159
- 2. Mostre o que muda (versão atual → nova, servidor/ambiente) e **confirme**, principalmente em produção; só depois
160
- do "sim" chame a tool com `confirm: true`.
163
+ 2. Mostre o que muda (versão atual → nova, servidor/ambiente). Pedido que já diz a app e o ambiente é a confirmação;
164
+ confirme só o que ficou em aberto (qual ambiente, qual app). Aí chame a tool com `confirm: true`.
161
165
  3. `deployApp(app_id, worker_id, part)` (build + implantação) ou `redeployApp(app_id, worker_id)` (só reimplanta a
162
- mais recente); `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
166
+ mais recente), um por worker, todos juntos; `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
163
167
  4. `getRequest` até `finished=true`; falhou → etapa com erro e `getBuildLog` (final do log). Pedido de um Solicitante
164
168
  fica aguardando aprovação (`pending_approval`): avise e não espere a execução.
169
+ 5. Produto com várias apps: migrations pendentes primeiro, depois server → GraphQL → front, uma camada só quando a
170
+ anterior terminou em todos os workers. O autodeploy do próprio Hefesto pode terminar "Falhou" com a versão nova no
171
+ ar: confira antes de refazer. Os dois em `references/mcp-roteiros.md`.
165
172
 
166
173
  Também estão no MCP: `cancelRequest`, `approveRequest`/`rejectRequest` (decidem o que um Solicitante pediu; escopo
167
174
  `deploy.approvals.write`), `rollbackApp` (abre uma solicitação de Rollback; exige a permissão de
@@ -178,5 +185,5 @@ rollback no Argos), `getWorkerHistory` e `listEnvironmentVars`/`setEnvironmentVa
178
185
  | `references/preparar-app.md` | O que o app precisa ter: Dockerfile, porta, path, health, SIGTERM, variáveis, build args, site, réplicas e tarefas em background |
179
186
  | `references/diagnostico.md` | Onde olhar (histórico, logs do container, Caddyfile), mensagens de erro do Hefesto e o que significam, erros comuns com causa |
180
187
  | `references/mcp-tools.md` | hefesto-mcp: tools com argumentos, escopos, resources e prompts |
181
- | `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, falha e revisão do que está rodando |
188
+ | `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, produto com várias apps (migrations e ordem das camadas), deploy do próprio Hefesto, falha e revisão do que está rodando |
182
189
  | `references/mcp-diagnostico.md` | hefesto-mcp: erros ao conectar e nas tools, e falhas por etapa da solicitação |
@@ -34,6 +34,7 @@
34
34
  | Deploy de `<versão>` desfeito automaticamente: A nova versão não ficou saudável (...) | a versão nova não respondeu < 400 no `health_path` (ou não abriu a porta) dentro do prazo; a anterior continua no ar | leia as últimas linhas da nova versão na mensagem; corrija a subida ou o `/health` |
35
35
  | A imagem buildada por esta solicitação (...) não está mais no registry | a retenção apagou a imagem entre o Build e o Deploy | faça um novo Deploy |
36
36
  | Interrompida: o server reiniciou durante a etapa X | o hefesto-server caiu no meio do Build/Deploy | confira o status do worker e use **Avançar** |
37
+ | Deploy de `<versão>` do próprio hefesto não confirmado: ... | autodeploy do hefesto-server: o rollout derrubou o processo e a conferência no Talos não fechou | `running_image_tag` do worker = versão do Build e `/health` 200 → está no ar, não refaça; versão antiga → falha de verdade (ver [mcp-roteiros.md](mcp-roteiros.md), "Deploy do próprio Hefesto") |
37
38
  | A solicitação já está em execução (409) | outro avanço da mesma solicitação está rodando | espere terminar |
38
39
  | O Talos recusou o Caddyfile (caddy validate) | configuração gerada inválida (domínio ou path estranho) | a mensagem traz a saída do validate; o Caddyfile anterior continua ativo |
39
40
  | Rollback exige a permissão de rollback no Argos | usuário sem `apps:agents:workers:rollback` | peça a permissão ao administrador do Argos |
@@ -8,14 +8,17 @@ Sequências de tools para as tarefas comuns. Todas começam por `getContext`, e
8
8
  Pedido típico: "faz o deploy do pedidos-api em homologação, sobe a minor".
9
9
 
10
10
  1. `listApps(search="pedidos")`: mais de uma parecida → pergunte qual.
11
- 2. `getApp(app_id)`: ache o ambiente `homol`; mais de um worker → pergunte em qual (ou faça um por vez). Anote o
12
- `running_image_tag` do worker e o `repository_id` do ambiente.
11
+ 2. `getApp(app_id)`: ache o ambiente `homol`. O deploy vai para **todos os workers** do ambiente, juntos (ver "Vários
12
+ workers"); só pergunte se o pedido citar um servidor. Anote o `running_image_tag` dos workers e o `repository_id`
13
+ do ambiente.
13
14
  3. `listBuilds(app_id, repository_id)`: última versão publicada (ex.: `1.4.0.0`); a minor vai gerar a próxima
14
15
  (`1.5.0.0`). A tag é da app, sem ambiente: em prod, um Deploy do mesmo commit já publicado em homol
15
16
  reaproveita a imagem (promoção, sem build), desde que os repositórios dos dois ambientes sejam a mesma fonte
16
17
  (URL, branch, `build_path`, registry).
17
- 4. Mostre ao usuário: aplicação, servidor/ambiente, versão em execução → versão nova. Confirme.
18
- 5. `deployApp(app_id, worker_id, part="minor")` → `requested_id`.
18
+ 4. Mostre ao usuário: aplicação, servidor/ambiente, versão em execução → versão nova. Pedido que já diz a app e o
19
+ ambiente ("faz o deploy do pedidos-api em prod") **é** a confirmação: não pergunte de novo. Confirme só o que o
20
+ pedido deixou em aberto (qual ambiente, qual app entre parecidas).
21
+ 5. `deployApp(app_id, worker_id, part="minor", confirm=true)`, um por worker → um `requested_id` cada.
19
22
  6. `getRequest(requested_id)` a cada poucos segundos até `finished=true`. O build costuma ser a etapa mais longa;
20
23
  para ver o progresso, `getBuildLog` com o `build_id` mais recente do `listBuilds` e `offset`.
21
24
 
@@ -35,9 +38,47 @@ só entra no próximo deploy/redeploy ([fluxo.md](fluxo.md)).
35
38
 
36
39
  ## Vários workers ou vários ambientes
37
40
 
38
- Um `deployApp` por worker. O build do mesmo repositório é compartilhado: duas solicitações seguidas para workers do
39
- mesmo ambiente não buildam duas vezes (a segunda reaproveita o build em andamento ou, sem commit novo, a última
40
- versão). Para promover de `homol` para `prod`, é um deploy em cada ambiente (cada um builda do próprio repositório).
41
+ Um `deployApp` por worker, **todos de uma vez** (sem esperar um terminar para mandar o próximo). O build do mesmo
42
+ repositório é compartilhado: solicitações seguidas para workers do mesmo ambiente não buildam duas vezes (a etapa
43
+ Build das outras diz "reaproveitado: executado por outra solicitação em andamento"). Para promover de `homol` para
44
+ `prod`, é um deploy em cada ambiente (cada um builda do próprio repositório; mesmo commit = promoção, sem build).
45
+
46
+ ## Produto com várias apps (server, GraphQL, front)
47
+
48
+ Pedido típico: "faz o deploy do pedidos" (pedidos-server, pedidos-graphql, pedidos-angular), ou "deploy do A e, quando
49
+ terminar, do B".
50
+
51
+ 1. **O que vai subir está no branch do ambiente.** O Hefesto builda do branch do repositório do ambiente (`getApp` →
52
+ `repository.branch`, em geral `master`). Mudança que só está na `development` não sobe: avise antes.
53
+ 2. **Migrations antes de tudo.** O Hefesto não roda migration ([preparar-app.md](preparar-app.md)). Compare
54
+ `poe status <banco> <ambiente>` com a última de `database/<banco>/migrations/versions/`. Pendente → `poe migrate
55
+ <banco> <ambiente>` **antes** do server: o código novo que lê uma coluna nova quebra contra o banco antigo (em
56
+ geral não só a função nova: toda consulta que carrega a tabela pelo ORM pede a coluna). Migration só de índice não
57
+ tem ordem com o deploy. Em produção, aplicar migration costuma exigir autorização explícita: peça, não contorne.
58
+ 3. **Uma camada por vez: server → GraphQL → front.** O GraphQL novo pede ao server campos que só a versão nova tem; o
59
+ front novo, operações que só o GraphQL novo tem. Cada camada vai em todos os workers juntos; a próxima só começa
60
+ quando **todas** as solicitações da anterior terminaram com sucesso (`getRequest` até `finished=true` em cada
61
+ `requested_id`). Apps sem dependência entre si (um MCP, um worker de fundo) podem ir junto com o server.
62
+ 4. **Falhou uma, para.** Não suba a camada seguinte por cima de uma que falhou: diagnostique ("Deploy falhou") e
63
+ reporte. A exceção é o autodeploy do próprio Hefesto (abaixo).
64
+ 5. **Vários produtos** ("o A, depois o B"): um produto inteiro por vez, na ordem pedida.
65
+
66
+ Para acompanhar várias solicitações, guarde os `requested_id` como saíram da resposta do `deployApp` e consulte com
67
+ eles mesmos; um id corrompido (espaço ou `\r` de fim de linha colado ao copiar entre comandos) dá `VALIDATION_ERROR`
68
+ em `requested_id`, e um laço de espera que trate isso como "ainda não terminou" fica preso para sempre.
69
+
70
+ ## Deploy do próprio Hefesto
71
+
72
+ O **hefesto-server** se reimplanta: antes do rollout ele espera as outras solicitações em execução terminarem (até
73
+ 30 min), e o rollout derruba o processo que executava a etapa Deploy. A reconciliação confere o container no Talos
74
+ depois do reinício e a recuperação conclui a solicitação sozinha (sucesso ou falha) em alguns minutos — até lá,
75
+ `getRequest` mostra a etapa Deploy em andamento. O MCP e o GraphQL do Hefesto também ficam fora do ar por alguns
76
+ segundos durante o próprio deploy: `getRequest` que falhar nessa janela é para repetir, não para desistir.
77
+
78
+ Terminou "Falhou" com "Deploy de `<versão>` do próprio hefesto não confirmado"? Antes de refazer, confira:
79
+ `getApp` do hefesto-server → cada worker com `running_image_tag` = versão do Build da solicitação e o
80
+ `/hefesto/server/health` em 200. Se estiver assim, a versão nova está no ar e só a confirmação se perdeu: não refaça o
81
+ deploy; reporte como concluído e cite a mensagem. Versão antiga no worker → aí sim é falha: siga "Deploy falhou".
41
82
 
42
83
  ## Deploy falhou
43
84
 
@@ -1,25 +1,27 @@
1
1
  ---
2
2
  name: orfeu
3
- description: "SDK Orfeu do servidor de autorização Argos: login/sessão no front Angular (@orfeu/angular), proteção de rota/resolver por operação, nível e permissão em Node (@orfeu/node: Express, Fastify, NestJS, Apollo) e Python (orfeu: FastAPI, Flask, Django, Strawberry), auditoria com trace e repasse de credencial entre serviços. Use ao proteger ou auditar um endpoint, integrar login, e antes de escrever à mão OIDC, refresh, validação de JWT, leitura de Authorization ou checagem de grupo. A estrutura do app/serviço em si é das skills angular, express, apollo ou fastapi."
3
+ description: "SDK Orfeu do servidor de autorização Argos: login/sessão no front Angular (@orfeu/angular) e React (@orfeu/react, React Router v7), proteção de rota/resolver por operação, nível e permissão em Node (@orfeu/node: Express, Fastify, NestJS, Apollo) e Python (orfeu: FastAPI, Flask, Django, Strawberry), auditoria com trace e repasse de credencial entre serviços. Use ao proteger ou auditar um endpoint, integrar login, e antes de escrever à mão OIDC, refresh, validação de JWT, leitura de Authorization ou checagem de grupo. A estrutura do app/serviço em si é das skills angular, express, apollo ou fastapi."
4
4
  ---
5
5
 
6
- # Orfeu — SDK do Argos (Angular, Node, Python)
6
+ # Orfeu — SDK do Argos (Angular, React, Node, Python)
7
7
 
8
- O **Orfeu** é o SDK do **Argos** (servidor de autorização OpenID Connect + RBAC). São três implementações
9
- com o mesmo modelo, versão **1.4.0** — desde a 1.3.0 as três saem sempre juntas, na mesma versão
10
- (`"@orfeu/angular": "^1.4.0"`, `"@orfeu/node": "^1.4.0"`, `orfeu[fastapi]==1.4.0`):
8
+ O **Orfeu** é o SDK do **Argos** (servidor de autorização OpenID Connect + RBAC). Os pacotes têm o mesmo modelo
9
+ e saem sempre juntos, na mesma versão (desde a 1.3.0), hoje a **1.7.1**: `"@orfeu/angular": "^1.7.1"`,
10
+ `"@orfeu/react": "^1.7.1"`, `"@orfeu/node": "^1.7.1"`, `orfeu[fastapi]==1.7.1`.
11
11
 
12
12
  | Pacote | Onde roda | O que faz |
13
13
  |---|---|---|
14
14
  | `@orfeu/angular` (npm) | front Angular | login (Authorization Code + PKCE), token só em memória, refresh pelo cookie do Argos, sessão entre abas, `/view` (rotas/apps do usuário), estado de conexão |
15
+ | `@orfeu/react` (npm, desde a **1.7.1**) | front React 19 | o mesmo do Angular (protocolo e comportamento iguais), com `OrfeuProvider`/hooks e guardas do React Router v7 em `@orfeu/react/router`. Instale pela faixa `^1.7.1` |
15
16
  | `@orfeu/node` (npm) | serviço Node / BFF GraphQL | autentica o serviço no Argos, sincroniza o catálogo de operações, guard por operação (401/403), auditoria em lote, log de operação, trace, `orfeuHeaders` |
16
17
  | `orfeu` (PyPI) | serviço Python | o mesmo do Node para FastAPI/Starlette, Flask, Django e Strawberry, mais o envelope `{status, message, data}` e `orfeu_headers` |
17
18
 
18
19
  **Não escreva à mão** nada que o SDK já faz: PKCE, troca de `code`, refresh, sincronização entre abas,
19
20
  validação de JWT/JWKS, introspecção de token, checagem de grupos, evento de auditoria, `traceparent`.
20
21
 
21
- > **Atualizando um app para a 1.4.0**? Siga o guia da skill `acropole`:
22
+ > **Atualizando um app**? Siga o guia da skill `acropole`:
22
23
  > [../acropole/references/fluxos/atualizar-libs-2026-10.md](../acropole/references/fluxos/atualizar-libs-2026-10.md) — passo a passo por camada, configuração no Argos, verificação e checklist.
24
+ > Da 1.4 para a 1.7.1, o que exige mudança no código está no §8.
23
25
 
24
26
  > **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/orfeu/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
25
27
 
@@ -27,7 +29,7 @@ validação de JWT/JWKS, introspecção de token, checagem de grupos, evento de
27
29
 
28
30
  ```
29
31
  navegador (Angular + @orfeu/angular)
30
- │ x-access-token: <token do usuário> (interceptor do app — a lib não exporta um)
32
+ │ x-access-token: <token do usuário> (interceptor do app; o da lib só troca o token vencido)
31
33
  │ x-client-id / x-route-id (opcionais, correlação)
32
34
  │ sem traceparent → no BFF o evento é entry: true
33
35
  ▼
@@ -42,6 +44,8 @@ serviço Python (orfeu) — audita a própria operação (entry: false, mesmo t
42
44
 
43
45
  - O front só fala com o Argos pelas chamadas da própria lib; nas **suas** APIs, um interceptor do app manda
44
46
  o token cru em `x-access-token` (receita em [references/angular-recipes.md](references/angular-recipes.md) §4).
47
+ O `OrfeuTokenInterceptor` da lib (1.5+) não põe token nenhum: só segura a requisição que já leva o token da
48
+ sessão quando ele está vencido ou quase, espera a renovação e troca pelo novo.
45
49
  - Cada serviço do meio repassa o contexto com `orfeuHeaders(req|ctx)` (Node) / `orfeu_headers(request)`
46
50
  (Python). **Nunca** use esses helpers em chamadas para terceiros: repassariam o token do usuário.
47
51
  - Chamar outro serviço **como o próprio serviço** (job, integração): `credential: false` /
@@ -64,11 +68,18 @@ Python (ver [references/diferencas.md](references/diferencas.md)).
64
68
 
65
69
  | Nível | Quem executa |
66
70
  |---|---|
67
- | `PUBLIC` | todos; nunca bloqueia. Credencial válida fica disponível ao handler; inválida é ignorada. |
68
- | `OPTIONAL` | sem credencial: anônimo. Com credencial: precisa ser válida (senão 401) e vale como `PRIVATE`. |
71
+ | `PUBLIC` | todos; nunca bloqueia e **não valida credencial nenhuma** (1.7+): não lê os headers, não chama o Argos e o handler roda sem usuário. |
72
+ | `OPTIONAL` | sem credencial: anônimo. Com credencial: precisa ser válida (senão 401) e vale como `PRIVATE` (precisa do catálogo de operações). |
69
73
  | `PRIVATE` | usuário autenticado com **ao menos um grupo** — em qualquer client do realm, a menos que o backend ligue `allowedClients`/`allowed_clients` (§4). |
70
74
  | `PROTECTED` | usuário com algum grupo em `allowed_groups` da operação (configurado no Argos). |
71
75
 
76
+ **Rota pública que quer saber quem chamou** (1.7+): até a 1.6 o `PUBLIC` expunha a credencial válida ao handler;
77
+ agora não. Troque por `OPTIONAL` (autoriza: credencial inválida dá 401) ou, só no Node, por **`identify`**, que
78
+ identifica sem autorizar — nunca bloqueia, credencial válida vira `orfeuUser`/`orfeuApiToken`, inválida ou Argos
79
+ fora vira anônimo, e não depende do catálogo: `sdk.identify(id, method?)` (Express), `fastify.orfeuIdentify(id,
80
+ method?)`, `@Identify(id, method?)` (Nest), `createIdentify(client)` ou `operation('public', r, { identify: true })`
81
+ (Apollo). Registra a operação como `public`. O `orfeu` Python não tem `identify`: use `OPTIONAL`.
82
+
72
83
  ## 4. Credenciais e decisão (igual no Node e no Python)
73
84
 
74
85
  Vale a **primeira presente**, nesta ordem; as seguintes nem são lidas. O valor vai **cru**:
@@ -83,16 +94,18 @@ o guard **nunca** lê `Authorization: Bearer` (esse header só aparece nas chama
83
94
 
84
95
  | Situação | Resultado |
85
96
  |---|---|
86
- | `PUBLIC` | sempre executa |
97
+ | `PUBLIC` | sempre executa, anônimo (a credencial nem é lida) |
87
98
  | sem credencial em `OPTIONAL` | executa anônimo |
88
99
  | sem credencial em `PRIVATE`/`PROTECTED` | 401 |
89
100
  | credencial inválida, expirada, revogada ou de outro realm (fora de `PUBLIC`) | 401 — nunca vira anônimo |
90
101
  | credencial válida sem permissão | 403 |
91
- | Argos fora ao validar (JWKS, introspecção) | 401 (anônimo em `PUBLIC`); nunca 500 |
102
+ | Argos fora ao validar (JWKS, introspecção) | 401; nunca 500 (`PUBLIC` não valida, então não depende do Argos) |
92
103
 
93
104
  **Validação do `x-access-token` (1.3+)**: só `RS256`; `exp`, `sub` e `iss` obrigatórios, com o `iss` do realm do
94
105
  token (exato com `issuerUrl`/`issuer_url` = URL pública do Argos; nunca derive do `authorizerUrl`); token **de
95
- aplicação** (`type: "app"`) não vale como usuário. Opções de endurecimento, iguais no Node e no Python:
106
+ aplicação** (`type: "app"`) não vale como usuário. `exp`, `nbf` e `iat` têm tolerância de relógio de 30 s (1.6+:
107
+ `clockToleranceSec`/`clock_tolerance_s`; `0` volta à conferência exata). Opções de endurecimento, iguais no Node e
108
+ no Python:
96
109
 
97
110
  | Opção (Node / Python) | Variável, sem a opção | Quando |
98
111
  |---|---|---|
@@ -149,6 +162,10 @@ bootstrap, rotas de callback/logoff, fluxos, estado para a UI, erros, SSR.
149
162
  - [references/angular-armadilhas.md](references/angular-armadilhas.md) — loop de login, 401, CORS, duas cópias da lib.
150
163
  - Padrões gerais do app: skill `angular`. Shell, layout e componentes: skill `trismegisto`.
151
164
 
165
+ **React (front)** → [references/react.md](references/react.md) — `createAuthClient`, `OrfeuProvider`, hooks
166
+ (`useAuth`, `useAuthFetch`…), guardas do React Router v7 (`authMiddleware`, `requireAuth`, `callbackLoader`),
167
+ `createAuthFetch`, testes e armadilhas. Shell pronto (`@trismegisto/react/spine`): skill `trismegisto`.
168
+
152
169
  **Node (Express, Fastify, NestJS, Apollo)** → [references/node.md](references/node.md) — configuração, ordem de
153
170
  subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
154
171
  - [references/node-api.md](references/node-api.md) — todos os exports dos 5 pontos de import.
@@ -166,13 +183,14 @@ subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
166
183
  - Estrutura do serviço: skill `fastapi`. Strawberry, Django e Flask: ainda não cobertos por skill
167
184
  de padrões.
168
185
 
169
- **Diferenças entre as três implementações** (comportamento atual: 1.4.0) →
186
+ **Diferenças entre as implementações** (comportamento atual: 1.7.1) →
170
187
  [references/diferencas.md](references/diferencas.md). Leia antes de supor que algo do Node vale igual no Python.
171
188
 
172
189
  ## 7. Não faça
173
190
 
174
191
  - Não leia `Authorization`/`Bearer`, não valide JWT nem confira grupos à mão: use o guard do SDK.
175
192
  - Não deixe rota/resolver de negócio sem operação; não use `PUBLIC` para "resolver depois".
193
+ - Não leia `orfeuUser`/`request.state.user` numa rota `PUBLIC` (1.7+ vem sempre vazio): use `OPTIONAL` ou `identify`.
176
194
  - Não declare operações depois da subida.
177
195
  - Não grave `ctx.orfeuUser` à mão no Apollo: a partir da 1.0.1 isso responde 401. Usuário que o app já
178
196
  validou entra por `trustUser(ctx, claims)`.
@@ -186,3 +204,15 @@ subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
186
204
  - Subscription do Apollo termina no `exp` do token (1.3+): o front reconecta e **reassina**.
187
205
  - Não repasse credencial com `orfeuHeaders`/`orfeu_headers` para fora dos seus serviços.
188
206
  - Não ponha segredo (o `secret` do serviço vem de variável de ambiente/cofre) em código, log ou `details`.
207
+
208
+ ## 8. Da 1.4 para a 1.7.1 (o que muda no código)
209
+
210
+ | Versão | Pacote | Mudança | O que fazer |
211
+ |---|---|---|---|
212
+ | 1.5.0 | `@orfeu/angular` | `OrfeuTokenInterceptor` (registrado pelo `provideAuth`) segura a requisição que leva o token da sessão vencido ou quase e troca pelo renovado; `getValidToken()` e `tokenStale` | com `withInterceptors([...])` (sem `withInterceptorsFromDi()`), ponha `orfeuTokenInterceptor` da lib **depois** do interceptor que põe o `x-access-token`; fora do `HttpClient` (WebSocket, `fetch`), `await auth.getValidToken()` em vez de `getToken()` |
213
+ | 1.6.0 | `@orfeu/angular` | logout limpa `profile`/`badge`/`badges`; `isJwtExpired` deprecated | troque `isJwtExpired` por `tokenStale`/`getValidToken()` |
214
+ | 1.6.0 | `@orfeu/node`, `orfeu` | tolerância de relógio de 30 s nos JWT (`clockToleranceSec`/`clock_tolerance_s`, `DEFAULT_CLOCK_TOLERANCE_SEC`/`_S`); aviso no log com `tlsVerify: false`/`tls_verify=False`; caches por token com teto | nada (para a conferência exata, `0`) |
215
+ | 1.6.0 | `orfeu` (FastAPI) | OpenAPI anotado com o `@operation` de cada rota (`summary` `<id> · <nível>`, `x-orfeu-operation`); `document_operations=False` desliga | nada; a 1.7.1 corrige as rotas de `include_router` no FastAPI ≥ 0.137 |
216
+ | 1.7.0 | `@orfeu/angular` | id_token conferido (`iss`, `aud` com o `clientId`, `exp` com 30 s de tolerância); erro `invalid_id_token`; `AuthConfig.issuer` opcional | nada, se a descoberta do realm responde; senão, passe `issuer` |
217
+ | 1.7.0 | `@orfeu/node`, `orfeu` | **`PUBLIC` não valida credencial**: handler sem usuário (`request.state.user` é `None`) | rota pública que lê a identidade: `OPTIONAL`, ou `identify` (só Node, §3) |
218
+ | 1.7.1 | `@orfeu/react` | primeira versão publicada | [references/react.md](references/react.md) |
@@ -1,9 +1,12 @@
1
- # API — @orfeu/angular 1.4.0
1
+ # API — @orfeu/angular 1.7.1
2
2
 
3
- > Conferida contra o código-fonte da 1.4.0 (`public-api.ts` de cada ponto de import). Tudo o que não está
3
+ > Conferida contra o código-fonte da 1.7.1 (`public-api.ts` de cada ponto de import). Tudo o que não está
4
4
  > aqui é interno: não importe de caminhos profundos (`@orfeu/angular/core/src/...`). Anda junto com
5
- > `@orfeu/node` e `orfeu`; a 1.3.0 mudou o callback com `?error` (state conferido antes de tudo, mensagem
6
- > genérica) e o `logout()` (`Promise<boolean>`, `logoutFailed$`).
5
+ > `@orfeu/react`, `@orfeu/node` e `orfeu`. Marcos: 1.3.0 — callback com `?error` (state conferido antes de tudo,
6
+ > mensagem genérica) e `logout()` (`Promise<boolean>`, `logoutFailed$`); 1.5.0 — `OrfeuTokenInterceptor`,
7
+ > `getValidToken()`, `tokenStale`; 1.6.0 — logout limpa `profile`/`badge`/`badges`, `isJwtExpired` deprecated;
8
+ > 1.7.0 — id_token conferido (`iss`, `aud`, `exp`), `AuthConfig.issuer`, `invalid_id_token`. A 1.4.0 e a 1.7.1 não
9
+ > mudaram esta lib (só alinharam a versão).
7
10
 
8
11
  ## `@orfeu/angular`
9
12
 
@@ -16,6 +19,8 @@ interface AuthConfig {
16
19
  /** @deprecated ignorado; o fluxo é sempre `code`. Valor diferente de 'code' gera aviso em dev. */
17
20
  responseType?: string;
18
21
  scope: string; // ex.: 'openid profile'
22
+ /** 1.7+: `iss` esperado do id_token, como o Argos emite (`<servidor>/realms/<realm>`). Opcional. */
23
+ issuer?: string;
19
24
  }
20
25
 
21
26
  const AUTH_CONFIG: InjectionToken<AuthConfig>;
@@ -27,12 +32,26 @@ Reexporta `AUTH_CONFIG` e `AuthConfig`.
27
32
 
28
33
  ### `provideAuth(config: AuthConfig, options?: AuthOptions): EnvironmentProviders`
29
34
 
30
- Fornece `AUTH_CONFIG` e `AUTH_OPTIONS` (com `eagerInit` resolvido) e, com `eagerInit !== false`,
31
- `provideAppInitializer(() => inject(AuthorizationService).initialize())`.
35
+ Fornece `AUTH_CONFIG` e `AUTH_OPTIONS` (com `eagerInit` resolvido), registra o `OrfeuTokenInterceptor` em
36
+ `HTTP_INTERCEPTORS` (1.5+; só tem efeito com `provideHttpClient(withInterceptorsFromDi())`) e, com
37
+ `eagerInit !== false`, `provideAppInitializer(() => inject(AuthorizationService).initialize())`.
32
38
 
33
39
  Alternativa sem `provideAuth`: `{ provide: AUTH_CONFIG, useValue: config }` (+ opcionalmente
34
- `{ provide: AUTH_OPTIONS, useValue: options }`). Nesse caso **não há** initializer: o `PrivateGuard` faz o
35
- refresh na primeira rota protegida.
40
+ `{ provide: AUTH_OPTIONS, useValue: options }`). Nesse caso **não há** initializer nem interceptor: o
41
+ `PrivateGuard` faz o refresh na primeira rota protegida.
42
+
43
+ ### `OrfeuTokenInterceptor` / `orfeuTokenInterceptor` (1.5+)
44
+
45
+ Requisição que leva o token da sessão (em qualquer header, puro ou como `Bearer <token>`) quando ele está vencido
46
+ ou a menos de 10 s do vencimento (`tokenStale`): espera `getValidToken()` e troca o token velho pelo novo nesses
47
+ headers. As demais passam direto, sem atraso. **Não acrescenta** token a requisição nenhuma: quem põe o
48
+ `x-access-token` nas APIs do app é um interceptor do próprio app ([angular-recipes.md](angular-recipes.md) §4), que
49
+ vem **antes** dele na lista.
50
+
51
+ | Export | Uso |
52
+ |---|---|
53
+ | `OrfeuTokenInterceptor` | classe (`HttpInterceptor`), registrada pelo `provideAuth`; vale com `withInterceptorsFromDi()` |
54
+ | `orfeuTokenInterceptor` | `HttpInterceptorFn`, para `provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor]))` |
36
55
 
37
56
  ### `AuthOptions` / `AUTH_OPTIONS`
38
57
 
@@ -65,8 +84,10 @@ Estado:
65
84
  | `badgeChanged$` | `Observable<void>` | emite quando o badge ativo muda (login, refresh, troca, outra aba). Sem valor inicial. |
66
85
  | `badge` | `Badge \| null` (getter) | badge cujo `id` é a claim `badge_id`, procurado na claim `badges`. |
67
86
  | `badges` | `Badge[]` (getter) | claim `badges` (ou `[]`). |
68
- | `profile` | `UserProfile` (getter) | `{ name, role, picture }` das claims de mesmo nome (`null` se ausentes). |
69
- | `getToken()` | `string \| null` | token de acesso atual (pode estar vencido; veja `tokenExpired`). Só em memória. |
87
+ | `profile` | `UserProfile` (getter) | `{ name, role, picture }` das claims de mesmo nome (`null` se ausentes). O logout limpa `profile`, `badge` e `badges` (1.6+). |
88
+ | `getToken()` | `string \| null` | token de acesso atual (pode estar vencido; veja `tokenExpired`). Só em memória. Para montar uma requisição fora do `HttpClient`, prefira `getValidToken()`. |
89
+ | `tokenStale` | `boolean` (getter, 1.5+) | há token e ele está vencido ou a menos de 10 s do vencimento. Critério de `getValidToken()` e do `OrfeuTokenInterceptor`. |
90
+ | `getValidToken()` | `Promise<string \| null>` (1.5+) | token pronto para uma requisição: se `tokenStale`, dispara/espera a renovação (até 10 s). **Nunca rejeita**: sem sessão devolve `null`; com o Argos fora, em backoff ou recusando o refresh, devolve o token que houver, sem um refresh por chamada. No SSR devolve o token atual. |
70
91
  | `logoutFailed$` | `Observable<OrfeuAuthError>` | (1.3+) emite `OrfeuAuthError('logout_failed')` quando o `GET /logout` falhou duas vezes. A sessão **continua**; mostre o erro e ofereça tentar de novo. Sem valor inicial. |
71
92
 
72
93
  `type ConnectionState = 'online' | 'reconnecting' | 'offline' | 'reauthorizing'`:
@@ -104,7 +125,11 @@ Métodos:
104
125
  `error_description` (de terceiros) **nunca** entra na mensagem.
105
126
  3. Sem `params.code` ou sem verifier gravado: rejeita `invalid_callback`.
106
127
  4. Segue como `token({ grant_type: 'authorization_code', code, redirect_uri, client_id, code_verifier, state })`:
107
- `state` divergente/ausente → `state_mismatch`; nonce divergente → `nonce_mismatch`.
128
+ `state` divergente/ausente → `state_mismatch`; nonce divergente → `nonce_mismatch`; id_token com `iss`
129
+ diferente do emissor esperado (`AuthConfig.issuer` ou o `issuer` da descoberta do realm), `aud` sem o
130
+ `clientId`, ou `exp` ausente ou vencido há mais de 30 s → `invalid_id_token` (1.7+; vale para todo id_token
131
+ recebido, com ou sem nonce guardado). Nos dois últimos casos limpa verifier/state/nonce e a URL de retorno, não
132
+ aplica o token e não mexe numa sessão existente.
108
133
 
109
134
  `redirect = false`: aplica o token mas **não** carrega o `/view` nem navega (o app decide).
110
135
 
@@ -141,7 +166,8 @@ Construtor: `new PrivateGuard(auth: AuthorizationService)`. Use direto nos array
141
166
 
142
167
  ```ts
143
168
  type OrfeuAuthErrorCode = 'state_mismatch' | 'nonce_mismatch' | 'invalid_callback' | 'callback_error' | 'not_authenticated'
144
- | 'logout_failed'; // 1.3+
169
+ | 'logout_failed' // 1.3+
170
+ | 'invalid_id_token'; // 1.7+
145
171
  class OrfeuAuthError extends Error { readonly code: OrfeuAuthErrorCode; name: 'OrfeuAuthError'; }
146
172
  ```
147
173
 
@@ -190,7 +216,7 @@ Sem dependência de Angular.
190
216
  | Função | Comportamento |
191
217
  |---|---|
192
218
  | `decodeJwt<T = any>(token: string): T \| null` | payload do JWT (base64url + UTF-8), **sem verificar assinatura**. `null` se inválido. |
193
- | `isJwtExpired(token: string): boolean` | `true` se `exp` no passado, sem `exp` ou token inválido. Usa o relógio local direto (a lib, internamente, prefere `exp − iat`). |
219
+ | `isJwtExpired(token: string): boolean` | **Deprecated (1.6+)**, sai na próxima major: sem uso na lib e sem tolerância de relógio. `true` se `exp` no passado, sem `exp` ou token inválido. Use `AuthorizationService.tokenStale`/`getValidToken()`. |
194
220
  | `generatePkcePair(): Promise<{ verifier: string; challenge: string }>` | par PKCE S256. |
195
221
  | `generateCodeVerifier(): string` | 32 bytes aleatórios em base64url (43 caracteres). |
196
222
  | `generateCodeChallenge(verifier: string): Promise<string>` | `base64url(SHA-256(verifier))`. |
@@ -1,4 +1,4 @@
1
- # Armadilhas e erros comuns — @orfeu/angular 1.4.0
1
+ # Armadilhas e erros comuns — @orfeu/angular 1.7.1
2
2
 
3
3
  Cada item: sintoma → causa → o que fazer.
4
4
 
@@ -10,6 +10,13 @@ Cada item: sintoma → causa → o que fazer.
10
10
  - O componente do callback não chama `handleCallback()` (ou chama `authorize()` de novo no `ngOnInit`).
11
11
  - O `redirectUrl` aponta para uma rota que não existe e cai no `**` protegido.
12
12
 
13
+ **Login falha com `invalid_id_token` depois de atualizar para a 1.7.** O id_token passou a ser conferido: `iss`
14
+ igual ao emissor esperado, `aud` com o `clientId` e `exp` válido (30 s de tolerância).
15
+ - `AuthConfig.issuer` errado (derivado de um endereço interno, com barra no fim ou sem `/realms/<realm>`): use o
16
+ `iss` exato que o Argos emite (`<servidor>/realms/<realm>`), ou tire a opção e deixe a lib usar a descoberta.
17
+ - Relógio da máquina muito adiantado ou atrasado (mais de 30 s): o `exp` do id_token parece vencido.
18
+ - Teste com id_token montado à mão: inclua `iss`, `aud` (o `clientId`) e `exp`.
19
+
13
20
  **`invalid_callback` ao abrir o callback.** A página foi recarregada (o `code` e o verifier já foram usados e
14
21
  limpos), aberta em outra aba ou o `sessionStorage` foi limpo. Ofereça "Entrar de novo" (`authorize('/')`).
15
22
 
@@ -43,6 +50,16 @@ não `location.href`.
43
50
  **App chama `logout()` em erro de API/401 e o usuário perde o trabalho.** Não faça isso. Use o interceptor
44
51
  com nova tentativa (`angular-recipes.md` §4) e o banner de conexão (`angular-recipes.md` §5).
45
52
 
53
+ **401 na primeira requisição depois de a aba voltar do segundo plano.** O navegador segurou os timers e a
54
+ renovação agendada não rodou a tempo. Desde a 1.5 o `OrfeuTokenInterceptor` resolve isso, mas só se estiver na
55
+ cadeia: com `withInterceptors([...])` (sem `withInterceptorsFromDi()`), inclua o `orfeuTokenInterceptor` da lib
56
+ **depois** do interceptor que põe o `x-access-token`. Fora do `HttpClient` (WebSocket, `fetch`), use
57
+ `await auth.getValidToken()` em vez de `getToken()`.
58
+
59
+ **Interceptor do app com o mesmo nome do da lib.** Receitas antigas chamavam o interceptor do app de
60
+ `orfeuTokenInterceptor`; desde a 1.5 a lib exporta um com esse nome. Renomeie o do app (`apiTokenInterceptor`) para
61
+ não importar um no lugar do outro.
62
+
46
63
  **Clicou em "Sair" e nada aconteceu.** O `GET /logout` falhou duas vezes (rede, 5xx, CORS — a origem do app
47
64
  precisa estar nas `redirect_uris` do client) e a 1.3 manteve a sessão de propósito: `logoutFailed$` emitiu e
48
65
  `logout()` resolveu `false`. Com o `@trismegisto/spine` ≥ 2.1.2 o aviso sai sozinho (o `SpineLogoutService` assina
@@ -1,6 +1,6 @@
1
- # Receitas — @orfeu/angular 1.4.0
1
+ # Receitas — @orfeu/angular 1.7.1
2
2
 
3
- Todas usam a API real da 1.4.0 ([angular-api.md](angular-api.md)). Componentes standalone, `inject()`, controle de fluxo
3
+ Todas usam a API real da 1.7.1 ([angular-api.md](angular-api.md)). Componentes standalone, `inject()`, controle de fluxo
4
4
  `@if`/`@for`. Troque textos e estilos pelos do app (design system, i18n).
5
5
 
6
6
  ## 1. Bootstrap
@@ -10,14 +10,15 @@ Todas usam a API real da 1.4.0 ([angular-api.md](angular-api.md)). Componentes s
10
10
  import { ApplicationConfig } from '@angular/core';
11
11
  import { provideHttpClient, withInterceptors } from '@angular/common/http';
12
12
  import { provideRouter } from '@angular/router';
13
- import { provideAuth } from '@orfeu/angular/core';
13
+ import { orfeuTokenInterceptor, provideAuth } from '@orfeu/angular/core';
14
14
  import { environment } from '../environments/environment';
15
15
  import { routes } from './app.routes';
16
- import { orfeuTokenInterceptor } from './core/orfeu-token.interceptor';
16
+ import { apiTokenInterceptor } from './core/api-token.interceptor';
17
17
 
18
18
  export const appConfig: ApplicationConfig = {
19
19
  providers: [
20
- provideHttpClient(withInterceptors([orfeuTokenInterceptor])),
20
+ // O do app põe o x-access-token; o da lib (1.5+), DEPOIS dele, troca o token vencido pelo renovado.
21
+ provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor])),
21
22
  provideRouter(routes),
22
23
  provideAuth({
23
24
  authority: environment.argosUrl, // ex.: 'https://argos.exemplo.com' (sem barra no fim)
@@ -32,6 +33,11 @@ export const appConfig: ApplicationConfig = {
32
33
 
33
34
  Com SSR, não use `location` no config (não existe no servidor): ponha a URL absoluta no `environment`.
34
35
 
36
+ Com `provideHttpClient(withInterceptorsFromDi())` o `provideAuth` já registra o `OrfeuTokenInterceptor` da lib (versão
37
+ de classe); com `withInterceptors([...])`, como acima, ponha o `orfeuTokenInterceptor` na lista, **depois** do
38
+ interceptor que acrescenta o token (ele só age em requisições que já levam o token da sessão). Se o
39
+ `AuthConfig.issuer` não for passado, a lib busca o emissor esperado do id_token na descoberta do realm (1.7+).
40
+
35
41
  ## 2. Rotas
36
42
 
37
43
  ```ts
@@ -146,7 +152,7 @@ protected async sair(): Promise<void> {
146
152
  ```
147
153
 
148
154
  Isso vale para app **sem** spine (ou assine o `logoutFailed$` uma vez, para um aviso único em todo `logout()`).
149
- App com `@trismegisto/spine` ≥ 2.1.2: o `SpineLogoutService` (`@trismegisto/spine/layout`) já assina o `logoutFailed$`
155
+ App com `@trismegisto/spine` ≥ 2.1.2: o `SpineLogoutService` (`@trismegisto/angular/spine/layout`) já assina o `logoutFailed$`
150
156
  e mostra o aviso para **qualquer** `logout()`, inclusive o do app — não mostre toast próprio (sairia em dobro). Num
151
157
  botão próprio, chame `inject(SpineLogoutService).logout()`: mesmo aviso e só apaga os recentes quando a saída deu certo.
152
158
 
@@ -156,8 +162,13 @@ As APIs com `@orfeu/node` leem o token cru em `x-access-token`. Opcionalmente, `
156
162
  deste front) e `x-route-id` (o `routed_id` da página atual no `/view`) entram na auditoria — só são gravados
157
163
  se forem GUIDs.
158
164
 
165
+ A lib não acrescenta o token às APIs do app (só às próprias chamadas ao Argos): isso é deste interceptor. O
166
+ `orfeuTokenInterceptor` da lib (1.5+) é outra coisa — segura a requisição que já leva o token vencido ou quase,
167
+ espera a renovação e troca pelo novo (aba em segundo plano, máquina suspensa). Não dê ao interceptor do app o mesmo
168
+ nome do da lib.
169
+
159
170
  ```ts
160
- // core/orfeu-token.interceptor.ts
171
+ // core/api-token.interceptor.ts
161
172
  import { HttpErrorResponse, HttpInterceptorFn, HttpRequest } from '@angular/common/http';
162
173
  import { inject } from '@angular/core';
163
174
  import { AUTH_CONFIG, AuthorizationService } from '@orfeu/angular/core';
@@ -167,7 +178,7 @@ import { environment } from '../../environments/environment';
167
178
  /** Só as APIs DESTE app. Nunca o Argos (preflight CORS com header estranho quebra o refresh) nem terceiros (vazaria o token). */
168
179
  const API_PREFIXES: string[] = [environment.apiUrl, '/api/'];
169
180
 
170
- export const orfeuTokenInterceptor: HttpInterceptorFn = (req, next) => {
181
+ export const apiTokenInterceptor: HttpInterceptorFn = (req, next) => {
171
182
  if (!API_PREFIXES.some(prefix => req.url.startsWith(prefix))) return next(req);
172
183
 
173
184
  const auth = inject(AuthorizationService);
@@ -200,8 +211,9 @@ export const orfeuTokenInterceptor: HttpInterceptorFn = (req, next) => {
200
211
  recusou, reautoriza (veja §5/§6).
201
212
  - Para mandar `x-route-id`, guarde o `routed_id` da página atual num serviço do app (ex.: ao montar o
202
213
  breadcrumb, §8) e acrescente-o em `setHeaders`.
203
- - GraphQL por WebSocket: mande o mesmo token em `connectionParams` (`{ 'x-access-token': token }`), lido na
204
- conexão; reconecte quando o token mudar.
214
+ - GraphQL por WebSocket: mande o token em `connectionParams` (`{ 'x-access-token': await auth.getValidToken() }`,
215
+ 1.5+: espera a renovação se o token estiver vencido ou quase), lido na conexão; reconecte quando o token mudar.
216
+ O mesmo vale para `fetch` fora do `HttpClient`.
205
217
 
206
218
  ## 5. Banner de conexão
207
219
 
@@ -441,7 +453,8 @@ import { TestBed } from '@angular/core/testing';
441
453
  import { HttpClient, provideHttpClient, withInterceptors } from '@angular/common/http';
442
454
  import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
443
455
  import { provideRouter } from '@angular/router';
444
- import { AuthorizationService, provideAuth } from '@orfeu/angular/core';
456
+ import { AuthorizationService, orfeuTokenInterceptor, provideAuth } from '@orfeu/angular/core';
457
+ import { apiTokenInterceptor } from './core/api-token.interceptor';
445
458
 
446
459
  const config = {
447
460
  authority: 'https://argos.test', realmId: 'realm-1', clientId: 'app-client',
@@ -459,7 +472,7 @@ beforeEach(() => {
459
472
  TestBed.configureTestingModule({
460
473
  providers: [
461
474
  provideRouter([]),
462
- provideHttpClient(withInterceptors([orfeuTokenInterceptor])),
475
+ provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor])),
463
476
  provideHttpClientTesting(),
464
477
  provideAuth(config, { eagerInit: false, expiryLog: false, autoReauthorize: false }),
465
478
  ],