@acropole/skills 1.7.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +5 -4
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/package.json +1 -1
  4. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
  5. package/skills/angular/SKILL.md +2 -2
  6. package/skills/angular/references/dados.md +3 -3
  7. package/skills/angular/references/estrutura.md +6 -5
  8. package/skills/angular/references/features.md +5 -5
  9. package/skills/angular/references/testes-build.md +1 -1
  10. package/skills/auto-servico/SKILL.md +18 -14
  11. package/skills/express/references/dados.md +4 -1
  12. package/skills/express/references/estrutura.md +2 -1
  13. package/skills/fastapi/references/banco.md +6 -2
  14. package/skills/fastapi/references/estrutura.md +1 -1
  15. package/skills/hefesto/SKILL.md +6 -2
  16. package/skills/orfeu/SKILL.md +43 -13
  17. package/skills/orfeu/references/angular-api.md +39 -13
  18. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  19. package/skills/orfeu/references/angular-recipes.md +25 -12
  20. package/skills/orfeu/references/angular.md +37 -15
  21. package/skills/orfeu/references/diferencas.md +17 -8
  22. package/skills/orfeu/references/node-api.md +41 -9
  23. package/skills/orfeu/references/node-armadilhas.md +16 -2
  24. package/skills/orfeu/references/node-recipes.md +13 -4
  25. package/skills/orfeu/references/node.md +31 -12
  26. package/skills/orfeu/references/python-api.md +41 -16
  27. package/skills/orfeu/references/python-recipes.md +13 -9
  28. package/skills/orfeu/references/python.md +33 -12
  29. package/skills/orfeu/references/react.md +133 -0
  30. package/skills/trismegisto/SKILL.md +42 -29
  31. package/skills/trismegisto/references/angular-api.md +608 -6
  32. package/skills/trismegisto/references/angular-exports.md +479 -791
  33. package/skills/trismegisto/references/angular-recipes.md +13 -7
  34. package/skills/trismegisto/references/angular.md +32 -9
  35. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  36. package/skills/trismegisto/references/catalogo/seletores.json +90 -65
  37. package/skills/trismegisto/references/react-api.md +16864 -0
  38. package/skills/trismegisto/references/react.md +237 -0
  39. package/skills/trismegisto/references/spine-api.md +5565 -1973
  40. package/skills/trismegisto/references/spine-recipes.md +113 -26
  41. package/skills/trismegisto/references/spine.md +95 -33
  42. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -1,4 +1,4 @@
1
- # Armadilhas e erros comuns — @orfeu/angular 1.4.0
1
+ # Armadilhas e erros comuns — @orfeu/angular 1.7.1
2
2
 
3
3
  Cada item: sintoma → causa → o que fazer.
4
4
 
@@ -10,6 +10,13 @@ Cada item: sintoma → causa → o que fazer.
10
10
  - O componente do callback não chama `handleCallback()` (ou chama `authorize()` de novo no `ngOnInit`).
11
11
  - O `redirectUrl` aponta para uma rota que não existe e cai no `**` protegido.
12
12
 
13
+ **Login falha com `invalid_id_token` depois de atualizar para a 1.7.** O id_token passou a ser conferido: `iss`
14
+ igual ao emissor esperado, `aud` com o `clientId` e `exp` válido (30 s de tolerância).
15
+ - `AuthConfig.issuer` errado (derivado de um endereço interno, com barra no fim ou sem `/realms/<realm>`): use o
16
+ `iss` exato que o Argos emite (`<servidor>/realms/<realm>`), ou tire a opção e deixe a lib usar a descoberta.
17
+ - Relógio da máquina muito adiantado ou atrasado (mais de 30 s): o `exp` do id_token parece vencido.
18
+ - Teste com id_token montado à mão: inclua `iss`, `aud` (o `clientId`) e `exp`.
19
+
13
20
  **`invalid_callback` ao abrir o callback.** A página foi recarregada (o `code` e o verifier já foram usados e
14
21
  limpos), aberta em outra aba ou o `sessionStorage` foi limpo. Ofereça "Entrar de novo" (`authorize('/')`).
15
22
 
@@ -43,6 +50,16 @@ não `location.href`.
43
50
  **App chama `logout()` em erro de API/401 e o usuário perde o trabalho.** Não faça isso. Use o interceptor
44
51
  com nova tentativa (`angular-recipes.md` §4) e o banner de conexão (`angular-recipes.md` §5).
45
52
 
53
+ **401 na primeira requisição depois de a aba voltar do segundo plano.** O navegador segurou os timers e a
54
+ renovação agendada não rodou a tempo. Desde a 1.5 o `OrfeuTokenInterceptor` resolve isso, mas só se estiver na
55
+ cadeia: com `withInterceptors([...])` (sem `withInterceptorsFromDi()`), inclua o `orfeuTokenInterceptor` da lib
56
+ **depois** do interceptor que põe o `x-access-token`. Fora do `HttpClient` (WebSocket, `fetch`), use
57
+ `await auth.getValidToken()` em vez de `getToken()`.
58
+
59
+ **Interceptor do app com o mesmo nome do da lib.** Receitas antigas chamavam o interceptor do app de
60
+ `orfeuTokenInterceptor`; desde a 1.5 a lib exporta um com esse nome. Renomeie o do app (`apiTokenInterceptor`) para
61
+ não importar um no lugar do outro.
62
+
46
63
  **Clicou em "Sair" e nada aconteceu.** O `GET /logout` falhou duas vezes (rede, 5xx, CORS — a origem do app
47
64
  precisa estar nas `redirect_uris` do client) e a 1.3 manteve a sessão de propósito: `logoutFailed$` emitiu e
48
65
  `logout()` resolveu `false`. Com o `@trismegisto/spine` ≥ 2.1.2 o aviso sai sozinho (o `SpineLogoutService` assina
@@ -1,6 +1,6 @@
1
- # Receitas — @orfeu/angular 1.4.0
1
+ # Receitas — @orfeu/angular 1.7.1
2
2
 
3
- Todas usam a API real da 1.4.0 ([angular-api.md](angular-api.md)). Componentes standalone, `inject()`, controle de fluxo
3
+ Todas usam a API real da 1.7.1 ([angular-api.md](angular-api.md)). Componentes standalone, `inject()`, controle de fluxo
4
4
  `@if`/`@for`. Troque textos e estilos pelos do app (design system, i18n).
5
5
 
6
6
  ## 1. Bootstrap
@@ -10,14 +10,15 @@ Todas usam a API real da 1.4.0 ([angular-api.md](angular-api.md)). Componentes s
10
10
  import { ApplicationConfig } from '@angular/core';
11
11
  import { provideHttpClient, withInterceptors } from '@angular/common/http';
12
12
  import { provideRouter } from '@angular/router';
13
- import { provideAuth } from '@orfeu/angular/core';
13
+ import { orfeuTokenInterceptor, provideAuth } from '@orfeu/angular/core';
14
14
  import { environment } from '../environments/environment';
15
15
  import { routes } from './app.routes';
16
- import { orfeuTokenInterceptor } from './core/orfeu-token.interceptor';
16
+ import { apiTokenInterceptor } from './core/api-token.interceptor';
17
17
 
18
18
  export const appConfig: ApplicationConfig = {
19
19
  providers: [
20
- provideHttpClient(withInterceptors([orfeuTokenInterceptor])),
20
+ // O do app põe o x-access-token; o da lib (1.5+), DEPOIS dele, troca o token vencido pelo renovado.
21
+ provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor])),
21
22
  provideRouter(routes),
