@neetru/sdk 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,13 +5,106 @@ 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).
 
+## [2.2.0] - 2026-05-25 — **auth.verifyToken — validação server-side de id_token via JWKS [feature]**
+
+Fix do bug `bug_a7ef1702680044e3994b74bdccecb2ab` — resolve P0-1 audit security pdv-agiliza.
+
+### Added
+
+- **`client.auth.verifyToken(token, options?): Promise<NeetruUser>`** — valida um id_token JWT
+  emitido por `auth.neetru.com` server-side, sem round-trip de rede por request. Usa JWKS local
+  cacheado (default TTL 1h, configurável via `options.jwksCacheTtlMs`).
+
+  Erros tipados novos (`NeetruErrorCode`):
+  - `token_expired` — `exp` no passado
+  - `token_invalid_signature` — assinatura não verificada pela JWKS
+  - `token_invalid_audience` — `aud` não bate com o `clientId` extraído do `apiKey`
+  - `token_invalid_issuer` — `iss` não é `https://auth.neetru.com`
+
+  Dependência nova: `jose` (Vercel/Cloudflare-friendly, sem Node nativo).
+
+- **`MockAuth.verifyToken(token)`** — decodifica JWT sem verificar assinatura (útil em testes).
+  Aceita `__mockVerifyToken(fn)` pra injetar falhas determinísticas.
+
+- **`VerifyTokenOptions`** — exportado em `index.ts` pra consumers tiparem as options.
+
+### Usage
+
+```ts
+// Next.js route handler
+import { createNeetruClient } from '@neetru/sdk';
+const client = createNeetruClient({ apiKey: 'nrt_a1b2c3_...', env: 'prod' });
+
+export async function POST(req: Request) {
+  const token = req.cookies.get('neetru-session')?.value ?? '';
+  try {
+    const user = await client.auth.verifyToken(token);
+    // user.uid, user.email, user.isStaff, user.tenantId disponíveis
+  } catch (err) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+}
+```
+
 ## [Unreleased]
 
-### Planned (post-2.0)
+### Planned (post-2.2)
 - size-limit budget no CI (<12KB gz core com db namespace).
 - CDN distribution (`cdn.neetru.com/sdk/v2/`).
 - Endpoint batch `/api/v1/sdk/telemetry/batch` (substitui drenagem N×1 do `track()` por 1 request).
 
