nf-key-extractor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devAlphaSystem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,427 @@
+# nf-key-extractor
+
+Extração local, somente por CPU, de chaves de acesso validadas de NF-e e NFC-e
+em arquivos PDF locais ou remotos. Primeiro, verifica o texto nativo do PDF;
+depois, Code 128/QR; e usa OCR local somente quando o perfil selecionado permite.
+Os arquivos remotos são baixados para o processo Node.js; a análise do PDF, o
+reconhecimento de códigos de barras e o OCR permanecem locais.
+
+O pacote aceita tanto as chaves numéricas legadas de 44 dígitos quanto o formato
+atual de 44 caracteres, introduzido para CNPJs alfanuméricos em julho de 2026.
+
+## Instalação
+
+```bash
+npm install nf-key-extractor
+```
+
+É necessário usar Node.js 20 ou mais recente. Não é preciso instalar o Tesseract
+no sistema, usar GPU ou serviço externo de extração, baixar modelos durante a
+execução nem fornecer credenciais de API ao pacote. A aplicação que chama o
+pacote pode fornecer credenciais quando a URL do PDF exigir autenticação.
+
+## Uma chamada de função
+
+```ts
+import { extractNFeAccessKeys } from "nf-key-extractor";
+
+const result = await extractNFeAccessKeys("/local/path/danfe.pdf", {
+  performance: "balanced",
+  passes: 2,
+});
+
+console.log(JSON.stringify(result, null, 2));
+```
+
+Também são aceitos `Buffer`, `Uint8Array` e `ArrayBuffer`:
+
+```ts
+const result = await extractNFeAccessKeys(pdfBuffer);
+```
+
+URLs públicas HTTP/HTTPS de PDFs podem ser informadas diretamente:
+
+```ts
+const result = await extractNFeAccessKeys("https://documents.example.com/public/danfe.pdf");
+```
+
+Para uma URL autenticada, use a opção `requestHeaders`, disponível somente na API:
+
+```ts
+const result = await extractNFeAccessKeys("https://documents.example.com/private/danfe.pdf", {
+  requestHeaders: {
+    Authorization: "Bearer <token>",
+  },
+});
+```
+
+O pacote não executa fluxos de login nem mantém um repositório de cookies. A
+aplicação chamadora é responsável pelas credenciais fornecidas e pelo estado da
+sessão. Prefira HTTPS sempre que enviar credenciais; cabeçalhos enviados a uma
+URL HTTP inicial não são protegidos por TLS. `requestHeaders` aceita somente
+valores do tipo string e não pode ser usada com um caminho local ou uma entrada
+em memória. Cabeçalhos de roteamento, enquadramento, intervalo e negociação de
+compressão são reservados pelo componente de download e não podem ser
+sobrescritos.
+
+### Download de PDFs remotos
+
+Somente URLs `http://` e `https://` são aceitas. O componente de download segue
+respostas HTTP 301, 302, 303, 307 e 308, com no máximo cinco redirecionamentos.
+Ele remove `Authorization`, `Cookie` e `Proxy-Authorization` quando um
+redirecionamento muda a origem ou rebaixa HTTPS para HTTP. Os demais cabeçalhos
+fornecidos pela aplicação chamadora são mantidos na solicitação redirecionada.
+
+O limite `maxFileSizeBytes` (30 MiB por padrão) é aplicado tanto ao
+`Content-Length` declarado quanto aos bytes recebidos durante a transferência.
+`timeoutMs` abrange o download e a extração em conjunto, enquanto `signal` pode
+cancelar qualquer uma das fases. É a assinatura do PDF, e não a extensão da URL
+ou o tipo de mídia da resposta, que determina se o conteúdo baixado é aceito.
+Falhas de download usam o código de erro `DOWNLOAD_ERROR`. Erros estruturados
+não reproduzem a URL, a string de consulta nem os valores dos cabeçalhos da
+solicitação.
+
+Trate URLs remotas como entradas confiáveis. O pacote não é um filtro de SSRF:
+uma URL e seus redirecionamentos podem alcançar qualquer local da rede acessível
+ao processo Node.js. Aplicações que aceitam URLs fornecidas por usuários devem
+aplicar sua própria política de confiança. Quando forem necessárias listas de
+permissão de host, DNS/IP ou redirecionamento, faça o download com um cliente
+controlado pela aplicação e envie os bytes resultantes ao extrator.
+
+## Resultado
+
+A função retorna um objeto compatível com JSON para sucesso, ausência de
+correspondência, entrada inválida, tempo limite e erros esperados de PDF:
+
+```json
+{
+  "status": "success",
+  "success": true,
+  "precisionScore": 0.99,
+  "bestMatch": {
+    "accessKey": "35260712345678000195550010000000011123456784",
+    "documentType": "NFe",
+    "model": "55",
+    "format": "numeric",
+    "isValid": true,
+    "precisionScore": 0.99,
+    "pages": [1],
+    "sources": ["pdf-text"],
+    "occurrences": 1,
+    "components": {
+      "accessKey": "35260712345678000195550010000000011123456784",
+      "format": "numeric",
+      "stateCode": "35",
+      "yearMonth": "2607",
+      "year": "26",
+      "month": "07",
+      "issuerId": "12345678000195",
+      "model": "55",
+      "documentType": "NFe",
+      "series": "001",
+      "invoiceNumber": "000000001",
+      "emissionType": "1",
+      "numericCode": "12345678",
+      "checkDigit": 4
+    }
+  },
+  "results": [
+    {
+      "accessKey": "35260712345678000195550010000000011123456784",
+      "documentType": "NFe",
+      "model": "55",
+      "format": "numeric",
+      "isValid": true,
+      "precisionScore": 0.99,
+      "pages": [1],
+      "sources": ["pdf-text"],
+      "occurrences": 1,
+      "components": {
+        "accessKey": "35260712345678000195550010000000011123456784",
+        "format": "numeric",
+        "stateCode": "35",
+        "yearMonth": "2607",
+        "year": "26",
+        "month": "07",
+        "issuerId": "12345678000195",
+        "model": "55",
+        "documentType": "NFe",
+        "series": "001",
+        "invoiceNumber": "000000001",
+        "emissionType": "1",
+        "numericCode": "12345678",
+        "checkDigit": 4
+      }
+    }
+  ],
+  "metadata": {
+    "performance": "balanced",
+    "ocrMode": "fallback",
+    "passesRequested": 2,
+    "passesUsed": 0,
+    "pagesTotal": 1,
+    "pagesProcessed": 1,
+    "pagesRendered": 0,
+    "ocrPages": 0,
+    "fileSizeBytes": 8421,
+    "maxPixelsPerPage": 12000000,
+    "maxSourceImagePixels": 60000000,
+    "durationMs": 12.34,
+    "complete": true,
+    "confidenceVersion": "1.0.0"
+  },
+  "warnings": [],
+  "error": null
+}
+```
+
+`results` contém todas as chaves únicas e validadas de NF-e/NFC-e detectadas
+pelas etapas executadas nas páginas processadas. Os perfis `fast` e `balanced`
+podem ignorar etapas de maior custo depois que uma evidência válida mais barata
+é encontrada; use `accurate` ou `ocr: 'always'` quando quiser verificações
+cruzadas adicionais. `bestMatch` é o resultado com a maior pontuação. O
+`precisionScore` do nível superior é conservador: quando várias chaves são
+retornadas, ele corresponde à menor pontuação entre os resultados.
+
+Todas as chaves permanecem como strings, portanto zeros à esquerda nunca são
+perdidos.
+
+### O que a pontuação significa
+
+`precisionScore` é uma pontuação determinística de confiança nas evidências,
+versionada por `metadata.confidenceVersion`. Código de barras/QR, texto nativo
+exato, texto reconstruído e OCR têm pontuações-base diferentes; fontes
+independentes que concordam entre si aumentam a pontuação. Toda chave retornada
+já passou pelas validações de formato, UF, mês, modelo 55/65, número da nota
+diferente de zero, CNPJ/CPF do emitente e dígito verificador oficial por módulo 11.
+
+A pontuação não é uma probabilidade calibrada estatisticamente. Meça precisão,
+recall e falsos positivos em um corpus privado representativo antes de usar um
+limiar em automações fiscais.
+
+## Opções
+
+| Opção                  | Valores                        | Padrão               | Significado                                                 |
+| ---------------------- | ------------------------------ | -------------------- | ----------------------------------------------------------- |
+| `performance`          | `fast`, `balanced`, `accurate` | `balanced`           | Seleciona escala de renderização, limites e política de OCR |
+| `passes`               | inteiro `1..5`                 | específico do perfil | Número de tentativas visuais distintas de renderização      |
+| `ocr`                  | `never`, `fallback`, `always`  | específico do perfil | Controla o OCR local do Tesseract                           |
+| `maxPages`             | inteiro positivo               | `10`, `30` ou `50`   | Máximo de páginas processadas                               |
+| `maxFileSizeBytes`     | inteiro positivo               | 30 MiB               | Limite de tamanho da entrada                                |
+| `maxPixelsPerPage`     | inteiro positivo               | específico do perfil | Limite de pixels da renderização e de imagens incorporadas  |
+| `maxSourceImagePixels` | inteiro positivo               | específico do perfil | Limite de pixels da imagem de origem decodificada           |
+| `timeoutMs`            | `0..3600000`                   | específico do perfil | Prazo do download/extração; `0` o desabilita                |
+| `stopAfterFirst`       | booleano                       | `false`              | Interrompe após a primeira chave validada                   |
+| `requestHeaders`       | registro de strings            | nenhum               | Cabeçalhos exclusivos da API para um download HTTP(S)       |
+| `signal`               | `AbortSignal`                  | nenhum               | Cancela o download ou a extração local                      |
+
+A etapa de texto nativo sempre é executada e não conta como uma passagem visual.
+Cada passagem usa uma escala ou rotação diferente; o extrator nunca repete uma
+operação idêntica apenas para aumentar a confiança.
+
+Perfis:
+
+- `fast`: texto nativo e Code 128/QR; OCR desabilitado por padrão.
+- `balanced`: duas estratégias visuais e OCR somente quando o texto/código de
+  barras não encontra uma chave válida.
+- `accurate`: resoluções maiores, passagens opcionais com rotação e OCR local
+  como alternativa.
+
+Os perfis `fast` e `balanced` ignoram o trabalho visual nas páginas que já
+produziram texto válido. O perfil `accurate` ainda executa as passagens de código
+de barras configuradas para fazer uma verificação cruzada independente. O OCR no
+modo `fallback` só é executado nas páginas não resolvidas pelas etapas
+anteriores; `ocr: 'always'` o executa de qualquer forma.
+
+## CLI
+
+Após a instalação:
+
+```text
+nf-key-extractor <file-or-url> [options]
+```
+
+Por exemplo:
+
+```bash
+nf-key-extractor ./nota.pdf --performance balanced --passes 2 --pretty
+nf-key-extractor https://documents.example.com/public/nota.pdf --pretty
+```
+
+O argumento posicional pode ser o caminho de um arquivo local ou uma URL pública
+HTTP/HTTPS. Intencionalmente, a CLI não oferece uma opção para credenciais ou
+cabeçalhos de solicitação personalizados; use a API da biblioteca com
+`requestHeaders` para downloads autenticados. Evite tokens de consulta assinados
+em URLs usadas na CLI, pois os argumentos do comando podem ficar visíveis no
+histórico do terminal ou na lista de processos do sistema operacional.
+
+Opções disponíveis:
+
+```text
+--performance fast|balanced|accurate
+--passes 1..5
+--ocr never|fallback|always
+--max-pages N
+--max-file-size BYTES
+--max-pixels N
+--max-source-pixels N
+--timeout-ms N
+--first
+--pretty
+--help
+```
+
+O fluxo de saída padrão contém somente JSON. O código de saída `0` significa que
+uma ou mais chaves foram encontradas (ou que a ajuda foi solicitada), `2`
+significa que uma varredura completa não encontrou nenhuma, e `1` indica um erro
+de entrada/processamento ou uma varredura incompleta sem chave.
+
+## Chaves de acesso atuais e legadas
+
+As chaves numéricas legadas continuam sendo aceitas. A expressão oficial atual é:
+
+```text
+^[0-9]{6}[A-Z0-9]{12}[0-9]{26}$
+```
+
+Somente as primeiras 12 posições do identificador do emitente dentro da chave
+podem ser alfanuméricas; as demais posições continuam numéricas. O cálculo do
+dígito verificador mapeia cada um dos primeiros 43 caracteres para `ASCII - 48`,
+aplica pesos repetidos de 2 a 9, da direita para a esquerda, e depois módulo 11.
+As chaves numéricas são um subconjunto compatível do mesmo algoritmo.
+
+O leitor de código de barras usa decodificação genérica de Code 128, portanto
+aceita tanto o Code Set C legado quanto a representação híbrida atual em Code
+Set C/A.
+
+Referências oficiais:
+
+- [MOC 7.0 - Visão Geral](https://www.confaz.fazenda.gov.br/legislacao/arquivo-manuais/moc7-visao-geral.pdf)
+- [Nota Técnica Conjunta DFe 2025.001 - CNPJ alfanumérico](https://www.nfe.fazenda.gov.br/Portal/exibirArquivo.aspx?conteudo=5ZkvIZt10mQ%3D)
+- [NT 2026.004 v1.01 - NF-e/NFC-e schemas](https://www.nfe.fazenda.gov.br/POrtal/exibirArquivo.aspx?AspxAutoDetectCookieSupport=1&conteudo=BTZQzgsO9Ws%3D)
+
+## Validação independente
+
+O analisador e o validador fiscais são públicos e não carregam dependências de
+PDF/OCR:
+
+```ts
+import { calculateAccessKeyCheckDigit, parseAccessKey, validateAccessKey, validateIssuerIdentifier } from "nf-key-extractor";
+
+const validation = validateAccessKey(accessKey);
+```
+
+## Comportamento de recursos e segurança
+
+- Execução somente por CPU; nenhum backend de GPU é usado.
+- O acesso à rede é usado apenas para baixar uma URL de entrada HTTP/HTTPS. Após
+  o download limitado, a extração é local; os bytes do PDF não são enviados a
+  um serviço de OCR nem a qualquer outro processador externo.
+- Os dados de idioma do OCR são instalados localmente com o pacote e carregados
+  explicitamente do disco, evitando o uso padrão da CDN do Tesseract.
+- Tamanho do arquivo, quantidade de páginas, pixels de imagens incorporadas e de
+  renderização, itens de texto, tamanho do texto, prazo e cancelamento têm
+  limites definidos.
+- A execução de JavaScript em PDFs é desabilitada.
+- As falhas esperadas são retornadas como JSON estruturado e nunca expõem
+  buffers nem objetos internos do PDF.
+
+PDFs criptografados que exigem senha são informados como `PASSWORD_REQUIRED`.
+PDFs ou digitalizações gravemente danificados ainda podem produzir `not_found`;
+o pacote não inventa uma chave que não passe pela validação fiscal determinística.
+
+Antes da renderização, o PDF.js ignora imagens incorporadas que excedam
+`maxSourceImagePixels`. Os valores padrão dos perfis permitem digitalizações em
+alta resolução sem deixar a decodificação da origem sem limites; aumente o
+limite explicitamente apenas para digitalizações confiáveis e excepcionalmente
+grandes.
+
+## Resultados de validação e benchmarks
+
+As medições a seguir foram coletadas em 22/07/2026 com Node.js 24.11.0, Windows
+x64 e um AMD Ryzen 5 5600G (12 processadores lógicos). Os tempos absolutos variam
+de uma máquina para outra; use os executores para comparar alterações no mesmo
+ambiente.
+
+### Benchmark sintético de correspondência exata
+
+Cada cenário usa um PDF gerado com uma chave esperada conhecida. Uma execução de
+aquecimento é excluída das iterações medidas.
+
+| Cenário             | Perfil / passagens | Iterações |     Média |       P50 |       P95 | Correspondência exata |
+| ------------------- | ------------------ | --------: | --------: | --------: | --------: | --------------------: |
+| Texto nativo do PDF | `fast` / 1         |        20 |   3,09 ms |   3,00 ms |   3,78 ms |                  100% |
+| Code 128            | `balanced` / 2     |        10 | 119,44 ms | 117,72 ms | 131,64 ms |                  100% |
+| QR de NFC-e         | `balanced` / 2     |        10 | 182,75 ms | 174,46 ms | 215,82 ms |                  100% |
+| OCR local           | `balanced` / 1     |         3 | 724,59 ms | 723,14 ms | 762,74 ms |                  100% |
+
+### Corpus privado de documentos reais
+
+O extrator também foi executado localmente em 12 PDFs privados de notas fiscais
+de compra (223.074 bytes no total). O diretório local `invoices/` é ignorado pelo
+Git e excluído da lista de arquivos permitidos no pacote npm. O executor emite
+somente métricas agregadas; nunca imprime nomes de arquivos, chaves de acesso ou
+conteúdo dos documentos.
+
+| Perfil                  | Execuções medidas por PDF | PDFs com chave | Erros / avisos |       Média |         P50 |         P95 |
+| ----------------------- | ------------------------: | -------------: | -------------: | ----------: | ----------: | ----------: |
+| `fast`, 1 passagem      |                         3 |          12/12 |          0 / 0 |     8,29 ms |     8,18 ms |     9,65 ms |
+| `balanced`, 2 passagens |                         3 |          12/12 |          0 / 0 |     8,28 ms |     7,66 ms |    13,35 ms |
+| `accurate`, 3 passagens |                         1 |          12/12 |          0 / 0 |   850,43 ms |   829,81 ms |   921,52 ms |
+| `accurate`, OCR forçado |                         1 |          12/12 |          0 / 0 | 1.934,50 ms | 1.907,04 ms | 2.036,73 ms |
+
+Os perfis `fast`, `balanced` e `accurate` retornaram o mesmo conjunto de chaves
+validadas nos 12 documentos, com exatamente uma chave por PDF e nenhum resultado
+incompleto. Todas as evidências finais desse corpus vieram do texto nativo
+reconstruído do PDF. O OCR forçado processou as 12 páginas, mas não reproduziu a
+chave completa de forma independente e, portanto, não aumentou a pontuação das
+evidências.
+
+Esses PDFs privados não têm uma referência correta rotulada manualmente e
+verificada de forma independente. Portanto, o resultado demonstra processamento
+bem-sucedido, validação fiscal determinística e concordância entre os perfis;
+ele não estabelece precisão/recall estatísticos nem prova que nenhuma chave foi
+ignorada. O benchmark sintético acima é o teste de correspondência exata com
+chaves esperadas conhecidas.
+
+O tarball empacotado da versão `0.1.0` também foi instalado em um projeto
+consumidor temporário e limpo com npm 11.6.1. A entrada ESM, a entrada CommonJS,
+o executável da CLI e as dependências locais de OCR e execução instalados foram
+resolvidos corretamente; ESM, CommonJS e CLI processaram com sucesso um PDF real
+privado. O projeto consumidor temporário foi removido após a verificação.
+
+O tarball empacotado da versão `0.2.0` foi gerado e instalado em outro projeto
+consumidor temporário e limpo com pnpm 10.34.5 e Node.js 24.11.0. As entradas ESM
+e CommonJS, `requestHeaders`, a extração de URLs HTTP/HTTPS, as declarações
+TypeScript e o executável da CLI instalados foram verificados com um PDF gerado
+e respostas de rede simuladas. Nenhum endpoint ativo nem credencial de produção
+foi usado.
+
+## Desenvolvimento
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm test:real
+pnpm test:coverage
+pnpm security:audit
+pnpm build
+pnpm check
+```
+
+A compilação gera ESM, CommonJS, declarações, mapas de código-fonte e a CLI em
+`dist/`. Os fixtures de integração são sintéticos e não contêm dados reais de
+contribuintes.
+
+Execute um benchmark em JSON com:
+
+```bash
+pnpm benchmark --scenario text --iterations 20 --performance fast --passes 1
+pnpm benchmark:real
+pnpm benchmark:real --include-accurate --include-ocr
+```
+
+Consulte [`benchmarks/README.md`](benchmarks/README.md) para conhecer os cenários
+e as métricas.

package/benchmarks/README.md

@@ -0,0 +1,53 @@
+# Testes de desempenho (benchmarks)
+
+O executor de benchmarks cria PDFs sintéticos em memória, verifica a
+correspondência exata da chave de acesso em cada iteração e grava um documento
+JSON na saída padrão.
+
+```bash
+pnpm benchmark --scenario text --iterations 20 --performance fast --passes 1
+pnpm benchmark --scenario barcode --iterations 10 --performance balanced --passes 2
+pnpm benchmark --scenario qr --iterations 10 --performance balanced --passes 2
+pnpm benchmark --scenario ocr --iterations 3 --performance accurate --passes 3
+```
+
+Os valores informados incluem tempo decorrido mínimo/médio/p50/p95/máximo, tempo
+de CPU, variação de RSS, informações do ambiente de execução, tamanho da entrada
+e taxa de correspondência exata. A primeira extração serve como aquecimento e é
+excluída das amostras.
+
+Não use os tempos absolutos de uma única máquina como critério de CI. Em vez
+disso, compare execuções repetidas no mesmo hardware e monitore regressões
+relativas.
+
+## Corpus privado de notas fiscais locais
+
+`real-corpus.ts` localiza recursivamente os PDFs em um diretório local, executa o
+aquecimento de cada perfil, mede a latência por documento e compara os conjuntos
+de chaves validadas retornados por todos os perfis. Sua saída JSON contém somente
+dados agregados: nunca inclui chaves de acesso, conteúdo dos documentos, caminhos
+ou nomes de arquivos.
+
+```bash
+pnpm exec tsx benchmarks/real-corpus.ts
+pnpm exec tsx benchmarks/real-corpus.ts --input-dir invoices --iterations 3 --warmup-iterations 1
+pnpm exec tsx benchmarks/real-corpus.ts --include-accurate
+pnpm exec tsx benchmarks/real-corpus.ts --include-accurate --include-ocr
+pnpm exec tsx benchmarks/real-corpus.ts --require-key-per-document
+```
+
+Os perfis `fast` e `balanced` sempre são executados. `--include-accurate`
+adiciona o modo `accurate` com OCR como alternativa, enquanto `--include-ocr`
+adiciona um perfil `accurate` que força o mecanismo de OCR local incluído no
+pacote. O OCR pode ser consideravelmente mais lento, por isso é opcional.
+
+O relatório inclui o tamanho do corpus, dados agregados de tempo de execução e
+memória, contagens de sucesso por perfil, latência média/p50/p95, contagens de
+documentos por categoria de origem não exclusiva, estabilidade entre iterações
+e concordância exata dos conjuntos de chaves. O executor termina com status
+diferente de zero em caso de erros de extração, processamento incompleto,
+resultados não determinísticos ou divergências entre perfis. Um resultado
+`not_found` válido é incluído nas contagens de sucesso, mas não é tratado como
+erro de processamento, a menos que `--require-key-per-document` esteja definido.
+A concordância entre perfis mede a consistência dos modos de extração; sem uma
+referência correta verificada de forma independente, ela não mede a acurácia.