@acropole/skills 1.7.0 → 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 +14 -11
- package/agents/revisor-orfeu.md +2 -1
- package/bin/install.js +41 -9
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +2 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
- package/skills/angular/SKILL.md +4 -3
- package/skills/angular/references/armadilhas.md +3 -3
- 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/auto-servico/references/roteiros.md +1 -1
- package/skills/auto-servico/references/tools.md +1 -1
- 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 +13 -6
- package/skills/hefesto/references/diagnostico.md +1 -0
- package/skills/hefesto/references/mcp-roteiros.md +48 -7
- 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/orquestracao/SKILL.md +3 -1
- package/skills/orquestracao/scripts/coord.sh +10 -2
- package/skills/trismegisto/SKILL.md +89 -35
- package/skills/trismegisto/references/angular-api.md +4548 -344
- package/skills/trismegisto/references/angular-exports.md +8275 -2579
- package/skills/trismegisto/references/angular-recipes.md +327 -6
- package/skills/trismegisto/references/angular-types.md +92 -0
- package/skills/trismegisto/references/angular.md +96 -16
- package/skills/trismegisto/references/catalogo/icones.json +7 -0
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
- package/skills/trismegisto/references/catalogo/tokens.json +114 -0
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5904 -1361
- package/skills/trismegisto/references/spine-recipes.md +140 -46
- package/skills/trismegisto/references/spine.md +121 -49
- package/skills/trismegisto/scripts/checar.mjs +66 -1
|
@@ -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
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# @orfeu/node — guia de uso (Express, Fastify, NestJS, Apollo)
|
|
2
2
|
|
|
3
|
-
> Escrito para a **1.
|
|
4
|
-
> `orfeuUser` forjado nas subscriptions do Apollo; a 1.3.0 trouxe as correções da auditoria de segurança
|
|
3
|
+
> Escrito para a **1.7.1** (peça `^1.7.1`; anda junto com `@orfeu/angular`, `@orfeu/react` e `orfeu`). A 1.0.0
|
|
4
|
+
> aceitava `orfeuUser` forjado nas subscriptions do Apollo; a 1.3.0 trouxe as correções da auditoria de segurança
|
|
5
|
+
> (§5); a 1.6.0, a tolerância de relógio; a 1.7.0 fez `public` deixar de validar credencial e criou o `identify`
|
|
6
|
+
> (§5).
|
|
5
7
|
> Se a versão instalada for outra, confira os nomes de [node-api.md](node-api.md)
|
|
6
8
|
> contra os `.d.ts` de `node_modules/@orfeu/node/dist/`. Conceitos comuns às três implementações estão no
|
|
7
9
|
> `SKILL.md` da skill; o que muda em relação ao Python e ao Angular está em [diferencas.md](diferencas.md).
|
|
@@ -31,7 +33,7 @@ Leia sob demanda:
|
|
|
31
33
|
## 1. Instalação
|
|
32
34
|
|
|
33
35
|
```bash
|
|
34
|
-
npm install @orfeu/node@^1.
|
|
36
|
+
npm install @orfeu/node@^1.7.1
|
|
35
37
|
npm install express # se usar @orfeu/node/express
|
|
36
38
|
npm install fastify # @orfeu/node/fastify
|
|
37
39
|
npm install @nestjs/common @nestjs/core reflect-metadata rxjs # @orfeu/node/nest
|
|
@@ -56,14 +58,15 @@ const client = new OrfeuClient({
|
|
|
56
58
|
allowedClients: ['<client_id do front>'], // backend de front próprio: ligue (§5)
|
|
57
59
|
issuerUrl: process.env.ORFEU_ISSUER_URL || undefined,
|
|
58
60
|
// acceptAnyRealm: false, tlsVerify: true, audit: true, logger: jsonLineLogger,
|
|
59
|
-
// permissionsRefresh: true, trustedProxies: DEFAULT_TRUSTED_PROXIES, checkRevocation: false
|
|
61
|
+
// permissionsRefresh: true, trustedProxies: DEFAULT_TRUSTED_PROXIES, checkRevocation: false,
|
|
62
|
+
// clockToleranceSec: DEFAULT_CLOCK_TOLERANCE_SEC (30) (padrões)
|
|
60
63
|
});
|
|
61
64
|
```
|
|
62
65
|
|
|
63
66
|
| Opção | Padrão | Efeito |
|
|
64
67
|
|---|---|---|
|
|
65
68
|
| `acceptAnyRealm` | `false` | `true` aceita tokens de qualquer realm (busca o JWKS do realm da claim `realm_id`). |
|
|
66
|
-
| `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo). |
|
|
69
|
+
| `tlsVerify` | `true` | `false` aceita certificado autoassinado **só** nas chamadas deste client (não mexe no processo); desde a 1.6 deixa um `console.warn` ao criar o client. |
|
|
67
70
|
| `audit` | `true` | `false` desliga a auditoria; objeto `{ flushIntervalMs, maxBuffer, batchSize }` ajusta o lote. |
|
|
68
71
|
| `logger` | `jsonLineLogger` | função `(record) => void` para outro destino; `false` desliga o log de operação. |
|
|
69
72
|
| `permissionsRefresh` | `true` | revalida o catálogo (grupos liberados) a cada 60 s ±20%; `false` ou `{ enabled, intervalMs, jitter }`. |
|
|
@@ -71,6 +74,7 @@ const client = new OrfeuClient({
|
|
|
71
74
|
| `issuerUrl` | — | URL pública do Argos (`SERVER_URL`): `iss` esperado = `${issuerUrl}/realms/${realm_id}`. Sem a opção, `ORFEU_ISSUER_URL`. |
|
|
72
75
|
| `trustedProxies` | `DEFAULT_TRUSTED_PROXIES` | proxies cujo `x-forwarded-for` vale para o IP da auditoria (loopback + redes privadas). Sem a opção, `ORFEU_TRUSTED_PROXIES`; `[]` = nenhum. |
|
|
73
76
|
| `checkRevocation` | `false` | lista de operações sensíveis (ou `true`) conferidas na introspecção do Argos; fail-closed. |
|
|
77
|
+
| `clockToleranceSec` | `30` (`DEFAULT_CLOCK_TOLERANCE_SEC`) | 1.6+: tolerância de relógio, em segundos, no `exp`/`nbf`/`iat` dos JWT (`validateToken`, `validateServiceToken`). Afrouxa: token vencido há menos de 30 s ainda vale; `0` = conferência exata. Valor inválido ou negativo volta ao padrão. |
|
|
74
78
|
|
|
75
79
|
As três variáveis `ORFEU_*` só são lidas **quando a opção não é passada** — e no construtor. Cliente criado no
|
|
76
80
|
topo de um módulo ESM roda antes do `dotenv.config()` e não as vê em `local`: prefira passar pelas settings do
|
|
@@ -119,12 +123,26 @@ Headers de credencial (`x-access-token` → `x-app-token` → `x-api-token`, a p
|
|
|
119
123
|
401/403 estão no `SKILL.md` §4 — a regra é a mesma do Python. Específico do Node: introspecção com cache de
|
|
120
124
|
60 s (token inativo: 10 s); `acceptAnyRealm: true` aceita JWT de outros realms.
|
|
121
125
|
|
|
126
|
+
**`public` não valida nada (1.7+)**: o guard libera sem ler `x-access-token`/`x-app-token`/`x-api-token` e sem
|
|
127
|
+
chamar o Argos (um token aleatório em rajada numa rota pública não vira mais introspecção), e o handler não recebe
|
|
128
|
+
`orfeuUser`/`orfeuApiToken`. Log e auditoria saem com `actor_type: public`. Para ter a identidade quando houver:
|
|
129
|
+
- **`optional`** — autoriza: sem credencial roda anônimo; credencial inválida ou vencida dá 401; o usuário precisa
|
|
130
|
+
de ao menos um grupo, o que depende do catálogo de operações (sem ele, `optional` com credencial dá 403);
|
|
131
|
+
- **`identify`** — só identifica, nunca bloqueia e não depende do catálogo nem do `startup()`: credencial válida
|
|
132
|
+
(access → app → api; o `x-api-token` só se concedido para a operação) preenche `orfeuUser`/`orfeuApiToken`;
|
|
133
|
+
inválida, vencida ou Argos fora vira anônimo. Registra a operação como `public` e gera o mesmo log/auditoria,
|
|
134
|
+
com o ator identificado. Quem decide o acesso é o app, depois. É exatamente o `public` até a 1.6:
|
|
135
|
+
`guard(id, Level.PUBLIC, method)` → `identify(id, method)` (Express), `fastify.orfeuIdentify(id, method?)`,
|
|
136
|
+
`@Identify(id, method?)` (Nest), `createIdentify(client)` ou `operation('public', r, { identify: true })`
|
|
137
|
+
(Apollo; `identify` com outro nível lança `OrfeuConfigError`). Receitas em [node-recipes.md](node-recipes.md).
|
|
138
|
+
|
|
122
139
|
O `x-access-token` é recusado (401 `Invalid token.`) quando (1.3+): o algoritmo não é `RS256`, a assinatura ou o
|
|
123
|
-
`kid` não conferem; falta `exp`, `sub` ou `iss`, ou venceu
|
|
140
|
+
`kid` não conferem; falta `exp`, `sub` ou `iss`, ou venceu (com a tolerância de `clockToleranceSec`, 1.6+); o
|
|
141
|
+
`iss` não é o do realm do token (com `issuerUrl`,
|
|
124
142
|
exatamente `${issuerUrl}/realms/${realm_id}`; sem, uma URL http(s) terminada em `/realms/${realm_id}`); o realm
|
|
125
143
|
não é o do app (modo estrito); é token **de aplicação** (`type: "app"`, client_credentials); ou `allowedClients`
|
|
126
144
|
está ligado e o `client_id`/`azp` não está na lista. Falha ao falar com o Argos (JWKS, `/apps/token`,
|
|
127
|
-
introspecção) nunca vira 500:
|
|
145
|
+
introspecção) nunca vira 500: 401 nos níveis que validam (`public` não valida; `identify` vira anônimo).
|
|
128
146
|
|
|
129
147
|
**`allowedClients`**: o access token do Argos é do realm inteiro e traz os grupos do usuário no client que fez o
|
|
130
148
|
login. Sem a lista, um usuário com qualquer grupo em **outro** client do realm passa nas operações `private`.
|
|
@@ -144,7 +162,7 @@ para o log.
|
|
|
144
162
|
|
|
145
163
|
Quem passou fica em `req.orfeuUser` (`TokenClaims`: `sub`, `realmId`, `groups`, `exp`, `raw`) ou
|
|
146
164
|
`req.orfeuApiToken` (`{ tokenId, appId }`) — no Apollo, `ctx.orfeuUser`/`ctx.orfeuApiToken`; no Nest,
|
|
147
|
-
`@OrfeuUser()`.
|
|
165
|
+
`@OrfeuUser()`. Em `public` (1.7+) ficam vazios; em `identify`, preenchidos só com credencial válida.
|
|
148
166
|
|
|
149
167
|
### Rota máquina-a-máquina: token de serviço (1.4+)
|
|
150
168
|
|
|
@@ -166,10 +184,10 @@ app.post('/interno/sincronizar', serviceGuard({ allowedApps: [process.env.APP_OR
|
|
|
166
184
|
|
|
167
185
|
| Framework | Captura (global) | Protege | Usuário |
|
|
168
186
|
|---|---|---|---|
|
|
169
|
-
| Express | `app.use(middleware)` de `orfeu(client)` | `guard(id, level, method?)` por rota | `req.orfeuUser` |
|
|
170
|
-
| Fastify | `await fastify.register(orfeuFastifyPlugin, { client })` | `preHandler: fastify.orfeuGuard(id, level, method?)` | `request.orfeuUser` |
|
|
171
|
-
| NestJS | `OrfeuModule.forRootAsync(opts)` | `@UseGuards(OrfeuGuard)` + `@Operation(id, level, method?)` no método | `@OrfeuUser()` |
|
|
172
|
-
| Apollo | `plugins: [orfeuPlugin(client)]`; WS: `context: orfeuWsContext(client)` | `operation(level, resolver, opts?)` em **todo** campo raiz + `secureResolvers` + `assertSchemaSecured` | `ctx.orfeuUser` |
|
|
187
|
+
| Express | `app.use(middleware)` de `orfeu(client)` | `guard(id, level, method?)` por rota; `identify(id, method?)` (1.7+) | `req.orfeuUser` |
|
|
188
|
+
| Fastify | `await fastify.register(orfeuFastifyPlugin, { client })` | `preHandler: fastify.orfeuGuard(id, level, method?)`; `fastify.orfeuIdentify(id, method?)` (1.7+) | `request.orfeuUser` |
|
|
189
|
+
| NestJS | `OrfeuModule.forRootAsync(opts)` | `@UseGuards(OrfeuGuard)` + `@Operation(id, level, method?)` ou `@Identify(id, method?)` (1.7+) no método | `@OrfeuUser()` |
|
|
190
|
+
| Apollo | `plugins: [orfeuPlugin(client)]`; WS: `context: orfeuWsContext(client)` | `operation(level, resolver, opts?)` em **todo** campo raiz (`{ identify: true }` com `public`, 1.7+) + `secureResolvers` + `assertSchemaSecured`; fora dele, `createGuard`/`createIdentify` | `ctx.orfeuUser` |
|
|
173
191
|
|
|
174
192
|
A captura só lê headers; **quem valida é o guard**. Rota sem guard (ou método Nest sem `@Operation`) não tem
|
|
175
193
|
usuário e **não é protegida nem auditada**.
|
|
@@ -246,6 +264,7 @@ O pacote não publica mocks. Opções (`node-recipes.md` §12):
|
|
|
246
264
|
|
|
247
265
|
- Não leia `Authorization`/`Bearer`; não valide JWT nem confira grupos à mão: use o guard.
|
|
248
266
|
- Não deixe rota/resolver de negócio sem guard; não use `PUBLIC` para "resolver depois".
|
|
267
|
+
- Não leia `orfeuUser` numa rota `PUBLIC` (1.7+: sempre vazio): use `OPTIONAL` ou `identify`.
|
|
249
268
|
- Não declare operações depois do `startup()` (não estarão no catálogo e serão negadas).
|
|
250
269
|
- Não use texto livre para nível/método: `Level.*`/`Method.*`.
|
|
251
270
|
- Não repasse credencial com `orfeuHeaders` para fora dos seus serviços.
|