@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.
- package/README.md +14 -11
- package/agents/revisor-orfeu.md +2 -1
- package/bin/install.js +41 -9
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +2 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
- package/skills/angular/SKILL.md +4 -3
- package/skills/angular/references/armadilhas.md +3 -3
- package/skills/angular/references/dados.md +3 -3
- package/skills/angular/references/estrutura.md +6 -5
- package/skills/angular/references/features.md +5 -5
- package/skills/angular/references/testes-build.md +1 -1
- package/skills/auto-servico/SKILL.md +18 -14
- package/skills/auto-servico/references/roteiros.md +1 -1
- package/skills/auto-servico/references/tools.md +1 -1
- package/skills/express/references/dados.md +4 -1
- package/skills/express/references/estrutura.md +2 -1
- package/skills/fastapi/references/banco.md +6 -2
- package/skills/fastapi/references/estrutura.md +1 -1
- package/skills/hefesto/SKILL.md +13 -6
- package/skills/hefesto/references/diagnostico.md +1 -0
- package/skills/hefesto/references/mcp-roteiros.md +48 -7
- package/skills/orfeu/SKILL.md +43 -13
- package/skills/orfeu/references/angular-api.md +39 -13
- package/skills/orfeu/references/angular-armadilhas.md +18 -1
- package/skills/orfeu/references/angular-recipes.md +25 -12
- package/skills/orfeu/references/angular.md +37 -15
- package/skills/orfeu/references/diferencas.md +17 -8
- package/skills/orfeu/references/node-api.md +41 -9
- package/skills/orfeu/references/node-armadilhas.md +16 -2
- package/skills/orfeu/references/node-recipes.md +13 -4
- package/skills/orfeu/references/node.md +31 -12
- package/skills/orfeu/references/python-api.md +41 -16
- package/skills/orfeu/references/python-recipes.md +13 -9
- package/skills/orfeu/references/python.md +33 -12
- package/skills/orfeu/references/react.md +133 -0
- package/skills/orquestracao/SKILL.md +3 -1
- package/skills/orquestracao/scripts/coord.sh +10 -2
- package/skills/trismegisto/SKILL.md +89 -35
- package/skills/trismegisto/references/angular-api.md +4548 -344
- package/skills/trismegisto/references/angular-exports.md +8275 -2579
- package/skills/trismegisto/references/angular-recipes.md +327 -6
- package/skills/trismegisto/references/angular-types.md +92 -0
- package/skills/trismegisto/references/angular.md +96 -16
- package/skills/trismegisto/references/catalogo/icones.json +7 -0
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
- package/skills/trismegisto/references/catalogo/tokens.json +114 -0
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5904 -1361
- package/skills/trismegisto/references/spine-recipes.md +140 -46
- package/skills/trismegisto/references/spine.md +121 -49
- 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
|
|
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
|
|
package/skills/hefesto/SKILL.md
CHANGED
|
@@ -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": "${
|
|
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
|
|
160
|
-
|
|
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
|
|
12
|
-
`running_image_tag`
|
|
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.
|
|
18
|
-
|
|
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
|
|
39
|
-
|
|
40
|
-
|
|
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
|
|
package/skills/orfeu/SKILL.md
CHANGED
|
@@ -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).
|
|
9
|
-
|
|
10
|
-
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
1
|
+
# API — @orfeu/angular 1.7.1
|
|
2
2
|
|
|
3
|
-
> Conferida contra o código-fonte da 1.
|
|
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
|
|
6
|
-
> genérica) e
|
|
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)
|
|
31
|
-
`
|
|
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
|
|
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'
|
|
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.
|
|
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.
|
|
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.
|
|
1
|
+
# Receitas — @orfeu/angular 1.7.1
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.
|
|
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 {
|
|
16
|
+
import { apiTokenInterceptor } from './core/api-token.interceptor';
|
|
17
17
|
|
|
18
18
|
export const appConfig: ApplicationConfig = {
|
|
19
19
|
providers: [
|
|
20
|
-
|
|
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/
|
|
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
|
|
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
|
|
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
|
],
|