@useinvio/nfse-sdk 3.0.0 → 3.1.0

package/dist/xsdValidation.js

@@ -1,8 +1,7 @@
-import { execFileSync } from 'node:child_process';
-import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ParseOption, XmlBufferInputProvider, XmlDocument, XmlParseError, XmlValidateError, XsdValidator, xmlRegisterInputProvider, } from 'libxml2-wasm';
 /** The DPS XML violates the NFS-e v1.01 XSD. This is a fiscal payload problem. */
 export class DpsXsdValidationError extends Error {
     details;
@@ -13,87 +12,96 @@ export class DpsXsdValidationError extends Error {
     }
 }
 /**
- * `xmllint` could not be run to completion (missing binary, spawn failure, or
- * an unexpected crash without stderr). This is an infrastructure problem, not
- * proof that the XML is fiscally invalid, and callers must not treat it as a
+ * The embedded XSD engine (libxml2 compiled to WebAssembly) could not load the
+ * official schemas or crashed. This is an infrastructure problem, not proof
+ * that the XML is fiscally invalid, and callers must not treat it as a
  * permanent rejection.
  */
-export class XmllintUnavailableError extends Error {
+export class XsdEngineUnavailableError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
         this.cause = cause;
-        this.name = 'XmllintUnavailableError';
+        this.name = 'XsdEngineUnavailableError';
     }
 }
