@acropole/skills 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +181 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,162 @@
1
+ ---
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."
4
+ ---
5
+
6
+ # Orfeu — SDK do Argos (Angular, Node, Python)
7
+
8
+ O **Orfeu** é o SDK do **Argos** (servidor de autorização OpenID Connect + RBAC). São três implementações
9
+ com o mesmo modelo, versão **1.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`):
11
+
12
+ | Pacote | Onde roda | O que faz |
13
+ |---|---|---|
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/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
+ | `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
+ **Não escreva à mão** nada que o SDK já faz: PKCE, troca de `code`, refresh, sincronização entre abas,
19
+ validação de JWT/JWKS, introspecção de token, checagem de grupos, evento de auditoria, `traceparent`.
20
+
21
+ > **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
+
23
+ ## 1. Como as peças se encaixam numa stack
24
+
25
+ ```
26
+ navegador (Angular + @orfeu/angular)
27
+ │ x-access-token: <token do usuário> (interceptor do app — a lib não exporta um)
28
+ │ x-client-id / x-route-id (opcionais, correlação)
29
+ │ sem traceparent → no BFF o evento é entry: true
30
+ ▼
31
+ BFF GraphQL / Node (@orfeu/node) — audita a própria operação
32
+ │ headers: orfeuHeaders(ctx) → x-access-token, traceparent (span do BFF), x-route-id, x-client-id
33
+ ▼
34
+ serviço Python (orfeu) — audita a própria operação (entry: false, mesmo trace_id)
35
+ │ headers: orfeu_headers(request) → idem, para o próximo serviço
36
+ ▼
37
+ ...
38
+ ```
39
+
40
+ - O front só fala com o Argos pelas chamadas da própria lib; nas **suas** APIs, um interceptor do app manda
41
+ o token cru em `x-access-token` (receita em [references/angular-recipes.md](references/angular-recipes.md) §4).
42
+ - Cada serviço do meio repassa o contexto com `orfeuHeaders(req|ctx)` (Node) / `orfeu_headers(request)`
43
+ (Python). **Nunca** use esses helpers em chamadas para terceiros: repassariam o token do usuário.
44
+ - Chamar outro serviço **como o próprio serviço** (job, integração): `credential: false` /
45
+ `credential=False` + o `x-api-token` do serviço. O `x-api-token` recebido **nunca** é repassado.
46
+
47
+ ## 2. Operação
48
+
49
+ Uma **operação** é o que se protege e audita: `identifier` + `method` + `level`. Cada rota/resolver protegido
50
+ declara uma; na subida, o serviço sincroniza o catálogo com o Argos (`POST /apps/operations/sync`) e busca
51
+ quais grupos podem executar cada uma (`GET /apps/operations`). Quem pode executar uma operação `protected` é
52
+ configurado **no Argos**, não no código. Mesmo `identifier` com `method` diferente = outra operação.
53
+
54
+ Declare **antes** da subida (operação declarada depois não está no catálogo e é negada). Use sempre as
55
+ constantes `Level.*`/`Method.*` (valor fora do conjunto = `OrfeuConfigError`).
56
+
57
+ `Method`: `READ`, `WRITE`, `DELETE`, `STREAM`. Passe explícito; a inferência automática difere entre Node e
58
+ Python (ver [references/diferencas.md](references/diferencas.md)).
59
+
60
+ ## 3. Níveis (`Level`)
61
+
62
+ | Nível | Quem executa |
63
+ |---|---|
64
+ | `PUBLIC` | todos; nunca bloqueia. Credencial válida fica disponível ao handler; inválida é ignorada. |
65
+ | `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**. |
67
+ | `PROTECTED` | usuário com algum grupo em `allowed_groups` da operação (configurado no Argos). |
68
+
69
+ ## 4. Credenciais e decisão (igual no Node e no Python)
70
+
71
+ Vale a **primeira presente**, nesta ordem; as seguintes nem são lidas. O valor vai **cru**:
72
+ o guard **nunca** lê `Authorization: Bearer` (esse header só aparece nas chamadas do SDK ao próprio Argos:
73
+ `/view`, `switch-badge`, sync de operações). Header só com espaços conta como ausente.
74
+
75
+ | Header | Quem manda | Validação | Permissão |
76
+ |---|---|---|---|
77
+ | `x-access-token` | usuário numa UI (token do `@orfeu/angular`) | local: JWT + JWKS do realm | grupos do token |
78
+ | `x-app-token` | usuário fora da UI (script, MCP) — token pessoal | introspecção no Argos (cache) | grupos do usuário no client |
79
+ | `x-api-token` | outro backend / integração | introspecção no Argos (cache) | só as operações concedidas ao token **neste** serviço |
80
+
81
+ | Situação | Resultado |
82
+ |---|---|
83
+ | `PUBLIC` | sempre executa |
84
+ | sem credencial em `OPTIONAL` | executa anônimo |
85
+ | sem credencial em `PRIVATE`/`PROTECTED` | 401 |
86
+ | credencial inválida, expirada, revogada ou de outro realm (fora de `PUBLIC`) | 401 — nunca vira anônimo |
87
+ | credencial válida sem permissão | 403 |
88
+
89
+ Corpos de 401/403 são genéricos; o motivo detalhado vai só para log e auditoria. Rota/resolver **sem**
90
+ operação declarada não é protegida, não tem usuário e não é auditada. As claims lidas no front servem para
91
+ exibir, nunca para decidir permissão.
92
+
93
+ **Identidade é da lib, nunca do contexto que o app monta** (Node/Apollo, 1.0.1+): o `decide()` só aceita
94
+ um `ctx.orfeuUser` sem credencial crua se ele tiver a marca da própria lib (token validado naquele
95
+ contexto, ou `trustUser(ctx, claims)` do `@orfeu/node/apollo`). Atribuir `ctx.orfeuUser = ...` direto dá
96
+ 401 nas operações não públicas, e o valor sem marca é tirado do contexto antes do resolver. As chaves que só
97
+ a lib grava estão em `ORFEU_RESERVED_CONTEXT_KEYS` (`orfeuUser`, `orfeuApiToken`, `orfeuCredential`,
98
+ `orfeuTrace`, `connectionParams`…): o `orfeuWsContext` descarta essas chaves se vierem do `extra`.
99
+
100
+ ## 5. Trace e auditoria
101
+
102
+ - 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).
104
+ Chegou **com** → mesmo `trace_id`, `span_id` novo, o span de quem chamou vira `parent_span_id`,
105
+ `entry: false` (passo interno da mesma ação). O navegador **não** manda `traceparent`; não invente um.
106
+ - **Um evento de auditoria por serviço**: cada serviço audita a própria operação. Uma ação que passa por
107
+ BFF → serviço gera um evento `entry: true` no BFF e um `entry: false` no serviço, ligados pelo `trace_id`.
108
+ Não grave num serviço um evento "em nome" do outro.
109
+ - Envio em lote, fora do caminho da requisição (a cada 1 s ou 200 eventos; buffer de 10 mil; backoff até
110
+ 60 s). Falha de auditoria nunca derruba a requisição. `outcome`: `denied` (401/403), `failure` (status
111
+ ≥ 400 ou exceção), `success`.
112
+ - **Alvo**: dentro do handler, `annotateOperation({...})` / `annotate_operation(...)` com `target_type`,
113
+ `target_id` e `details` (≤ 4 KB, sem segredo nem dado pessoal sensível).
114
+ - `x-route-id` (id da tela) e `x-client-id` (id do app front) são etiquetas de correlação: não são
115
+ verificados nem usados para permissão; na auditoria só entram se forem GUIDs.
116
+ - Log de operação: uma linha por chamada protegida no logger `orfeu.operation`, com os mesmos campos nas
117
+ duas linguagens (`operation`, `operation_id`, `actor_type`, `permission_result`, `duration_ms`,
118
+ `trace_id`, `span_id`…).
119
+
120
+ ## 6. Índice por stack (leia sob demanda)
121
+
122
+ **Angular (front)** → [references/angular.md](references/angular.md) — princípio "a sessão nunca cai sozinha",
123
+ bootstrap, rotas de callback/logoff, fluxos, estado para a UI, erros, SSR.
124
+ - [references/angular-api.md](references/angular-api.md) — todos os exports.
125
+ - [references/angular-recipes.md](references/angular-recipes.md) — bootstrap, callback, logoff, interceptor do
126
+ token, banner de conexão, badge, menu/breadcrumb do `/view`, testes.
127
+ - [references/angular-armadilhas.md](references/angular-armadilhas.md) — loop de login, 401, CORS, duas cópias da lib.
128
+ - Padrões gerais do app: skill `angular`. Shell, layout e componentes: skill `trismegisto`.
129
+
130
+ **Node (Express, Fastify, NestJS, Apollo)** → [references/node.md](references/node.md) — configuração, ordem de
131
+ subida, adapters, respostas, `orfeuHeaders`, auditoria, encerramento.
132
+ - [references/node-api.md](references/node-api.md) — todos os exports dos 5 pontos de import.
133
+ - [references/node-recipes.md](references/node-recipes.md) — um exemplo por framework, BFF → backend, subida
134
+ resiliente, recarregar permissões, encerramento, testes com Argos simulado.
135
+ - [references/node-armadilhas.md](references/node-armadilhas.md) — 403 para todos, eventos perdidos etc.
136
+ - Estrutura do servidor: skills `express` e `apollo`. Fastify e NestJS: ainda não cobertos
137
+ por skill de padrões.
138
+
139
+ **Python (FastAPI, Flask, Django, Strawberry)** → [references/python.md](references/python.md) — configuração,
140
+ `@operation`, `request.state`, envelope, auditoria, `orfeu_headers`, logs, testes.
141
+ - [references/python-api.md](references/python-api.md) — todos os exports e adapters.
142
+ - [references/python-recipes.md](references/python-recipes.md) — FastAPI, permissão, rota pública/opcional,
143
+ chamadas entre serviços, WebSocket, log JSON, testes, Strawberry, Flask/Django, armadilhas (§13).
144
+ - Estrutura do serviço: skill `fastapi`. Strawberry, Django e Flask: ainda não cobertos por skill
145
+ de padrões.
146
+
147
+ **Diferenças entre as três implementações** (comportamento atual: 1.0.0, Node 1.0.1) →
148
+ [references/diferencas.md](references/diferencas.md). Leia antes de supor que algo do Node vale igual no Python.
149
+
150
+ ## 7. Não faça
151
+
152
+ - Não leia `Authorization`/`Bearer`, não valide JWT nem confira grupos à mão: use o guard do SDK.
153
+ - Não deixe rota/resolver de negócio sem operação; não use `PUBLIC` para "resolver depois".
154
+ - Não declare operações depois da subida.
155
+ - Não grave `ctx.orfeuUser` à mão no Apollo: a partir da 1.0.1 isso responde 401. Usuário que o app já
156
+ validou entra por `trustUser(ctx, claims)`.
157
+ - Não espalhe o `connectionParams` (`({ connectionParams }) => ({ ...connectionParams })`) no contexto do
158
+ WebSocket: repasse só a allowlist de headers (skill `apollo` em `references/subscriptions.md`).
159
+ - 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.
161
+ - Não repasse credencial com `orfeuHeaders`/`orfeu_headers` para fora dos seus serviços.
162
+ - Não ponha segredo (o `secret` do serviço vem de variável de ambiente/cofre) em código, log ou `details`.
@@ -0,0 +1,201 @@
1
+ # API — @orfeu/angular 1.0.0
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/...`).
5
+
6
+ ## `@orfeu/angular`
7
+
8
+ ```ts
9
+ interface AuthConfig {
10
+ authority: string; // origem do Argos (ex.: 'https://argos.exemplo.com'); '' ou relativo = mesma origem da UI
11
+ realmId: string;
12
+ clientId: string;
13
+ redirectUrl: string; // URL absoluta da rota de callback, igual à cadastrada no client do Argos
14
+ /** @deprecated ignorado; o fluxo é sempre `code`. Valor diferente de 'code' gera aviso em dev. */
15
+ responseType?: string;
16
+ scope: string; // ex.: 'openid profile'
17
+ }
18
+
19
+ const AUTH_CONFIG: InjectionToken<AuthConfig>;
20
+ ```
21
+
22
+ ## `@orfeu/angular/core`
23
+
24
+ Reexporta `AUTH_CONFIG` e `AuthConfig`.
25
+
26
+ ### `provideAuth(config: AuthConfig, options?: AuthOptions): EnvironmentProviders`
27
+
28
+ Fornece `AUTH_CONFIG` e `AUTH_OPTIONS` (com `eagerInit` resolvido) e, com `eagerInit !== false`,
29
+ `provideAppInitializer(() => inject(AuthorizationService).initialize())`.
30
+
31
+ Alternativa sem `provideAuth`: `{ provide: AUTH_CONFIG, useValue: config }` (+ opcionalmente
32
+ `{ provide: AUTH_OPTIONS, useValue: options }`). Nesse caso **não há** initializer: o `PrivateGuard` faz o
33
+ refresh na primeira rota protegida.
34
+
35
+ ### `AuthOptions` / `AUTH_OPTIONS`
36
+
37
+ ```ts
38
+ interface AuthOptions {
39
+ eagerInit?: boolean; // padrão true
40
+ expiryLog?: boolean; // padrão isDevMode()
41
+ initInIframe?: boolean; // padrão false
42
+ autoReauthorize?: boolean; // padrão true
43
+ }
44
+ const AUTH_OPTIONS: InjectionToken<AuthOptions>; // opcional na injeção
45
+ ```
46
+
47
+ Detalhes de cada opção na tabela de [angular.md](angular.md) §3.
48
+
49
+ ### `AuthorizationService` (`providedIn: 'root'`)
50
+
51
+ Estado:
52
+
53
+ | Membro | Tipo | Comportamento |
54
+ |---|---|---|
55
+ | `isAuth$` | `Observable<boolean>` | `distinctUntilChanged`. `true` do primeiro token aplicado até um logout explícito. **Não** vira `false` quando o token vence. Valor inicial `false`. |
56
+ | `authenticated` | `boolean` (getter) | valor atual de `isAuth$`. |
57
+ | `tokenExpired$` | `Observable<boolean>` | `true` enquanto o token atual está vencido e nenhum outro chegou. Só informa. |
58
+ | `tokenExpired` | `boolean` (getter) | calculado na hora (`Date.now() >= vencimento`). |
59
+ | `connectionState$` | `Observable<ConnectionState>` | `distinctUntilChanged`. Inicial `'online'`. |
60
+ | `connectionState` | `ConnectionState` (getter) | valor atual. |
61
+ | `reauthorizationRequired$` | `Observable<boolean>` | `true` quando o Argos recusou o refresh; volta a `false` quando um token novo chega ou no logout. |
62
+ | `reauthorizationRequired` | `boolean` (getter) | valor atual. |
63
+ | `badgeChanged$` | `Observable<void>` | emite quando o badge ativo muda (login, refresh, troca, outra aba). Sem valor inicial. |
64
+ | `badge` | `Badge \| null` (getter) | badge cujo `id` é a claim `badge_id`, procurado na claim `badges`. |
65
+ | `badges` | `Badge[]` (getter) | claim `badges` (ou `[]`). |
66
+ | `profile` | `UserProfile` (getter) | `{ name, role, picture }` das claims de mesmo nome (`null` se ausentes). |
67
+ | `getToken()` | `string \| null` | token de acesso atual (pode estar vencido; veja `tokenExpired`). Só em memória. |
68
+
69
+ `type ConnectionState = 'online' | 'reconnecting' | 'offline' | 'reauthorizing'`:
70
+ - `online`: renovação funcionando (também o estado sem sessão);
71
+ - `reconnecting`: tentando renovar depois de uma falha (ou ao voltar a rede/foco);
72
+ - `offline`: o Argos não respondeu (rede, CORS, timeout, 5xx, 401/403 sem código de recusa do Argos — ex.: a
73
+ página de um gateway). Sessão intacta, tentando de novo. Também é emitido pelo evento `offline` do
74
+ navegador quando há sessão;
75
+ - `reauthorizing`: o Argos recusou o refresh; reautorização automática em andamento ou bloqueada (veja
76
+ `reauthorizationRequired$`), ou outra aba está reautorizando.
77
+
78
+ Métodos:
79
+
80
+ | Assinatura | Comportamento |
81
+ |---|---|
82
+ | `initialize(): Promise<void>` | `silentRenew()` + `view.update(token)`. **Nunca lança.** No SSR não faz nada; em iframe só roda com `initInIframe: true`. Chamado pelo initializer do `provideAuth`. |
83
+ | `ensureAuthenticated(): Promise<boolean>` | Com sessão: `true` (se o token estiver vencido, dispara a renovação na hora). Sem sessão: tenta `silentRenew()`, a menos que já se saiba que não há sessão (refresh recusado sem sessão, ou logout). SSR → `false`. |
84
+ | `startLogin(returnUrl: string): Promise<void>` | Com `connectionState === 'offline'`: guarda a URL (se for caminho relativo seguro) e navega para ela quando a sessão voltar; não redireciona. Senão: `authorize(returnUrl)`. |
85
+ | `authorize(returnUrl?: string, options?: { prompt?: 'none' \| 'login' }): Promise<void>` | Gera PKCE (S256), `state` e `nonce` (`crypto.randomUUID()`), grava no `sessionStorage` (`pkce_code_verifier`, `oidc_state`, `oidc_nonce` e, se `returnUrl` começar com `/` e não com `//`, `orfeu_return_url`) e faz `window.location.href = <authority>/api/realms/<realm>/protocol/openid-connect/authorize?...` com `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`, `nonce`, `code_challenge`, `code_challenge_method=S256` e `prompt` se pedido. SSR: não faz nada. `returnUrl` absoluta ou `//host` é ignorada (proteção contra open redirect). |
86
+ | `handleCallback(params: CallbackParams, redirect = true): Promise<void>` | Caminho recomendado para a rota de callback (veja abaixo). |
87
+ | `token(params: Record<string, string>, redirect = true): Promise<void>` | `POST /token` (`application/x-www-form-urlencoded`, `withCredentials`). Se `params.state` vier, é conferido com o gravado **antes** da requisição e não é enviado. Com `id_token` e nonce gravado, confere o nonce. Sucesso: limpa verifier/state/nonce, aplica o token, avisa as abas e, com `redirect`, carrega o `/view` e navega (URL de retorno → `routes[0].route_redirect` → `/home`). Baixo nível: prefira `handleCallback`. |
88
+ | `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
+ | `reauthorize(): Promise<void>` | `silentRenew()`; se falhar, `authorize()` **sem** URL de retorno. Para voltar à mesma tela, prefira `authorize(router.url)`. |
90
+ | `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. |
92
+
93
+ `handleCallback(params, redirect = true)`:
94
+ 1. `params.error` em `login_required`/`interaction_required`/`consent_required`/`account_selection_required`
95
+ vindo de uma reautorização silenciosa desta aba: confere o `state` e chama `authorize(urlGuardada)`
96
+ (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)`.
98
+ 3. Sem `params.code` ou sem verifier gravado: rejeita `invalid_callback`.
99
+ 4. Segue como `token({ grant_type: 'authorization_code', code, redirect_uri, client_id, code_verifier, state })`:
100
+ `state` divergente/ausente → `state_mismatch`; nonce divergente → `nonce_mismatch`.
101
+
102
+ `redirect = false`: aplica o token mas **não** carrega o `/view` nem navega (o app decide).
103
+
104
+ Tipos:
105
+
106
+ ```ts
107
+ interface Badge { id: string; name: string; }
108
+ interface BadgePayload { badge_id: string | null; badges: Badge[]; }
109
+ interface UserProfile { name: string | null; role: string | null; picture: string | null; }
110
+ interface CallbackParams {
111
+ code?: string | null; state?: string | null; error?: string | null; error_description?: string | null;
112
+ }
113
+ type ConnectionState = 'online' | 'reconnecting' | 'offline' | 'reauthorizing';
114
+ ```
115
+
116
+ `route.snapshot.queryParams` (tipo `Params`) é aceito direto como `CallbackParams`.
117
+
118
+ ### `classifyRefreshError(err: unknown): 'rejected' | 'offline'`
119
+
120
+ `'rejected'` quando `err` é `HttpErrorResponse` 400/401 com `error.error` em `invalid_refresh`,
121
+ `expired_refresh`, `client_mismatch`, `revoked`, `no_refresh_cookie`, `invalid_grant`, `invalid_client`,
122
+ `unauthorized_client`. Qualquer outra coisa → `'offline'`. Útil para tratar o resultado de um
123
+ `silentRenew()` chamado pelo app.
124
+
125
+ ### `PrivateGuard` (`providedIn: 'root'`, `CanActivate`, `CanActivateChild`)
126
+
127
+ `canActivate(route, state)` / `canActivateChild(route, state)` → `Observable<boolean>`:
128
+ 1. `ensureAuthenticated()` → `true` libera;
129
+ 2. senão `await startLogin(state.url)` e devolve `false` (falha ao iniciar o login → `console.error` e `false`).
130
+
131
+ Construtor: `new PrivateGuard(auth: AuthorizationService)`. Use direto nos arrays de guard das rotas.
132
+
133
+ ### `OrfeuAuthError` / `OrfeuAuthErrorCode`
134
+
135
+ ```ts
136
+ type OrfeuAuthErrorCode = 'state_mismatch' | 'nonce_mismatch' | 'invalid_callback' | 'callback_error' | 'not_authenticated';
137
+ class OrfeuAuthError extends Error { readonly code: OrfeuAuthErrorCode; name: 'OrfeuAuthError'; }
138
+ ```
139
+
140
+ ### `ViewService` (`providedIn: 'root'`)
141
+
142
+ O `/view` (`GET <authority>/api/realms/<realm>/protocol/openid-connect/view`, `withCredentials`,
143
+ `Authorization: Bearer <token>` quando há token) devolve o que o usuário pode navegar: rotas (menu) e apps.
144
+ A lib o carrega sozinha no boot, no login, na troca de badge e quando outra aba manda um token.
145
+
146
+ | Membro | Comportamento |
147
+ |---|---|
148
+ | `currentView$` / `currentView` | `View` atual. Começa `null`; em erro, `{ routes: [], apps: [] }`. |
149
+ | `viewError$` / `viewError` | último erro do `/view` (`HttpErrorResponse` etc.) ou `null` depois de um sucesso. |
150
+ | `viewToken` | token do último `update()` bem-sucedido (`null` = sem token, `undefined` = nunca carregou). |
151
+ | `update(token?: string \| null): Promise<any>` | busca e publica em `currentView`. **Não lança**: em erro publica e devolve `emptyView()`. Chamadas simultâneas com o mesmo token compartilham a requisição. |
152
+ | `view(token?): Promise<any>` | busca sem publicar; em erro devolve `emptyView()`. |
153
+ | `fetchView(token?): Promise<View>` | busca sem publicar; **rejeita** em erro (e emite em `viewError$`). |
154
+ | `clearView(): Promise<void>` | `currentView = null`, `viewToken = undefined`. |
155
+ | `updateBreadcrumb(route: any[]): void` | recebe a cadeia de nós `Route` da raiz até a página (índice 0 = raiz, ignorado); publica `breadCrumb` (`{ icon, urls: [{ label: route_display_name, routerLink: route_redirect }] }`, `icon` = `route_icon` do último) e `logControl` (os nós a partir do nível 1). |
156
+ | `breadCrumb$` / `breadCrumb`, `logControl$` / `logControl` | estado publicado por `updateBreadcrumb`. Começam `null`. |
157
+ | `getLevel(url)`, `getLevelControl(url, type)`, `getUrlAtLevel(url, level)` | profundidade/prefixo da URL depois de trocar o `baseHref` por `/` (`getLevelControl` desconta 1 quando `type === 'activate'`). |
158
+
159
+ ```ts
160
+ type Route = {
161
+ routed_id: string; // id da rota (página) no Argos — o que vai em x-route-id
162
+ route_id?: string; route_name?: string; route_display_name?: string; route_icon?: string;
163
+ route_order?: number; route_path?: string; route_redirect?: string; route_redirect_to?: string;
164
+ route_type?: string; routes?: Route[]; // filhos
165
+ };
166
+ interface AppDef { id: string; name: string; app_url: string; }
167
+ type View = { routes?: Route[]; apps?: AppDef[] };
168
+ interface BreadCrumb { icon: string; urls: { label: string; routerLink: string }[] }
169
+ function emptyView(): View; // { routes: [], apps: [] }
170
+ ```
171
+
172
+ ### `RealmAppsService` (`providedIn: 'root'`)
173
+
174
+ `getApplications(token?: string | null): Promise<AppDef[]>` — devolve `currentView.apps` (ou `[]`). Se
175
+ `token` for diferente do usado no último `/view` carregado, recarrega o `/view` com ele antes. Mesmo token ou
176
+ sem token: sem requisição. Passe `auth.getToken()`.
177
+
178
+ ## `@orfeu/angular/util`
179
+
180
+ Sem dependência de Angular.
181
+
182
+ | Função | Comportamento |
183
+ |---|---|
184
+ | `decodeJwt<T = any>(token: string): T \| null` | payload do JWT (base64url + UTF-8), **sem verificar assinatura**. `null` se inválido. |
185
+ | `isJwtExpired(token: string): boolean` | `true` se `exp` no passado, sem `exp` ou token inválido. Usa o relógio local direto (a lib, internamente, prefere `exp − iat`). |
186
+ | `generatePkcePair(): Promise<{ verifier: string; challenge: string }>` | par PKCE S256. |
187
+ | `generateCodeVerifier(): string` | 32 bytes aleatórios em base64url (43 caracteres). |
188
+ | `generateCodeChallenge(verifier: string): Promise<string>` | `base64url(SHA-256(verifier))`. |
189
+ | `base64UrlEncode(bytes: Uint8Array): string` | base64url sem padding. |
190
+
191
+ ## `sessionStorage` e canal (para depurar)
192
+
193
+ | Chave | Conteúdo |
194
+ |---|---|
195
+ | `pkce_code_verifier`, `oidc_state`, `oidc_nonce` | fluxo de login em andamento (limpos no fim ou em erro) |
196
+ | `orfeu_return_url` | URL a restaurar depois do login |
197
+ | `orfeu_auto_reauth_at` | momento da última reautorização automática desta aba (janela de 5 min) |
198
+ | `orfeu_silent_reauth` | marca a tentativa `prompt=none` em andamento |
199
+
200
+ Canal `BroadcastChannel('auth_<clientId>')`, mensagens: `TOKEN_UPDATED { accessToken }`, `REFRESH_STARTED`,
201
+ `REFRESH_FAILED`, `LOGOUT`, `REAUTH_STARTED`. Logs no console com o prefixo `[orfeu-angular]`.
@@ -0,0 +1,116 @@
1
+ # Armadilhas e erros comuns — @orfeu/angular 1.0.0
2
+
3
+ Cada item: sintoma → causa → o que fazer.
4
+
5
+ ## Login e callback
6
+
7
+ **Loop: vai ao Argos, volta, vai de novo.**
8
+ - A rota de callback (ou `/logoff`) está sob `PrivateGuard` (direto ou por um pai com `canActivateChild`).
9
+ Sem sessão, o guard inicia outro login antes de o callback rodar. Tire essas rotas da árvore protegida.
10
+ - O componente do callback não chama `handleCallback()` (ou chama `authorize()` de novo no `ngOnInit`).
11
+ - O `redirectUrl` aponta para uma rota que não existe e cai no `**` protegido.
12
+
13
+ **`invalid_callback` ao abrir o callback.** A página foi recarregada (o `code` e o verifier já foram usados e
14
+ limpos), aberta em outra aba ou o `sessionStorage` foi limpo. Ofereça "Entrar de novo" (`authorize('/')`).
15
+
16
+ **`state_mismatch`.** Login iniciado em uma aba e concluído em outra, dois logins simultâneos na mesma aba, ou
17
+ o link do Argos foi reaproveitado. Mesma saída: `authorize()`.
18
+
19
+ **`callback_error` com `redirect_uri` inválido.** `AuthConfig.redirectUrl` precisa ser **idêntico** ao
20
+ cadastrado no client do Argos (esquema, host, porta, base href, barra final).
21
+
22
+ **`TypeError` de `crypto.subtle`/`randomUUID` e o login nem começa** (console:
23
+ `[orfeu-angular] PrivateGuard: falha ao iniciar o login`). O app está em contexto inseguro (HTTP fora de
24
+ `localhost`). Sirva por HTTPS.
25
+
26
+ **Depois do login cai numa rota inexistente.** Sem URL de retorno, a lib navega para
27
+ `routes[0].route_redirect` do `/view` ou `/home`. Crie `/home` (ou garanta que o `/view` traga a rota).
28
+
29
+ **`returnUrl` ignorada.** Só caminhos relativos começando com `/` (não `//`) são aceitos. Passe `router.url`,
30
+ não `location.href`.
31
+
32
+ ## Sessão e renovação
33
+
34
+ **"O usuário continua logado com o token vencido."** É o comportamento esperado: `authenticated` só cai com
35
+ `logout()`. Use `tokenExpired$` para saber do vencimento e `connectionState$` para saber do servidor.
36
+
37
+ **App chama `logout()` em erro de API/401 e o usuário perde o trabalho.** Não faça isso. Use o interceptor
38
+ com nova tentativa (`angular-recipes.md` §4) e o banner de conexão (`angular-recipes.md` §5).
39
+
40
+ **Muitos `/token` seguidos.** Algo chama `silentRenew()` em loop (ex.: num `setInterval` ou a cada
41
+ requisição). A lib já agenda a renovação; chame `silentRenew()` só para reagir a um 401.
42
+
43
+ **`reauthorizationRequired$` fica `true` e nada acontece.** A reautorização automática está desligada
44
+ (`autoReauthorize: false`), já foi tentada há menos de 5 min nesta aba, ou outra aba está cuidando (espere
45
+ até 2 min). Mostre o botão que chama `auth.authorize(router.url)`.
46
+
47
+ **Boot demora quando o servidor está inalcançável.** Com `eagerInit: true` o primeiro render espera a
48
+ tentativa de refresh. Se a rede deixa a requisição pendurada, o app espera junto. Para apps que precisam
49
+ abrir mesmo assim, use `eagerInit: false` (o `PrivateGuard` faz o refresh na primeira rota protegida e, offline,
50
+ adia a navegação até a conexão voltar).
51
+
52
+ **Rota protegida "não abre" quando offline e sem sessão.** Esperado: `startLogin()` guarda a URL e navega
53
+ sozinho quando a conexão volta. Mostre o banner `offline`.
54
+
55
+ **Abas dessincronizadas.** Navegador sem `BroadcastChannel`, `clientId` diferente entre as abas (canal é
56
+ `auth_<clientId>`) ou origens diferentes (o canal é por origem).
57
+
58
+ ## APIs do app
59
+
60
+ **API responde 401 sempre.**
61
+ - O token foi mandado em `Authorization: Bearer …`. O `@orfeu/node` só lê `x-access-token` (valor cru, sem
62
+ `Bearer`).
63
+ - O interceptor não casou a URL (prefixo errado) ou o token ainda é `null` (requisição disparada antes do
64
+ login concluir; ex.: em `APP_INITIALIZER` próprio rodando antes do `provideAuth`).
65
+ - Realm diferente: o token é do realm de `AuthConfig.realmId`; a API precisa estar no mesmo realm (ou aceitar
66
+ outros).
67
+
68
+ **API responde 403.** O usuário está autenticado mas sem permissão para a operação (grupos/badge). Não é
69
+ problema de token: não renove nem deslogue; mostre "sem permissão". Às vezes a troca de badge resolve.
70
+
71
+ **Refresh quebra depois de adicionar um interceptor.** O interceptor está pondo header próprio
72
+ (`x-access-token`, `x-client-id`…) nas chamadas ao Argos; isso força um preflight CORS que o Argos não aceita.
73
+ Restrinja o interceptor às URLs das suas APIs.
74
+
75
+ **Token vazando para terceiros.** Interceptor que põe `x-access-token` em toda requisição. Use lista explícita
76
+ de prefixos.
77
+
78
+ ## Injeção e empacotamento
79
+
80
+ **`NullInjectorError: No provider for InjectionToken AUTH_CONFIG`.**
81
+ - Falta `provideAuth(...)` (ou `{ provide: AUTH_CONFIG, ... }`) no `ApplicationConfig`.
82
+ - Há **duas cópias** da lib no bundle (uma biblioteca interna trouxe a própria em `node_modules`, ou um
83
+ `paths` do `tsconfig` aponta para outra pasta). Confira com `npm ls @orfeu/angular`; bibliotecas devem
84
+ declarar `@orfeu/angular` como peer.
85
+
86
+ **Duas sessões / serviço "não vê" o login.** Mesma causa: duas cópias, ou o serviço foi fornecido de novo
87
+ num componente (`providers: [AuthorizationService]`). Ele é `providedIn: 'root'`: nunca o declare em
88
+ `providers`.
89
+
90
+ **Erro de import `@orfeu/angular/core/src/...`.** Só os três pontos de import são públicos.
91
+
92
+ ## SSR
93
+
94
+ **Rotas protegidas renderizam vazias no servidor / guard bloqueia no SSR.** No servidor a lib é inerte e o
95
+ `PrivateGuard` devolve `false`. Renderize as rotas protegidas só no cliente (`RenderMode.Client` nessas rotas)
96
+ e não use `location` no config.
97
+
98
+ ## Testes
99
+
100
+ **`NullInjectorError` de `AUTH_CONFIG` num teste de componente.** O componente injeta `AuthorizationService`
101
+ real. Forneça o falso (`{ provide: AuthorizationService, useValue: fake }`) ou `provideAuth(...)` com
102
+ `provideHttpClientTesting()`.
103
+
104
+ **`PrivateGuard` real com serviço falso falha.** O falso precisa de `ensureAuthenticated()` e `startLogin()`.
105
+
106
+ **Teste "trava" ou vaza timers.** O serviço real agenda renovação: use `eagerInit: false`, fake timers e deixe o
107
+ `TestBed` destruir o serviço entre testes.
108
+
109
+ ## Diagnóstico rápido
110
+
111
+ - Console: mensagens com o prefixo `[orfeu-angular]` (renovação falhou e quando tenta de novo, reautorização,
112
+ falha do `/view`, `token expira em …` em modo dev).
113
+ - `sessionStorage`: `pkce_code_verifier`/`oidc_state`/`oidc_nonce` presentes fora de um login = fluxo
114
+ interrompido; `orfeu_auto_reauth_at` = reautorização automática recente.
115
+ - Aba Rede: `POST …/protocol/openid-connect/token` (refresh/troca do code), `GET …/view`, `GET …/logout`.
116
+ Status 0/erro de CORS no `/token` = servidor inalcançável ou CORS sem credenciais para a origem do app.