22
23
  provideAuth({
23
24
  authority: environment.argosUrl, // ex.: 'https://argos.exemplo.com' (sem barra no fim)
@@ -32,6 +33,11 @@ export const appConfig: ApplicationConfig = {
32
33
 
33
34
  Com SSR, não use `location` no config (não existe no servidor): ponha a URL absoluta no `environment`.
34
35
 
36
+ Com `provideHttpClient(withInterceptorsFromDi())` o `provideAuth` já registra o `OrfeuTokenInterceptor` da lib (versão
37
+ de classe); com `withInterceptors([...])`, como acima, ponha o `orfeuTokenInterceptor` na lista, **depois** do
38
+ interceptor que acrescenta o token (ele só age em requisições que já levam o token da sessão). Se o
39
+ `AuthConfig.issuer` não for passado, a lib busca o emissor esperado do id_token na descoberta do realm (1.7+).
40
+
35
41
  ## 2. Rotas
36
42
 
37
43
  ```ts
@@ -146,7 +152,7 @@ protected async sair(): Promise<void> {
146
152
  ```
147
153
 
148
154
  Isso vale para app **sem** spine (ou assine o `logoutFailed$` uma vez, para um aviso único em todo `logout()`).
149
- App com `@trismegisto/spine` ≥ 2.1.2: o `SpineLogoutService` (`@trismegisto/spine/layout`) já assina o `logoutFailed$`
155
+ App com `@trismegisto/spine` ≥ 2.1.2: o `SpineLogoutService` (`@trismegisto/angular/spine/layout`) já assina o `logoutFailed$`
150
156
  e mostra o aviso para **qualquer** `logout()`, inclusive o do app — não mostre toast próprio (sairia em dobro). Num
151
157
  botão próprio, chame `inject(SpineLogoutService).logout()`: mesmo aviso e só apaga os recentes quando a saída deu certo.
152
158
 
@@ -156,8 +162,13 @@ As APIs com `@orfeu/node` leem o token cru em `x-access-token`. Opcionalmente, `
156
162
  deste front) e `x-route-id` (o `routed_id` da página atual no `/view`) entram na auditoria — só são gravados
157
163
  se forem GUIDs.
158
164
 
165
+ A lib não acrescenta o token às APIs do app (só às próprias chamadas ao Argos): isso é deste interceptor. O
166
+ `orfeuTokenInterceptor` da lib (1.5+) é outra coisa — segura a requisição que já leva o token vencido ou quase,
167
+ espera a renovação e troca pelo novo (aba em segundo plano, máquina suspensa). Não dê ao interceptor do app o mesmo
168
+ nome do da lib.
169
+
159
170
  ```ts
160
- // core/orfeu-token.interceptor.ts
171
+ // core/api-token.interceptor.ts
161
172
  import { HttpErrorResponse, HttpInterceptorFn, HttpRequest } from '@angular/common/http';
162
173
  import { inject } from '@angular/core';
163
174
  import { AUTH_CONFIG, AuthorizationService } from '@orfeu/angular/core';
@@ -167,7 +178,7 @@ import { environment } from '../../environments/environment';
167
178
  /** Só as APIs DESTE app. Nunca o Argos (preflight CORS com header estranho quebra o refresh) nem terceiros (vazaria o token). */
168
179
  const API_PREFIXES: string[] = [environment.apiUrl, '/api/'];
169
180
 
170
- export const orfeuTokenInterceptor: HttpInterceptorFn = (req, next) => {
181
+ export const apiTokenInterceptor: HttpInterceptorFn = (req, next) => {
171
182
  if (!API_PREFIXES.some(prefix => req.url.startsWith(prefix))) return next(req);
172
183
 
173
184
  const auth = inject(AuthorizationService);
@@ -200,8 +211,9 @@ export const orfeuTokenInterceptor: HttpInterceptorFn = (req, next) => {
200
211
  recusou, reautoriza (veja §5/§6).
201
212
  - Para mandar `x-route-id`, guarde o `routed_id` da página atual num serviço do app (ex.: ao montar o
202
213
  breadcrumb, §8) e acrescente-o em `setHeaders`.
203
- - GraphQL por WebSocket: mande o mesmo token em `connectionParams` (`{ 'x-access-token': token }`), lido na
204
- conexão; reconecte quando o token mudar.
214
+ - GraphQL por WebSocket: mande o token em `connectionParams` (`{ 'x-access-token': await auth.getValidToken() }`,
215
+ 1.5+: espera a renovação se o token estiver vencido ou quase), lido na conexão; reconecte quando o token mudar.
216
+ O mesmo vale para `fetch` fora do `HttpClient`.
205
217
 
206
218
  ## 5. Banner de conexão
207
219
 
@@ -441,7 +453,8 @@ import { TestBed } from '@angular/core/testing';
441
453
  import { HttpClient, provideHttpClient, withInterceptors } from '@angular/common/http';
442
454
  import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
443
455
  import { provideRouter } from '@angular/router';
444
- import { AuthorizationService, provideAuth } from '@orfeu/angular/core';
456
+ import { AuthorizationService, orfeuTokenInterceptor, provideAuth } from '@orfeu/angular/core';
457
+ import { apiTokenInterceptor } from './core/api-token.interceptor';
445
458
 
446
459
  const config = {
447
460
  authority: 'https://argos.test', realmId: 'realm-1', clientId: 'app-client',
@@ -459,7 +472,7 @@ beforeEach(() => {
459
472
  TestBed.configureTestingModule({
460
473
  providers: [
461
474
  provideRouter([]),
462
- provideHttpClient(withInterceptors([orfeuTokenInterceptor])),
475
+ provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor])),
463
476
  provideHttpClientTesting(),
464
477
  provideAuth(config, { eagerInit: false, expiryLog: false, autoReauthorize: false }),
465
478
  ],
@@ -1,7 +1,8 @@
1
1
  # @orfeu/angular — guia de uso (front)
2
2
 
3
- > Escrito para a **1.4.0** (anda junto com `@orfeu/node` e `orfeu`; a 1.3.0 mudou o callback com `?error` e o
4
- > `logout()`, §5 e §8). Se a versão instalada for outra, confira os nomes de [angular-api.md](angular-api.md)
3
+ > Escrito para a **1.7.1** (anda junto com `@orfeu/react`, `@orfeu/node` e `orfeu`; a 1.3.0 mudou o callback com
4
+ > `?error` e o `logout()`, a 1.5.0 trouxe o `OrfeuTokenInterceptor` e o `getValidToken()`, a 1.7.0 passou a conferir
5
+ > o id_token — §5, §6 e §8). Se a versão instalada for outra, confira os nomes de [angular-api.md](angular-api.md)
5
6
  > contra os `.d.ts` de `node_modules/@orfeu/angular/types/` antes de copiar código. Conceitos comuns às três
6
7
  > implementações (níveis, headers, trace, auditoria) estão no `SKILL.md` da skill; diferenças entre elas em
7
8
  > [diferencas.md](diferencas.md).
@@ -39,7 +40,7 @@ Consequências para quem integra:
39
40
  ## 2. Instalação e requisitos
40
41
 
41
42
  ```bash
42
- npm install @orfeu/angular@^1.4.0
43
+ npm install @orfeu/angular@^1.7.1
43
44
  ```
44
45
 
45
46
  | Peer | Versão |
@@ -58,8 +59,8 @@ Pontos de import:
58
59
  | Import | Conteúdo |
59
60
  |---|---|
60
61
  | `@orfeu/angular` | `AUTH_CONFIG` e `AuthConfig` |
61
- | `@orfeu/angular/core` | tudo o que um app usa: `provideAuth`, `AuthorizationService`, `PrivateGuard`, `ViewService`, `RealmAppsService`, `OrfeuAuthError`, `AUTH_OPTIONS`, tipos. Reexporta `AUTH_CONFIG`/`AuthConfig` |
62
- | `@orfeu/angular/util` | `decodeJwt`, `isJwtExpired`, PKCE (sem Angular) |
62
+ | `@orfeu/angular/core` | tudo o que um app usa: `provideAuth`, `AuthorizationService`, `OrfeuTokenInterceptor`/`orfeuTokenInterceptor`, `PrivateGuard`, `ViewService`, `RealmAppsService`, `OrfeuAuthError`, `AUTH_OPTIONS`, tipos. Reexporta `AUTH_CONFIG`/`AuthConfig` |
63
+ | `@orfeu/angular/util` | `decodeJwt`, `isJwtExpired` (deprecated desde a 1.6), PKCE (sem Angular) |
63
64
 
64
65
  Na dúvida, importe de `@orfeu/angular/core`.
65
66
 
@@ -70,13 +71,14 @@ Na dúvida, importe de `@orfeu/angular/core`.
70
71
  import { ApplicationConfig } from '@angular/core';
71
72
  import { provideHttpClient, withInterceptors } from '@angular/common/http';
72
73
  import { provideRouter } from '@angular/router';
73
- import { provideAuth } from '@orfeu/angular/core';
74
+ import { orfeuTokenInterceptor, provideAuth } from '@orfeu/angular/core';
74
75
  import { routes } from './app.routes';
75
- import { orfeuTokenInterceptor } from './core/orfeu-token.interceptor'; // angular-recipes.md §4
76
+ import { apiTokenInterceptor } from './core/api-token.interceptor'; // angular-recipes.md §4
76
77
 
77
78
  export const appConfig: ApplicationConfig = {
78
79
  providers: [
79
- provideHttpClient(withInterceptors([orfeuTokenInterceptor])),
80
+ // o do app põe o x-access-token; o da lib, depois, troca o token vencido pelo renovado (§6)
81
+ provideHttpClient(withInterceptors([apiTokenInterceptor, orfeuTokenInterceptor])),
80
82
  provideRouter(routes),
81
83
  provideAuth(
82
84
  {
@@ -85,6 +87,7 @@ export const appConfig: ApplicationConfig = {
85
87
  clientId: environment.clientId, // client do app cadastrado no Argos
86
88
  redirectUrl: `${location.origin}/callback`, // EXATAMENTE como cadastrado no client
87
89
  scope: 'openid profile',
90
+ // issuer: environment.argosIssuer, // opcional (1.7+): iss esperado do id_token (<servidor>/realms/<realm>)
88
91
  },
89
92
  { /* AuthOptions: tudo opcional, ver tabela */ },
90
93
  ),
@@ -94,7 +97,14 @@ export const appConfig: ApplicationConfig = {
94
97
 
95
98
  Todas as chamadas vão para `${authority}/api/realms/${realmId}/...` (`/protocol/openid-connect/authorize`,
96
99
  `/token`, `/view`, `/logout` e `/auth/switch-badge`). `responseType` ainda é aceito no tipo, mas é ignorado
97
- (deprecated): o fluxo é sempre `code`.
100
+ (deprecated): o fluxo é sempre `code`. `issuer` (1.7+, opcional) é o `iss` esperado do id_token; sem ele, vem do
101
+ `issuer` da descoberta (`${authority}/api/realms/${realmId}/.well-known/openid-configuration`, buscada uma vez, no
102
+ primeiro login com id_token) e, com a descoberta fora, basta o `iss` ter a forma `…/realms/<realmId>` (aviso no
103
+ console em desenvolvimento).
104
+
105
+ O `provideAuth` também registra o `OrfeuTokenInterceptor` (1.5+) em `HTTP_INTERCEPTORS`, que só vale com
106
+ `provideHttpClient(withInterceptorsFromDi())`; com `withInterceptors([...])`, inclua o `orfeuTokenInterceptor` na
107
+ lista, como acima.
98
108
 
99
109
  | `AuthOptions` | Padrão | Efeito |
100
110
  |---|---|---|
@@ -128,14 +138,21 @@ hora. Sem sessão e sem tentativa anterior, tenta o refresh. Se não der, chama
128
138
 
129
139
  **Callback**: `handleCallback(route.snapshot.queryParams)` confere `state` (também quando vem `?error`, antes de
130
140
  qualquer efeito — 1.3+), troca o `code` com o
131
- `code_verifier`, confere o `nonce` do `id_token`, aplica o token, avisa as outras abas, carrega o `/view` e
141
+ `code_verifier`, confere o `id_token` (`nonce`; e, 1.7+, `iss` igual ao emissor esperado, `aud` com o `clientId` e
142
+ `exp` presente e não vencido há mais de 30 s), aplica o token, avisa as outras abas, carrega o `/view` e
132
143
  navega para a URL de retorno (ou a 1ª rota do `/view`, ou `/home`). Rejeita com `OrfeuAuthError` — sempre
133
144
  envolva em `try/catch`.
134
145
 
135
146
  **Renovação** (automática, não chame nada): ≥ 120 s de vida → renova 60 s antes de vencer (+ 0–5 s); vida
136
147
  curta → na metade do tempo restante (mínimo 5 s). Falhou por rede/5xx → `connectionState$ = 'offline'` e
137
148
  tenta de novo com backoff 15 s, 30 s, 60 s, 60 s… para sempre. Eventos `online`, `focus` e aba visível
138
- renovam na hora (debounce 1 s).
149
+ renovam na hora (debounce 1 s); desde a 1.5, também `resume` (aba congelada voltando) e `pageshow` (volta pelo
150
+ bfcache).
151
+
152
+ **Aba em segundo plano** (1.5+): o navegador segura os timers de abas ocultas e para tudo com a máquina suspensa,
153
+ então a renovação agendada pode chegar depois do vencimento. O `OrfeuTokenInterceptor` segura as requisições que
154
+ levam o token da sessão vencido ou a menos de 10 s do vencimento (`tokenStale`), espera a renovação (até 10 s) e
155
+ troca o token velho pelo novo; as demais passam direto. Fora do `HttpClient`, use `await auth.getValidToken()`.
139
156
 
140
157
  **Refresh recusado** pelo Argos (400/401 com `invalid_refresh`, `expired_refresh`, `revoked`,
141
158
  `client_mismatch`, `no_refresh_cookie`, `invalid_grant`, `invalid_client`, `unauthorized_client`):
@@ -149,7 +166,8 @@ para o login interativo mantendo a URL. Nunca desloga.
149
166
  sem outra aberta recupera a sessão pelo cookie no boot.
150
167
 
151
168
  **Logout**: `logout()` → `GET /logout?client_id=…` (com cookie) e devolve `Promise<boolean>`. Confirmado pelo
152
- Argos: limpa o estado local, avisa as abas, navega para `/logoff?loggedOut=true` e resolve `true`. Com erro
169
+ Argos: limpa o estado local (inclusive `profile`, `badge` e `badges`, 1.6+), avisa as abas, navega para
170
+ `/logoff?loggedOut=true` e resolve `true`. Com erro
153
171
  (rede, 5xx), repete uma vez; falhando de novo, a sessão **continua** (no Argos ela segue válida — anunciar
154
172
  "saiu" seria mentira), `logoutFailed$` emite `OrfeuAuthError('logout_failed')` e resolve `false`. Mostre o erro
155
173
  e ofereça tentar de novo (`angular-recipes.md` §3). Com o `@trismegisto/spine` ≥ 2.1.2 o shell já faz isso para
@@ -157,13 +175,16 @@ qualquer `logout()` (o `SpineLogoutService` assina o `logoutFailed$`): o app nã
157
175
 
158
176
  ## 6. Chamando as APIs do app
159
177
 
160
- A lib **não** tem interceptor: ela só põe credencial nas próprias chamadas ao Argos. As APIs do app que usam
161
- `@orfeu/node` leem o token **cru** no header **`x-access-token`** (não usam `Authorization: Bearer`).
162
- Use o interceptor de [angular-recipes.md](angular-recipes.md) §4, que:
178
+ A lib **não** acrescenta o token às APIs do app: ela só põe credencial nas próprias chamadas ao Argos. As APIs do
179
+ app que usam `@orfeu/node` leem o token **cru** no header **`x-access-token`** (não usam `Authorization: Bearer`).
180
+ Use o interceptor do app de [angular-recipes.md](angular-recipes.md) §4 (`apiTokenInterceptor`), que:
163
181
  - só toca nas URLs das **suas** APIs (lista explícita) — nunca nas do Argos nem de terceiros;
164
182
  - manda `x-access-token: <auth.getToken()>` e, opcionalmente, `x-client-id`/`x-route-id` para a auditoria;
165
183
  - num 401 com sessão viva, espera uma renovação (`silentRenew()`) e repete **uma** vez.
166
184
 
185
+ Depois dele, o `orfeuTokenInterceptor` da lib troca o token vencido ou quase pelo renovado (§5, "Aba em segundo
186
+ plano"). Para WebSocket ou `fetch`, `await auth.getValidToken()`.
187
+
167
188
  O browser **não** manda `traceparent`: a chamada do usuário é a entrada do trace (`entry: true`) na API.
168
189
 
169
190
  ## 7. Estado para a interface
@@ -192,6 +213,7 @@ permissão. Quem decide é a API (`@orfeu/node`) e o `/view` (o que o usuário p
192
213
  | `invalid_callback` | callback sem `code` ou sem `code_verifier` no `sessionStorage` (recarregou o callback, abriu em outra aba, storage limpo) |
193
214
  | `state_mismatch` | `state` ausente ou diferente do gravado em `authorize()` — inclusive num `?error` (link forjado, aba antiga), que então não tem efeito nenhum |
194
215
  | `nonce_mismatch` | `nonce` do `id_token` diferente do gravado |
216
+ | `invalid_id_token` | (1.7+) `id_token` com `iss` diferente do emissor esperado, `aud` sem o `clientId`, ou `exp` ausente ou vencido há mais de 30 s. Mesmo tratamento do nonce divergente: o token não é aplicado e uma sessão existente não muda |
195
217
  | `not_authenticated` | `switchBadge()` sem sessão; `silentRenew()` no servidor (SSR) |
196
218
 
197
219
  Erros HTTP (`HttpErrorResponse`) do `/token` no callback e do `switch-badge` são repassados como vieram.
@@ -1,7 +1,8 @@
1
- # Diferenças entre as implementações — comportamento atual (1.4.0)
1
+ # Diferenças entre as implementações — comportamento atual (1.7.1)
2
2
 
3
- Levantado no código-fonte dos três pacotes na **1.4.0** — desde a 1.3.0 `@orfeu/node`, `@orfeu/angular` e `orfeu`
4
- saem sempre na mesma versão. Quando sair uma versão nova, confira de novo antes de confiar nesta tabela. O que
3
+ Conferido no código-fonte da **1.7.1** — desde a 1.3.0 `@orfeu/node`, `@orfeu/angular` e `orfeu` saem sempre na
4
+ mesma versão, e o `@orfeu/react` entrou na família na 1.7.1. Quando sair uma versão nova, confira de novo antes de
5
+ confiar nesta tabela. O que
5
6
  **não** está aqui é igual nas duas linguagens de
6
7
  backend: precedência e nomes dos headers de credencial (`x-access-token`, `x-app-token`, `x-api-token`),
7
8
  `traceparent`, `x-route-id`, `x-client-id`, regra 401/403 por nível, `Level`/`Method`, cache de
@@ -15,13 +16,17 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
15
16
  | Configuração | objeto `{ authorizerUrl, realmId, appId, secret, ... }` | parâmetros `authorizer_url, realm_id, app_id, secret, *, tls_verify, audit, ...` (keyword-only); o Django lê as settings `ORFEU_*` |
16
17
  | Variáveis de ambiente lidas pela lib (1.3+) | `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL`, `ORFEU_TRUSTED_PROXIES`, só quando a opção não é passada, no construtor | as mesmas três, com a mesma regra; `check_revocation` só por argumento (Django: `ORFEU_CHECK_REVOCATION`) |
17
18
  | Endurecimento do token (1.3+) | `allowedClients`, `issuerUrl`, `trustedProxies`, `checkRevocation` | `allowed_clients`, `issuer_url`, `trusted_proxies`, `check_revocation` — mesma semântica, mesmos padrões (desligado / — / loopback + redes privadas / `False`) |
19
+ | Tolerância de relógio nos JWT (1.6+) | `clockToleranceSec` (padrão `DEFAULT_CLOCK_TOLERANCE_SEC` = 30) | `clock_tolerance_s` (padrão `DEFAULT_CLOCK_TOLERANCE_S` = 30.0; Django: setting `ORFEU_CLOCK_TOLERANCE`) — mesma semântica; `0` = conferência exata |
20
+ | `public` (1.7+) | não lê credencial nem chama o Argos; handler sem `orfeuUser`/`orfeuApiToken`. No Apollo, um usuário validado por outro campo (ou por `trustUser`) continua em `ctx.orfeuUser` | igual; `request.state.user` = `None` (FastAPI), `request.orfeu_user`/`g.orfeu_user` = `None`. No Strawberry, `info.context["orfeu_user"]` pode ter o usuário validado por outro campo |
21
+ | Identificar sem autorizar (1.7+) | `identify`: `sdk.identify(id, method?)` (Express), `fastify.orfeuIdentify(id, method?)`, `@Identify(id, method?)` (Nest), `createIdentify(client)` ou `operation('public', r, { identify: true })` (Apollo) — o comportamento do `public` até a 1.6 | **não existe**: use `optional` (credencial inválida dá 401) |
22
+ | OpenAPI (1.6+) | não há | FastAPI: `/docs` mostra `<id> · <nível>` em cada rota e `x-orfeu-operation` (`document_operations=False` desliga; `install_openapi_operations`/`annotate_openapi_operations` em `orfeu.adapters.fastapi`; rotas de `include_router` no FastAPI ≥ 0.137 só a partir da 1.7.1) |
18
23
  | Nomes de variáveis de ambiente nos exemplos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (convenção do Django) |
19
24
  | Token de outro realm | `acceptAnyRealm: true` aceita (busca o JWKS do realm da claim `realm_id`) | `accept_any_realm=True` (Django: `ORFEU_ACCEPT_ANY_REALM`), mesmo comportamento e mesmos limites (realm só `[A-Za-z0-9_-]`, cache de 64, realm sem JWKS bloqueado 30 s, 20 realms novos/min); exige `orfeu` >= 1.2.0 (no Node, os limites valem a partir do `@orfeu/node` 1.1.1) |
20
25
  | Validação do JWT | `jose` com JWKS remoto (cache interno da lib); JWKS buscado **sob demanda**. Só `RS256`; `exp`, `sub` e `iss` obrigatórios; `type: "app"` recusado (1.3+) | exige `kid` e RS256; JWKS buscado **na subida** (falha a subida se não vier), cache de 1 h e nova busca se o `kid` for desconhecido (no máximo a cada 30 s por realm, 1.2+). Mesmas recusas da 1.3 |
21
26
  | Token de serviço (1.4+) | `validateServiceToken(token, { allowedApps, realmFor, checkRevocation })`; rotas `serviceGuard` (Express), `orfeuServiceGuard` (Fastify), `@ServiceRoute` + `@OrfeuService` (Nest); Apollo: no `context` | `validate_service_token(token, allowed_apps=, realm_for=, check_revocation=)`; `@service_route(...)` em FastAPI (HTTP/WS), Flask e Django (não combina com `@operation`); Strawberry: no contexto |
22
- | Argos fora durante a validação (JWKS, `/apps/token`, introspecção) | 401 (anônimo em `public`); nunca 500 | igual desde a 1.3 (antes virava 500) |
27
+ | Argos fora durante a validação (JWKS, `/apps/token`, introspecção) | 401; nunca 500 (`public` não valida) | igual desde a 1.3 (antes virava 500) |
23
28
  | Subscription com token que vence | Apollo `secureResolvers`: no `exp`, último `GraphQLError` 401 (`UNAUTHENTICATED`) e o stream acaba (1.3+) | não documentado no Strawberry nem no WebSocket do FastAPI: não suponha o mesmo |
24
- | Timeouts das chamadas ao Argos | só a auditoria tem (10 s); token do serviço, sync, operações e introspecção **sem timeout** | 10 s em todas (introspecção: 5 s) |
29
+ | Timeouts das chamadas ao Argos | só a auditoria (10 s) e a introspecção de revogação do `checkRevocation` (5 s); token do serviço, sync, operações e introspecção do `x-app-token`/`x-api-token` **sem timeout** | 10 s em todas (introspecção: 5 s); um `httpx.AsyncClient` reaproveitado por event loop (1.6+) |
25
30
  | Erro de rede na subida | erro cru do `fetch` (não é `OrfeuError`) | embrulhado: `OrfeuAuthError` / `OrfeuSyncError` / `OrfeuError` |
26
31
  | Quem chama a subida | o app: `client.startup()` / `OrfeuClient.create()` depois de declarar as rotas; Nest: `OrfeuModule.forRootAsync` | FastAPI: automático no lifespan (`Orfeu(app, ...)`); Flask e Django: **na construção**, síncrono; Strawberry: o app chama `startup_async()` no lifespan |
27
32
  | Permissões (`allowed_groups`) | revalidadas a cada 60 s por padrão (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; opção `permissionsRefresh`); antes, só na subida ou em `fetchOperations()` manual | idem (`permissions_refresh`); antes, só na subida ou em `fetch_operations()` manual |
@@ -33,7 +38,7 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
33
38
  | `ApiTokenClaims` | tipo **não** reexportado na raiz (`NonNullable<Request['orfeuApiToken']>`) | **não** exportado em `orfeu`; importe de `orfeu.models` |
34
39
  | Usuário injetado pelo app (contexto sem credencial crua) | Apollo: só por `trustUser(ctx, claims)` (1.0.1); `ctx.orfeuUser` gravado direto é ignorado (401 fora de `public`) e removido do contexto. Express/Fastify/Nest: não existe — o guard sempre decide pela credencial dos headers e regrava `orfeuUser` | não existe: a guarda sempre decide pela credencial da requisição |
35
40
  | Contexto do WebSocket | Apollo `orfeuWsContext(client, extra)`: o `extra` entra antes dos campos do Orfeu e perde as chaves de `ORFEU_RESERVED_CONTEXT_KEYS` (1.0.1) | FastAPI: a guarda lê os 3 headers do handshake, sem `extra`; Strawberry/graphql-ws lê do `connection_init` (python-recipes.md §11) |
36
- | Onde fica o usuário | `req.orfeuUser` / `req.orfeuApiToken`; Apollo `ctx.orfeuUser`; Nest `@OrfeuUser()` | FastAPI `request.state.user` / `.api_token` (**ausente** no anônimo); Flask `g.orfeu_user` (`None` no anônimo); Django `request.orfeu_user`; Strawberry `info.context["orfeu_user"]` |
41
+ | Onde fica o usuário | `req.orfeuUser` / `req.orfeuApiToken`; Apollo `ctx.orfeuUser`; Nest `@OrfeuUser()` | FastAPI `request.state.user` / `.api_token` (`user` = `None` no anônimo e em `public` desde a 1.7; antes, ausente); Flask `g.orfeu_user` (`None` no anônimo); Django `request.orfeu_user`; Strawberry `info.context["orfeu_user"]` |
37
42
  | Declaração | por rota: `guard(id, level, method?)`, `preHandler: fastify.orfeuGuard(...)`, `@Operation(...)`, `operation(level, resolver)` | decorator `@operation(id=..., level=..., method=...)` logo abaixo do decorator de rota; a guarda resolve a rota pelo roteador |
38
43
  | Rota sem operação | passa sem proteção nem auditoria | idem; no FastAPI há uma rede de segurança: se o roteador cair num endpoint com `@operation` que a guarda não resolveu, a resposta vira 500 `route_unresolved` (WebSocket: fecha 1008) |
39
44
  | NestJS | `OrfeuModule.forRootAsync(opts)` recebe as **opções prontas** (sem `useFactory`/`inject`: não dá para usar `ConfigService`); falha na subida derruba o bootstrap. `OrfeuGuard` não é global: `@UseGuards(OrfeuGuard)` no controller; método **sem `@Operation` é liberado** (o guard devolve `true`) | — |
@@ -50,13 +55,17 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
50
55
  | IP do cliente na auditoria (1.3+) | nunca o primeiro `x-forwarded-for`; socket fora de `trustedProxies` → socket; de proxy → entrada mais à direita que não é proxy. Apollo HTTP: regra pela direita (sem socket no plugin) | igual (`trusted_proxies`, `orfeu.trace.DEFAULT_TRUSTED_PROXIES`) |
51
56
  | `orfeuHeaders` / `orfeu_headers` fora de operação protegida | Express/Fastify: funciona em qualquer rota que passou pela captura global (mesmo sem guard); Nest: só em método com `@Operation`; Apollo: com o plugin/contexto instalado | devolve `{}` fora de chamada guardada |
52
57
 
53
- ## Front: `@orfeu/angular` × backends
58
+ ## Front: `@orfeu/angular` (e `@orfeu/react`) × backends
59
+
60
+ O `@orfeu/react` segue o `@orfeu/angular` (mesmo protocolo, mesmas chaves de `sessionStorage`, mesmo canal); as
61
+ diferenças de API estão em [react.md](react.md).
54
62
 
55
63
  | Assunto | `@orfeu/angular` | Node / Python |
56
64
  |---|---|---|
57
65
  | URL do Argos | `authority` = **origem** do Argos, sem `/api`; a lib monta `${authority}/api/realms/${realmId}/...` | `authorizerUrl` / `authorizer_url` = URL base **com** o prefixo da API (`…/api`) |
58
66
  | Identidade | `clientId` (client OIDC do app front) + `realmId` | `appId`/`app_id` + `secret` (serviço cadastrado no Argos) |
59
- | Envio do token às APIs | a lib **não exporta interceptor**: o app escreve um que manda `x-access-token` só para as próprias APIs (receita em [angular-recipes.md](angular-recipes.md) §4) | leem `x-access-token` cru |
67
+ | Envio do token às APIs | a lib **não acrescenta** o token: o app escreve um interceptor que manda `x-access-token` só para as próprias APIs (receita em [angular-recipes.md](angular-recipes.md) §4). O `orfeuTokenInterceptor` da lib (1.5+) só troca o token vencido ou quase pelo renovado, depois dele | leem `x-access-token` cru |
68
+ | Tolerância de relógio | `exp` do id_token: 30 s (1.7+); o access token não é verificado no front | 30 s (1.6+) |
60
69
  | `x-client-id` / `x-route-id` | o interceptor do app que acrescenta (opcional) | repassados por `orfeuHeaders`/`orfeu_headers` |
61
70
  | `traceparent` | nunca envia | gera/continua |
62
71
  | Claims | decodificadas **sem** verificar assinatura, só para exibir | verificadas (JWKS) e usadas na decisão |
@@ -1,11 +1,14 @@
1
- # API — @orfeu/node 1.4.0
1
+ # API — @orfeu/node 1.7.1
2
2
 
3
- > Conferida contra o código-fonte da 1.4.0 (`src/index.ts` e `src/adapters/*`). O que não está aqui é
4
- > interno. Peça `"@orfeu/node": "^1.4.0"` (anda junto com `@orfeu/angular` e `orfeu`). Marcos: 1.0.1 —
3
+ > Conferida contra o código-fonte da 1.7.1 (`src/index.ts` e `src/adapters/*`). O que não está aqui é
4
+ > interno. Peça `"@orfeu/node": "^1.7.1"` (anda junto com `@orfeu/angular`, `@orfeu/react` e `orfeu`). Marcos: 1.0.1 —
5
5
  > `trustUser`/`ORFEU_RESERVED_CONTEXT_KEYS` no Apollo; 1.1 — recarga das permissões e `close()`; 1.1.1 — limites
6
6
  > do `acceptAnyRealm`; 1.3.0 — auditoria de segurança (`iss`/`exp`/`sub` obrigatórios, token `type: app` recusado
7
7
  > como usuário, `allowedClients`, `issuerUrl`, `trustedProxies`, `checkRevocation`, IP da auditoria, subscription
8
- > termina no `exp`); 1.4.0 — token de serviço (`validateServiceToken`, `serviceGuard`). Endpoints citados são relativos a `authorizerUrl` (que já inclui o prefixo da API).
8
+ > termina no `exp`); 1.4.0 — token de serviço (`validateServiceToken`, `serviceGuard`); 1.6.0 — `clockToleranceSec`,
9
+ > aviso com `tlsVerify: false`, caches por token com teto de 10 000 entradas e chamadas simultâneas com o mesmo token
10
+ > esperando a mesma ida ao Argos; 1.7.0 — `public` não valida credencial nenhuma e `identify` (Express, Fastify, Nest,
11
+ > Apollo) para identificar sem autorizar. A 1.5.0 e a 1.7.1 não mudaram esta lib. Endpoints citados são relativos a `authorizerUrl` (que já inclui o prefixo da API).
9
12
 
10
13
  ## `@orfeu/node` (núcleo)
11
14
 
@@ -26,7 +29,9 @@ interface OrfeuClientOptions {
26
29
  issuerUrl?: string; // sem a opção: ORFEU_ISSUER_URL
27
30
  trustedProxies?: string[]; // sem a opção: ORFEU_TRUSTED_PROXIES; padrão DEFAULT_TRUSTED_PROXIES; [] = nenhum
28
31
  checkRevocation?: boolean | string[]; // padrão false; identificadores das operações ou true
32
+ clockToleranceSec?: number; // 1.6+: padrão DEFAULT_CLOCK_TOLERANCE_SEC (30); 0 = conferência exata
29
33
  }
34
+ const DEFAULT_CLOCK_TOLERANCE_SEC = 30; // 1.6+
30
35
  interface PermissionsRefreshOptions { enabled?: boolean; intervalMs?: number /*60_000*/; jitter?: number /*0.2*/ }
31
36
 
32
37
  class OrfeuClient {
@@ -72,6 +77,8 @@ class OrfeuClient {
72
77
  | `validateAppToken(token)` | introspecção (`POST /realms/{realm}/tokens/introspect`, autenticada com o token do serviço; reautentica uma vez em 401). Cache por hash do token: 60 s ativo (limitado ao `exp`), 10 s inativo. Devolve `TokenClaims` com `raw.token_type = 'app_token'` e `raw.token_id`. Inativo, outro tipo, outro realm, `client_id` fora do `allowedClients`, Argos sem introspecção ou `/apps/token` recusando → `OrfeuTokenError`. |
73
78
  | `validateApiToken(token, id, method)` | introspecção; `{ tokenId, appId }` se o token for do tipo `api` **e** tiver a operação concedida neste serviço; senão `null`. Argos sem introspecção (404) → `POST /realms/{realm}/apps/tokens/validate` (cache 30 s por token+operação). Erro de rede/servidor → `OrfeuTokenError`. |
74
79
  | `checkPermission(claims, id, method)` | usa o cache do `fetchOperations()`: operação desconhecida → `false`; `public` → `true`; `private`/`optional` → `claims.groups.length > 0`; `protected` → algum grupo em `allowed_groups`. |
80
+ | `clockToleranceSec` (opção, 1.6+) | tolerância de relógio (segundos) no `exp`/`nbf`/`iat` do `validateToken` e do `validateServiceToken`, para a diferença de relógio entre o Argos e o serviço. **Afrouxa**: token vencido há menos de 30 s ainda vale. Valor não numérico ou negativo volta ao padrão. |
81
+ | Caches por token (1.6+) | introspecção (`x-app-token`/`x-api-token`), revogação e validate antigo: teto de 10 000 entradas (poda as vencidas; acima disso sai a menos usada), também para token inativo. Chamadas simultâneas com o mesmo token esperam a mesma ida ao Argos. |
75
82
  | `operationIdOf(id, method)` | UUID da operação no Argos (depois do `fetchOperations()`), para logs. |
76
83
  | `recordAudit(event)` | põe um evento na fila (no-op com `audit: false`). Nunca bloqueia. |
77
84
  | `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`. |
@@ -115,8 +122,9 @@ function clearRegistry(): void; // para testes
115
122
  `detectMethod`: último segmento após `:` em minúsculas; começa com `get|list|fetch|read` → `read`; com
116
123
  `delete|remove|destroy` → `delete`; contém `stream|subscribe|watch|listen` → `stream`; senão `write`.
117
124
 
118
- `guard()`, `orfeuGuard()`, `@Operation()` e `createGuard()` registram no **registro global** no momento da
119
- declaração; `secureResolvers()` registra no global **e** no client. Antes do `startup()`, copie o global para o
125
+ `guard()`, `identify()`, `orfeuGuard()`, `orfeuIdentify()`, `@Operation()`, `@Identify()`, `createGuard()` e
126
+ `createIdentify()` registram no **registro global** no momento da declaração (os de identificação, com nível
127
+ `public`); `secureResolvers()` registra no global **e** no client. Antes do `startup()`, copie o global para o
120
128
  client (`for (const op of getRegistry()) client.registerOperation(op)`) — ou use `OrfeuClient.create`.
121
129
 
122
130
  ### Headers (constantes)
@@ -291,10 +299,17 @@ function orfeu(client: OrfeuClient): OrfeuMiddleware;
291
299
  interface OrfeuMiddleware {
292
300
  middleware: (req, res, next) => Promise<void>; // captura credencial, trace e correlação
293
301
  guard: (id: string, level: Level, method?: Method) => (req, res, next) => Promise<void>;
302
+ identify: (id: string, method?: Method) => (req, res, next) => Promise<void>; // 1.7+: identifica sem autorizar
294
303
  serviceGuard: (opts?: ValidateServiceTokenOptions) => (req, res, next) => Promise<void>; // 1.4+: só token de serviço
295
304
  }
296
305
  ```
297
306
 
307
+ - `identify(id, method?)` (1.7+): registra a operação como `public` e **nunca bloqueia**; não depende do catálogo
308
+ nem do `startup()`. Credencial válida (access → app → api; o `x-api-token` só se concedido para a operação)
309
+ preenche `req.orfeuUser`/`req.orfeuApiToken`, inclusive usuário sem grupo; ausente, inválida, vencida ou Argos
310
+ fora → anônimo, sem 401. Mesmo log/auditoria de um `public`, com o ator identificado. Quem bloqueia é um
311
+ middleware seguinte do app. É o `guard(id, Level.PUBLIC, method)` até a 1.6.
312
+
298
313
  - `guard()` registra a operação (global) **quando é chamado** (na definição da rota). Na requisição: decide;
299
314
  negado → responde `401/403` JSON e não chama `next`; permitido → `req.orfeuUser`/`req.orfeuApiToken` e
300
315
  `next()` dentro do contexto da auditoria. Log + evento quando a resposta termina (`finish`), com o status final.
@@ -310,6 +325,8 @@ const orfeuFastifyPlugin: FastifyPluginAsync<OrfeuPluginOptions>; // nome 'orfeu
310
325
  interface OrfeuPluginOptions { client: OrfeuClient }
311
326
  type OrfeuFastifyGuard = (request, reply, done: (err?: Error) => void) => void;
312
327
  // decorador: fastify.orfeuGuard(id: string, level: Level, method?: Method): OrfeuFastifyGuard
328
+ // decorador (1.7+): fastify.orfeuIdentify(id: string, method?: Method): OrfeuFastifyGuard — identifica sem autorizar
329
+ // decorador (1.4+): fastify.orfeuServiceGuard(opts?: ValidateServiceTokenOptions)
313
330
  ```
314
331
 
315
332
  - Hook `onRequest` captura; `fastify.orfeuGuard(...)` registra a operação e devolve um `preHandler` **no estilo
@@ -322,8 +339,9 @@ type OrfeuFastifyGuard = (request, reply, done: (err?: Error) => void) => void;
322
339
  ```ts
323
340
  class OrfeuModule { static forRootAsync(options: OrfeuModuleOptions): DynamicModule } // OrfeuModuleOptions = OrfeuClientOptions
324
341
  function Operation(id: string, level: Level, method?: Method): MethodDecorator; // SetMetadata(OPERATION_KEY, { id, level, method })
342
+ function Identify(id: string, method?: Method): MethodDecorator; // 1.7+: { id, level: 'public', method, identify: true }
325
343
  const OPERATION_KEY = 'orfeu:operation';
326
- interface OperationMeta { id: string; level: Level; method: Method; }
344
+ interface OperationMeta { id: string; level: Level; method: Method; identify?: boolean; }
327
345
  const OrfeuUser: () => ParameterDecorator; // request.orfeuUser (TokenClaims | undefined)
328
346
  class OrfeuGuard implements CanActivate {}
329
347
  class OrfeuAnnotationInterceptor implements NestInterceptor {}
@@ -335,6 +353,9 @@ class OrfeuAnnotationInterceptor implements NestInterceptor {}
335
353
  - `OrfeuGuard`: método **sem** `@Operation` → libera (sem checar nada). Com `@Operation`: negado lança
336
354
  `UnauthorizedException(detail)`/`ForbiddenException(detail)`. Só contexto HTTP (Express ou Fastify por baixo).
337
355
  - `@Operation` lê-se no **método** (handler), não na classe.
356
+ - `@Identify(id, method?)` (1.7+): o `OrfeuGuard` nunca bloqueia a rota; credencial válida vai para `@OrfeuUser()`
357
+ (ou `req.orfeuApiToken`), ausente ou inválida segue anônima. Quem bloqueia é o handler
358
+ (`if (!user) throw new UnauthorizedException()`) ou outro guard.
338
359
  - `OrfeuClient` é injetável em qualquer provider (`constructor(private readonly orfeu: OrfeuClient)`).
339
360
 
340
361
  ## `@orfeu/node/apollo`
@@ -353,6 +374,9 @@ function assertSchemaSecured(schema: GraphQLSchema): void;
353
374
  function createGuard(client: OrfeuClient): <TParent, TArgs, TContext extends OrfeuContext, TReturn>(
354
375
  id: string, level: Level, resolver: (parent: TParent, args: TArgs, context: TContext, info: unknown) => TReturn, method?: Method,
355
376
  ) => (parent: TParent, args: TArgs, context: TContext, info: unknown) => Promise<TReturn>;
377
+ function createIdentify(client: OrfeuClient): <TParent, TArgs, TContext extends OrfeuContext, TReturn>( // 1.7+
378
+ id: string, resolver: (parent: TParent, args: TArgs, context: TContext, info: unknown) => TReturn, method?: Method,
379
+ ) => (parent: TParent, args: TArgs, context: TContext, info: unknown) => Promise<TReturn>;
356
380
  const envelopeOutcome: OutcomeResolver;
357
381
 
358
382
  interface OrfeuContext extends BaseContext {
@@ -360,7 +384,10 @@ interface OrfeuContext extends BaseContext {
360
384
  orfeuRouteId?: string; orfeuClientId?: string; orfeuTrace?: OrfeuTrace; orfeuClientIp?: string;
361
385
  orfeuCredential?: { header: string; value: string };
362
386
  }
363
- interface OperationOptions { id?: string; method?: Method; description?: string; }
387
+ interface OperationOptions {
388
+ id?: string; method?: Method; description?: string;
389
+ identify?: boolean; // 1.7+, só com nível 'public' (outro nível → OrfeuConfigError): o campo identifica sem autorizar
390
+ }
364
391
  interface SecureResolversOptions {
365
392
  onForbidden?: (denial: OperationDenial) => unknown; // valor ≠ undefined vira o resultado do campo no 403
366
393
  outcome?: OutcomeResolver; // padrão envelopeOutcome
@@ -407,8 +434,13 @@ class OrfeuDenied extends Error { readonly status: 401 | 403; readonly reason: D
407
434
  contexto e quer filtrar a mesma lista.
408
435
  - `createGuard(client)(id, level, resolver, method?)`: proteção resolver a resolver (alternativa antiga).
409
436
  Negado → `Error('Unauthorized: …')` (401) ou `OrfeuForbiddenError('Forbidden: …')` (403).
437
+ - `createIdentify(client)(id, resolver, method?)` e `operation('public', resolver, { identify: true })` (1.7+): o
438
+ resolver roda sempre; credencial válida em `ctx.orfeuUser`/`ctx.orfeuApiToken`, inválida ou ausente = anônimo.
439
+ Sem credencial, um usuário já marcado neste contexto (outro campo, `trustUser`) continua em `ctx.orfeuUser`.
440
+ - Campo `public` (1.7+) não valida credencial: o contexto é do documento, então um usuário validado por outro campo
441
+ (ou posto por `trustUser`) continua em `ctx.orfeuUser`, mas o campo `public` não o valida.
410
442
  - Decisão (`decide()`): sem credencial no contexto, a permissão só é decidida sobre um `ctx.orfeuUser`
411
443
  **marcado pela lib** (validado neste contexto ou por `trustUser`). Um `orfeuUser`/`orfeuApiToken` sem a marca
412
444
  é ignorado (cai na regra comum: 401 fora de `public`) e removido do contexto antes do resolver, inclusive
413
445
  em campos `public`/`optional` anônimos. Até a 1.0.0 qualquer `orfeuUser` no contexto valia como
414
- autenticado — nunca use versão anterior à 1.0.1 (peça `^1.4.0`).
446
+ autenticado — nunca use versão anterior à 1.0.1 (peça `^1.7.1`).
@@ -1,4 +1,4 @@
1
- # Armadilhas e erros comuns — @orfeu/node 1.4.0
1
+ # Armadilhas e erros comuns — @orfeu/node 1.7.1
2
2
 
3
3
  Cada item: sintoma → causa → o que fazer.
4
4
 
@@ -107,7 +107,21 @@ sem usuário e sem auditoria. O `OrfeuGuard` do Nest libera métodos sem `@Opera
107
107
  rota de negócio; no Apollo, `secureResolvers` + `assertSchemaSecured` impedem isso na subida.
108
108
 
109
109
  **Handler que lia o usuário sem guard.** O `middleware`/plugin só captura headers; `req.orfeuUser` só existe
110
- depois do guard. Proteja a rota (mesmo que `Level.PUBLIC`, para ter o usuário quando houver).
110
+ depois do guard. Proteja a rota com o nível certo; para ter o usuário quando houver sem bloquear ninguém, use
111
+ `identify` (1.7+) — `Level.PUBLIC` não serve mais para isso.
112
+
113
+ **Rota `public` perdeu o usuário depois de atualizar para a 1.7.** Desde a 1.7.0 o `public` não lê credencial nem
114
+ chama o Argos: `req.orfeuUser`/`ctx.orfeuUser` ficam vazios (no Apollo, só o usuário validado por outro campo do
115
+ mesmo documento continua lá). Troque `guard(id, Level.PUBLIC, method)` por `identify(id, method)` (mesmo
116
+ comportamento de antes: nunca bloqueia, credencial inválida vira anônimo, sem catálogo) ou por `Level.OPTIONAL`
117
+ (credencial inválida dá 401 e o usuário precisa de ao menos um grupo). Fastify: `orfeuIdentify`; Nest:
118
+ `@Identify`; Apollo: `{ identify: true }` ou `createIdentify`.
119
+
120
+ **`OrfeuConfigError: operation(): 'identify' só vale com nível 'public'`.** `{ identify: true }` com outro nível;
121
+ para validar e autorizar, use `optional` sem `identify`.
122
+
123
+ **Token vencido há poucos segundos ainda passa.** Esperado desde a 1.6: `clockToleranceSec` (padrão 30 s) cobre a
124
+ diferença de relógio entre o Argos e o serviço. Para a conferência exata, `clockToleranceSec: 0`.
111
125
 
112
126
  **`@Operation` na classe.** Não funciona: o guard lê o metadado do método.
113
127
 
@@ -1,6 +1,6 @@
1
- # Receitas — @orfeu/node 1.4.0
1
+ # Receitas — @orfeu/node 1.7.1
2
2
 
3
- Todas usam a API real da 1.4.0 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
3
+ Todas usam a API real da 1.7.1 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
4
4
  `REALM_ID`, `APP_ID`, `APP_SECRET`, `ORFEU_ALLOWED_CLIENTS`, `ORFEU_ISSUER_URL` — use os nomes que o projeto já tem.
5
5
 
6
6
  ## 1. Express
@@ -23,12 +23,17 @@ const client = new OrfeuClient({
23
23
  issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
24
24
  checkRevocation: ['clientes:delete'], // operações sensíveis
25
25
  });
26
- const { middleware, guard } = orfeu(client);
26
+ const { middleware, guard, identify } = orfeu(client);
27
27
 
28
28
  const app = express();
29
29
  app.use(express.json(), middleware); // body parser ANTES dos guards; middleware só captura
30
30
 
31
- app.get('/health', guard('health:check', Level.PUBLIC), (_req, res) => res.json({ ok: true }));
31
+ app.get('/health', guard('health:check', Level.PUBLIC), (_req, res) => res.json({ ok: true })); // sem usuário (1.7+)
32
+
33
+ // público que personaliza quando há login (1.7+): identify nunca bloqueia; credencial inválida = anônimo
34
+ app.get('/vitrine', identify('vitrine:get', Method.READ), async (req, res) => {
35
+ res.json(await repo.showcase({ viewer: req.orfeuUser?.sub ?? null }));
36
+ });
32
37
 
33
38
  app.get('/clientes', guard('clientes:list', Level.PRIVATE), async (req, res) => {
34
39
  res.json(await repo.list({ owner: req.orfeuUser?.sub }));
@@ -56,6 +61,10 @@ const server = app.listen(Number(process.env.PORT ?? 3000));
56
61
  ```
57
62
 
58
63
  - Erro do handler: use o tratamento de erro do Express normalmente; status ≥ 400 vira `outcome: failure`.
64
+ - `Level.PUBLIC` (1.7+) não lê credencial: o handler nunca tem `req.orfeuUser`. Para ter a identidade, `identify`
65
+ (como `/vitrine`, nunca bloqueia) ou `Level.OPTIONAL` (credencial inválida dá 401; precisa do catálogo). No
66
+ Fastify, `preHandler: fastify.orfeuIdentify('vitrine:get')`; no Nest, `@Identify('vitrine:get')`; no Apollo,
67
+ `operation(Level.PUBLIC, resolver, { identify: true })` ou `createIdentify(client)`.
59
68
  - Express 4 não captura rejeição de handler `async`: envolva em `try/catch` (ou use Express 5).
60
69
 
61
70
  ## 2. Fastify