@neetru/sdk 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -5,6 +5,110 @@ All notable changes to `@neetru/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.8.0] - 2026-10-03 — **feat(apps): chave `nrt_` só de servidor, `verifyAccessToken`, mobile integrado, correlation id**
+
+Release **minor**. Nenhuma API pública removida; produtos que ainda usam a chave no navegador **continuam funcionando** (só ganham um aviso). Base para produtos com app móvel (primeiro: PDV em React Native/Expo).
+
+### Contexto (decisão do dono, 2026-10-03)
+
+- A credencial `nrt_` do produto é **SÓ DE SERVIDOR**. Site e app falam com a API do **próprio produto**; o backend do produto usa o SDK. Navegador/app nunca carregam segredo.
+- Dados de negócio: app → `<produto>.neetru.com/api/v1` → SDK no servidor → Core. Direto ao Core só assuntos de plataforma com o **token do usuário** (login no auth.neetru.com, barra de conta, `/userinfo`).
+- Corrige a premissa da 3.7.0 ("a chave `nrt_` … roda no browser"): isso deixa de ser aceito como desenho.
+
+### Adicionado
+
+- **Guarda da chave fora do servidor.** `createNeetruClient` detecta chave (via `apiKey` ou `NEETRU_API_KEY`) rodando em **navegador** (`window` + `document`) ou **React Native** (`navigator.product === 'ReactNative'`):
+  - padrão nesta minor: **aviso único** no console, em PT-BR, explicando o caminho certo — **nunca imprime a chave**;
+  - `strictServerOnlyKey: true` → falha **FECHADO** com `NeetruError('server_only_key')` (`reason`: `browser` | `react-native`);
+  - **na próxima MAJOR (4.0) a falha fechada vira o padrão.** Node/Edge (servidor) não são afetados.
+  - `missing_api_key` fora do servidor agora explica que a chamada deve ir pela API do produto.
+- **`verifyAccessToken(token, { audience, requiredScopes?, issuer?, jwksUrl?, clockToleranceSec?, allowClientCredentials? })`** — validação server-side do access_token do auth.neetru.com, no formato real do Core (`src/lib/oidc/tokens.ts`): RS256 via JWKS `…/api/v1/oauth/.well-known/jwks` (cache compartilhado com `auth.verifyToken`), `iss`, `exp` (tolerância 5s), **`aud ∈ audience`** (lista: web + iOS + Android do produto; vazia = `invalid_config`), formato de access token (`jti` + `scope` + `client_id` === `aud` — **id_token é recusado**), usuário final (token de máquina `client:` só com `allowClientCredentials`), escopos exigidos (`insufficient_scope`, 403). Validação local: token revogado vale até expirar (15 min no Core).
+- **`authenticateProductRequest(req, { audience, cookie? })`** — a API do produto aceita `Authorization: Bearer <access_token>` **além** do cookie do site. Bearer inválido lança (nunca cai pro cookie em silêncio). Aceita `Request`, `Headers` ou `req.headers` do Node. Mais `accessTokenErrorToHttp(err)` (401/403 RFC 6750 com `WWW-Authenticate`, 503 se o JWKS cair, 500 sem vazar detalhe), `readBearerToken`, `readCookie`.
+- **`@neetru/sdk/mobile` integrado:**
+  - **recusa `apiKey` SEMPRE** (`server_only_key`; no tipo, `apiKey?: never`) e exige `oidcClientId` (client OIDC público do app);
+  - guarda o **access_token** do `/token` e expõe `getAccessToken()` (renova 1x se vencido/a <30s);
+  - `getUserInfo()` no `/api/v1/oauth/userinfo` do Core (renova 1x num 401; `NeetruAuthRequiredError` sem sessão);
+  - `authFetch(path, init)` → API do produto (`productApiUrl`, só `https://` ou localhost) com Bearer + `x-correlation-id`, renova 1x num 401; **outra origem é recusada** (o token nunca vaza pra terceiros);
+  - `refreshTokens` **deduplicado** (o Core faz rotation com detecção de replay: dois refresh concorrentes derrubavam a sessão inteira).
+- **`createNeetruClient({ endUserAuth })`** — provedor do token do usuário final **síncrono ou assíncrono** (`getIdToken()` + `refreshTokens()` opcional), usado pelo `support` (`X-Neetru-End-User-Token`) e pela barra de conta (`fetchNeetruAccountBar`). O `MobileAuthNamespace` encaixa direto; no backend do produto pode ser o id_token que o app mandou.
+- **`x-correlation-id` em toda requisição** (`httpRequest` e gateway de IA): UUID por chamada (o do chamador — header ou opção `correlationId` — vence; id inseguro com CR/LF é trocado), o mesmo id nas retentativas, exposto em **`NeetruError.correlationId`** (novo campo; 6º argumento opcional do construtor). Sem `crypto` (RN sem polyfill) cai num gerador não-criptográfico — nunca derruba a chamada.
+- Novos códigos em `NeetruErrorCode`: `server_only_key`, `token_invalid`, `insufficient_scope`.
+- Exportados do barrel: `verifyAccessToken`, `authenticateProductRequest`, `accessTokenErrorToHttp`, `readBearerToken`, `readCookie`, `NEETRU_OIDC_ISSUER`, `detectNonServerRuntime` e os tipos (`VerifyAccessTokenOptions`, `VerifiedAccessToken`, `EndUserTokenProvider`, …).
+
+### Corrigido
+
+- **Logout não revogava nada no servidor (web e mobile).** O `signOut` mandava `JSON { token: <id_token> }` pro `/api/v1/oauth/revoke`; o Core exige `application/x-www-form-urlencoded` (400) e id_token não é revogável — o **refresh_token de 30 dias seguia válido** depois do "sair". Agora revoga o **refresh_token** (e, no mobile, também o access_token) no formato do Core (RFC 7009, `token_type_hint` + `client_id` do client público). A sessão local é limpa sempre; se o servidor não confirmar, avisa no console (sem imprimir token).
+- **`client.db` em React Native caía em memória em silêncio** (dados sumiam ao fechar o app). Agora é **fora de escopo com erro claro** (`runtime_unsupported`) em qualquer uso; `mocks.db` explícito continua valendo.
+
+### Mudança de comportamento (ler antes de atualizar)
+
+- `@neetru/sdk/mobile` (entrypoint da 3.6.0, ainda sem app em produção): `apiKey` agora lança; sem `oidcClientId` lança (não cai mais no keyId da chave).
+- Navegador com chave: aparece **um** `console.warn` por carregamento de página. Nada quebra.
+- `signOut` web: com refresh_token salvo, faz 1 POST form-urlencoded ao `/revoke` (antes: JSON que dava 400). Sem refresh_token, não chama o servidor.
+
+### Migração dos produtos (PDV, GestoVendas, Zelo)
+
+1. Tirar a chave do bundle do navegador: remover `NEXT_PUBLIC_NEETRU_API_KEY` / `NEXT_PUBLIC_NEETRU_PUBLIC_KEY`; a chave fica só em `NEETRU_API_KEY` no servidor (injetada pelo Core/agente).
+2. Toda chamada que hoje o navegador faz com o SDK + chave (support, usage, db, ai…) passa por uma rota da API do produto (`/api/v1/...`) que usa `getServerNeetruClient()`; o id_token do usuário vai junto via `endUserAuth`.
+3. As rotas da API aceitam o app com `authenticateProductRequest(req, { audience: [web, ios, android], cookie })`.
+4. Ligar `strictServerOnlyKey: true` no client do navegador assim que (1) estiver feito — falha cedo se alguma chave voltar.
+5. `neetru deploy` (CLI ≥ 2.30.0) passa a **bloquear** o deploy se achar `nrt_…` no pacote público.
+
+### Interno
+
+- **Gate de pre-push local** (padrão da skill `neetru-pre-push` — Actions da org sem billing, o gate local É o CI): `scripts/pre-push-gate.mjs` (template da loja, sem dependências) + `.githooks/pre-push` (+ `.gitattributes` forçando LF no hook — com `core.autocrlf=true` o shebang com CRLF quebraria no Windows). Etapas = as do `ci.yml`: `npm run lint` (`tsc --noEmit`) → `npm test` (→ `npm run build` com `NEETRU_PREPUSH_FULL=1`); push direto pra `main` bloqueado (`NEETRU_ALLOW_MAIN_PUSH=1` pra fuga consciente); `NEETRU_SKIP_PREPUSH=1` só em emergência, com motivo no PR. O `prepare` liga `core.hooksPath=.githooks` só quando existe `.git` (arquivo ou diretório — vale em worktree) e nunca falha: não afeta `npm publish` nem quem instala o pacote do registry (lá o `prepare` nem roda). Sem mudança no pacote publicado — não exige release.
+
+## [3.7.0] - 2026-09-29 — **feat(support): identidade do usuário final (`X-Neetru-End-User-Token`) nos tickets**
+
+Release **minor** (capacidade nova; nenhuma API pública removida ou renomeada — ver "Mudança de comportamento" abaixo).
+
+### Contexto
+
+Auditoria das APIs públicas do Core (2026-09-29, HIGH-2): a chave `nrt_` do produto identifica o **produto**, não a pessoa — e roda no browser. Os tickets de suporte eram "possuídos" pelo dono da chave, igual pra todos os usuários finais, e `GET /api/sdk/v1/support/tickets` listava os tickets de **todo mundo** do produto (screenshots, console logs, URLs). Contrato final do Core (Neetru/neetru-core#513):
+
+- `X-Neetru-End-User-Token: <id_token>` (aceita também `Bearer <id_token>`), sempre junto do `Authorization` da chave do produto. **Só id_token**: token com `jti` (access token) → `401 invalid_end_user_token`.
+- **Obrigatório** em `GET /api/sdk/v1/support/tickets` (sem header → `403 end_user_token_required`) e nas mutações `/{id}/contest|satisfaction|satisfaction-attempt|resolved-seen`.
+- **Opcional** no `POST` de criação: com header o ticket fica amarrado ao `endUserId` (= `sub`); sem header nasce sem dono e **não aceita** contest/satisfaction.
+- id_token de client OIDC de **outro produto** → `403 end_user_token_product_mismatch`.
+- Token expirado / usuário inativo → `401 invalid_end_user_token`.
+- A listagem não traz mais `attachments`/`consoleLogs`: `screenshotUrl` vem `null` na lista e `screenshotAttached` diz se há print. `limit` padrão 20, máximo 50.
+
+**Dependência de deploy:** esta versão precisa estar publicada **junto/antes** do deploy do Core #513; senão a aba "Meus tickets" dos produtos (ex.: pdv) passa a receber 403.
+
+### Adicionado
+
+- `client.support.*` envia **automaticamente** `X-Neetru-End-User-Token` com o **id_token** do usuário logado (`client.auth.getIdToken()`, lido a cada chamada — nunca o access token). Login feito depois de criar o client já vale; `getIdToken` que lança é tratado como "sem usuário".
+- **Renovação automática 1x:** num `401 invalid_end_user_token`, o SDK chama `client.auth.refreshTokens()` (refresh_token rotation) UMA vez e repete a chamada com o id_token novo; se não renovar (ou falhar de novo), lança `NeetruAuthRequiredError`. Numa operação obrigatória sem id_token (expirado localmente), também tenta o refresh 1x antes de desistir.
+- `AuthNamespace.refreshTokens?(): Promise<boolean>` — agora exposto pelo auth OIDC web (já existia internamente e no `@neetru/sdk/mobile`). Opcional no tipo: mocks/implementações próprias podem omitir.
+- **`NeetruAuthRequiredError`** (exportado de `@neetru/sdk`, subclasse de `NeetruError`, `code: 'auth_required'`), com `reason`:
+  - `no_signed_in_user` — `listMyTickets`, `contestTicket`, `submitSatisfaction`, `recordSatisfactionAttempt` e `markResolvedSeen` **sem usuário logado** falham ANTES do request, com mensagem clara (em vez do 403 opaco do Core);
+  - `end_user_token_required` — o Core respondeu 403 exigindo a identidade;
+  - `invalid_end_user_token` — o Core recusou o token e o refresh não resolveu → refazer login.
+- `403 end_user_token_product_mismatch` → `NeetruError` com `code: 'forbidden'` e `reason: 'end_user_token_product_mismatch'`, mensagem explicando que o login é de outro produto (config: `oidcClientId` × `apiKey`/`productId`). Não tenta refresh.
+- `SupportTicket.screenshotAttached?: boolean` (da listagem do Core; fallback: há `screenshotUrl`). `listMyTickets({ limit })` — inteiro 1-50 (omitido = 20 do Core); fora disso `validation_failed` sem request.
+- Novos códigos em `NeetruErrorCode`: `auth_required` e `gone`.
+- **HTTP 410** (`statusToCode(410) === 'gone'`): mensagem útil ("endpoint removido do Core") + o substituto do header `X-Neetru-Replacement` — cobre o legado `/api/v1/sdk/entitlements/check`, que o Core agora responde 410. (O `client.entitlements.check()` do SDK já lançava localmente desde a 3.4.x; o 410 protege quem ainda chama a rota direto.)
+
+### Mudança de comportamento (ler antes de atualizar)
+
+- **Mutações de ticket exigem usuário logado no SDK.** `contestTicket`/`submitSatisfaction`/`recordSatisfactionAttempt`/`markResolvedSeen` sem id_token lançam `NeetruAuthRequiredError` sem chamar o Core. Quem chamava isso **server-side só com a chave do produto** (sem usuário final) passa a receber o erro.
+- **Tickets legados sem dono** (criados antes do corte de 2026-09-29, sem `endUserId`): o Core mantém a regra antiga pra eles (posse pela chave do produto) e ignora o header nesse caso — então **continuam mutáveis pelo SDK desde que haja QUALQUER usuário logado** no app (o id_token vai, o Core aplica a regra legada). Não há caminho no SDK pra mutá-los sem usuário logado.
+- **Tickets criados a partir de 2026-09-29 sem header** (sem dono) não aceitam contest/satisfaction no Core — pra o usuário acompanhar o ticket, crie-o com o usuário logado.
+- `listMyTickets()` passa a devolver `screenshotUrl: null` (a lista do Core não traz mais o anexo); use `screenshotAttached`.
+
+### Mantido (compatível)
+
+- `createTicket` **sem** usuário logado continua funcionando, sem o header e sem tentar refresh (fluxo de report anônimo / server-side).
+- Outros 403 (`forbidden_product`, `forbidden` de ticket de outro usuário) seguem como `NeetruError` comum.
+- `MockSupport` (env `dev`) mantém o comportamento (ganha `screenshotAttached`).
+
+### Também entra nesta versão (mesclado no #34, ainda não publicado)
+
+- Batch de quick-wins do Labs: bundle publicado minificado e sem sourcemap (~6x menor), `@deprecated` do namespace `entitlements` no index, e opt-in `deadlineMs` em `httpRequest` (orçamento total de tempo com retries).
+- **Corrigido junto (regressão do #34, nunca publicada):** o `minify: true` apagava os magic comments `/* webpackIgnore: true */` dos `import("pg")`/`import("drizzle-orm/node-postgres")` dinâmicos → o webpack/Next do produto voltaria a tentar empacotar `pg` no bundle do browser (bug_0f836014; o teste `no-node-deps-in-browser-bundle` falhava 4/13 com `dist/` presente, inclusive na `main`). Agora minifica identificadores+sintaxe sem apagar whitespace/comentários: dist ~2,1 MB (vs 1,5 MB full; 8,5 MB antes do #34).
+
 ## [3.6.0] - 2026-09-24 — **feat(mobile): `@neetru/sdk/mobile` — namespace de auth OIDC+PKCE para React Native/Expo**
 
 Release **minor** (capacidade nova, aditiva — subpath novo, nenhuma API existente muda).

package/README.md

@@ -50,6 +50,71 @@ if (!check.allowed && check.behavior === 'readonly') {
 }
 ```
 
+> **A credencial `nrt_` é SÓ DE SERVIDOR (3.8.0).** O código acima roda no
+> backend do produto. Site e app nunca carregam a chave: eles chamam a API do
+> próprio produto com o token do usuário, e o backend usa o SDK. Ver
+> [Apps e site sem chave no cliente](#apps-e-site-sem-chave-no-cliente-380).
+
+## Apps e site sem chave no cliente (3.8.0)
+
+```
+app/site ──Authorization: Bearer <access_token>──▶ API do produto ──SDK + nrt_──▶ Core
+```
+
+**Backend do produto** (aceita Bearer do app além do cookie do site):
+
+```ts
+import { authenticateProductRequest, accessTokenErrorToHttp, getServerNeetruClient } from '@neetru/sdk';
+
+export async function GET(req: Request) {
+  try {
+    const auth = await authenticateProductRequest(req, {
+      // client_id OIDC do MESMO produto: web + iOS + Android
+      audience: [process.env.NEETRU_OIDC_CLIENT_ID_WEB!, process.env.NEETRU_OIDC_CLIENT_ID_IOS!,
+                 process.env.NEETRU_OIDC_CLIENT_ID_ANDROID!],
+      requiredScopes: ['openid'],
+      cookie: { name: 'session', verify: verifySessionCookie }, // o caminho que o site já tem
+    });
+    if (!auth) return Response.json({ error: 'unauthorized' }, { status: 401 });
+    const neetru = getServerNeetruClient({ apiKey: process.env.NEETRU_API_KEY }); // servidor
+    // ... regra de negócio em nome de auth.token.sub
+  } catch (err) {
+    const r = accessTokenErrorToHttp(err);
+    return Response.json(r.body, { status: r.status, headers: r.headers });
+  }
+}
+```
+
+`verifyAccessToken(token, { audience, requiredScopes })` valida assinatura RS256
+(JWKS `auth.neetru.com/api/v1/oauth/.well-known/jwks`, cacheado), `iss`, `exp`,
+`aud ∈ audience` e exige formato de access token (`jti` + `scope` + `client_id`)
+— id_token não serve de credencial de API. Validação local: token revogado vale
+até expirar (15 min no Core); o logout do app revoga o refresh_token.
+
+**App React Native/Expo** (`@neetru/sdk/mobile` — recusa `apiKey` sempre):
+
+```ts
+import { createMobileAuthNamespace } from '@neetru/sdk/mobile';
+
+const auth = createMobileAuthNamespace({
+  oidcClientId: 'oidc-pdv-ios',                 // client OIDC PÚBLICO do app
+  productApiUrl: 'https://pdv.neetru.com/api/v1',
+  storage: secureStoreAdapter,                  // expo-secure-store
+  openAuthUrl: (url) => WebBrowser.openAuthSessionAsync(url, redirectUri).then(() => {}),
+});
+await auth.signIn({ redirectUri });
+// ... deep link de volta:
+await auth.completeSignIn(callbackUrl);
+const res = await auth.authFetch('/vendas');   // Bearer access_token, renova 1x num 401
+const me = await auth.getUserInfo();           // /userinfo do Core
+await auth.signOut();                          // limpa local + revoga refresh/access no Core
+```
+
+`client.db` em React Native lança erro claro (dados de negócio vão pela API do
+produto). Chave detectada em navegador/RN pelo `createNeetruClient`: aviso único
+nesta minor; `strictServerOnlyKey: true` bloqueia já; **a próxima MAJOR bloqueia
+sempre**.
+
 ## Princípios
 
 - **Vendor-neutral** — superfície pública NÃO vaza Firebase/Stripe/etc. Backend Neetru pode mudar no futuro sem reescrever produto.
@@ -57,7 +122,7 @@ if (!check.allowed && check.behavior === 'readonly') {
 - **Universal** — browser, Node ≥20, Edge runtimes (Vercel Edge, Cloudflare Workers). Usa `fetch` global + WebCrypto.
 - **Fail-closed segurança** — `baseUrl` allowlist (`*.neetru.com` + localhost) rejeita phishing/MITM. Bypass: `NEETRU_ALLOW_INSECURE_BASEURL=1`.
 - **Idempotency-Key automático** — mutations (`usage.report`, `webhooks.test`, `notifications.send`, `support.createTicket`) injetam UUID v4 header. `retries: 0` default em POSTs para defesa em camada.
-- **Tipado** — erros via `NeetruError` com `.code`, `.status`, `.requestId`.
+- **Tipado** — erros via `NeetruError` com `.code`, `.status`, `.requestId`, `.correlationId` (3.8.0: `x-correlation-id` gerado em toda requisição).
 - **Dev mode** — `NEETRU_ENV=dev` ativa mocks automáticos — zero rede em testes locais.
 
 ## Namespaces 3.0