@acropole/skills 1.4.1 → 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.
@@ -1,6 +1,6 @@
1
- # Receitas — @orfeu/angular 1.0.0
1
+ # Receitas — @orfeu/angular 1.4.0
2
2
 
3
- Todas usam a API real da 1.0.0 ([angular-api.md](angular-api.md)). Componentes standalone, `inject()`, controle de fluxo
3
+ Todas usam a API real da 1.4.0 ([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
@@ -104,7 +104,8 @@ export class CallbackComponent implements OnInit {
104
104
  private describe(err: unknown): string {
105
105
  if (err instanceof OrfeuAuthError) {
106
106
  switch (err.code) {
107
- case 'callback_error': return `O servidor de autenticação recusou o login: ${err.message}`;
107
+ // 1.3+: mensagem genérica ("O login não foi concluído (<error>).") — nunca mostre o error_description
108
+ case 'callback_error': return err.message;
108
109
  case 'invalid_callback': // recarregou esta página ou abriu o link em outra aba
109
110
  case 'state_mismatch':
110
111
  case 'nonce_mismatch': return 'Este link de login não é mais válido. Entre de novo.';
@@ -133,8 +134,21 @@ export class LogoffComponent {
133
134
  }
134
135
  ```
135
136
 
136
- Botão "Sair" em qualquer lugar: `inject(AuthorizationService).logout()` (não devolve promise; a navegação para
137
- `/logoff` acontece sozinha).
137
+ Botão "Sair" em qualquer lugar: `inject(AuthorizationService).logout()`. Com o Argos confirmando, a navegação
138
+ para `/logoff` acontece sozinha e a promise resolve `true`. Se o Argos falhar (1.3+), a lib repete uma vez e,
139
+ falhando de novo, **mantém a sessão**, emite `logoutFailed$` e resolve `false` — avise a pessoa no próprio botão:
140
+
141
+ ```ts
142
+ protected async sair(): Promise<void> {
143
+ if (await this.auth.logout()) return; // true: a lib já navegou para /logoff
144
+ this.avisar('Não foi possível sair agora. Tente de novo.'); // toast do app; a sessão continua
145
+ }
146
+ ```
147
+
148
+ 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$`
150
+ e mostra o aviso para **qualquer** `logout()`, inclusive o do app — não mostre toast próprio (sairia em dobro). Num
151
+ botão próprio, chame `inject(SpineLogoutService).logout()`: mesmo aviso e só apaga os recentes quando a saída deu certo.
138
152
 
139
153
  ## 4. Interceptor: token nas APIs do app
140
154
 
@@ -387,8 +401,8 @@ acontecer fora dele (na janela principal) — depois disso o iframe recupera a s
387
401
  ```ts
388
402
  import { TestBed } from '@angular/core/testing';
389
403
  import { provideRouter } from '@angular/router';
390
- import { AuthorizationService } from '@orfeu/angular/core';
391
- import { BehaviorSubject, EMPTY, of } from 'rxjs';
404
+ import { AuthorizationService, type OrfeuAuthError } from '@orfeu/angular/core';
405
+ import { BehaviorSubject, EMPTY, of, Subject } from 'rxjs';
392
406
 
393
407
  const fakeAuth = {
394
408
  authenticated: true,
@@ -408,7 +422,8 @@ const fakeAuth = {
408
422
  handleCallback: vi.fn().mockResolvedValue(undefined),
409
423
  switchBadge: vi.fn().mockResolvedValue(undefined),
410
424
  silentRenew: vi.fn().mockResolvedValue(undefined),
411
- logout: vi.fn(),
425
+ logout: vi.fn().mockResolvedValue(true), // 1.3+: Promise<boolean>
426
+ logoutFailed$: new Subject<OrfeuAuthError>(), // 1.3+
412
427
  };
413
428
 
414
429
  TestBed.configureTestingModule({
@@ -1,6 +1,7 @@
1
1
  # @orfeu/angular — guia de uso (front)
2
2
 
3
- > Escrito para a **1.0.0**. Se a versão instalada for outra, confira os nomes de [angular-api.md](angular-api.md)
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)
4
5
  > contra os `.d.ts` de `node_modules/@orfeu/angular/types/` antes de copiar código. Conceitos comuns às três
5
6
  > implementações (níveis, headers, trace, auditoria) estão no `SKILL.md` da skill; diferenças entre elas em
6
7
  > [diferencas.md](diferencas.md).
@@ -32,11 +33,13 @@ Consequências para quem integra:
32
33
  - **Não** chame `logout()` por causa de erro de rede, 401 de API ou token vencido. A lib já está renovando.
33
34
  `logout()` é só para o botão "Sair".
34
35
  - Se o app precisa encerrar a sessão por regra própria (ex.: inatividade), ele chama `logout()` explicitamente.
36
+ - Nem o `logout()` encerra a sessão se o Argos não confirmar (1.3+): a sessão continua, `logoutFailed$` emite e
37
+ o `logout()` resolve `false`.
35
38
 
36
39
  ## 2. Instalação e requisitos
37
40
 
38
41
  ```bash
39
- npm install @orfeu/angular
42
+ npm install @orfeu/angular@^1.4.0
40
43
  ```
41
44
 
42
45
  | Peer | Versão |
@@ -123,7 +126,8 @@ hora. Sem sessão e sem tentativa anterior, tenta o refresh. Se não der, chama
123
126
  - servidor inalcançável (`connectionState === 'offline'`) → não redireciona para uma página que não carrega:
124
127
  guarda a URL e navega para ela sozinho quando a conexão voltar e a sessão for recuperada pelo cookie.
125
128
 
126
- **Callback**: `handleCallback(route.snapshot.queryParams)` confere `state`, troca o `code` com o
129
+ **Callback**: `handleCallback(route.snapshot.queryParams)` confere `state` (também quando vem `?error`, antes de
130
+ qualquer efeito — 1.3+), troca o `code` com o
127
131
  `code_verifier`, confere o `nonce` do `id_token`, aplica o token, avisa as outras abas, carrega o `/view` e
128
132
  navega para a URL de retorno (ou a 1ª rota do `/view`, ou `/home`). Rejeita com `OrfeuAuthError` — sempre
129
133
  envolva em `try/catch`.
@@ -144,8 +148,12 @@ para o login interativo mantendo a URL. Nunca desloga.
144
148
  (`LOGOUT`); só uma aba reautoriza (`REAUTH_STARTED`). O token **não** vai para `localStorage`: uma aba nova
145
149
  sem outra aberta recupera a sessão pelo cookie no boot.
146
150
 
147
- **Logout**: `logout()` → `GET /logout?client_id=…` (com cookie); com sucesso ou erro, limpa o estado local,
148
- avisa as abas e navega para `/logoff?loggedOut=true`.
151
+ **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
153
+ (rede, 5xx), repete uma vez; falhando de novo, a sessão **continua** (no Argos ela segue válida — anunciar
154
+ "saiu" seria mentira), `logoutFailed$` emite `OrfeuAuthError('logout_failed')` e resolve `false`. Mostre o erro
155
+ e ofereça tentar de novo (`angular-recipes.md` §3). Com o `@trismegisto/spine` ≥ 2.1.2 o shell já faz isso para
156
+ qualquer `logout()` (o `SpineLogoutService` assina o `logoutFailed$`): o app não mostra aviso próprio.
149
157
 
150
158
  ## 6. Chamando as APIs do app
151
159
 
@@ -179,9 +187,10 @@ permissão. Quem decide é a API (`@orfeu/node`) e o `/view` (o que o usuário p
179
187
 
180
188
  | `code` | Quando |
181
189
  |---|---|
182
- | `callback_error` | o Argos voltou com `?error=...` (mensagem = `error_description` ou `error`) |
190
+ | `callback_error` | o Argos voltou com `?error=...` e o `state` confere. Mensagem genérica `O login não foi concluído (<error>).` (1.3+); o `error_description` nunca entra — não o mostre na tela |
191
+ | `logout_failed` | (1.3+, via `logoutFailed$`) o `GET /logout` falhou duas vezes; a sessão continua |
183
192
  | `invalid_callback` | callback sem `code` ou sem `code_verifier` no `sessionStorage` (recarregou o callback, abriu em outra aba, storage limpo) |
184
- | `state_mismatch` | `state` ausente ou diferente do gravado em `authorize()` |
193
+ | `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 |
185
194
  | `nonce_mismatch` | `nonce` do `id_token` diferente do gravado |
186
195
  | `not_authenticated` | `switchBadge()` sem sessão; `silentRenew()` no servidor (SSR) |
187
196
 
@@ -1,7 +1,8 @@
1
- # Diferenças entre as implementações — comportamento atual (1.0.0; `@orfeu/node` 1.0.1)
1
+ # Diferenças entre as implementações — comportamento atual (1.4.0)
2
2
 
3
- Levantado no código-fonte dos três pacotes na **1.0.0** e, no Node, na **1.0.1** (só o adapter Apollo mudou). A padronização está planejada: quando sair uma versão
4
- nova, confira de novo antes de confiar nesta tabela. O que **não** está aqui é igual nas duas linguagens de
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
5
+ **não** está aqui é igual nas duas linguagens de
5
6
  backend: precedência e nomes dos headers de credencial (`x-access-token`, `x-app-token`, `x-api-token`),
6
7
  `traceparent`, `x-route-id`, `x-client-id`, regra 401/403 por nível, `Level`/`Method`, cache de
7
8
  introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos do log de operação.
@@ -11,15 +12,20 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
11
12
  | Assunto | Node | Python |
12
13
  |---|---|---|
13
14
  | Nomes da API | camelCase: `orfeuHeaders`, `annotateOperation({ ... })` (objeto), `flushAudit()`, `fetchOperations()` | snake_case: `orfeu_headers`, `annotate_operation(target_type=..., ...)` (kwargs), `flush_audit()`, `fetch_operations()` |
14
- | Configuração | objeto `{ authorizerUrl, realmId, appId, secret, ... }`; nunca lê variável de ambiente | parâmetros `authorizer_url, realm_id, app_id, secret, *, tls_verify, audit`; não lê variável de ambiente, **exceto** o Django (settings `ORFEU_*`) |
15
+ | 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
+ | 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
+ | 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`) |
15
18
  | 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) |
16
19
  | 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) |
17
- | Validação do JWT | `jose` com JWKS remoto (cache interno da lib); JWKS buscado **sob demanda** | 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 |
20
+ | 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
+ | 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) |
23
+ | 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 |
18
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) |
19
25
  | Erro de rede na subida | erro cru do `fetch` (não é `OrfeuError`) | embrulhado: `OrfeuAuthError` / `OrfeuSyncError` / `OrfeuError` |
20
26
  | 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 |
21
27
  | 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 |
22
- | `fetchOperations` / `fetch_operations` com token do serviço vencido (401) | reautentica uma vez e repete (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1); antes lançava `OrfeuError` | idem (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) |
28
+ | `fetchOperations` / `fetch_operations` com token do serviço vencido (401) | reautentica uma vez e repete (≥ 1.1); antes lançava `OrfeuError` | idem (≥ 1.1) |
23
29
  | Reautenticação automática no 401 | só na auditoria e na introspecção | idem |
24
30
  | Inferência de `Method` sem `method` explícito | pelo **último segmento do id** após `:` (`tasks:list` → `read`); Apollo: pelo tipo raiz (Query → `read`, Mutation → `write`/`delete`, Subscription → `stream`) | pelo **nome da função** (`get_`/`list_`/... → `read`) |
25
31
  | Convenção de id nos exemplos | `recurso:acao` | `recurso.acao` |
@@ -41,6 +47,7 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
41
47
  | Flush da auditoria no encerramento | `await client.close()` no SIGTERM do app (para a recarga + flush; `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) — Fastify/Nest/Apollo fazem sozinhos; antes, `flushAudit()` manual | automático no shutdown do lifespan (FastAPI); Flask `orfeu.shutdown()`/`atexit`; Django `atexit` |
42
48
  | Log de operação padrão | uma linha JSON no **stdout** (`jsonLineLogger`); `logger: false` desliga | `logging` padrão (`orfeu.operation`), **sem handler**: sem configurar, as linhas INFO não aparecem; `JsonLogFormatter` opcional |
43
49
  | `traceparent` repassado | flags propagadas como chegaram | só o bit *sampled* é propagado |
50
+ | 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`) |
44
51
  | `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 |
45
52
 
46
53
  ## Front: `@orfeu/angular` × backends
@@ -1,8 +1,11 @@
1
- # API — @orfeu/node 1.0.1
1
+ # API — @orfeu/node 1.4.0
2
2
 
3
- > Conferida contra o código-fonte da 1.0.1 (`src/index.ts` e `src/adapters/*`). O que não está aqui é
4
- > interno. A 1.0.1 só mudou o adapter Apollo (`trustUser`, `ORFEU_RESERVED_CONTEXT_KEYS`, confiança no
5
- > `orfeuUser` por marca da lib); peça `^1.0.1`. Endpoints citados são relativos a `authorizerUrl` (que já inclui o prefixo da API).
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 —
5
+ > `trustUser`/`ORFEU_RESERVED_CONTEXT_KEYS` no Apollo; 1.1 — recarga das permissões e `close()`; 1.1.1 — limites
6
+ > do `acceptAnyRealm`; 1.3.0 — auditoria de segurança (`iss`/`exp`/`sub` obrigatórios, token `type: app` recusado
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).
6
9
 
7
10
  ## `@orfeu/node` (núcleo)
8
11
 
@@ -18,7 +21,13 @@ interface OrfeuClientOptions {
18
21
  tlsVerify?: boolean; // padrão true
19
22
  audit?: boolean | AuditOptions; // padrão true
20
23
  logger?: OperationLogger | false; // padrão jsonLineLogger
24
+ permissionsRefresh?: boolean | PermissionsRefreshOptions; // padrão true (60 s ±20%)
25
+ allowedClients?: string[]; // sem a opção: ORFEU_ALLOWED_CLIENTS (vírgula); ausente/vazio = desligado
26
+ issuerUrl?: string; // sem a opção: ORFEU_ISSUER_URL
27
+ trustedProxies?: string[]; // sem a opção: ORFEU_TRUSTED_PROXIES; padrão DEFAULT_TRUSTED_PROXIES; [] = nenhum
28
+ checkRevocation?: boolean | string[]; // padrão false; identificadores das operações ou true
21
29
  }
30
+ interface PermissionsRefreshOptions { enabled?: boolean; intervalMs?: number /*60_000*/; jitter?: number /*0.2*/ }
22
31
 
23
32
  class OrfeuClient {
24
33
  constructor(options: OrfeuClientOptions);
@@ -36,7 +45,12 @@ class OrfeuClient {
36
45
  refreshOperations(): Promise<boolean>; // revalidação (If-None-Match); nunca lança; true = sucesso
37
46
  startPermissionsRefresh(): void; stopPermissionsRefresh(): void;
38
47
  readonly lastPermissionsSyncAt: Date | null; readonly permissionsStale: boolean;
48
+ readonly permissionsRefreshRunning: boolean;
39
49
  close(timeoutMs?: number): Promise<void>; // para a recarga + flushAudit
50
+ readonly isTrustedProxy: TrustedProxyMatcher; // montado de trustedProxies (1.3+)
51
+ requiresRevocationCheck(identifier: string): boolean; // checkRevocation cobre a operação? (1.3+)
52
+ assertAccessTokenActive(token: string): Promise<void>; // introspecção RFC 7662; inativo/Argos fora → OrfeuTokenError (1.3+)
53
+ validateServiceToken(token: string, opts?: ValidateServiceTokenOptions): Promise<ServiceTokenClaims>; // 1.4+
40
54
  validateToken(token: string): Promise<TokenClaims>;
41
55
  validateAppToken(token: string): Promise<TokenClaims>;
42
56
  validateApiToken(token: string, identifier: string, method: string): Promise<ApiTokenClaims | null>;
@@ -53,9 +67,9 @@ class OrfeuClient {
53
67
  | `startup()` | sem operações → `OrfeuConfigError`. Depois `authenticate()`, prepara o JWKS, `syncOperations()`, `fetchOperations()`. |
54
68
  | `authenticate()` | `POST /realms/{realm}/apps/token` com `{ app_id, secret }` → guarda o token do serviço. Não-2xx ou sem `access_token` → `OrfeuAuthError`. |
55
69
  | `syncOperations()` | `POST /realms/{realm}/apps/operations/sync` com `{ operations: [{ identifier, method, level, description }] }`. Exige token do serviço (`OrfeuAuthError` se não houver). Não-2xx → `OrfeuSyncError`. **Não** reautentica sozinho em 401. |
56
- | `fetchOperations()` | `GET /realms/{realm}/apps/operations` → substitui o cache local de operações (`operation_id`, `level`, `allowed_groups`). Não-2xx → `OrfeuError`. **Não** reautentica sozinho em 401. |
57
- | `validateToken(jwt)` | verifica assinatura com o JWKS de `/realms/{realm}/protocol/openid-connect/certs` (cache do `jose`) e exige `realm_id` = `realmId` (com `acceptAnyRealm`, usa o JWKS do realm do token). Lança `OrfeuTokenError`. |
58
- | `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 ou Argos sem introspecção → `OrfeuTokenError`. |
70
+ | `fetchOperations()` | `GET /realms/{realm}/apps/operations` → substitui o cache local de operações (`operation_id`, `level`, `allowed_groups`). Não-2xx → `OrfeuError`. Reautentica uma vez no 401 e resolve `true` quando o catálogo mudou (1.1+). |
71
+ | `validateToken(jwt)` | verifica com o JWKS de `/realms/{realm}/protocol/openid-connect/certs` (cache do `jose`), **só `RS256`**, e exige (1.3+) `exp`, `sub` e `iss`; `realm_id` = `realmId` (com `acceptAnyRealm`, usa o JWKS do realm do token); `iss` do realm do token — com `issuerUrl`, exatamente `${issuerUrl}/realms/${realm_id}`, sem ele uma URL http(s) terminada em `/realms/${realm_id}`. Recusa token de aplicação (`type: "app"`) e, com `allowedClients`, `client_id`/`azp` fora da lista (ou nenhum dos dois). Com `checkRevocation: true`, confere também a revogação. Lança `OrfeuTokenError`; falha ao falar com o Argos também vira `OrfeuTokenError` (nunca 500). |
72
+ | `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`. |
59
73
  | `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`. |
60
74
  | `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`. |
61
75
  | `operationIdOf(id, method)` | UUID da operação no Argos (depois do `fetchOperations()`), para logs. |
@@ -63,6 +77,10 @@ class OrfeuClient {
63
77
  | `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`. |
64
78
  | `close(timeoutMs = 3000)` | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) para a recarga de permissões e faz o `flushAudit`. Use no encerramento. |
65
79
  | `permissionsRefresh` (opção) | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) `true` (padrão: 60 s, ±20%), `false` ou `{ enabled, intervalMs, jitter }`. O `startup()` agenda a recarga; timer com `unref()`. |
80
+ | `allowedClients` (opção, 1.3+) | `client_id`s (no Argos, o id do client do front) cujos tokens de usuário este backend aceita, em `x-access-token` e `x-app-token`; fora da lista → 401. Comparação sem diferenciar maiúsculas; com `client_id` **e** `azp`, os dois precisam estar na lista. **A opção passada vence a variável, mesmo `[]`** (que desliga). Padrão desligado: ligue em backend de front próprio; não no que atende qualquer app do realm de propósito (admin do Argos). `x-api-token` não é afetado. |
81
+ | `issuerUrl` (opção, 1.3+) | URL pública do Argos (`SERVER_URL`, sem `/realms`) — o `issuer` da discovery sem `/realms/<realm>`. Nunca derive do `authorizerUrl` (endereço interno, com `/argos/api`): o valor errado recusa todo token. |
82
+ | `trustedProxies` (opção, 1.3+) | IPs/CIDRs dos proxies cujo `x-forwarded-for` vale para o IP da auditoria. Padrão `DEFAULT_TRUSTED_PROXIES` (loopback + redes privadas). |
83
+ | `checkRevocation` (opção, 1.3+) | Sem a opção, um access token revogado (logout, `/revoke`, sessão encerrada) vale até o `exp` (até 10 min no Argos). Lista de identificadores: só nessas operações o token é conferido na introspecção RFC 7662 (`/realms/{realm}/protocol/openid-connect/token/introspect`); `true`: em toda validação. Cache 10 s (ativo) / 60 s (inativo); Argos fora → 401 (fail-closed). Com `acceptAnyRealm`, token de outro realm é recusado nessas operações. |
66
84
 
67
85
  ### Tipos de identidade
68
86
 
@@ -131,6 +149,44 @@ function formatTraceparent(t: OrfeuTrace): string; // '00-<traceId>-<spanId>-<fl
131
149
  com exatamente 55 caracteres; versões futuras lidas pelos 4 primeiros campos. Inválido → `undefined` (e
132
150
  `resolveTrace` começa um trace novo).
133
151
 
152
+ ### Token de serviço — máquina-a-máquina (1.4+)
153
+
154
+ ```ts
155
+ interface ValidateServiceTokenOptions {
156
+ allowedApps?: string[]; // app_ids aceitos (sem diferenciar maiúsculas); ausente = qualquer app válida; [] = nenhuma
157
+ realmFor?: (appId: string) => Promise<string | null | undefined> | string | null | undefined; // realm do REGISTRO da app
158
+ checkRevocation?: boolean; // padrão: o checkRevocation === true do client
159
+ }
160
+ interface ServiceTokenClaims { appId: string; realmId: string; clientId?: string; exp: number; raw: Record<string, unknown> }
161
+ client.validateServiceToken(token: string, opts?: ValidateServiceTokenOptions): Promise<ServiceTokenClaims>;
162
+ ```
163
+
164
+ Valida o JWT client_credentials de uma aplicação (`type: "app"`, `sub` = app_id), que o `validateToken` recusa como
165
+ usuário desde a 1.3. Regras: `type === "app"` (checado antes de qualquer rede); RS256 pelo JWKS do **realm de
166
+ verificação**, que **nunca** vem do token — sem `realmFor`, o `realmId` do client; com `realmFor(appId)`, o realm do
167
+ registro da app (`null` = app desconhecida → 401 sem buscar JWKS); realm diferente do `realmId` só com
168
+ `acceptAnyRealm`; `exp`/`sub`/`iss` obrigatórios; `realm_id` do token igual ao realm de verificação; `allowedClients`
169
+ **não** se aplica. Qualquer falha (inclusive Argos fora) → `OrfeuTokenError` (401). Rotas: `serviceGuard(opts?)`
170
+ (Express, `req.orfeuService`), `fastify.orfeuServiceGuard(opts?)` (Fastify, `request.orfeuService`),
171
+ `@ServiceRoute(opts?)` + `@OrfeuService()` (Nest, pelo `OrfeuGuard`; `SERVICE_KEY`). O token vai em
172
+ `x-access-token`; a rota não entra no catálogo nem gera log/auditoria de operação; 401 genérico
173
+ (`Service token required.` / `Invalid service token.`). No Apollo, chame `validateServiceToken` no `context`.
174
+
175
+ ### IP do cliente (1.3+)
176
+
177
+ ```ts
178
+ const DEFAULT_TRUSTED_PROXIES: readonly string[]; // loopback + redes privadas (IPv4 e fc00::/7)
179
+ type TrustedProxyMatcher = (ip: string) => boolean;
180
+ function trustedProxyMatcher(entries?: readonly string[]): TrustedProxyMatcher;
181
+ // captureRequestContext(get, socketAddress?, isTrustedProxy?) e clientIpOf(header, fallback?, isTrustedProxy?)
182
+ // ganharam o matcher como último parâmetro opcional
183
+ ```
184
+
185
+ O **primeiro** valor do `x-forwarded-for` nunca é usado (quem chama escreve o que quiser nele). Conexão direta de
186
+ fora de `trustedProxies` → IP do socket (cabeçalhos ignorados); de proxy confiável → a entrada **mais à direita**
187
+ do `x-forwarded-for` que não é proxy (todas confiáveis: a mais à esquerda); sem ele, `x-real-ip`; senão o socket.
188
+ No Apollo HTTP (sem socket no plugin) vale a regra pela direita.
189
+
134
190
  ### `orfeuHeaders`
135
191
 
136
192
  ```ts
@@ -235,6 +291,7 @@ function orfeu(client: OrfeuClient): OrfeuMiddleware;
235
291
  interface OrfeuMiddleware {
236
292
  middleware: (req, res, next) => Promise<void>; // captura credencial, trace e correlação
237
293
  guard: (id: string, level: Level, method?: Method) => (req, res, next) => Promise<void>;
294
+ serviceGuard: (opts?: ValidateServiceTokenOptions) => (req, res, next) => Promise<void>; // 1.4+: só token de serviço
238
295
  }
239
296
  ```
240
297
 
@@ -328,6 +385,9 @@ class OrfeuDenied extends Error { readonly status: 401 | 403; readonly reason: D
328
385
  - Negação: 401 sempre `GraphQLError` (`extensions: { code: 401, status: 401, reason: 'UNAUTHENTICATED', operation }`);
329
386
  403 em Query/Mutation → `onForbidden(denial)` se devolver algo, senão `GraphQLError` (`code: 403`,
330
387
  `reason: 'FORBIDDEN'`); Subscription → sempre `GraphQLError`. Mensagens `Unauthorized: …`/`Forbidden: …`.
388
+ - **Subscription termina no `exp`** (1.3+): Subscription não pública aberta com token de usuário recebe um último
389
+ `GraphQLError` 401 (`UNAUTHENTICATED`) quando o token vence, e o stream acaba — no Argos, a cada ~10 min. O
390
+ cliente reconecta com o token novo e **reassina** (o spine recria o socket; a tela reassina).
331
391
  - `envelopeOutcome`: resultado `{ status: number, message? }` com `status >= 400` é auditado como `failure`
332
392
  (com `status` e `message`); outros resultados: sem exceção = `success`.
333
393
  - `assertSchemaSecured(schema)`: lança `OrfeuConfigError` listando campos raiz cujo `resolve`/`subscribe` não
@@ -351,4 +411,4 @@ class OrfeuDenied extends Error { readonly status: 401 | 403; readonly reason: D
351
411
  **marcado pela lib** (validado neste contexto ou por `trustUser`). Um `orfeuUser`/`orfeuApiToken` sem a marca
352
412
  é ignorado (cai na regra comum: 401 fora de `public`) e removido do contexto antes do resolver, inclusive
353
413
  em campos `public`/`optional` anônimos. Até a 1.0.0 qualquer `orfeuUser` no contexto valia como
354
- autenticado — por isso o mínimo é `^1.0.1`.
414
+ autenticado — nunca use versão anterior à 1.0.1 (peça `^1.4.0`).
@@ -1,4 +1,4 @@
1
- # Armadilhas e erros comuns — @orfeu/node 1.0.1
1
+ # Armadilhas e erros comuns — @orfeu/node 1.4.0
2
2
 
3
3
  Cada item: sintoma → causa → o que fazer.
4
4
 
@@ -11,7 +11,7 @@ As rotas foram declaradas depois do `startup()`, ou faltou copiar o registro glo
11
11
 
12
12
  **`OrfeuAuthError: Authentication failed: HTTP 401`.** `APP_ID`/`APP_SECRET` errados, serviço de outro realm, ou
13
13
  `authorizerUrl` sem o prefixo da API (o SDK chama `<authorizerUrl>/realms/<realm>/apps/token`). Repetir não
14
- resolve.
14
+ resolve. Desde a 1.3 a mensagem traz só o status, nunca o corpo da resposta do Argos.
15
15
 
16
16
  **`OrfeuSyncError` na subida.** O Argos recusou o catálogo (geralmente nível/método inválido vindo de JS sem
17
17
  tipos — o SDK já barra isso no registro — ou serviço sem permissão de sincronizar). Leia a mensagem: ela traz o
@@ -40,9 +40,9 @@ grupos em `allowed_groups` no Argos. Libere os grupos no Argos; com `@orfeu/node
40
40
  registrado tarde, módulo carregado com `import()` dinâmico): ela não está no catálogo buscado e
41
41
  `checkPermission` devolve `false` (só `public` escapa). Declare tudo antes do `startup()`.
42
42
 
43
- **Permissão mudou no Argos e o serviço não percebeu.** O catálogo com `allowed_groups` é lido no `startup()`.
44
- Com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 a recarga é automática; antes, recarregue com `fetchOperations()` (reautenticando se der 401). Grupos do **usuário** mudam quando o token dele
45
- é renovado.
43
+ **Permissão mudou no Argos e o serviço não percebeu.** Com `@orfeu/node` ≥ 1.1 a recarga é automática (até
44
+ ~1 min); confira se `permissionsRefresh` não foi desligado e o `client.permissionsStale`. Grupos do **usuário**
45
+ mudam quando o token dele é renovado.
46
46
 
47
47
  **401 com token válido.**
48
48
  - O front mandou `Authorization: Bearer …`. O SDK só lê `x-access-token` / `x-app-token` / `x-api-token`, valor
@@ -63,6 +63,40 @@ ela. Use `trustUser(ctx, claims)` (`node-recipes.md` §4). Também quebra a marc
63
63
  **Teste de resolver que passava e virou 401 na 1.0.1.** O teste montava `{ orfeuUser: { sub, groups } }` à mão
64
64
  e chamava o resolver protegido. Monte com `trustUser({}, claims)`.
65
65
 
66
+ ### Depois de atualizar para a 1.3
67
+
68
+ **401 em todo token depois de ligar `issuerUrl`.** O valor não é o emissor público: foi derivado do
69
+ `authorizerUrl` (endereço interno, com `/argos/api`) ou ficou com barra/realm a mais. Use o `issuer` da discovery
70
+ (`{authority}/api/realms/{realm}/.well-known/openid-configuration`) sem o `/realms/<realm>`.
71
+
72
+ **401 só para quem entra por outro front do realm.** É o `allowedClients` funcionando: o `client_id`/`azp` do
73
+ token não está na lista. Num serviço chamado por gateways de vários apps, liste os fronts de todos. A lista
74
+ compara com o **id** do client no Argos, não com o nome exibido.
75
+
76
+ **`allowedClients` ligado no `.env` e nada acontece.** O código passa `allowedClients: []` (lista vazia vinda das
77
+ settings), que desliga e ignora o `ORFEU_ALLOWED_CLIENTS`; ou o `OrfeuClient` é criado no topo de um módulo ESM,
78
+ antes do `dotenv.config()`. Passe `undefined` quando a lista estiver vazia e monte o client depois de carregar o
79
+ ambiente.
80
+
81
+ **Testes com Argos simulado viraram 401.** O token fake não tem `exp`, `sub` ou `iss` (`<url>/realms/<realm_id>`),
82
+ não é `RS256`, é um token de app (`type: "app"`) usado como usuário, ou o `client_id` não está no
83
+ `allowedClients` do teste.
84
+
85
+ **Subscription cai a cada ~10 min com `UNAUTHENTICATED`.** É a 1.3 encerrando o stream no `exp` do token. O
86
+ cliente precisa reconectar com o token novo e **reassinar**; tela que não reassina para de atualizar sem erro
87
+ visível.
88
+
89
+ **IP da auditoria mudou.** O primeiro `x-forwarded-for` não vale mais. Proxy fora de loopback/redes privadas →
90
+ configure `trustedProxies`; usuários na rede privada sem proxy → `trustedProxies` só com os proxies (senão eles
91
+ escrevem o IP que quiserem).
92
+
93
+ **Rota chamada por outra aplicação (client_credentials) virou 401.** A 1.3 recusa `type: "app"` como usuário. Use o
94
+ token de serviço da 1.4 (`serviceGuard`, [node.md](node.md) §5). Fake de teste que devolve claims para qualquer token
95
+ esconde isso: faça o fake recusar `type: "app"` no `validateToken`.
96
+
97
+ **Operação sensível dá 401 com o Argos fora.** `checkRevocation` é fail-closed de propósito. Use a lista de
98
+ operações sensíveis, não `true`.
99
+
66
100
  **`x-api-token` dá 401 mesmo válido.** O token não tem **esta** operação (identificador + método) concedida
67
101
  **neste** serviço. Conferir no Argos.
68
102
 
@@ -127,7 +161,7 @@ descartados do evento, mas continuam no log).
127
161
 
128
162
  ## Auditoria e log
129
163
 
130
- **Eventos perdidos ao reiniciar.** Faltou `await client.close()` (ou `flushAudit()` em versão antiga) no SIGTERM (`node-recipes.md` §11).
164
+ **Eventos perdidos ao reiniciar.** Faltou `await client.close()` no SIGTERM (`node-recipes.md` §11).
131
165
 
132
166
  **Aviso `[orfeu] authorizer has no audit endpoint (404); auditing paused for 10 min`.** O Argos não tem a
133
167
  ingestão de auditoria; a fila é descartada e o SDK tenta de novo depois. Se a auditoria não é desejada:
@@ -1,7 +1,7 @@
1
- # Receitas — @orfeu/node 1.0.1
1
+ # Receitas — @orfeu/node 1.4.0
2
2
 
3
- Todas usam a API real da 1.0.1 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
4
- `REALM_ID`, `APP_ID`, `APP_SECRET` — use os nomes que o projeto já tem.
3
+ Todas usam a API real da 1.4.0 ([node-api.md](node-api.md)). Variáveis de ambiente de exemplo: `AUTHORIZER_URL`,
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
7
7
 
@@ -10,11 +10,18 @@ import express from 'express';
10
10
  import { Level, Method, OrfeuClient, annotateOperation, getRegistry } from '@orfeu/node';
11
11
  import { orfeu } from '@orfeu/node/express';
12
12
 
13
+ const lista = (v?: string) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
14
+ const allowedClients = lista(process.env.ORFEU_ALLOWED_CLIENTS);
15
+
16
+ // Crie o client DEPOIS de carregar o ambiente (dotenv): as opções abaixo são lidas aqui.
13
17
  const client = new OrfeuClient({
14
18
  authorizerUrl: process.env.AUTHORIZER_URL!,
15
19
  realmId: process.env.REALM_ID!,
16
20
  appId: process.env.APP_ID!,
17
21
  secret: process.env.APP_SECRET!,
22
+ allowedClients: allowedClients.length ? allowedClients : undefined, // [] desligaria
23
+ issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
24
+ checkRevocation: ['clientes:delete'], // operações sensíveis
18
25
  });
19
26
  const { middleware, guard } = orfeu(client);
20
27
 
@@ -146,7 +153,7 @@ export class ClientesController {
146
153
  módulo do app. Métodos sem `@Operation` continuam **abertos** — confira todos.
147
154
  - `OrfeuClient` é injetável (`constructor(private readonly orfeu: OrfeuClient) {}`) para `checkPermission`,
148
155
  `flushAudit` etc.
149
- - Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy` (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1). Antes, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
156
+ - Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy`.
150
157
 
151
158
  ## 4. Apollo Server (HTTP + WebSocket)
152
159
 
@@ -195,6 +202,8 @@ await client.startup(); // secureResolvers já registrou as operações n
195
202
 
196
203
  const apollo = new ApolloServer<OrfeuContext>({ schema, plugins: [orfeuPlugin(client)] });
197
204
  const { url } = await startStandaloneServer(apollo, { listen: { port: 4000 }, context: async () => ({}) });
205
+ // Subscription não pública termina com um 401 (UNAUTHENTICATED) no exp do token (~10 min no Argos):
206
+ // o cliente reconecta com o token novo e reassina.
198
207
 
199
208
  // subscriptions: o graphql-ws executa o schema sem os plugins do Apollo — o contexto precisa do orfeuWsContext
200
209
  const httpServer = createServer();
@@ -416,8 +425,8 @@ client.lastPermissionsSyncAt; // Date | null — último sucesso
416
425
  client.permissionsStale; // true após 5 intervalos sem sucesso (bom para o /health, sem derrubar)
417
426
  ```
418
427
 
419
- Versão anterior a essa: as permissões só eram lidas no `startup()` — recarregue com `fetchOperations()` num
420
- `setInterval` (`unref()`), chamando `authenticate()` antes de repetir quando der 401 (o token do serviço vence).
428
+ >>>>
429
+
421
430
 
422
431
  ## 11. Encerramento sem perder eventos
423
432
 
@@ -432,8 +441,8 @@ for (const signal of ['SIGTERM', 'SIGINT'] as const) {
432
441
  ```
433
442
 
434
443
  Em container sem init, o processo Node é o PID 1 e só termina no SIGTERM se tratar o sinal (como acima).
435
- `close()` existe a partir de `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; antes, `flushAudit()` (não havia recarga para parar). Fastify (`fastify.close()`),
436
- Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o encerramento do client sozinhos.
444
+ Fastify (`fastify.close()`), Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o
445
+ encerramento do client sozinhos.
437
446
 
438
447
  ## 12. Testes
439
448
 
@@ -492,11 +501,14 @@ export async function startFakeArgos(opts: { realm?: string; appId?: string; sec
492
501
  await new Promise<void>((resolve) => server.listen(0, 'localhost', resolve));
493
502
  const { port } = server.address() as AddressInfo;
494
503
 
504
+ const url = `http://localhost:${port}`;
505
+
495
506
  return {
496
- url: `http://localhost:${port}`, realm, appId, secret, audits,
497
- signUser: (sub: string, groups: string[] = []) =>
498
- new SignJWT({ groups, realm_id: realm }).setProtectedHeader({ alg: 'RS256', kid: 'k1' })
499
- .setSubject(sub).setIssuedAt().setExpirationTime('1h').sign(privateKey),
507
+ url, realm, appId, secret, audits,
508
+ // 1.3+: exp, sub e iss obrigatórios; iss = <url>/realms/<realm>; client_id conta com allowedClients
509
+ signUser: (sub: string, groups: string[] = [], clientId = 'front-de-teste') =>
510
+ new SignJWT({ groups, realm_id: realm, client_id: clientId }).setProtectedHeader({ alg: 'RS256', kid: 'k1' })
511
+ .setSubject(sub).setIssuer(`${url}/realms/${realm}`).setIssuedAt().setExpirationTime('1h').sign(privateKey),
500
512
  close: () => new Promise<void>((resolve) => server.close(() => resolve())),
501
513
  };
502
514
  }
@@ -539,3 +551,5 @@ it('401 sem credencial, 403 sem grupo, 204 com grupo', async () => {
539
551
  - `jose` vem com o `@orfeu/node`, mas declare-o como `devDependency` do app se o teste o importa.
540
552
  - `authorizerUrl` do simulado não tem `/api`: o SDK monta `<authorizerUrl>/realms/<realm>/…`.
541
553
  - `clearRegistry()` antes de cada arquivo que declara rotas: o registro global é do processo.
554
+ - Teste do `allowedClients`: `new OrfeuClient({ ..., allowedClients: ['front-de-teste'] })` e um token com
555
+ `signUser(sub, groups, 'outro-front')` → 401. Token sem `iss`/`exp`/`sub` ou com `type: 'app'` → 401.