@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.
- package/README.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +4 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +382 -0
- package/skills/orfeu/SKILL.md +32 -6
- package/skills/orfeu/references/angular-api.md +14 -6
- package/skills/orfeu/references/angular-armadilhas.md +17 -2
- package/skills/orfeu/references/angular-recipes.md +23 -8
- package/skills/orfeu/references/angular.md +16 -7
- package/skills/orfeu/references/diferencas.md +13 -6
- package/skills/orfeu/references/node-api.md +68 -8
- package/skills/orfeu/references/node-armadilhas.md +40 -6
- package/skills/orfeu/references/node-recipes.md +26 -12
- package/skills/orfeu/references/node.md +66 -12
- package/skills/orfeu/references/python-api.md +53 -13
- package/skills/orfeu/references/python-recipes.md +22 -22
- package/skills/orfeu/references/python.md +68 -10
- package/skills/trismegisto/SKILL.md +5 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Receitas — @orfeu/angular 1.
|
|
1
|
+
# Receitas — @orfeu/angular 1.4.0
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.
|
|
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
|
-
|
|
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()
|
|
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.
|
|
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
|
|
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)
|
|
148
|
-
avisa as abas
|
|
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=...`
|
|
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.
|
|
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.
|
|
4
|
-
nova, confira de novo antes de confiar nesta tabela. O que
|
|
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, ... }
|
|
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
|
|
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 (
|
|
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
|
+
# API — @orfeu/node 1.4.0
|
|
2
2
|
|
|
3
|
-
> Conferida contra o código-fonte da 1.0
|
|
4
|
-
> interno.
|
|
5
|
-
> `
|
|
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`.
|
|
57
|
-
| `validateToken(jwt)` | verifica
|
|
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
|
|
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 —
|
|
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
|
+
# 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.**
|
|
44
|
-
|
|
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()`
|
|
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
|
+
# Receitas — @orfeu/node 1.4.0
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.0
|
|
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
|
|
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
|
-
|
|
420
|
-
|
|
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()`
|
|
436
|
-
|
|
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
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
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.
|