+## [2.1.1] - 2026-05-25 — **DbDocRef identity + DbBatchOp discriminated union [patch]**
+
+Dois fixes LOW reportados por pdv-agiliza (tickets `bug_97b3f0488d1c49cf8c5f94e5d544289b` + `bug_6aab9adc182640218652a65cdcb71b63`).
+Sem breaking changes — todos os usos de `doc()` existentes continuam funcionando.
+
+### Fixed
+
+- **`DbDocRef.id / .path / .collection`** (fix #13, ticket `bug_97b3f0488d1c49cf8c5f94e5d544289b`):
+  `DbDocRef` agora expõe três propriedades readonly de identidade:
+  - `id: string` — ID do documento dentro da coleção.
+  - `path: string` — Caminho completo `"colecao/docId"`.
+  - `collection: string` — Nome da coleção parent.
+  Análogo ao `DocumentReference.id/.path` do Firestore Web SDK. Elimina a necessidade
+  de adaptadores externos que reattachavam `collection + id` manualmente.
+  Implementado em `DbCollectionRefImpl.doc()` (offline), `createLazyCollectionRef.doc()`
+  (client-db) e `MockDb.doc()` (mocks).
+
+- **`DbBatchOp` discriminated union** (fix #14, ticket `bug_6aab9adc182640218652a65cdcb71b63`):
+  `DbBatchOp` foi convertido de `interface` opaca (campo `op: 'add'|'set'|'update'|'remove'`
+  com `id?`/`data?` opcionais) para **discriminated union** pelo campo `kind`:
+  ```ts
+  type DbBatchOp<T = Record<string, unknown>> =
+    | { kind: 'add';    data: Omit<T, 'id'> }
+    | { kind: 'set';    id: string; data: Omit<T, 'id'> }
+    | { kind: 'update'; id: string; data: Partial<Omit<T, 'id'>> }
+    | { kind: 'remove'; id: string };
+  ```
+  O `.d.ts` público agora expõe claramente quais campos são obrigatórios por variante.
+  O campo `collection` foi removido da operação (sempre opera na coleção do `DbCollectionRef`).
+
+### Migration (2.0.0 → 2.1.1)
+
+Callers que usavam `batch()` devem trocar `op` por `kind` e remover o campo `collection`:
+
+```ts
+// antes (2.0.0)
+col.batch([
+  { op: 'add',    collection: 'orders', data: { total: 10 } },
+  { op: 'set',    collection: 'orders', id: 'x', data: { total: 20 } },
+  { op: 'update', collection: 'orders', id: 'y', data: { total: 30 } },
+  { op: 'remove', collection: 'orders', id: 'z' },
+]);
+
+// depois (2.1.1)
+col.batch([
+  { kind: 'add',    data: { total: 10 } },
+  { kind: 'set',    id: 'x', data: { total: 20 } },
+  { kind: 'update', id: 'y', data: { total: 30 } },
+  { kind: 'remove', id: 'z' },
+]);
+```
+
 ## [2.0.0] - 2026-05-22 — **client.db NeetruDb (Documentos engine-aware + SQL) [M2]**
 
 Major bump — breaking changes no namespace `db`. Liga todos os building blocks M2 na superfície pública.

package/dist/auth.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var jose = require('jose');
 var idb = require('idb');
 
 var __defProp = Object.defineProperty;
@@ -2956,10 +2957,9 @@ var DbCollectionRefImpl = class {
     const batchId = `batch-${Date.now()}-${Math.random().toString(36).slice(2)}`;
     const busChanges = [];
     for (const op of ops) {
-      const id = op.id ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-      const data = op.data ?? {};
-      const collection = op.collection;
-      if (op.op === "add") {
+      const collection = this._collection;
+      if (op.kind === "add") {
+        const data = op.data;
         const mutation = await this._queue.enqueue({
           collection,
           op: "add",
@@ -2983,7 +2983,9 @@ var DbCollectionRefImpl = class {
           }
         });
         busChanges.push({ type: "added", collection, doc: { id: docId, data } });
-      } else if (op.op === "set") {
+      } else if (op.kind === "set") {
+        const id = op.id;
+        const data = op.data;
         const existing = await this._store.getDoc(collection, id);
         const mutation = await this._queue.enqueue({
           collection,
@@ -3012,7 +3014,9 @@ var DbCollectionRefImpl = class {
           collection,
           doc: { id, data }
         });
-      } else if (op.op === "update") {
+      } else if (op.kind === "update") {
+        const id = op.id;
+        const data = op.data;
         const existing = await this._store.getDoc(collection, id);
         const merged = { ...existing?.data ?? {}, ...data };
         const mutation = await this._queue.enqueue({
@@ -3041,7 +3045,8 @@ var DbCollectionRefImpl = class {
           }
         });
         busChanges.push({ type: "modified", collection, doc: { id, data: merged } });
-      } else if (op.op === "remove") {
+      } else if (op.kind === "remove") {
+        const id = op.id;
         const existing = await this._store.getDoc(collection, id);
         await this._queue.enqueue({
           collection,
@@ -3150,6 +3155,15 @@ var DbCollectionRefImpl = class {
     assertValidId(id);
     const self = this;
     return {
+      get id() {
+        return id;
+      },
+      get path() {
+        return `${self._collection}/${id}`;
+      },
+      get collection() {
+        return self._collection;
+      },
       async get() {
         return self._buildGetResult(id);
       },
@@ -4283,6 +4297,15 @@ function createLazyCollectionRef(name, getDocsPromise) {
     },
     doc(id) {
       return {
+        get id() {
+          return id;
+        },
+        get path() {
+          return `${name}/${id}`;
+        },
+        get collection() {
+          return name;
+        },
         async get() {
           return (await getRef()).doc(id).get();
         },
@@ -4823,6 +4846,61 @@ var MockAuth = class {
       this._listeners.delete(listener);
     };
   }
+  /**
+   * Mock de `verifyToken` — decodifica o JWT sem verificar assinatura (pra testes).
+   * Em dev, retorna o user atual do mock se já estiver logado. Aceita qualquer token
+   * não-vazio sem chamar rede.
+   *
+   * Para simular falhas em testes, use `MockAuth.__mockVerifyToken(fn)`.
+   */
+  async verifyToken(token) {
+    if (this._verifyTokenOverride) {
+      return this._verifyTokenOverride(token);
+    }
+    if (!token) {
+      throw Object.assign(new Error("Token inv\xE1lido"), { code: "token_invalid_signature" });
+    }
+    try {
+      const parts = token.split(".");
+      if (parts.length === 3) {
+        const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const pad = "=".repeat((4 - b64.length % 4) % 4);
+        const decoded = JSON.parse(
+          typeof atob === "function" ? atob(b64 + pad) : Buffer.from(b64 + pad, "base64").toString("utf-8")
+        );
+        if (typeof decoded.sub === "string") {
+          return {
+            uid: decoded.sub,
+            email: typeof decoded.email === "string" ? decoded.email : "",
+            emailVerified: typeof decoded.email_verified === "boolean" ? decoded.email_verified : void 0,
+            displayName: typeof decoded.name === "string" ? decoded.name : void 0,
+            photoURL: typeof decoded.picture === "string" ? decoded.picture : void 0,
+            isStaff: decoded.is_staff === true,
+            isCustomer: decoded.is_customer === true,
+            tenantId: typeof decoded.tenant_id === "string" ? decoded.tenant_id : void 0,
+            ...decoded
+          };
+        }
+      }
+    } catch {
+    }
+    if (this._user) return this._user;
+    throw Object.assign(new Error("Nenhum user mock dispon\xEDvel"), { code: "token_invalid_signature" });
+  }
+  _verifyTokenOverride = null;
+  /**
+   * Injeta override pra `verifyToken` em testes — permite simular expiração,
+   * assinatura inválida etc sem precisar de JWT real.
+   *
+   * @example
+   * ```ts
+   * const mock = new MockAuth(null);
+   * mock.__mockVerifyToken(async () => { throw new NeetruError('token_expired', '...'); });
+   * ```
+   */
+  __mockVerifyToken(fn) {
+    this._verifyTokenOverride = fn;
+  }
   /** Helper de tests — força um user state arbitrário. */
   __setUser(user) {
     this._user = user;
@@ -4996,6 +5074,37 @@ function resolveEnv(configEnv) {
   }
   return "prod";
 }
+var _jwksCache = /* @__PURE__ */ new Map();
+var DEFAULT_JWKS_TTL_MS = 60 * 60 * 1e3;
+function _getJwks(jwksUrl, cacheTtlMs) {
+  const now = Date.now();
+  const cached = _jwksCache.get(jwksUrl);
+  if (cached && now - cached.createdAt < cacheTtlMs) {
+    return cached.jwks;
+  }
+  const jwks = jose.createRemoteJWKSet(new URL(jwksUrl));
+  _jwksCache.set(jwksUrl, { jwks, createdAt: now });
+  return jwks;
+}
+function __resetJwksCacheForTests() {
+  _jwksCache.clear();
+}
+function _jwtPayloadToUser(payload) {
+  const sub = payload.sub ?? "";
+  const email = typeof payload.email === "string" ? payload.email : "";
+  return {
+    uid: sub,
+    email,
+    emailVerified: typeof payload.email_verified === "boolean" ? payload.email_verified : void 0,
+    displayName: typeof payload.name === "string" ? payload.name : void 0,
+    photoURL: typeof payload.picture === "string" ? payload.picture : void 0,
+    isStaff: payload.is_staff === true,
+    isCustomer: payload.is_customer === true,
+    tenantId: typeof payload.tenant_id === "string" ? payload.tenant_id : void 0,
+    // Spreads todos os claims originais (aud, iss, iat, exp, etc).
+    ...payload
+  };
+}
 function createOidcAuthNamespace(config) {
   const STORAGE_KEY = "neetru_id_token";
   const listeners = /* @__PURE__ */ new Set();
@@ -5103,6 +5212,45 @@ function createOidcAuthNamespace(config) {
       return () => {
         listeners.delete(listener);
       };
+    },
+    async verifyToken(token, options) {
+      if (!token || typeof token !== "string") {
+        throw new NeetruError("token_invalid_signature", "token must be a non-empty string");
+      }
+      const overrideAuthUrl = typeof globalThis.NEETRU_AUTH_URL === "string" ? globalThis.NEETRU_AUTH_URL : null;
+      const idpOrigin = overrideAuthUrl ?? config.baseUrl.replace(/^https?:\/\/api\./, "https://auth.");
+      const issuer = idpOrigin;
+      const jwksUrl = `${idpOrigin}/api/v1/oauth/.well-known/jwks.json`;
+      const cacheTtlMs = options?.jwksCacheTtlMs ?? DEFAULT_JWKS_TTL_MS;
+      const audience = config.apiKey ? config.apiKey.split("_")[1] ?? void 0 : void 0;
+      const jwks = _getJwks(jwksUrl, cacheTtlMs);
+      try {
+        const { payload } = await jose.jwtVerify(token, jwks, {
+          issuer,
+          ...audience ? { audience } : {},
+          algorithms: ["RS256"]
+        });
+        return _jwtPayloadToUser(payload);
+      } catch (err) {
+        const errName = err?.code ?? err?.name ?? "";
+        const errMsg = err?.message ?? String(err);
+        if (errName === "ERR_JWT_EXPIRED") {
+          throw new NeetruError("token_expired", `Token expired: ${errMsg}`);
+        }
+        if (errName === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED") {
+          throw new NeetruError("token_invalid_signature", `Token signature invalid: ${errMsg}`);
+        }
+        if (errName === "ERR_JWT_CLAIM_VALIDATION_FAILED") {
+          if (errMsg.includes('"aud"') || errMsg.includes("audience")) {
+            throw new NeetruError("token_invalid_audience", `Token audience mismatch: ${errMsg}`);
+          }
+          if (errMsg.includes('"iss"') || errMsg.includes("issuer")) {
+            throw new NeetruError("token_invalid_issuer", `Token issuer mismatch: ${errMsg}`);
+          }
+          throw new NeetruError("token_invalid_signature", `Token claim validation failed: ${errMsg}`);
+        }
+        throw new NeetruError("token_invalid_signature", `Token verification failed: ${errMsg}`);
+      }
     }
   };
 }
@@ -5149,6 +5297,7 @@ function createNeetruClient(config = {}) {
   return client;
 }
 
+exports.__resetJwksCacheForTests = __resetJwksCacheForTests;
 exports.createNeetruClient = createNeetruClient;
 //# sourceMappingURL=auth.cjs.map
 //# sourceMappingURL=auth.cjs.map