@acropole/skills 1.4.0 → 1.5.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 CHANGED
@@ -13,7 +13,7 @@ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` enc
13
13
 
14
14
  | Skill | Assunto | Exemplo de pedido que a dispara |
15
15
  | --- | --- | --- |
16
- | `acropole` | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos `app-novo`, `tela-nova`, `endpoint-novo`, `revisar`, `doctor` | `/acropole`, "cria a estrutura do app novo", "esse app segue o padrão?" |
16
+ | `acropole` | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos `app-novo`, `tela-nova`, `endpoint-novo`, `revisar`, `doctor`, `atualizar-libs` | `/acropole`, "cria a estrutura do app novo", "esse app segue o padrão?" |
17
17
  | `angular` | Estrutura dos apps Angular, bootstrap com o spine, telas por `router_id`, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" |
18
18
  | `trismegisto` | Interface com o design system (`@trismegisto/*`, componentes `hm-*`, tokens `--hm-*`, tema, ícones, a11y) e o shell spine | "troca essa tabela por um data grid", "o botão some no tema escuro" |
19
19
  | `orfeu` | SDK Orfeu: login/sessão no front, operações e níveis no backend, auditoria, `traceparent`, propagação entre serviços | "protege essa rota", "o usuário toma 403", "audita a exclusão" |
@@ -52,6 +52,7 @@ O Claude Code chama o revisor quando a tarefa bate com a descrição dele; você
52
52
  | `/acropole endpoint-novo` | Rota/resolver (fastapi, express ou apollo) + operação do Orfeu + propagação de headers + auditoria + teste |
53
53
  | `/acropole revisar [caminho]` | Roda os verificadores sobre o diff/arquivos e chama os revisores. Relata; não corrige sem pedido |
54
54
  | `/acropole doctor [pasta]` | Diagnostica versões `@trismegisto/*`, cópias de `@orfeu/angular`, ordem de `styles`, `provideHttpClient(withInterceptorsFromDi())`, Dockerfile, `orfeu` Python. Achados em `corrige` (aplicados com `--fix`, só se você pedir), `avisa` e `pergunta` |
55
+ | `/acropole atualizar-libs [pasta]` | Guia para levar um app às libs de 2026-10 (`@trismegisto/*` 2.1.2, `@orfeu/*` e `orfeu` 1.4.0): o que muda em cada camada, configuração no Argos, variáveis novas, verificação, armadilhas e checklist |
55
56
 
56
57
  ## Verificadores
57
58
 
@@ -151,7 +152,8 @@ Trusted Publishing (OIDC, sem `NPM_TOKEN` no repositório), e ninguém cria tag
151
152
  **Environment `release`.** O job de publicação usa o environment `release`, criado no GitHub **sem regras de
152
153
  proteção** (repo privado em conta Free, sem *Required reviewers*). Ele existe porque é o nome cadastrado no
153
154
  Trusted Publisher do npm (dono `konvndor`, repositório `acropole`, workflow `release.yml`, environment `release`):
154
- o npm só aceita o token OIDC vindo dele. A aprovação é o clique em *Run workflow*.
155
+ o npm só aceita o token OIDC vindo dele. A aprovação é o clique em *Run workflow*. O repositório é privado: o npm
156
+ não gera proveniência e o `package.json` publicado não leva `repository` (não acrescente).
155
157
 
156
158
  **Primeira publicação (1.0.0).** O Trusted Publisher só pode ser usado depois que o pacote existe no npm, então a
157
159
  1.0.0 sai pelo script local, com token:
package/package.json CHANGED
@@ -1,12 +1,11 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e os MCPs do auto-serviço do Argos e de deploy do Hefesto. Instale com: npx @acropole/skills",
5
5
  "bin": { "acropole-skills": "bin/install.js" },
6
6
  "files": ["bin", "skills", "agents"],
7
7
  "engines": { "node": ">=18" },
8
8
  "license": "MIT",
9
- "repository": { "type": "git", "url": "git+https://github.com/konvndor/acropole.git" },
10
9
  "keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review", "mcp", "argos"],
11
10
  "scripts": {
12
11
  "bump": "node scripts/bump.mjs",
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: acropole
3
- description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
3
+ description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, diagnóstico (doctor) e atualização das libs (@trismegisto 2.1.2, Orfeu 1.4.0). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, um diagnóstico de versões/configuração do projeto, ou subir as libs @trismegisto/@orfeu/orfeu de um app.
4
4
  user-invocable: true
5
- argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor] [alvo]"
5
+ argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor | atualizar-libs] [alvo]"
6
6
  ---
7
7
 
8
8
  # acropole — fluxos entre as skills
@@ -22,6 +22,7 @@ dependências, scripts, testes mínimos, pendências e checklist). Divergência
22
22
  | `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
23
23
  | `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
24
24
  | `/acropole doctor [pasta]` | Diagnostica o projeto (versões, `angular.json`, `provideHttpClient`, Dockerfile, `orfeu` Python) | [references/fluxos/doctor.md](references/fluxos/doctor.md) |
25
+ | `/acropole atualizar-libs [pasta]` | Atualiza um app para as libs de 2026-10 (`@trismegisto/*` 2.1.2, `@orfeu/*` e `orfeu` 1.4.0): front, gateway, server, Argos, variáveis, verificação, armadilhas e checklist | [references/fluxos/atualizar-libs-2026-10.md](references/fluxos/atualizar-libs-2026-10.md) |
25
26
 
26
27
  Com argumento: carregue **só** o playbook do comando e siga-o. Argumento desconhecido: mostre a tabela
27
28
  acima e pergunte.
@@ -63,6 +64,7 @@ acima e pergunte.
63
64
  | agente de IA no Hefesto, MCP de deploy, "faz o deploy/redeploy pelo MCP", "por que o deploy falhou" com as tools do hefesto-mcp | hefesto |
64
65
  | "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
65
66
  | versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
67
+ | atualizar/subir `@trismegisto/*`, `@orfeu/*` ou `orfeu` de um app, `allowedClients`, "conta e segurança" do spine | este fluxo `atualizar-libs` (+ as skills de cada camada) |
66
68
 
67
69
  Ainda não coberto por nenhuma skill: React, Strawberry, Fastify, Django, Flask. Diga isso ao usuário em
68
70
  vez de aplicar por analogia o padrão de outra stack.
@@ -0,0 +1,382 @@
1
+ # Fluxo: atualizar um app para as libs de 2026-10
2
+
3
+ Guia para levar **qualquer** app da plataforma às versões publicadas em 2026-10-13:
4
+
5
+ | Pacote | Versão | Regra |
6
+ | --- | --- | --- |
7
+ | `@trismegisto/*` (tokens, icons, primitives, core, angular, charts, maps, spine) | **2.1.2** | as 8 andam juntas: todas na mesma versão |
8
+ | `@orfeu/angular`, `@orfeu/node`, `orfeu` (PyPI) | **1.4.0** | as 3 andam juntas desde a 1.3.0 |
9
+ | `@acropole/skills` | **1.5.0** | onde este guia mora |
10
+
11
+ O que muda de comportamento veio na **2.1.0** e na **1.3.0** (auditoria de segurança). A **2.1.2** do spine trata
12
+ a falha de logout e monta a pilha de toasts (§2.3 item 8); a **1.4.0** do Orfeu traz a validação do **token de
13
+ serviço** (máquina-a-máquina), que a 1.3 passou a recusar como usuário (§3.3). A skill `orfeu` já descreve a 1.4.0 e
14
+ os catálogos de API da skill `trismegisto` (`*-api.md`, `angular-exports.md`) já estão na 2.1.
15
+
16
+ Faça camada por camada, na ordem do documento, e rode a verificação (§7) de cada uma antes de ir para a próxima.
17
+ Não mescle nada sem o PR do repositório do app (branch → `development` → `master`).
18
+
19
+ ## 1. Para quem é e pré-requisitos
20
+
21
+ Para o agente que vai atualizar um app (front Angular com spine, gateway Apollo/Express com `@orfeu/node`, server
22
+ FastAPI com `orfeu`, pasta `database/`). Antes de mexer:
23
+
24
+ - **Skills em dia**: `npx @acropole/skills@latest` (1.5.0 ou mais nova) e nova sessão do Claude Code.
25
+ - **Diagnóstico**: `/acropole doctor <pasta do app>` (fluxo [doctor.md](doctor.md)). Anote as versões atuais: o
26
+ caminho muda se o app vier de `@trismegisto` 1.x (§2.2) ou de `@orfeu` 1.0.x (§3.1).
27
+ - **Argos do ambiente** com as mudanças de 2026-10-13 — sem elas a seção "Conta e segurança" do spine não abre e
28
+ a validação nova recusa tokens:
29
+ - `iss` em todo token (`{SERVER_URL}/realms/{realm}`; todo Argos desde 2026-10);
30
+ - área da conta por **Bearer**: `{authority}/api/realms/{realm}/account/*` (merge "Conta do usuário (MFA, códigos e
31
+ sessões) também por Bearer para os apps");
32
+ - correções de segurança do auth (CORS por realm/client, cookie `argos_login`, `typ: at+jwt`).
33
+
34
+ Como conferir: `GET {authority}/api/realms/{realm}/account/security` **sem** token responde 401, não 404; e
35
+ `GET {authority}/api/realms/{realm}/.well-known/openid-configuration` traz o `issuer`.
36
+ - **Runtime**: Angular ≥ 21 (peer das libs; o padrão dos apps é 22+), `rxjs` `^7.8`; `@apollo/server` ≥ 4; Python
37
+ ≥ 3.11 para o `orfeu`; Node da major da imagem do app.
38
+ - **Argos local** (quem roda o Argos na máquina para desenvolver): o `.env` dele precisa de `CORE_TOKEN_SECRET` com
39
+ 32+ caracteres (`openssl rand -hex 32`; com `CHANGE_ME` ou curto o auth não sobe) e `TRUST_PROXY` sem `true`
40
+ (recusado na subida).
41
+
42
+ ## 2. Front Angular com spine
43
+
44
+ ### 2.1 Dependências
45
+
46
+ ```bash
47
+ # só os pacotes que o app já usa, todos em 2.1.2
48
+ npm install @trismegisto/tokens@2.1.2 @trismegisto/icons@2.1.2 @trismegisto/primitives@2.1.2 \
49
+ @trismegisto/core@2.1.2 @trismegisto/angular@2.1.2 @trismegisto/spine@2.1.2 @orfeu/angular@1.4.0
50
+ # opcionais, se já estão no package.json
51
+ npm install @trismegisto/charts@2.1.2 @trismegisto/maps@2.1.2
52
+ npm ls @orfeu/angular # UMA cópia só (o spine aceita ^1.0.0; duas cópias = NullInjectorError/segunda sessão)
53
+ ```
54
+
55
+ No `package.json`, faixa `^2.1.2` e `^1.4.0` (nunca `^2`/`^1`). Lockfile no mesmo commit — revise o diff dele
56
+ (§8, campos `libc`). App que já está em `^2.1.1` não quebra: pega a 2.1.2 no próximo `npm install`, mas suba a faixa
57
+ para não depender do lockfile.
58
+
59
+ ### 2.2 Só se o app vier de `@trismegisto` 1.x: quebras da 2.0
60
+
61
+ Nenhuma delas dá erro de build — procure à mão:
62
+
63
+ | Antes | Depois | Como achar |
64
+ | --- | --- | --- |
65
+ | `--hm-space-quarck`, `.hm-gap-quarck`, `.hm-{m,p}{,t,b,s,e,x,y}-quarck` | `--hm-space-micro`, `-micro` | `grep -rn quarck src` (o `var()` com nome errado só fica inválido) |
66
+ | slots `[atalhos]`/`[acoes]` do `hm-header` | `[shortcuts]`/`[actions]` | o conteúdo antigo cai em silêncio no slot padrão, junto da marca |
67
+ | `hm-wizard [orientation]` | removido (trilha lateral sempre) | trilha em cima: `hm-stepper` sozinho |
68
+ | `hm-opening-scene`, `measureOpeningTarget`/`applyOpeningTarget`, `.hm-opening*` | removidos | não há substituto |
69
+
70
+ ### 2.3 O que a 2.1 muda no app
71
+
72
+ 1. **Conta e segurança no modal de configurações** (`?settings=seguranca`): MFA, códigos de recuperação e sessões
73
+ dentro do próprio app, pela API da conta do Argos com o access token da sessão. Não há código a escrever; a seção
74
+ só aparece com `authority` e `realmId` do `AUTH_CONFIG` preenchidos (sem `CHANGE_ME`) e exige o Argos do §1 e a
75
+ origem do app nas `redirect_uris` (§5). Link próprio do app para "segurança da conta" no Argos vira duplicado:
76
+ pergunte ao usuário se sai. Para usar a mesma API em outro lugar: `SpineAccountSecurityService`
77
+ (`@trismegisto/spine/layout`).
78
+ 2. **Menu lateral, `opensMenu`**: item que entra num módulo (abre o submenu) ganha a seta "abre o menu do módulo".
79
+ Quem usa `hm-sidebar-node` (o spine usa) ganha sozinho. `hm-sidebar-link` montado à mão para entrada de módulo:
80
+ `[opensMenu]="true"`. Seta/ícone próprio desenhado para isso sai.
81
+ 3. **Tour e novidades**: não dividem mais a tela (as novidades esperam o tour ficar `idle`); `SpineNewsService.showAll()`
82
+ marca como vistas. Apague contorno do app que atrasava novidades ou suprimia o tour (`setTimeout`, flag própria). Se
83
+ o app coordena algo com o tour: `OnboardingService.state$` (`'idle' | 'pending' | 'running'`) e `stop()`.
84
+ 4. **Favoritos, recentes e buscas recentes por usuário** (`SpineUserStorage`, chave `<clientId>_<lista>_<sub>`): a
85
+ chave antiga é apagada no primeiro uso — **favoritos e recentes somem uma vez**. Avise as pessoas (uma novidade
86
+ em `provideSpineNews` serve). Código do app que lia a chave antiga do `localStorage` passa a usar
87
+ `SpineQuickAccessService`. No logout, recentes e buscas saem; favoritos ficam.
88
+ 5. **`hm-session-recovery`**: `origin` só `http(s)`. Quando o `origin` vem da URL/referrer, declare
89
+ `[allowedOrigins]` com as origens aceitas (sem a lista, qualquer `http(s)` vale — redirect aberto). `returned` emite
90
+ o endereço normalizado; `safeReturnUrl` está exportada.
91
+ 6. **Texto com marcação em `[innerHTML]`**: `formatMessage`/`fmt`/`pluralMessage` **com parâmetros** num
92
+ `[innerHTML]` é XSS (parâmetro vindo do servidor não é escapado). Troque por `formatMessageHtml`/
93
+ `pluralMessageHtml` (ou `escapeHtml`) de `@trismegisto/primitives`. A regra `check-strings` que reprova isso roda
94
+ só no repositório das libs: no app, procure à mão
95
+ (`grep -rn "innerHTML" src | grep -E "formatMessage|fmt\(|pluralMessage"`). `formatter` próprio no `hm-chart`
96
+ também escapa com `escapeHtml`.
97
+ 7. **Confirmação no `hm-data-grid`**: ação destrutiva por linha declara `confirm` no `DataGridRowAction` (objeto ou
98
+ função da linha, `DataGridActionConfirm`); `actionTriggered` só sai depois do "sim". Tire o
99
+ `HermesDialogService.confirm` que o handler fazia à mão para essa ação (senão pergunta duas vezes).
100
+ 8. **`@orfeu/angular` 1.3+ e logout**:
101
+ - `logout()` devolve `Promise<boolean>` e **não anuncia "saiu" se o Argos falhou** (repete uma vez; falhando, a
102
+ sessão continua e `logoutFailed$` emite). O **`@trismegisto/spine` 2.1.2** trata isso sozinho: todas as saídas
103
+ do shell (menu do perfil, "Sair" das configurações, atalho `Mod+Shift+L`, tela `/blocked`) passam pelo
104
+ `SpineLogoutService` (`@trismegisto/spine/layout`), que assina o `logoutFailed$` **uma vez** e mostra o aviso
105
+ `SpineMessages.session.logoutFailed` — **inclusive para um `logout()` chamado direto pelo app** — e só apaga os
106
+ recentes quando a saída deu certo. **Nada a fazer no app.**
107
+ - Botão de sair próprio do app: chame `inject(SpineLogoutService).logout()` (mesmo aviso, limpa os recentes só no
108
+ sucesso, `pending` para o estado de carregando). **Não** assine o `logoutFailed$` nem mostre toast próprio: o
109
+ aviso sairia em dobro.
110
+ - Toasts: na 2.1.2 o `spine-layout` monta o `<hm-toast-stack>` (antes nenhum template montava, e os toasts do
111
+ `HermesToastService` — configurações, Conta e segurança, auto-serviço — sumiam). O app **não** monta outro; se já
112
+ montava, pode tirar (o `@trismegisto/angular` 2.1.2 faz só uma pilha desenhar).
113
+ - App **sem** spine: trate o retorno do `logout()` ou o `logoutFailed$` (skill `orfeu`).
114
+ - Callback com `?error` confere o `state` antes de qualquer efeito (sem o state deste login → `state_mismatch`, nada
115
+ é limpo) e a mensagem é genérica, **sem** `error_description`. Callback próprio do app (fora do spine) usa
116
+ `handleCallback(route.snapshot.queryParams)` em `try/catch` e nunca mostra `error_description`.
117
+ 9. **"Copiar token de acesso"** (configurações) só aparece com `SpineConfig.technicalDocs` (sem ele, só em
118
+ `isDevMode()`). Quem precisa disso em `homol` liga `technicalDocs` lá — nunca em `prod`.
119
+ 10. **Contornos de CSS que a 2.1 corrige** — procure e apague (`grep -rn -E "TEMPORÁRIO|CONTORNO|TODO\(hermes\)" src`):
120
+
121
+ | Contorno no app | Corrigido na lib |
122
+ | --- | --- |
123
+ | tamanho fixo no ✓ dos atalhos do `hm-date-range-picker` (`.hm-date-range__preset-check`) | `@trismegisto/core` usa `--hm-icon-md` (antes `--hm-icon-sm`, inexistente) |
124
+ | `scrollbar-color: var(--hm-border) transparent` em contêiner rolável | o reset declara `color-scheme` e `scrollbar-color` herdado (o `scrollbar-width: thin` pode ficar) |
125
+ | largura/`min-width` forçada no `hm-date-range-picker` numa barra de filtros | `size` de 10 caracteres + `.hm-field` com `minmax(0, 1fr)` |
126
+ | largura extra/`overflow` na coluna de ações do `hm-data-grid` | `initialWidth` vira mínimo e a coluna cresce com o conteúdo |
127
+ | `scale="diverging"` + `--hm-data-diverging-*` redeclarados para semáforo no mapa | `hm-map-choropleth scale="status"` (com `breaks`) |
128
+ | reset manual do submenu do `hm-menu` ao fechar | o menu esquece o submenu aberto |
129
+
130
+ Confira cada um na tela (tema claro e escuro) antes de apagar.
131
+
132
+ ## 3. Gateway Apollo / servidor Express com `@orfeu/node`
133
+
134
+ ### 3.1 Dependência
135
+
136
+ `"@orfeu/node": "^1.4.0"`. Vindo da 1.0.x, a 1.1 também entra: permissões revalidadas a cada ~60 s e
137
+ **`client.close()` no SIGTERM** no lugar de `flushAudit()` ([arquitetura.md](../arquitetura.md) §11); e desde a
138
+ 1.0.1 nunca `ctx.orfeuUser = ...` à mão (`trustUser`) nem `connectionParams` espalhado no contexto do WebSocket.
139
+
140
+ ### 3.2 Opções novas do `OrfeuClient`
141
+
142
+ Passe **explicitamente, a partir das settings** do app — não confie na leitura automática de `ORFEU_*`: num módulo
143
+ ESM que cria o `OrfeuClient` no topo (padrão do Express), o construtor roda antes do `dotenv.config()` e em `local` a
144
+ variável não é vista.
145
+
146
+ ```ts
147
+ const lista = (v?: string) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
148
+ const allowedClients = lista(settings.ORFEU_ALLOWED_CLIENTS); // ou a variável que o app já tinha
149
+
150
+ const orfeu = new OrfeuClient({
151
+ authorizerUrl: settings.AUTHORIZER_URL!, realmId: settings.REALM_ID!,
152
+ appId: settings.APP_ID!, secret: settings.APP_SECRET!, tlsVerify,
153
+ allowedClients: allowedClients.length ? allowedClients : undefined, // [] desliga E ignora o ORFEU_ALLOWED_CLIENTS
154
+ issuerUrl: settings.ORFEU_ISSUER_URL || undefined,
155
+ // trustedProxies: só se o padrão não serve (abaixo)
156
+ // checkRevocation: ['pedidos:delete', 'pedidos:approve'], // operações sensíveis
157
+ });
158
+ ```
159
+
160
+ | Opção | O que faz | Ligar? |
161
+ | --- | --- | --- |
162
+ | `allowedClients` | token de usuário (`x-access-token` e `x-app-token`) cujo `client_id`/`azp` não está na lista → 401 | **Sim** em todo backend que atende só o front do próprio app (o caso comum). **Não** em backend que atende qualquer app do realm de propósito (admin do Argos, auto-serviço). Serviço compartilhado que recebe o token repassado por gateways de vários apps: liste os fronts de **todos** eles, ou deixe desligado. `x-api-token` não é afetado |
163
+ | `issuerUrl` | `iss` esperado exato: `${issuerUrl}/realms/${realm_id}` | recomendado em `homol`/`prod`. Valor = `issuer` da discovery sem o `/realms/<realm>`. **Não** derive do `authorizerUrl` (endereço interno, com `/argos/api`) |
164
+ | `trustedProxies` | de quais proxies o `x-forwarded-for` vale para o IP da auditoria | padrão loopback + redes privadas (onde ficam Caddy/ingress) serve na maioria. Configure só com os IPs dos proxies quando usuários chegam por rede privada **sem** proxy, ou quando o proxy está fora dessas faixas |
165
+ | `checkRevocation` | confere o token na introspecção do Argos (RFC 7662), fail-closed, cache 10 s/60 s | lista das operações sensíveis (exclusão, aprovação, troca de permissão). `true` (tudo) custa uma ida ao Argos por token novo; Argos fora → 401 nessas operações |
166
+
167
+ Valor de `allowedClients`: o **`client_id` do token**, que no Argos é o id do client do front — o mesmo
168
+ `authorizationServer.clientId` do environment do Angular (os READMEs do Orfeu usam nomes como `hefesto-ui` só de
169
+ ilustração). Comparação sem diferenciar maiúsculas. Exemplo real: o Hefesto troca o embrulho próprio de `client_id`
170
+ pelo `allowedClients` do Orfeu e **mantém** a variável `ALLOWED_CLIENT_IDS`, que passa a alimentar a opção.
171
+
172
+ ### 3.3 Recusas novas (sem mudar código)
173
+
174
+ - Token sem `iss`, `exp` ou `sub`, algoritmo diferente de `RS256`, ou `iss` que não termina em `/realms/<realm_id>`
175
+ → 401. Todo Argos de 2026-10 emite os três; quem quebra são **fakes de teste** (§7).
176
+ - Token de aplicação (`type: "app"`, client_credentials) não vale mais como usuário → 401. **Rota máquina-a-máquina
177
+ que recebia esse token por um guard de operação quebra.** Use o token de serviço da **1.4.0**:
178
+ `client.validateServiceToken(token, { allowedApps, realmFor, checkRevocation })` e, nas rotas, `serviceGuard(opts)`
179
+ (Express, `req.orfeuService`), `fastify.orfeuServiceGuard(opts)` (Fastify) ou `@ServiceRoute(opts)` +
180
+ `@OrfeuService()` (Nest); no Apollo, `validateServiceToken` direto no `context`. O token vai em `x-access-token`; a
181
+ rota não entra no catálogo nem na auditoria de operação; o realm de verificação **nunca** vem do token (sem
182
+ `realmFor`, o `realmId` do client; com `realmFor(appId)`, o do registro da app); `allowedClients` não se aplica.
183
+ Token client_credentials numa rota **de usuário** passa de 403 para 401.
184
+ - Falha ao falar com o Argos (JWKS, `/apps/token`, introspecção) → anônimo em `public`, 401 no resto; nunca 500.
185
+ - **Subscription termina no `exp`**: em `secureResolvers`, a subscription não pública aberta com token de usuário
186
+ recebe um último erro 401 (`UNAUTHENTICATED`) quando o token vence e o stream acaba — no Argos, a cada **~10 min**
187
+ (`CORE_TOKEN_LIFE` = 600 s). O spine derruba e recria o socket com o token novo quando vê o código de auth, mas a
188
+ assinatura que recebeu o erro **já terminou**: a tela reassina (no `error` do `subscribe`, ou no `wsReconnected$`,
189
+ receita 6 da skill `trismegisto` em `references/spine-recipes.md`). Guarda própria de `exp` no gateway fica
190
+ redundante; a revalidação periódica de **permissão** do app (se houver) continua.
191
+ - IP da auditoria: nunca mais o primeiro `x-forwarded-for`; do socket, ou a entrada mais à direita que não é proxy.
192
+
193
+ ### 3.4 Redis
194
+
195
+ Toda conexão nomeada (`connectionName` no ioredis, `<app>-graphql-publisher`/`-subscriber`), `REDIS_CLIENT_NAME`
196
+ no `.env.example`, com teste do nome padrão e da sobrescrita — [arquitetura.md](../arquitetura.md) §3.1.
197
+ Aproveite a atualização para fechar isso se o app ainda não tem.
198
+
199
+ ## 4. Server FastAPI com `orfeu` (Python)
200
+
201
+ 1. `requirements.txt`: `orfeu[fastapi]==1.4.0` (versão exata). Recrie o ambiente do zero e rode o `pytest`.
202
+ 2. Mesmas opções, como argumentos keyword-only do adapter, vindos das settings (pydantic):
203
+
204
+ ```python
205
+ orfeu = Orfeu(
206
+ app=application,
207
+ authorizer_url=settings.authorizer_url, realm_id=settings.realm_id,
208
+ app_id=settings.app_id, secret=settings.app_secret,
209
+ tls_verify=settings.authorizer_tls_verify,
210
+ allowed_clients=settings.allowed_clients or None, # [] desliga e ignora ORFEU_ALLOWED_CLIENTS
211
+ issuer_url=settings.orfeu_issuer_url or None,
212
+ # trusted_proxies=[...], check_revocation=["pedidos:delete"],
213
+ )
214
+ ```
215
+ Django: settings `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES`, `ORFEU_CHECK_REVOCATION`.
216
+ 3. Mesmas recusas do §3.3. Rota máquina-a-máquina: `await client.validate_service_token(token, allowed_apps=...,
217
+ realm_for=..., check_revocation=...)` ou `@service_route(allowed_apps=..., realm_for=...)` (FastAPI HTTP/WebSocket,
218
+ `request.state.service`; Flask `g.orfeu_service`; Django `request.orfeu_service`) — **não** combine com
219
+ `@operation`; no Strawberry, valide no contexto. **JWKS fora / `/apps/token` recusando** agora vira 401 (ou anônimo em `public`), não mais
220
+ 500: alerta que olhava 500 deixa de disparar — monitore a taxa de 401 e a saúde do Argos.
221
+ 4. Vindo de antes da 1.2: `accept_any_realm` existe (padrão `False`) e a busca forçada do JWKS tem intervalo mínimo de
222
+ 30 s (chave recém-rotacionada pode levar até 30 s para ser aceita). Vindo de antes da 1.1: recarga das permissões e
223
+ `shutdown_async()` no lifespan (o adapter já faz).
224
+ 5. Redis: `client_name` no `redis.ConnectionPool(...)` = `REDIS_CLIENT_NAME` (padrão `<app>-server`),
225
+ `arquitetura.md` §3.1.
226
+
227
+ **Banco (`database/`)**: aproveite para conferir o seed — **nunca dado real de pessoa** (login, nome, e-mail,
228
+ vínculo federado, MFA, membro de grupo); usuário de seed é fictício. Um `seed-regerar` a partir de produção traz
229
+ pessoas reais de volta: reverta as tabelas de identidade e confira o diff.
230
+ Regra completa em `references/banco.md` da skill `fastapi`.
231
+
232
+ ## 5. Configuração no Argos para o app funcionar
233
+
234
+ O CORS do Argos agora é **por realm e por client**, montado das `redirect_uris`:
235
+
236
+ - Nas rotas de um realm (`/realms/{realm}/...`, inclusive a área da conta do §2.3), só passam as origens das
237
+ `redirect_uris` dos clients habilitados **daquele realm**.
238
+ - `/token`, `/revoke` e `/logout` com `Origin` exigem a origem de uma `redirect_uri` do **próprio client** do pedido;
239
+ senão `403 origin_not_allowed` — o refresh falha, o app fica "offline"/em loop de login e o logout não sai.
240
+ - O auto-serviço embutido no app chama o argos-admin, que usa a mesma lista (`403 cors_origin_not_allowed`).
241
+
242
+ O que conferir no client do front, **em cada ambiente**:
243
+
244
+ - [ ] `redirect_uris` com `<origem>/<app>/callback` e `<origem>/<app>/logoff` para **cada** origem em que o app é
245
+ servido (dois DNS = duas origens; `localhost:4200` e `127.0.0.1:4200` também são origens diferentes).
246
+ - [ ] **Nada de `localhost`** nos clients de `homol`/`prod`: uma `redirect_uri` local libera o CORS do Argos de
247
+ produção para qualquer página servida na máquina de quem desenvolve. `localhost` só no client de dev/local.
248
+ - [ ] Sem curinga (`https://*`) nem esquema de app nativo: são descartados da lista, não liberam nada.
249
+ - [ ] Acesso dos grupos ao client e roteadores liberados (como no [app-novo.md](app-novo.md)).
250
+
251
+ Outras mudanças do Argos que o app sente:
252
+
253
+ - **`typ: at+jwt`**: o Argos só aceita access token como Bearer. Nunca mande o `id_token` como Bearer ou
254
+ `x-access-token`.
255
+ - **Cookie `argos_login`**: a sessão de login fica presa ao navegador que abriu o `/authorize`. Link da tela de login
256
+ copiado para outro navegador (ou outro contexto do puppeteer) dá `login_session_mismatch`: o login sempre começa
257
+ pelo app (`authorize()` do Orfeu), no mesmo navegador, com cookies.
258
+
259
+ ## 6. Variáveis de ambiente novas
260
+
261
+ | Camada | Variável | Obrigatória | Valor |
262
+ | --- | --- | --- | --- |
263
+ | gateway / express / server | `ORFEU_ALLOWED_CLIENTS` (ou a variável própria que o app já tinha, passada à opção) | sim, quando o backend é do front do app (§3.2) | `client_id` do(s) front(s), separados por vírgula; vazia = desligado |
264
+ | gateway / express / server | `ORFEU_ISSUER_URL` | recomendada em `homol`/`prod` | `issuer` da discovery sem `/realms/<realm>` |
265
+ | gateway / express / server | `ORFEU_TRUSTED_PROXIES` | não | IPs/CIDRs dos proxies, vírgula; ausente = loopback + redes privadas |
266
+ | gateway / express / server | — (`checkRevocation`/`check_revocation` é código) | não | lista das operações sensíveis |
267
+ | gateway / server | `REDIS_CLIENT_NAME` | não (tem padrão) | `<app>-<componente>`; o papel vira sufixo; sem espaços |
268
+ | front | — (sem variável nova) | — | `authority`/`realmId` reais em todos os environments; `technicalDocs` no `SpineConfig` (código) |
269
+ | Argos local | `CORE_TOKEN_SECRET` | sim | 32+ caracteres; `TRUST_PROXY` nunca `true` |
270
+
271
+ Toda variável nova vai no `.env.example` da camada (só nomes e IDs públicos) e no cadastro do deploy (skill
272
+ `hefesto`) de cada ambiente.
273
+
274
+ ## 7. Verificação
275
+
276
+ **Testes e build** (cada camada alterada, `arquitetura.md` §10):
277
+
278
+ - front: `ng test`, `ng build`, `lint:a11y`; `npm ls @orfeu/angular` com uma cópia; verificadores das skills
279
+ `trismegisto` e `angular` nos arquivos alterados;
280
+ - gateway/express: `vitest`, `typecheck`, `build`; server: `pytest` num ambiente recriado; banco: `poe test`;
281
+ - `/acropole doctor` sem achado de versão;
282
+ - testes que assinam JWT à mão: o token fake precisa de `iss` (`<url>/realms/<realm_id>`, ou exato com
283
+ `issuerUrl`), `exp`, `sub`, `RS256` e `client_id` da lista quando `allowedClients` está ligado; teste que mandava
284
+ token `type: "app"` como usuário passa a esperar 401; teste do IP da auditoria pelo `x-forwarded-for` muda; teste
285
+ de callback com `?error` sem `state` espera `state_mismatch`.
286
+
287
+ **Smoke num ambiente com o Argos novo** (DevTools aberto na aba Rede e no Console):
288
+
289
+ - [ ] Login → callback → tela inicial; nenhum `origin_not_allowed`/erro de CORS.
290
+ - [ ] Troca de crachá: o menu recarrega e as telas abrem.
291
+ - [ ] Configurações › **Conta e segurança** (`?settings=seguranca`): métodos, códigos e sessões carregam
292
+ (`GET …/account/security` 200 com `Authorization: Bearer`); a sessão atual aparece marcada.
293
+ - [ ] Logout pelo menu do perfil: `GET …/logout` 200 e `/logoff?loggedOut=true`. Com a rede cortada no DevTools
294
+ (spine ≥ 2.1.2): o aviso de falha aparece **uma** vez e a sessão **continua**. Idem para botão de sair próprio
295
+ do app, se houver.
296
+ - [ ] Subscription: tela ao vivo aberta por mais de 10 min — depois da renovação do token os eventos continuam.
297
+ - [ ] Com `allowedClients`: token de outro client do realm → 401; o do front do app → 200.
298
+ - [ ] Favoritos/recentes: somem uma vez na primeira entrada (esperado) e voltam a gravar por usuário.
299
+ - [ ] Menu lateral com a seta nos módulos; tour e novidades nunca juntos na primeira entrada.
300
+ - [ ] Redis: `CLIENT LIST` mostra `name=<app>-…` em todas as conexões do app.
301
+
302
+ ## 8. Armadilhas conhecidas
303
+
304
+ - **`allowedClients: []` desliga em silêncio** e ignora o `ORFEU_ALLOWED_CLIENTS` (a opção passada vence a variável,
305
+ mesmo vazia). Passe `undefined`/`None` quando a lista estiver vazia, ou recuse lista vazia na subida em
306
+ `homol`/`prod`.
307
+ - **Embrulho próprio com padrão diferente.** Um embrulho de `client_id` do app pode ter "vazio = client do console"
308
+ como padrão; o do Orfeu é "vazio = desligado". Ao trocar um pelo outro mantendo o nome da variável, mantenha o
309
+ padrão nas settings do app (ou torne a variável obrigatória).
310
+ - **Nome do client no lugar do id.** A lista compara com o `client_id`/`azp` do token (o id do client no Argos), não
311
+ com o nome exibido. Token sem nenhum dos dois → 401; com os dois, os dois precisam estar na lista.
312
+ - **Serviço compartilhado.** Server chamado por gateways de vários apps recebe o token do front de cada um: com
313
+ `allowedClients` só do próprio app, os outros apps tomam 401. `x-app-token` (MCP) preso a outro client também.
314
+ - **`issuerUrl` errado** recusa **todo** token. Tire do `issuer` da discovery, nunca do `authorizerUrl`.
315
+ - **Leitura de `ORFEU_*` antes do `dotenv`** (cliente criado no topo de um módulo ESM): em `local` a opção fica
316
+ desligada sem aviso. Passe pelas settings (§3.2).
317
+ - **Subscription que acaba a cada ~10 min** com `UNAUTHENTICATED`: tela que não reassina para de atualizar sem erro
318
+ visível (§3.3).
319
+ - **`trustedProxies` padrão confia em redes privadas**: com usuários chegando direto pela rede interna (sem proxy),
320
+ eles escrevem o IP que quiserem no `x-forwarded-for` da auditoria. Liste só os proxies.
321
+ - **`checkRevocation: true`** põe o Argos no caminho de toda chamada com token novo e é fail-closed: Argos fora = 401
322
+ em tudo. Use a lista de operações sensíveis.
323
+ - **Python sem 500**: falha do Argos virou 401/anônimo; alerta por 500 não pega mais (§4).
324
+ - **CORS por client**: origem fora das `redirect_uris` do **mesmo** client quebra refresh e logout, não só o login.
325
+ `localhost` em client de produção é falha de segurança, não comodidade (§5).
326
+ - **`id_token` como Bearer** deixou de valer (`typ: at+jwt`).
327
+ - **Link da tela de login do Argos** (favorito, e-mail, teste automatizado) noutro navegador: `login_session_mismatch`.
328
+ - **Duas cópias de `@orfeu/angular`** depois do install (faixas diferentes entre app e spine): `npm ls` e `npm dedupe`.
329
+ - **Quebras silenciosas da 2.0** (app vindo da 1.x): `quarck` e slots `atalhos`/`acoes` não dão erro (§2.2).
330
+ - **Contorno de CSS apagado sem conferir**: alguns apps têm o mesmo seletor por outro motivo (cor própria de
331
+ propósito). Leia o comentário antes de apagar.
332
+ - **Favoritos zerados** geram chamado se ninguém avisar (§2.3 item 4).
333
+
334
+ - **Rotas máquina-a-máquina quebradas pela 1.3, e as suítes não pegam.** O `validateToken` passou a recusar o token
335
+ client_credentials (`type: "app"`) e a rota responde 401 — mas a suíte com o Orfeu **mockado** (`validateToken`
336
+ devolvendo claims) continua verde. Migre para o token de serviço da 1.4.0 (§3.3; especificação em
337
+ `packages/orfeu/docs/especificacoes/token-de-servico.md` do monorepo) e, nos fakes, **imite a recusa de
338
+ `type: "app"`** no `validateToken`.
339
+ - **JWT de teste incompleto.** Todo token de teste precisa de `iss` terminando em `/realms/<realm_id>`, `exp` e `sub`.
340
+ Operação fora do catálogo dá 403: preencha as operações no teste passando pelo middleware real. Orfeu real sem
341
+ rede: Node `(client as any).jwks = createLocalJWKSet({ keys: [jwk] })` (`jose` vem com o `@orfeu/node`); Python
342
+ `client._jwks = {"keys": [jwk]}` e `client._jwks_fetched_at = time.monotonic()`.
343
+ - **npm 10.x apaga campos `"libc"`** de lockfile gerado por npm mais novo (quebra o `npm ci` em Alpine). Revise o diff
344
+ do lock; se mudou o que não devia, restaure o arquivo e troque só as entradas das libs.
345
+ - **`allowedClients` confere todos os ids presentes**: `client_id` **e** `azp`, se vierem, precisam estar na lista
346
+ (embrulhos antigos olhavam só o `client_id`). `[]` desliga; variável `ORFEU_*` vazia conta como ausente — é seguro
347
+ repassar `${VAR:-}` no compose.
348
+ - **`trustedProxies` não aceita a sintaxe do Express**: nem os nomes `loopback, linklocal, uniquelocal` nem número de
349
+ saltos. Converta para CIDRs (o Argos tem `orfeuTrustedProxies()` em `trust-proxy.ts`; o Hefesto mapeia
350
+ `TRUSTED_PROXY_HOPS=0` → `[]`).
351
+ - **Subscription no `exp` disputa com o fechamento do gateway**: o Orfeu manda 401 `Unauthorized: Invalid token.`,
352
+ que pode chegar antes ou depois da mensagem do próprio gateway. Em teste de expiração, dê `exp` com folga ≥ 2 s e
353
+ aceite as duas mensagens.
354
+ - **Token client_credentials em rota de usuário** (`/me/*`, `/auto-service/*` do Argos) agora é 401, não 403: ajuste
355
+ testes e clientes que tratavam o 403.
356
+
357
+ ## 9. Checklist
358
+
359
+ - [ ] Skills em dia (`@acropole/skills` 1.5.0+) e `/acropole doctor` rodado antes e depois
360
+ - [ ] Argos do ambiente com `iss`, conta por Bearer e CORS por client (§1)
361
+ - [ ] `@trismegisto/*` todas em `^2.1.2`; `@orfeu/angular` `^1.4.0` com uma cópia; lockfile commitado e com o diff
362
+ revisado (`libc`)
363
+ - [ ] (vindo da 1.x) `quarck` → `micro`, slots `shortcuts`/`actions`, sem `hm-wizard [orientation]` nem `hm-opening-scene`
364
+ - [ ] `[innerHTML]` com parâmetro só por `formatMessageHtml`/`pluralMessageHtml`/`escapeHtml`
365
+ - [ ] Ações destrutivas do `hm-data-grid` com `confirm` (sem confirmação dupla)
366
+ - [ ] `hm-session-recovery` com `allowedOrigins` quando o `origin` vem de fora
367
+ - [ ] Falha de logout com o spine 2.1.2 (nada no app; botão próprio usa `SpineLogoutService`, sem toast próprio nem
368
+ `logoutFailed$`); sem `<hm-toast-stack>` montado pelo app; callback próprio por `handleCallback`, sem
369
+ `error_description`
370
+ - [ ] Contornos de CSS corrigidos pela 2.1 removidos e conferidos nos dois temas
371
+ - [ ] Contorno de tour/novidades removido; `opensMenu` em link de módulo montado à mão; usuários avisados do reset de favoritos
372
+ - [ ] `@orfeu/node` `^1.4.0` e `orfeu[fastapi]==1.4.0`; `close()`/`shutdown_async()` no encerramento
373
+ - [ ] Rotas máquina-a-máquina (token client_credentials) com `serviceGuard`/`orfeuServiceGuard`/`@ServiceRoute` ou
374
+ `@service_route`, e um teste com o Orfeu real que prove 200 com token de serviço e 401 com token de usuário
375
+ - [ ] `allowedClients`/`allowed_clients` ligado (com os `client_id` certos) onde o backend é do front do app; nunca `[]`
376
+ - [ ] `issuerUrl`/`issuer_url` em `homol`/`prod`; `trustedProxies` revisto; `checkRevocation` nas operações sensíveis
377
+ - [ ] Telas com subscription reassinam depois do `UNAUTHENTICATED`
378
+ - [ ] Conexões Redis nomeadas, `REDIS_CLIENT_NAME` no `.env.example`, com teste
379
+ - [ ] Seed sem dado real de pessoa
380
+ - [ ] `redirect_uris` com todas as origens do app em cada ambiente; sem `localhost` em `homol`/`prod`
381
+ - [ ] Variáveis novas no `.env.example` e no deploy de cada ambiente
382
+ - [ ] Testes, build e smoke do §7 passando; PR no repositório do app
@@ -6,8 +6,8 @@ description: "SDK Orfeu do servidor de autorização Argos: login/sessão no fro
6
6
  # Orfeu — SDK do Argos (Angular, Node, Python)
7
7
 
8
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.0.0** — no Node, **1.0.1** (correção de segurança no adapter Apollo; peça
10
- `"@orfeu/node": "^1.0.1"`, nunca `^1.0.0`):
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`):
11
11
 
12
12
  | Pacote | Onde roda | O que faz |
13
13
  |---|---|---|
@@ -18,6 +18,9 @@ com o mesmo modelo, versão **1.0.0** — no Node, **1.0.1** (correção de segu
18
18
  **Não escreva à mão** nada que o SDK já faz: PKCE, troca de `code`, refresh, sincronização entre abas,
19
19
  validação de JWT/JWKS, introspecção de token, checagem de grupos, evento de auditoria, `traceparent`.
20
20
 
21
+ > **Atualizando um app para a 1.4.0**? Siga o guia da skill `acropole`:
22
+ > [../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.
23
+
21
24
  > **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).
22
25
 
23
26
  ## 1. Como as peças se encaixam numa stack
@@ -63,7 +66,7 @@ Python (ver [references/diferencas.md](references/diferencas.md)).
63
66
  |---|---|
64
67
  | `PUBLIC` | todos; nunca bloqueia. Credencial válida fica disponível ao handler; inválida é ignorada. |
65
68
  | `OPTIONAL` | sem credencial: anônimo. Com credencial: precisa ser válida (senão 401) e vale como `PRIVATE`. |
66
- | `PRIVATE` | usuário autenticado com **ao menos um grupo**. |
69
+ | `PRIVATE` | usuário autenticado com **ao menos um grupo** — em qualquer client do realm, a menos que o backend ligue `allowedClients`/`allowed_clients` (§4). |
67
70
  | `PROTECTED` | usuário com algum grupo em `allowed_groups` da operação (configurado no Argos). |
68
71
 
69
72
  ## 4. Credenciais e decisão (igual no Node e no Python)
@@ -85,6 +88,24 @@ o guard **nunca** lê `Authorization: Bearer` (esse header só aparece nas chama
85
88
  | sem credencial em `PRIVATE`/`PROTECTED` | 401 |
86
89
  | credencial inválida, expirada, revogada ou de outro realm (fora de `PUBLIC`) | 401 — nunca vira anônimo |
87
90
  | credencial válida sem permissão | 403 |
91
+ | Argos fora ao validar (JWKS, introspecção) | 401 (anônimo em `PUBLIC`); nunca 500 |
92
+
93
+ **Validação do `x-access-token` (1.3+)**: só `RS256`; `exp`, `sub` e `iss` obrigatórios, com o `iss` do realm do
94
+ 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:
96
+
97
+ | Opção (Node / Python) | Variável, sem a opção | Quando |
98
+ |---|---|---|
99
+ | `allowedClients` / `allowed_clients` | `ORFEU_ALLOWED_CLIENTS` | **ligue** em backend que atende o front do próprio app: token de usuário de outro client do realm → 401. Não no que atende qualquer app do realm (admin do Argos). Valor = `client_id` do front; `[]` desliga |
100
+ | `issuerUrl` / `issuer_url` | `ORFEU_ISSUER_URL` | recomendado em produção (fixa o emissor) |
101
+ | `trustedProxies` / `trusted_proxies` | `ORFEU_TRUSTED_PROXIES` | padrão loopback + redes privadas; só os proxies, se usuários chegam pela rede privada sem proxy |
102
+ | `checkRevocation` / `check_revocation` | — | operações sensíveis: sem ela, um access token revogado vale até o `exp` (até 10 min); com ela, introspecção no Argos, fail-closed |
103
+
104
+ **Token de serviço (máquina-a-máquina, 1.4+)**: a rota que **outra aplicação** chama com o token client_credentials
105
+ dela (`type: "app"`, recusado como usuário desde a 1.3) usa `serviceGuard()` (Express), `orfeuServiceGuard`
106
+ (Fastify), `@ServiceRoute()` + `@OrfeuService()` (Nest) ou `@service_route(...)` (FastAPI, Flask, Django); por código,
107
+ `validateServiceToken`/`validate_service_token` (Apollo e Strawberry, no contexto). O realm de verificação nunca vem
108
+ do token (`realmFor`/`realm_for`); `allowedClients` não se aplica; a rota não entra no catálogo de operações.
88
109
 
89
110
  Corpos de 401/403 são genéricos; o motivo detalhado vai só para log e auditoria. Rota/resolver **sem**
90
111
  operação declarada não é protegida, não tem usuário e não é auditada. As claims lidas no front servem para
@@ -100,7 +121,8 @@ a lib grava estão em `ORFEU_RESERVED_CONTEXT_KEYS` (`orfeuUser`, `orfeuApiToken
100
121
  ## 5. Trace e auditoria
101
122
 
102
123
  - Correlação só pelo header W3C **`traceparent`** (sem OpenTelemetry). Chegou **sem** `traceparent` (navegador,
103
- cliente externo) → trace novo e evento com **`entry: true`** (é a ação do usuário; só aqui o IP é gravado).
124
+ cliente externo) → trace novo e evento com **`entry: true`** (é a ação do usuário; só aqui o IP é gravado —
125
+ nunca o primeiro `x-forwarded-for`: o do socket, ou o mais à direita que não é proxy confiável).
104
126
  Chegou **com** → mesmo `trace_id`, `span_id` novo, o span de quem chamou vira `parent_span_id`,
105
127
  `entry: false` (passo interno da mesma ação). O navegador **não** manda `traceparent`; não invente um.
106
128
  - **Um evento de auditoria por serviço**: cada serviço audita a própria operação. Uma ação que passa por
@@ -144,7 +166,7 @@ subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
144
166
  - Estrutura do serviço: skill `fastapi`. Strawberry, Django e Flask: ainda não cobertos por skill
145
167
  de padrões.
146
168
 
147
- **Diferenças entre as três implementações** (comportamento atual: 1.0.0, Node 1.0.1) →
169
+ **Diferenças entre as três implementações** (comportamento atual: 1.4.0) →
148
170
  [references/diferencas.md](references/diferencas.md). Leia antes de supor que algo do Node vale igual no Python.
149
171
 
150
172
  ## 7. Não faça
@@ -157,6 +179,10 @@ subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
157
179
  - Não espalhe o `connectionParams` (`({ connectionParams }) => ({ ...connectionParams })`) no contexto do
158
180
  WebSocket: repasse só a allowlist de headers (skill `apollo` em `references/subscriptions.md`).
159
181
  - Não guarde o token do usuário (nem outra credencial) em `localStorage`/`sessionStorage` no front.
160
- - Não chame `logout()` por erro de rede, 401 ou token vencido: a lib do front já está renovando.
182
+ - Não chame `logout()` por erro de rede, 401 ou token vencido: a lib do front já está renovando. E não suponha
183
+ que ele saiu: desde a 1.3 `logout()` devolve `Promise<boolean>` e, se o Argos falhar, mantém a sessão e emite
184
+ `logoutFailed$` — quem chama fora do spine avisa a pessoa.
185
+ - Não passe `allowedClients: []`/`allowed_clients=[]` achando que "usa a variável": a lista vazia desliga.
186
+ - Subscription do Apollo termina no `exp` do token (1.3+): o front reconecta e **reassina**.
161
187
  - Não repasse credencial com `orfeuHeaders`/`orfeu_headers` para fora dos seus serviços.
162
188
  - Não ponha segredo (o `secret` do serviço vem de variável de ambiente/cofre) em código, log ou `details`.
@@ -1,7 +1,9 @@
1
- # API — @orfeu/angular 1.0.0
1
+ # API — @orfeu/angular 1.4.0
2
2
 
3
- > Conferida contra o código-fonte da 1.0.0 (`public-api.ts` de cada ponto de import). Tudo o que não está
4
- > aqui é interno: não importe de caminhos profundos (`@orfeu/angular/core/src/...`).
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á
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
7
 
6
8
  ## `@orfeu/angular`
7
9
 
@@ -65,6 +67,7 @@ Estado:
65
67
  | `badges` | `Badge[]` (getter) | claim `badges` (ou `[]`). |
66
68
  | `profile` | `UserProfile` (getter) | `{ name, role, picture }` das claims de mesmo nome (`null` se ausentes). |
67
69
  | `getToken()` | `string \| null` | token de acesso atual (pode estar vencido; veja `tokenExpired`). Só em memória. |
70
+ | `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. |
68
71
 
69
72
  `type ConnectionState = 'online' | 'reconnecting' | 'offline' | 'reauthorizing'`:
70
73
  - `online`: renovação funcionando (também o estado sem sessão);
@@ -88,13 +91,17 @@ Métodos:
88
91
  | `silentRenew(): Promise<void>` | Refresh por cookie (`grant_type=refresh_token&client_id=…`). Chamadas simultâneas compartilham a mesma promise; se outra aba anunciou um refresh, espera o resultado dela (até 15 s, depois rejeita com `Error('cross_tab_timeout')`). Rejeita com o erro HTTP se falhar. SSR: rejeita com `OrfeuAuthError('not_authenticated')`. Não dispara a reautorização automática (isso é do agendamento interno). |
89
92
  | `reauthorize(): Promise<void>` | `silentRenew()`; se falhar, `authorize()` **sem** URL de retorno. Para voltar à mesma tela, prefira `authorize(router.url)`. |
90
93
  | `switchBadge(badgeTypeId: string): Promise<void>` | Sem sessão: rejeita com `OrfeuAuthError('not_authenticated')` sem requisição. Com sessão: `POST <authority>/api/realms/<realm>/auth/switch-badge` com `{ badge_id }` e `Authorization: Bearer <token>`, aplica o token devolvido (`badgeChanged$` emite), avisa as abas e espera o `/view` recarregar. Erro HTTP é repassado; a sessão continua. |
91
- | `logout(): void` | `GET /logout?client_id=…` (`withCredentials`); com sucesso **ou erro**, limpa o estado local e os timers, avisa as abas (`LOGOUT`) e navega para `/logoff` com `queryParams: { loggedOut: 'true' }`. Não devolve promise. |
94
+ | `logout(): Promise<boolean>` | `GET /logout?client_id=…` (`withCredentials`). Confirmado pelo Argos: limpa o estado local e os timers, avisa as abas (`LOGOUT`), navega para `/logoff` com `queryParams: { loggedOut: 'true' }` e resolve `true`. Com erro (rede, 5xx), repete uma vez; falhando de novo, **nada é encerrado nem anunciado** (a sessão SSO e o cookie de refresh seguem válidos no Argos), `logoutFailed$` emite e resolve `false`. Nunca rejeita; quem ignora o retorno continua funcionando. (Até a 1.0.x devolvia `void` e anunciava "saiu" mesmo com erro.) |
92
95
 
93
96
  `handleCallback(params, redirect = true)`:
94
97
  1. `params.error` em `login_required`/`interaction_required`/`consent_required`/`account_selection_required`
95
98
  vindo de uma reautorização silenciosa desta aba: confere o `state` e chama `authorize(urlGuardada)`
96
99
  (login interativo). Resolve sem token (a página vai ser redirecionada).
97
- 2. `params.error` (outro caso): limpa o fluxo e rejeita `OrfeuAuthError('callback_error', error_description || error)`.
100
+ 2. `params.error` (outro caso), 1.3+: confere o `state` **antes de qualquer efeito** — ausente ou divergente
101
+ (link forjado, aba antiga) rejeita `state_mismatch` e **não mexe** no login em andamento (verifier/state/nonce
102
+ ficam). Com o state certo, limpa o fluxo e rejeita `OrfeuAuthError('callback_error')` com mensagem genérica
103
+ `O login não foi concluído (<error>).` — o código OAuth só entra quando é um identificador (`[a-z_]`), e o
104
+ `error_description` (de terceiros) **nunca** entra na mensagem.
98
105
  3. Sem `params.code` ou sem verifier gravado: rejeita `invalid_callback`.
99
106
  4. Segue como `token({ grant_type: 'authorization_code', code, redirect_uri, client_id, code_verifier, state })`:
100
107
  `state` divergente/ausente → `state_mismatch`; nonce divergente → `nonce_mismatch`.
@@ -133,7 +140,8 @@ Construtor: `new PrivateGuard(auth: AuthorizationService)`. Use direto nos array
133
140
  ### `OrfeuAuthError` / `OrfeuAuthErrorCode`
134
141
 
135
142
  ```ts
136
- type OrfeuAuthErrorCode = 'state_mismatch' | 'nonce_mismatch' | 'invalid_callback' | 'callback_error' | 'not_authenticated';
143
+ type OrfeuAuthErrorCode = 'state_mismatch' | 'nonce_mismatch' | 'invalid_callback' | 'callback_error' | 'not_authenticated'
144
+ | 'logout_failed'; // 1.3+
137
145
  class OrfeuAuthError extends Error { readonly code: OrfeuAuthErrorCode; name: 'OrfeuAuthError'; }
138
146
  ```
139
147