@neetru/sdk 3.1.1 → 3.1.4

package/README.md

@@ -77,6 +77,42 @@ if (!check.allowed && check.behavior === 'readonly') {
 
 ## Exemplos por namespace
 
+### Login OIDC — Authorization Code + PKCE (3.1.3)
+
+O SDK implementa o lado-**browser** do fluxo; a troca `code → tokens` acontece no
+**backend do produto** (confidential client com `client_id` + `client_secret`
+registrados em `oidc_clients/{id}` no Core — modelo Firebase/Facebook).
+
+```ts
+// 1) Browser — iniciar login (gera state CSRF + nonce + PKCE S256 e redireciona)
+const neetru = createNeetruClient({ oidcClientId: 'meu-app-oidc' });
+await neetru.auth.signIn({
+  redirectUri: 'https://app.exemplo.com/auth/callback',
+  postLoginRedirect: '/dashboard',
+});
+
+// 2) Browser — na página de callback: valida state e devolve o material do exchange
+const cb = await neetru.auth.handleRedirectCallback();
+if (cb) {
+  // mande pro SEU backend (nunca exponha client_secret no browser)
+  await fetch('/api/auth/exchange', { method: 'POST', body: JSON.stringify(cb) });
+  location.assign(cb.postLoginRedirect ?? '/');
+}
+
+// 3) Backend do produto — troca o code por tokens no IdP Neetru
+//    POST https://auth.neetru.com/api/v1/oauth/token  (x-www-form-urlencoded)
+//    Authorization: Basic base64(clientId:clientSecret)
+//    grant_type=authorization_code & code & redirect_uri & code_verifier
+//    → valide claim `nonce` do id_token === cb.nonce; sete cookie httpOnly.
+
+// 4) Server-side — valide o id_token em qualquer request (JWKS cacheado)
+const user = await neetru.auth.verifyToken(idTokenDoCookie);
+```
+
+`auth.getIdToken()` expõe o JWT cru se o app optar por armazená-lo em
+`localStorage['neetru_id_token']` (alternativa SPA; o padrão recomendado é o
+cookie httpOnly do backend).
+
 ### Webhooks outbound (v1.2)
 
 ```ts
@@ -95,17 +131,20 @@ Eventos recebidos no seu endpoint chegam com:
 - `X-Neetru-Signature: sha256=<hmac>` (se `secret` registrado)
 - `X-Neetru-Timestamp: <ms>` (replay protection — rejeitar > 5min skew)
 
-#### Verificar assinatura no consumer (3.0 — async + Universal)
+#### Verificar assinatura no consumer (3.1.3 — async + Universal)
+
+O HMAC do Core cobre `` `${timestamp}.${rawBody}` `` (o timestamp é o valor de
+`X-Neetru-Timestamp`). Prefira `verifyWebhookRequest`, que lê os headers,
+valida o skew (5 min) e o HMAC de uma vez:
 
 ```ts
-import { verifyWebhookSignature } from '@neetru/sdk';
+import { verifyWebhookRequest } from '@neetru/sdk';
 
 // Next.js Route Handler (Edge OU Node runtime — funciona em ambos)
 export async function POST(req: Request) {
   const raw = await req.text();
-  const sig = req.headers.get('X-Neetru-Signature');
-  const ok = await verifyWebhookSignature(raw, sig, process.env.NEETRU_WEBHOOK_SECRET!);
-  if (!ok) return new Response('unauthorized', { status: 401 });
+  const result = await verifyWebhookRequest(raw, req.headers, process.env.NEETRU_WEBHOOK_SECRET!);
+  if (!result.ok) return new Response('unauthorized', { status: 401 });
 
   const event = JSON.parse(raw);
   // ... handle event
@@ -113,7 +152,19 @@ export async function POST(req: Request) {
 }
 ```
 
+Verificação manual com `verifyWebhookSignature` exige passar o timestamp:
+
+```ts
+const ok = await verifyWebhookSignature(
+  raw,
+  req.headers.get('X-Neetru-Signature'),
+  process.env.NEETRU_WEBHOOK_SECRET!,
+  req.headers.get('X-Neetru-Timestamp') ?? undefined,
+);
+```
+
 > **Breaking 3.0**: era `boolean` sync usando `node:crypto`. Agora `Promise<boolean>` via WebCrypto.subtle — funciona em Cloudflare Workers, Vercel Edge, browsers e Node ≥20.
+> **Fix 3.1.3**: até 3.1.2 o helper verificava o HMAC só sobre o body — entregas reais do Core (assinadas com `timestamp.body`) sempre falhavam. Passe o `timestamp` (ou use `verifyWebhookRequest`).
 
 ### Notifications produto → user (v1.2)
 

package/dist/auth.cjs

@@ -1095,7 +1095,8 @@ function createTelemetryNamespace(config) {
         message: input.message
       };
       if (input.metadata) body.metadata = input.metadata;
-      if (input.productSlug) body.productSlug = input.productSlug;
+      const productSlug = input.productSlug ?? config.productId;
+      if (productSlug) body.productSlug = productSlug;
       let cid = input.correlationId;
       if (!cid) {
         try {
@@ -4603,13 +4604,69 @@ function createRestSyncTransport(config) {
       if (!config) {
         return { docs: [], newWatermark: Date.now(), resyncRequired: false };
       }
-      return { docs: [], newWatermark: Date.now(), resyncRequired: false };
+      return { docs: [], newWatermark: Date.now(), resyncRequired: true };
     },
-    async fullResync(_collections) {
+    async fullResync(collections) {
       if (!config) {
         return { docs: [], newWatermark: Date.now() };
       }
-      return { docs: [], newWatermark: Date.now() };
+      const { httpRequest: httpRequest2 } = await Promise.resolve().then(() => (init_http(), http_exports));
+      const tenantScopeId = config.tenantId ?? config.productId;
+      const tenantHeaders = tenantScopeId ? { "x-neetru-tenant": tenantScopeId } : void 0;
+      const now = Date.now();
+      const docs = [];
+      for (const collection of collections) {
+        let raw;
+        try {
+          raw = await httpRequest2(config, {
+            method: "GET",
+            path: DATASTORE_COLLECTION_ENDPOINT(collection),
+            requireAuth: true,
+            retries: 2,
+            headers: tenantHeaders,
+            // Teto do Core é 200. Coleções > 200 docs truncam silenciosamente
+            // aqui (paginação cursor é tarefa Core separada) — a detecção de
+            // deleção-por-ausência do SyncEngine NÃO deve rodar sobre truncamento,
+            // então mantemos o limite no máximo do servidor por ora.
+            query: { limit: 200 }
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new NeetruDbError(
+            "db_unavailable",
+            `[RestSyncTransport] fullResync falhou na cole\xE7\xE3o "${collection}": ${msg}`
+          );
+        }
+        const resp = raw;
+        const items = Array.isArray(resp?.items) ? resp.items : [];
+        for (const item of items) {
+          if (!item || typeof item !== "object") continue;
+          const record = item;
+          const id = typeof record["id"] === "string" ? record["id"] : null;
+          if (!id) continue;
+          const { id: _inlinedId, ...data } = record;
+          let serverTimestamp = now;
+          const updatedAt = data["_updatedAt"];
+          if (typeof updatedAt === "number") {
+            serverTimestamp = updatedAt;
+          } else if (updatedAt !== null && typeof updatedAt === "object" && typeof updatedAt["_seconds"] === "number") {
+            serverTimestamp = updatedAt["_seconds"] * 1e3;
+          } else if (typeof updatedAt === "string") {
+            const parsed = Date.parse(updatedAt);
+            if (!Number.isNaN(parsed)) serverTimestamp = parsed;
+          }
+          const serverVersion = `rest_${id}_${serverTimestamp}`;
+          docs.push({
+            collection,
+            id,
+            data,
+            serverVersion,
+            serverTimestamp,
+            deleted: false
+          });
+        }
+      }
+      return { docs, newWatermark: now };
     }
   };
 }
@@ -4849,6 +4906,15 @@ function createLazyCollectionRef(name, getDocsPromise) {
 // src/checkout.ts
 init_errors();
 init_http();
+function checkoutAuth(accessToken, method) {
+  if (!accessToken || typeof accessToken !== "string") {
+    throw new NeetruError(
+      "validation_failed",
+      `checkout.${method} requer o access_token OIDC do usu\xE1rio final (passe \`accessToken\`). A chave de API do SDK (nrt_*) N\xC3O \xE9 aceita pelo endpoint de checkout \u2014 ele autentica a identidade do cliente que est\xE1 assinando (Bearer access_token OIDC ou cookie de sess\xE3o).`
+    );
+  }
+  return { requireAuth: false, headers: { authorization: `Bearer ${accessToken}` } };
+}
 function parseStartResponse(raw) {
   if (!raw || typeof raw !== "object") {
     throw new NeetruError("invalid_response", "checkout.start response is not an object");
@@ -4926,11 +4992,13 @@ function createHttpCheckoutNamespace(config) {
       };
       if (input.tenantType) body.targetTenantType = input.tenantType;
       if (input.tenantId) body.targetTenantId = input.tenantId;
+      const { requireAuth, headers } = checkoutAuth(input.accessToken, "start");
       const raw = await httpRequest(config, {
         method: "POST",
         path: "/api/v1/checkout/intents",
         body,
-        requireAuth: true,
+        requireAuth,
+        headers,
         idempotencyKey: true
       });
       const result = parseStartResponse(raw);
@@ -4940,25 +5008,29 @@ function createHttpCheckoutNamespace(config) {
       }
       return result;
     },
-    async get(intentId) {
+    async get(intentId, opts) {
       if (!intentId || typeof intentId !== "string") {
         throw new NeetruError("validation_failed", "checkout.get: intentId is required");
       }
+      const { requireAuth, headers } = checkoutAuth(opts?.accessToken, "get");
       const raw = await httpRequest(config, {
         method: "GET",
         path: `/api/v1/checkout/intents/${encodeURIComponent(intentId)}`,
-        requireAuth: true
+        requireAuth,
+        headers
       });
       return parseGetResponse(raw);
     },
-    async cancel(intentId) {
+    async cancel(intentId, opts) {
       if (!intentId || typeof intentId !== "string") {
         throw new NeetruError("validation_failed", "checkout.cancel: intentId is required");
       }
+      const { requireAuth, headers } = checkoutAuth(opts?.accessToken, "cancel");
       const raw = await httpRequest(config, {
         method: "DELETE",
         path: `/api/v1/checkout/intents/${encodeURIComponent(intentId)}`,
-        requireAuth: true
+        requireAuth,
+        headers
       });
       return {
         ok: true,
@@ -5002,14 +5074,14 @@ var MockCheckout = class {
       requiresKyc: false
     };
   }
-  async get(intentId) {
+  async get(intentId, _opts) {
     const found = this.intents.get(intentId);
     if (!found) {
       throw new NeetruError("not_found", `Mock intent ${intentId} not found`);
     }
     return { ...found };
   }
-  async cancel(intentId) {
+  async cancel(intentId, _opts) {
     const found = this.intents.get(intentId);
     if (!found) {
       throw new NeetruError("not_found", `Mock intent ${intentId} not found`);
@@ -5464,6 +5536,31 @@ var MockAuth = class {
     if (this._user) return this._user;
     throw Object.assign(new Error("Nenhum user mock dispon\xEDvel"), { code: "token_invalid_signature" });
   }
+  /**
+   * Mock de `handleRedirectCallback` (Bug 2 / 3.1.3) — não há redirect real no
+   * mock, então retorna `null` por default. Use `__setPendingCallback(result)`
+   * em testes pra simular um retorno do IdP.
+   */
+  async handleRedirectCallback(_currentUrl) {
+    return this._pendingCallback;
+  }
+  /**
+   * Mock de `getIdToken` (Bug 2 / 3.1.3). Retorna `null` por default; use
+   * `__setIdToken(token)` pra injetar um token cru em testes.
+   */
+  getIdToken() {
+    return this._idToken;
+  }
+  _pendingCallback = null;
+  _idToken = null;
+  /** Test helper — simula o material devolvido por um callback OIDC. */
+  __setPendingCallback(result) {
+    this._pendingCallback = result;
+  }
+  /** Test helper — injeta o id_token cru retornado por `getIdToken`. */
+  __setIdToken(token) {
+    this._idToken = token;
+  }
   _verifyTokenOverride = null;
   /**
    * Injeta override pra `verifyToken` em testes — permite simular expiração,
@@ -5682,6 +5779,49 @@ function _jwtPayloadToUser(payload) {
     ...payload
   };
 }
+var OIDC_TX_KEY = "neetru_oauth_tx";
+function resolveIdpOrigin(baseUrl) {
+  const overrideAuthUrl = typeof globalThis.NEETRU_AUTH_URL === "string" ? globalThis.NEETRU_AUTH_URL : null;
+  return overrideAuthUrl ?? baseUrl.replace(/^https?:\/\/api\./, "https://auth.");
+}
+function getWebCrypto() {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function" || !c.subtle) {
+    throw new NeetruError(
+      "runtime_unsupported",
+      "auth.signIn requer WebCrypto (crypto.subtle) \u2014 indispon\xEDvel neste runtime. Use HTTPS (ou http://localhost) num browser moderno."
+    );
+  }
+  return c;
+}
+function base64UrlFromBytes(bytes) {
+  let str = "";
+  for (const b of bytes) str += String.fromCharCode(b);
+  const b64 = typeof btoa === "function" ? btoa(str) : Buffer.from(str, "binary").toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function randomUrlSafe(crypto2, byteLen) {
+  const bytes = new Uint8Array(byteLen);
+  crypto2.getRandomValues(bytes);
+  return base64UrlFromBytes(bytes);
+}
+async function pkceChallengeS256(crypto2, verifier) {
+  const data = new TextEncoder().encode(verifier);
+  const digest = await crypto2.subtle.digest("SHA-256", data);
+  return base64UrlFromBytes(new Uint8Array(digest));
+}
+function cleanCallbackUrl(parsed) {
+  try {
+    const history = globalThis.history;
+    if (!history || typeof history.replaceState !== "function") return;
+    const clean = new URL(parsed.toString());
+    for (const p of ["code", "state", "error", "error_description", "iss", "session_state"]) {
+      clean.searchParams.delete(p);
+    }
+    history.replaceState(history.state ?? null, "", clean.pathname + clean.search + clean.hash);
+  } catch {
+  }
+}
 function createOidcAuthNamespace(config) {
   const STORAGE_KEY = "neetru_id_token";
   const listeners = /* @__PURE__ */ new Set();
@@ -5694,6 +5834,13 @@ function createOidcAuthNamespace(config) {
       return null;
     }
   }
+  function getSessionStorage() {
+    try {
+      return typeof globalThis.sessionStorage !== "undefined" ? globalThis.sessionStorage : null;
+    } catch {
+      return null;
+    }
+  }
   function decodeJwtPayload(token) {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
@@ -5777,20 +5924,48 @@ function createOidcAuthNamespace(config) {
   return {
     async signIn(options) {
       if (typeof globalThis.location !== "undefined" && typeof globalThis.location.assign === "function") {
+        const crypto2 = getWebCrypto();
         const redirectUri = options?.redirectUri ?? globalThis.location.origin;
         const scope = options?.scope ?? "openid profile email";
-        const state = options?.postLoginRedirect ?? globalThis.location.href;
-        const overrideAuthUrl = typeof globalThis.NEETRU_AUTH_URL === "string" ? globalThis.NEETRU_AUTH_URL : null;
-        const idpOrigin = overrideAuthUrl ?? config.baseUrl.replace(/^https?:\/\/api\./, "https://auth.");
+        let clientId = config.oidcClientId;
+        if (!clientId && config.apiKey) {
+          clientId = parseApiKey(config.apiKey).keyId;
+        }
+        if (!clientId) {
+          throw new NeetruError(
+            "invalid_config",
+            "auth.signIn requer `oidcClientId` (ou `apiKey`) configurado para montar o client_id."
+          );
+        }
+        const state = randomUrlSafe(crypto2, 16);
+        const nonce = randomUrlSafe(crypto2, 16);
+        const codeVerifier = randomUrlSafe(crypto2, 32);
+        const codeChallenge = await pkceChallengeS256(crypto2, codeVerifier);
+        const session = getSessionStorage();
+        if (!session) {
+          throw new NeetruError(
+            "runtime_unsupported",
+            "auth.signIn requer sessionStorage para guardar a transa\xE7\xE3o PKCE entre o redirect e o callback."
+          );
+        }
+        const tx = {
+          state,
+          nonce,
+          codeVerifier,
+          redirectUri,
+          postLoginRedirect: options?.postLoginRedirect
+        };
+        session.setItem(OIDC_TX_KEY, JSON.stringify(tx));
+        const idpOrigin = resolveIdpOrigin(config.baseUrl);
         const url = new URL("/api/v1/oauth/authorize", idpOrigin);
         url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", clientId);
         url.searchParams.set("redirect_uri", redirectUri);
         url.searchParams.set("scope", scope);
         url.searchParams.set("state", state);
-        if (config.apiKey) {
-          const { keyId } = parseApiKey(config.apiKey);
-          url.searchParams.set("client_id", keyId);
-        }
+        url.searchParams.set("nonce", nonce);
+        url.searchParams.set("code_challenge", codeChallenge);
+        url.searchParams.set("code_challenge_method", "S256");
         globalThis.location.assign(url.toString());
         return;
       }
@@ -5799,6 +5974,67 @@ function createOidcAuthNamespace(config) {
         "auth.signIn requires a browser context or mocks. Use NEETRU_ENV=dev or pass mocks.auth."
       );
     },
+    async handleRedirectCallback(currentUrl) {
+      const href = currentUrl ?? (typeof globalThis.location !== "undefined" ? globalThis.location.href : void 0);
+      if (!href) return null;
+      let parsed;
+      try {
+        parsed = new URL(href);
+      } catch {
+        return null;
+      }
+      const params = parsed.searchParams;
+      const idpError = params.get("error");
+      if (idpError) {
+        const desc = params.get("error_description") ?? idpError;
+        getSessionStorage()?.removeItem(OIDC_TX_KEY);
+        cleanCallbackUrl(parsed);
+        throw new NeetruError(idpError, `OIDC authorize falhou: ${desc}`);
+      }
+      const code = params.get("code");
+      if (!code) return null;
+      const returnedState = params.get("state");
+      const session = getSessionStorage();
+      const txRaw = session?.getItem(OIDC_TX_KEY) ?? null;
+      let tx = null;
+      if (txRaw) {
+        try {
+          tx = JSON.parse(txRaw);
+        } catch {
+          tx = null;
+        }
+      }
+      if (!tx) {
+        throw new NeetruError(
+          "oidc_state_mismatch",
+          "Callback OIDC sem transa\xE7\xE3o pendente \u2014 `signIn` n\xE3o foi iniciado nesta sess\xE3o (ou j\xE1 consumido)."
+        );
+      }
+      if (!returnedState || returnedState !== tx.state) {
+        session?.removeItem(OIDC_TX_KEY);
+        cleanCallbackUrl(parsed);
+        throw new NeetruError(
+          "oidc_state_mismatch",
+          "state do callback OIDC n\xE3o confere com o da transa\xE7\xE3o (poss\xEDvel CSRF)."
+        );
+      }
+      session?.removeItem(OIDC_TX_KEY);
+      cleanCallbackUrl(parsed);
+      return {
+        code,
+        codeVerifier: tx.codeVerifier,
+        redirectUri: tx.redirectUri,
+        nonce: tx.nonce,
+        state: tx.state,
+        postLoginRedirect: tx.postLoginRedirect
+      };
+    },
+    getIdToken() {
+      const storage = getStorage();
+      const token = storage?.getItem(STORAGE_KEY) ?? null;
+      if (!token) return null;
+      return tokenToUser(token) ? token : null;
+    },
     async signOut() {
       const storage = getStorage();
       const storedToken = storage?.getItem(STORAGE_KEY) ?? null;
@@ -5905,6 +6141,7 @@ function createNeetruClient(config = {}) {
   const env = resolveEnv(config.env);
   const resolved = Object.freeze({
     apiKey,
+    oidcClientId: config.oidcClientId,
     baseUrl,
     fetch: fetchImpl.bind(globalThis),
     env,