@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.
- package/README.md +5 -4
- package/agents/revisor-orfeu.md +2 -1
- package/package.json +1 -1
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +2 -2
- package/skills/angular/SKILL.md +2 -2
- package/skills/angular/references/dados.md +3 -3
- package/skills/angular/references/estrutura.md +6 -5
- package/skills/angular/references/features.md +5 -5
- package/skills/angular/references/testes-build.md +1 -1
- package/skills/auto-servico/SKILL.md +18 -14
- package/skills/express/references/dados.md +4 -1
- package/skills/express/references/estrutura.md +2 -1
- package/skills/fastapi/references/banco.md +6 -2
- package/skills/fastapi/references/estrutura.md +1 -1
- package/skills/hefesto/SKILL.md +6 -2
- package/skills/orfeu/SKILL.md +43 -13
- package/skills/orfeu/references/angular-api.md +39 -13
- package/skills/orfeu/references/angular-armadilhas.md +18 -1
- package/skills/orfeu/references/angular-recipes.md +25 -12
- package/skills/orfeu/references/angular.md +37 -15
- package/skills/orfeu/references/diferencas.md +17 -8
- package/skills/orfeu/references/node-api.md +41 -9
- package/skills/orfeu/references/node-armadilhas.md +16 -2
- package/skills/orfeu/references/node-recipes.md +13 -4
- package/skills/orfeu/references/node.md +31 -12
- package/skills/orfeu/references/python-api.md +41 -16
- package/skills/orfeu/references/python-recipes.md +13 -9
- package/skills/orfeu/references/python.md +33 -12
- package/skills/orfeu/references/react.md +133 -0
- package/skills/trismegisto/SKILL.md +42 -29
- package/skills/trismegisto/references/angular-api.md +608 -6
- package/skills/trismegisto/references/angular-exports.md +479 -791
- package/skills/trismegisto/references/angular-recipes.md +13 -7
- package/skills/trismegisto/references/angular.md +32 -9
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +90 -65
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5565 -1973
- package/skills/trismegisto/references/spine-recipes.md +113 -26
- package/skills/trismegisto/references/spine.md +95 -33
- package/skills/trismegisto/scripts/checar.mjs +66 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Armadilhas e erros comuns — @orfeu/angular 1.
|
|
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.
|
|
1
|
+
# Receitas — @orfeu/angular 1.7.1
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.
|
|
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 {
|
|
16
|
+
import { apiTokenInterceptor } from './core/api-token.interceptor';
|
|
17
17
|
|
|
18
18
|
export const appConfig: ApplicationConfig = {
|
|
19
19
|
providers: [
|
|
20
|
-
|
|
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/
|
|
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
|
|
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
|
|
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
|
-
> `logout()`,
|
|
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.
|
|
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
|
|
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 {
|
|
76
|
+
import { apiTokenInterceptor } from './core/api-token.interceptor'; // angular-recipes.md §4
|
|
76
77
|
|
|
77
78
|
export const appConfig: ApplicationConfig = {
|
|
78
79
|
providers: [
|
|
79
|
-
|
|
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 `
|
|
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
|
|
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**
|
|
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.
|
|
1
|
+
# Diferenças entre as implementações — comportamento atual (1.7.1)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
|
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
|
|
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` (
|
|
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
|
|
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.
|
|
1
|
+
# API — @orfeu/node 1.7.1
|
|
2
2
|
|
|
3
|
-
> Conferida contra o código-fonte da 1.
|
|
4
|
-
> interno. Peça `"@orfeu/node": "^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`).
|
|
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()
|
|
119
|
-
|
|
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 {
|
|
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.
|
|
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.
|
|
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
|
|
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.
|
|
1
|
+
# Receitas — @orfeu/node 1.7.1
|
|
2
2
|
|
|
3
|
-
Todas usam a API real da 1.
|
|
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
|