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