-function isExecFileSyncFailure(error) {
-    return typeof error === 'object' && error !== null;
+/**
+ * @deprecated Since 3.1.0 the SDK no longer runs the `xmllint` binary.
+ * Kept as an alias so existing `instanceof XmllintUnavailableError` checks still work.
+ */
+export const XmllintUnavailableError = XsdEngineUnavailableError;
+/** Virtual URL scheme for the bundled schemas, so includes never touch disk or network. */
+const SCHEMA_URL_PREFIX = 'nfse-sdk-xsd://v1.01/';
+const ENTRY_SCHEMA = 'DPS_v1.01.xsd';
+/** Never load DTDs, external entities or network resources while parsing. */
+export const SAFE_PARSE_OPTIONS = ParseOption.XML_PARSE_NONET | ParseOption.XML_PARSE_NO_XXE;
+let compiledValidator;
+function schemaSourceDir() {
+    return fileURLToPath(new URL('../schemas/nfse/v1.01/Schemas/1.01/', import.meta.url));
 }
-function toText(value) {
-    if (value === null || value === undefined)
-        return '';
-    return Buffer.isBuffer(value) ? value.toString('utf8') : String(value);
+function loadSchemaBuffers() {
+    const dir = schemaSourceDir();
+    const encoder = new TextEncoder();
+    const buffers = {};
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.xsd'))
+            continue;
+        let text = readFileSync(join(dir, file), 'utf8');
+        if (file === 'tiposSimples_v1.01.xsd') {
+            // libxml2 treats ^/$ literally in XSD regexes. The official package ships
+            // one JavaScript-style anchor, so normalize that expression in memory.
+            text = text.replace('<xs:pattern value="^0{0,4}\\d{1,5}$"/>', '<xs:pattern value="0{0,4}\\d{1,5}"/>');
+        }
+        buffers[`${SCHEMA_URL_PREFIX}${file}`] = encoder.encode(text);
+    }
+    return buffers;
 }
-function describeSpawnFailure(error) {
-    const parts = [];
-    if (error.message)
-        parts.push(error.message);
-    if (error.code)
-        parts.push(`code=${error.code}`);
-    if (error.path)
-        parts.push(`path=${error.path}`);
-    if (error.spawnargs?.length)
-        parts.push(`spawnargs=${error.spawnargs.join(' ')}`);
-    const stdout = toText(error.stdout).trim();
-    if (stdout)
-        parts.push(`stdout=${stdout}`);
-    const stderr = toText(error.stderr).trim();
-    if (stderr)
-        parts.push(`stderr=${stderr}`);
-    return parts.length ? parts.join(' | ') : 'Falha desconhecida ao executar xmllint.';
+/** Compiles the official schemas once per process; later calls reuse the validator. */
+function getValidator() {
+    if (compiledValidator)
+        return compiledValidator;
+    let schemaDoc;
+    try {
+        const buffers = loadSchemaBuffers();
+        const entry = buffers[`${SCHEMA_URL_PREFIX}${ENTRY_SCHEMA}`];
+        if (!entry)
+            throw new Error(`${ENTRY_SCHEMA} nao encontrado em ${schemaSourceDir()}`);
+        xmlRegisterInputProvider(new XmlBufferInputProvider(buffers));
+        schemaDoc = XmlDocument.fromBuffer(entry, { url: `${SCHEMA_URL_PREFIX}${ENTRY_SCHEMA}`, option: SAFE_PARSE_OPTIONS });
+        compiledValidator = XsdValidator.fromDoc(schemaDoc);
+        return compiledValidator;
+    }
+    catch (error) {
+        throw new XsdEngineUnavailableError(`Nao foi possivel carregar os XSD oficiais v1.01: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    finally {
+        // The validator keeps its own compiled copy of the schema.
+        schemaDoc?.dispose();
+    }
 }
-function schemaSourceDir() {
-    return fileURLToPath(new URL('../schemas/nfse/v1.01/Schemas/1.01/', import.meta.url));
+function detailsOf(error) {
+    const details = error.details.map((detail) => detail.message.trim()).filter(Boolean);
+    return details.length ? details : [error.message.trim() || error.name];
 }
-/** Validates a generated DPS against the official v1.01 schema before signing. */
+/**
+ * Validates a DPS against the official v1.01 schema before signing.
+ * Runs in-process (libxml2 in WebAssembly): no `xmllint`, no temp files, no network.
+ */
 export function validateDpsXmlAgainstXsd(xml) {
-    const workDir = mkdtempSync(join(tmpdir(), 'nfse-sdk-xsd-'));
-    const schemasDir = join(workDir, 'schemas');
+    const validator = getValidator();
+    let doc;
     try {
-        cpSync(schemaSourceDir(), schemasDir, { recursive: true });
-        // libxml2 treats ^/$ literally in XSD regexes. The official package ships
-        // one JavaScript-style anchor, so normalize that expression in our copy.
-        const simpleTypesPath = join(schemasDir, 'tiposSimples_v1.01.xsd');
-        const simpleTypes = readFileSync(simpleTypesPath, 'utf8').replace('<xs:pattern value="^0{0,4}\\d{1,5}$"/>', '<xs:pattern value="0{0,4}\\d{1,5}"/>');
-        writeFileSync(simpleTypesPath, simpleTypes);
-        const xmlPath = join(workDir, 'dps.xml');
-        writeFileSync(xmlPath, xml);
-        try {
-            execFileSync('xmllint', ['--noout', '--schema', join(schemasDir, 'DPS_v1.01.xsd'), xmlPath], {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-        }
-        catch (error) {
-            if (!isExecFileSyncFailure(error)) {
-                throw new XmllintUnavailableError(`Falha ao executar xmllint: ${String(error)}`, error);
-            }
-            if (error.code === 'ENOENT') {
-                throw new XmllintUnavailableError(`xmllint nao encontrado no ambiente de execucao (path=${error.path ?? 'xmllint'}). ` +
-                    'Instale o pacote libxml2/xmllint antes de validar o XSD.', error);
-            }
-            const stderrText = toText(error.stderr).trim();
-            if (stderrText) {
-                const details = stderrText.split('\n').map((line) => line.trim()).filter(Boolean);
-                throw new DpsXsdValidationError(details.length ? details : [stderrText]);
-            }
-            // xmllint failed but produced no stderr: do not mask this as an XML
-            // schema violation, since we have no evidence about the XML content.
-            throw new XmllintUnavailableError(`xmllint falhou sem stderr: ${describeSpawnFailure(error)}`, error);
+        doc = XmlDocument.fromString(xml, { option: SAFE_PARSE_OPTIONS });
+        validator.validate(doc);
+    }
+    catch (error) {
+        if (error instanceof XmlValidateError || error instanceof XmlParseError) {
+            throw new DpsXsdValidationError(detailsOf(error));
         }
+        throw new XsdEngineUnavailableError(`Falha no motor de validacao XSD: ${error instanceof Error ? error.message : String(error)}`, error);
     }
     finally {
-        rmSync(workDir, { recursive: true, force: true });
+        doc?.dispose();
     }
 }
 //# sourceMappingURL=xsdValidation.js.map

package/dist/xsdValidation.js.map

@@ -1 +1 @@
-{"version":3,"file":"xsdValidation.js","sourceRoot":"","sources":["../xsdValidation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xsdValidation.js","sourceRoot":"","sources":["../xsdValidation.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -12,4 +12,4 @@ The payloads in `payloads.ts` are shared by these examples and exercised by the
 - [`client-resource.ts`](./client-resource.ts): use `NfseClient` with certificate and defaults configured once.
 - [`handle-errors.ts`](./handle-errors.ts): normalize SEFIN rejection details for your application.
 
-The examples assume Node.js 20+ and a valid A1/PFX certificate. They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.
+The examples assume Node.js 20+ and a valid A1/PFX certificate, loaded with `NfseCertificate.fromEnv()` from `NFSE_CERT_PATH` (or `NFSE_CERT_BASE64`) and `NFSE_CERT_PASSWORD` (or `NFSE_CERT_PASSWORD_FILE`). They are intentionally explicit about fiscal fields; the SDK does not infer municipal taxation, withholding, CST or total tax burden.

package/examples/client-resource.ts

@@ -1,12 +1,10 @@
-import { NfseClient } from '@useinvio/nfse-sdk';
+import { NfseCertificate, NfseClient } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
 const client = new NfseClient({
   environment: 'sandbox',
-  certificate: {
-    content: process.env.NFSE_CERTIFICATE_BASE64!,
-    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
-  },
+  // NFSE_CERT_PATH or NFSE_CERT_BASE64, plus NFSE_CERT_PASSWORD or NFSE_CERT_PASSWORD_FILE
+  certificate: NfseCertificate.fromEnv(),
   defaults: { prestador: nationalInvoice.prestador, servico: nationalInvoice.servico },
 });
 

package/examples/emit-homologation.ts

@@ -1,11 +1,10 @@
-import { EmitirNotaError, emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
+import { EmitirNotaError, emitirNfse, NfseCertificate } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-
+const certificate = NfseCertificate.fromEnv(); // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
 
 try {
-  const resultado = await emitirNfse(nationalInvoice, pfx);
+  const resultado = await emitirNfse(nationalInvoice, certificate);
   console.log(resultado.chaveAcesso);
   console.log(resultado.nfseXml);
 } catch (error) {

package/examples/handle-errors.ts

@@ -1,11 +1,11 @@
-import { EmitirNotaError, emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+import { EmitirNotaError, emitirNfse, NfseCertificate, type DpsJsonRequest } from '@useinvio/nfse-sdk';
 import { nationalInvoice } from './payloads.js';
 
 async function emitWithStructuredErrors(nota: DpsJsonRequest) {
-  const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+  const certificate = NfseCertificate.fromEnv(); // NFSE_CERT_PATH + NFSE_CERT_PASSWORD
 
   try {
-    return await emitirNfse(nota, pfx);
+    return await emitirNfse(nota, certificate);
   } catch (error) {
     if (!(error instanceof EmitirNotaError)) throw error;
 

package/llms.txt

@@ -20,10 +20,13 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
 - `emitirNfse(input, pfx, options?)`: issue an invoice from a DPS XML string or `DpsJsonRequest`.
 - `buildDpsFromJson(input)`: build unsigned DPS XML from declarative JSON.
 - `buildDpsId(prestador, nDPS, serie?)`: derive the 45-character DPS Id.
-- `loadPfx(...)` and `loadPfxFromBuffer(...)`: extract key/certificate material from an A1/PFX certificate.
+- `NfseCertificate`: opaque A1 certificate for signing and mTLS (`fromEnv`, `fromFile`, `fromBase64`, `fromPfx`, `fromPem`). Exposes only metadata (CNPJ/CPF, validity, fingerprint); the private key lives outside the object and never appears in logs or JSON. Env convention: `NFSE_CERT_PATH` or `NFSE_CERT_BASE64`, plus `NFSE_CERT_PASSWORD` or `NFSE_CERT_PASSWORD_FILE`.
+- `loadPfx(...)` and `loadPfxFromBuffer(...)`: legacy loaders that return the key as PEM; prefer `NfseCertificate`.
 - `consultarNfse(...)`, `enviarEvento(...)`, `extrairErros(...)`: lower-level SEFIN helpers.
 - `setSefinRequestObserver(...)` and `createSefinLatencyTracker(...)`: observe SEFIN round-trip latency when `NFSE_SEFIN_LATENCY_METRICS` is enabled; percentiles require `includePercentiles: true`.
 - `gzipBase64(...)`, `gunzipBase64(...)`, `signDps(...)`, `verifyDps(...)`: protocol utilities for custom flows.
+- `DPS_JSON_REQUEST_SCHEMA`: JSON Schema 2020-12 for the canonical `DpsJsonRequest` (formats and code domains; cross-field rules stay in `validateDpsJsonRequest`).
+- `@useinvio/nfse-sdk/agent`: framework-neutral agent/MCP tools (`validate_dps`, `build_dps_xml`, `get_nfse`) and `toAgentIssues(error)`. Certificate and environment come from the host context, never from tool input.
 
 ## File Map
 
@@ -33,9 +36,15 @@ It is not a fiscal decision engine. Do not infer tax codes, accounting rules, te
 - `fiscalValidation.ts`: structural and layout-oriented validation for the JSON input. This intentionally rejects unsupported or ambiguous fiscal shapes.
 - `sefinClient.ts`: HTTPS mTLS requests to SEFIN, latency observation, response parsing, error normalization, invoice query, issue transport, and event transport.
 - `config.ts`: SEFIN base URLs, environment names, and `tpAmb` mapping.
-- `loadPfx.ts`: PFX/A1 certificate decoding with `node-forge`.
+- `certificate.ts`: `NfseCertificate`, ICP-Brasil CNPJ/CPF extraction, env loading, per-certificate mTLS agent, and the internal `resolveCredentials` used by signing and transport.
+- `loadPfx.ts`: PFX/A1 certificate decoding with `node-forge` (shared parser plus legacy loaders).
+- `xsdValidation.ts`: in-process XSD validation with libxml2 compiled to WebAssembly; schemas compiled once per process.
 - `signXml.ts`: XMLDSIG signing and verification helpers.
 - `gzipB64.ts`: GZip/Base64 helpers.
+- `fiscalDomains.ts`: code domains shared by the validator and the JSON Schema.
+- `dpsJsonSchema.ts`: JSON Schema for `DpsJsonRequest`; `satisfies` checks fail the build when a type gains a field the schema does not describe.
+- `jsonSchemaCheck.ts`: internal validator for the portable keyword subset the schema may use.
+- `agent.ts`: agent tool definitions, unified `NfseAgentIssue` shape, and error mapping.
 
 ## Core Data Shape
 
@@ -63,17 +72,18 @@ Keep values as strings when they represent fiscal codes, identifiers, decimals,
 - Currency discrepancies are warnings; explicit values retain priority. Service amounts must remain positive after rounding; all foreign amounts are serialized with two decimals.
 - `validateDpsJsonRequest` returns independent normalized data, errors in `issues`, and non-blocking `warnings`.
 - `EmitirNotaError` covers SEFIN rejection and incomplete/invalid HTTP 2xx authorization responses, including missing/invalid/conflicting 50-digit access keys. Reconcile before retrying; the SDK never retries automatically.
-- `sefinClient.ts` uses PEM key/cert material for mTLS, not the raw PFX in the Node TLS handshake.
+- `sefinClient.ts` uses a per-certificate `https.Agent` (from `NfseCertificate`) or PEM key/cert (legacy `PfxMaterial`) for mTLS, never the raw PFX in the Node TLS handshake. Access keys are validated as 50 digits before any request (`ChaveAcessoInvalidaError`).
+- XSD validation needs no system `xmllint`; it runs in WebAssembly. `XmllintUnavailableError` is a deprecated alias of `XsdEngineUnavailableError`.
 - SEFIN latency metrics are off by default, enabled through `NFSE_SEFIN_LATENCY_METRICS`, and emitted for the external request only; keep them separate from API route latency when integrating observability.
 
 ## Change Guidance for LLMs
 
 - Preserve the public API names exported by `index.ts` unless the task explicitly asks for a breaking change.
 - Prefer adding or adjusting focused tests in `test/` when changing XML generation, validation, signing, transport parsing, or client defaults.
-- When adding support for a new NFS-e layout field, update the TypeScript interface, validation rules, builder output, docs/examples, and tests together.
+- When adding support for a new NFS-e layout field, update the TypeScript interface, validation rules, JSON Schema (`dpsJsonSchema.ts`), builder output, docs/examples, and tests together.
 - Do not add fiscal assumptions to make examples pass. Required fiscal choices should stay explicit in user input.
 - Be careful with XML ordering. The generated order should follow the SEFIN schema, and tests may compare XML snippets.
-- Do not hand-wave certificate handling. PFX content may arrive as a `Buffer` or base64 string.
+- Do not hand-wave certificate handling. Accept `CertificateInput` (`NfseCertificate | PfxMaterial`) and go through `resolveCredentials`; never log, serialize, or return key material, the PFX bytes, or the password.
 - Network calls to SEFIN should stay isolated in `sefinClient.ts` so tests can mock transport boundaries.
 
 ## Useful Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useinvio/nfse-sdk",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "TypeScript SDK for Brazil's national NFS-e: JSON to DPS/XML, XMLDSIG, GZip/Base64, mTLS and SEFIN errors.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -62,9 +66,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@xmldom/xmldom": "^0.8.13",
-    "node-forge": "^1.3.1",
-    "xml-crypto": "^6.0.0"
+    "@xmldom/xmldom": "^0.8.15",
+    "libxml2-wasm": "^0.7.2",
+    "node-forge": "^1.4.3",
+    "xml-crypto": "^6.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.14",