@open-nav/core 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 open-nav contributors
+
+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.
+
+---
+
+This repository vendors XML schemas, sample documents and validation message
+catalogues published by the Hungarian Tax and Customs Administration
+(Nemzeti Adó- és Vámhivatal) under the MIT license. Those files live under
+`schemas/` and `conformance/`, retain NAV's copyright, and are covered by
+`schemas/NAV-LICENCE.md`. See `schemas/README.md` for provenance.

package/README.md

@@ -0,0 +1,132 @@
+# @open-nav/core
+
+The parts of the NAV Online Számla interface that have a right answer:
+authentication, the schema, XML, exact decimal arithmetic and validation.
+No network access — everything here is pure, so it is testable and safe to
+run anywhere.
+
+```sh
+npm install @open-nav/core
+```
+
+## Authentication
+
+Every request NAV accepts carries a SHA-512 password hash and a SHA3-512
+request signature. The signature is not over the request body: it is over
+`requestId + yyyyMMddHHmmss + signKey`, followed by a **concatenation of
+per-invoice hashes in index order** when the operation submits invoices.
+
+```ts
+import { passwordHash, requestSignature, createRequestId } from '@open-nav/core';
+
+const requestId = createRequestId(); // safe against the 30 char / [+a-zA-Z0-9_] rule
+const timestamp = new Date();
+
+const signature = requestSignature(requestId, timestamp, process.env.NAV_SIGN_KEY!, [
+  { index: 1, operation: 'CREATE', base64Payload: encoded },
+]);
+const hash = passwordHash(process.env.NAV_PASSWORD!); // the SHA-512 half
+```
+
+Verified against **all 11 of NAV's published request samples**, the
+three-invoice batch included, which is the case that catches an
+implementation that hashes in the wrong order or hashes a re-serialised copy
+of the payload.
+
+`decodeExchangeToken` handles the other half: the token NAV returns is
+AES-128-ECB encrypted with your exchange key, and arrives padded or unpadded
+depending on the operation.
+
+## The schema, generated from the XSDs
+
+The types and the runtime metadata that drives serialisation, parsing and
+validation are generated from NAV's own XSDs — ~700 elements across six
+namespaces — and must not be hand-edited. One descriptor table drives all
+three directions, so they cannot disagree with each other.
+
+```ts
+import {
+  serializeDocument,
+  parseDocumentAs,
+  encodeInvoiceData,
+  decodeInvoiceData,
+} from '@open-nav/core';
+
+const xml = serializeDocument('InvoiceData', document);
+const back = parseDocumentAs<InvoiceData>(xml, 'InvoiceData');
+const base64 = encodeInvoiceData(document); // what goes in the request
+```
+
+All **41 official NAV sample documents** round-trip to canonically equal XML.
+
+Namespaces are the trap worth naming: a tax number sits in `OSA/3.0/data`
+while its `taxpayerId` child sits in `OSA/3.0/base`. The generated
+descriptors know which, so you never write a prefix.
+
+## Exact arithmetic
+
+Invoice amounts run to 18 digits and quantities to 10 decimal places. IEEE
+754 doubles cannot carry either, and being one forint out rejects the whole
+batch, so amounts are **decimal strings end to end** and arithmetic goes
+through `Decimal`, which is BigInt-scaled.
+
+```ts
+import { Decimal, computeInvoiceSummary, checkInvoiceSummary } from '@open-nav/core';
+
+Decimal.from('0.1').add('0.2').toString(); // '0.3', not 0.30000000000000004
+
+const invoice = document.invoiceMain.invoice!; // an InvoiceType
+const summary = computeInvoiceSummary(invoice); // per VAT rate, plus the totals
+const findings = checkInvoiceSummary(invoice); // where it fails to reconcile
+```
+
+Summation is not the whole rule. A line that omits its VAT amount has it
+**derived from the rate**, a VAT exemption is identified by its legal case
+and not by the free text beside it, and a foreign-currency invoice needs a
+forint twin for every amount. Reproduces the summaries of 24 of NAV's 30
+sample invoices; the remaining 6 are internally contradictory upstream — see
+[`conformance/README.md`](../../conformance/README.md).
+
+## Validating before NAV does
+
+Two layers, both local: the generated schema, and the business rules that are
+`INVALID_...` faults in NAV's catalogue.
+
+```ts
+import { validateInvoice, faultMessage } from '@open-nav/core';
+
+const report = validateInvoice(document, { operation: 'CREATE', language: 'hu' });
+if (!report.valid) {
+  for (const issue of report.errors) {
+    console.error(issue.path, issue.code, issue.message, issue.navMessage);
+  }
+}
+faultMessage('ANNULMENT_IN_PROGRESS', 'hu'); // NAV's own wording, in hu, en or de
+```
+
+Findings carry NAV's own fault code where one exists, so an error you see
+locally is the error you would have seen remotely. The catalogue is generated
+from `schemas/i18n/` — 236 codes, in Hungarian, English and German. It covers
+NAV's _business validation_ codes; the technical ones (`INVALID_SIGNATURE`,
+`INVALID_REQUEST_ID` and the rest) are not in NAV's message files, and arrive
+with their own text on the response instead.
+
+Rules NAV can only decide server-side — whether the invoice number is
+already used, whether the customer's tax number is live — are listed in
+`LOCALLY_UNDECIDABLE` rather than guessed at.
+
+Warnings do not make a report invalid, and that distinction is load-bearing:
+the taxpayer-id check digit is a warning because 2 of the 4 tax numbers in
+NAV's own samples fail it while NAV itself validates against its registry. A
+validator that cries wolf gets switched off.
+
+## Also here
+
+`OPERATIONS`, `BASE_URLS`, `MAX_INVOICE_BATCH_SIZE`, `QUERY_PAGE_SIZE` and
+the other interface constants; `parseTaxNumber` and the county/VAT-code
+tables; NAV's timestamp formats; and the `NavError` hierarchy the client
+throws.
+
+## Licence
+
+MIT. Not affiliated with NAV.

package/dist/constants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Protocol level constants for the NAV Online Számla (Online Invoice) system.
+ *
+ * The reference documentation is published by NAV at
+ * https://onlineszamla.nav.gov.hu/dokumentaciok — this library targets
+ * interface version 3.0 of the invoice service.
+ */
+/** XML namespace of the invoice service request/response envelopes. */
+export declare const NS_API = "http://schemas.nav.gov.hu/OSA/3.0/api";
+/** XML namespace of the invoice payload (`InvoiceData`). */
+export declare const NS_DATA = "http://schemas.nav.gov.hu/OSA/3.0/data";
+/** XML namespace of shared invoice building blocks (addresses, tax numbers). */
+export declare const NS_BASE = "http://schemas.nav.gov.hu/OSA/3.0/base";
+/** XML namespace of the annulment payload (`InvoiceAnnulment`). */
+export declare const NS_ANNUL = "http://schemas.nav.gov.hu/OSA/3.0/annul";
+/** XML namespace of the NTCA common header/user blocks. */
+export declare const NS_COMMON = "http://schemas.nav.gov.hu/NTCA/1.0/common";
+/** Value of `header/requestVersion` for this interface version. */
+export declare const REQUEST_VERSION = "3.0";
+/** Value of `header/headerVersion` for this interface version. */
+export declare const HEADER_VERSION = "1.0";
+/** Base URL of the NAV production invoice service. */
+export declare const PRODUCTION_BASE_URL = "https://api.onlineszamla.nav.gov.hu/invoiceService/v3";
+/** Base URL of the NAV test ("teszt") invoice service. */
+export declare const TEST_BASE_URL = "https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3";
+/** Well known NAV environments and their base URLs. */
+export declare const BASE_URLS: {
+    readonly production: "https://api.onlineszamla.nav.gov.hu/invoiceService/v3";
+    readonly test: "https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3";
+};
+export type NavEnvironment = keyof typeof BASE_URLS;
+/** Operation names (path segments) exposed by the invoice service. */
+export declare const OPERATIONS: readonly ["tokenExchange", "manageInvoice", "manageAnnulment", "queryTransactionStatus", "queryTransactionList", "queryInvoiceData", "queryInvoiceDigest", "queryInvoiceChainDigest", "queryInvoiceCheck", "queryTaxpayer"];
+export type NavOperation = (typeof OPERATIONS)[number];
+/**
+ * Maximum number of invoice operations NAV accepts in a single
+ * `manageInvoice` request.
+ */
+export declare const MAX_INVOICE_BATCH_SIZE = 100;
+/** Page size used by NAV for every paged query response. */
+export declare const QUERY_PAGE_SIZE = 100;
+/**
+ * Maximum length of the `requestId` header field. NAV also requires it to be
+ * unique per taxpayer, forever.
+ */
+export declare const REQUEST_ID_MAX_LENGTH = 30;
+/** Characters NAV allows in a `requestId`. */
+export declare const REQUEST_ID_PATTERN: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,eAAO,MAAM,MAAM,0CAA0C,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,OAAO,2CAA2C,CAAC;AAEhE,gFAAgF;AAChF,eAAO,MAAM,OAAO,2CAA2C,CAAC;AAEhE,mEAAmE;AACnE,eAAO,MAAM,QAAQ,4CAA4C,CAAC;AAElE,2DAA2D;AAC3D,eAAO,MAAM,SAAS,8CAA8C,CAAC;AAErE,mEAAmE;AACnE,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,kEAAkE;AAClE,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,0DAA0D,CAAC;AAE3F,0DAA0D;AAC1D,eAAO,MAAM,aAAa,+DAA+D,CAAC;AAE1F,uDAAuD;AACvD,eAAO,MAAM,SAAS;;;CAGZ,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,SAAS,CAAC;AAEpD,sEAAsE;AACtE,eAAO,MAAM,UAAU,6NAWb,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,QAA0B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,58 @@
+/**
+ * Protocol level constants for the NAV Online Számla (Online Invoice) system.
+ *
+ * The reference documentation is published by NAV at
+ * https://onlineszamla.nav.gov.hu/dokumentaciok — this library targets
+ * interface version 3.0 of the invoice service.
+ */
+/** XML namespace of the invoice service request/response envelopes. */
+export const NS_API = 'http://schemas.nav.gov.hu/OSA/3.0/api';
+/** XML namespace of the invoice payload (`InvoiceData`). */
+export const NS_DATA = 'http://schemas.nav.gov.hu/OSA/3.0/data';
+/** XML namespace of shared invoice building blocks (addresses, tax numbers). */
+export const NS_BASE = 'http://schemas.nav.gov.hu/OSA/3.0/base';
+/** XML namespace of the annulment payload (`InvoiceAnnulment`). */
+export const NS_ANNUL = 'http://schemas.nav.gov.hu/OSA/3.0/annul';
+/** XML namespace of the NTCA common header/user blocks. */
+export const NS_COMMON = 'http://schemas.nav.gov.hu/NTCA/1.0/common';
+/** Value of `header/requestVersion` for this interface version. */
+export const REQUEST_VERSION = '3.0';
+/** Value of `header/headerVersion` for this interface version. */
+export const HEADER_VERSION = '1.0';
+/** Base URL of the NAV production invoice service. */
+export const PRODUCTION_BASE_URL = 'https://api.onlineszamla.nav.gov.hu/invoiceService/v3';
+/** Base URL of the NAV test ("teszt") invoice service. */
+export const TEST_BASE_URL = 'https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3';
+/** Well known NAV environments and their base URLs. */
+export const BASE_URLS = {
+    production: PRODUCTION_BASE_URL,
+    test: TEST_BASE_URL,
+};
+/** Operation names (path segments) exposed by the invoice service. */
+export const OPERATIONS = [
+    'tokenExchange',
+    'manageInvoice',
+    'manageAnnulment',
+    'queryTransactionStatus',
+    'queryTransactionList',
+    'queryInvoiceData',
+    'queryInvoiceDigest',
+    'queryInvoiceChainDigest',
+    'queryInvoiceCheck',
+    'queryTaxpayer',
+];
+/**
+ * Maximum number of invoice operations NAV accepts in a single
+ * `manageInvoice` request.
+ */
+export const MAX_INVOICE_BATCH_SIZE = 100;
+/** Page size used by NAV for every paged query response. */
+export const QUERY_PAGE_SIZE = 100;
+/**
+ * Maximum length of the `requestId` header field. NAV also requires it to be
+ * unique per taxpayer, forever.
+ */
+export const REQUEST_ID_MAX_LENGTH = 30;
+/** Characters NAV allows in a `requestId`. */
+export const REQUEST_ID_PATTERN = /^[+a-zA-Z0-9_]{1,30}$/;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,MAAM,GAAG,uCAAuC,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,OAAO,GAAG,wCAAwC,CAAC;AAEhE,gFAAgF;AAChF,MAAM,CAAC,MAAM,OAAO,GAAG,wCAAwC,CAAC;AAEhE,mEAAmE;AACnE,MAAM,CAAC,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAElE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,SAAS,GAAG,2CAA2C,CAAC;AAErE,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AAEpC,sDAAsD;AACtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,uDAAuD,CAAC;AAE3F,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,4DAA4D,CAAC;AAE1F,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,UAAU,EAAE,mBAAmB;IAC/B,IAAI,EAAE,aAAa;CACX,CAAC;AAIX,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,wBAAwB;IACxB,sBAAsB;IACtB,kBAAkB;IAClB,oBAAoB;IACpB,yBAAyB;IACzB,mBAAmB;IACnB,eAAe;CACP,CAAC;AAIX;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC"}

package/dist/crypto/hash.d.ts

@@ -0,0 +1,16 @@
+/** Uppercase hexadecimal SHA-512 digest of a UTF-8 string. */
+export declare function sha512(value: string): string;
+/** Uppercase hexadecimal SHA3-512 digest of a UTF-8 string. */
+export declare function sha3_512(value: string): string;
+/**
+ * Hash of the technical user's password for the `user/passwordHash` field.
+ *
+ * NAV expects the uppercase hex SHA-512 digest of the password, declared on
+ * the element with `cryptoType="SHA-512"`.
+ */
+export declare function passwordHash(password: string): string;
+/** `cryptoType` attribute value used for `passwordHash`. */
+export declare const PASSWORD_HASH_CRYPTO_TYPE = "SHA-512";
+/** `cryptoType` attribute value used for `requestSignature` and invoice hashes. */
+export declare const SIGNATURE_CRYPTO_TYPE = "SHA3-512";
+//# sourceMappingURL=hash.d.ts.map

package/dist/crypto/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/crypto/hash.ts"],"names":[],"mappings":"AAUA,8DAA8D;AAC9D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,4DAA4D;AAC5D,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,aAAa,CAAC"}

package/dist/crypto/hash.js

@@ -0,0 +1,30 @@
+import { getCryptoProvider } from './provider.js';
+const encoder = new TextEncoder();
+function toHexUpper(bytes) {
+    let out = '';
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, '0');
+    return out.toUpperCase();
+}
+/** Uppercase hexadecimal SHA-512 digest of a UTF-8 string. */
+export function sha512(value) {
+    return toHexUpper(getCryptoProvider().sha512(encoder.encode(value)));
+}
+/** Uppercase hexadecimal SHA3-512 digest of a UTF-8 string. */
+export function sha3_512(value) {
+    return toHexUpper(getCryptoProvider().sha3_512(encoder.encode(value)));
+}
+/**
+ * Hash of the technical user's password for the `user/passwordHash` field.
+ *
+ * NAV expects the uppercase hex SHA-512 digest of the password, declared on
+ * the element with `cryptoType="SHA-512"`.
+ */
+export function passwordHash(password) {
+    return sha512(password);
+}
+/** `cryptoType` attribute value used for `passwordHash`. */
+export const PASSWORD_HASH_CRYPTO_TYPE = 'SHA-512';
+/** `cryptoType` attribute value used for `requestSignature` and invoice hashes. */
+export const SIGNATURE_CRYPTO_TYPE = 'SHA3-512';
+//# sourceMappingURL=hash.js.map

package/dist/crypto/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/crypto/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,SAAS,UAAU,CAAC,KAAiB;IACnC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpE,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;AAC3B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,UAAU,CAAC,iBAAiB,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,UAAU,CAAC,iBAAiB,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC;AAEnD,mFAAmF;AACnF,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC"}

package/dist/crypto/node-provider.d.ts

@@ -0,0 +1,9 @@
+import type { CryptoProvider } from './provider.js';
+/**
+ * The default {@link CryptoProvider}, backed by Node's built-in `node:crypto`.
+ *
+ * Works on Node, Bun and Deno. It does **not** work on Cloudflare Workers,
+ * whose `node:crypto` lacks SHA-3 — use {@link createWebCryptoProvider} there.
+ */
+export declare const nodeCryptoProvider: CryptoProvider;
+//# sourceMappingURL=node-provider.d.ts.map

package/dist/crypto/node-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-provider.d.ts","sourceRoot":"","sources":["../../src/crypto/node-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAShC,CAAC"}

package/dist/crypto/node-provider.js

@@ -0,0 +1,18 @@
+import { createHash, createDecipheriv, randomBytes } from 'node:crypto';
+/**
+ * The default {@link CryptoProvider}, backed by Node's built-in `node:crypto`.
+ *
+ * Works on Node, Bun and Deno. It does **not** work on Cloudflare Workers,
+ * whose `node:crypto` lacks SHA-3 — use {@link createWebCryptoProvider} there.
+ */
+export const nodeCryptoProvider = {
+    sha512: (data) => Uint8Array.from(createHash('sha512').update(data).digest()),
+    sha3_512: (data) => Uint8Array.from(createHash('sha3-512').update(data).digest()),
+    aes128EcbDecrypt: (ciphertext, key) => {
+        const decipher = createDecipheriv('aes-128-ecb', key, null);
+        decipher.setAutoPadding(false);
+        return Uint8Array.from(Buffer.concat([decipher.update(ciphertext), decipher.final()]));
+    },
+    randomBytes: (length) => Uint8Array.from(randomBytes(length)),
+};
+//# sourceMappingURL=node-provider.js.map

package/dist/crypto/node-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-provider.js","sourceRoot":"","sources":["../../src/crypto/node-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAChD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;IACjF,gBAAgB,EAAE,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE;QACpC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5D,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC/B,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9D,CAAC"}

package/dist/crypto/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The low-level cryptographic primitives the NAV protocol needs, abstracted so
+ * the library can run on any JavaScript runtime.
+ *
+ * The default is {@link nodeCryptoProvider}, backed by Node's built-in
+ * `node:crypto`. On runtimes whose `node:crypto` lacks SHA-3 — notably
+ * Cloudflare Workers (workerd/BoringSSL), where `createHash('sha3-512')` throws
+ * `Digest method not supported` — install {@link createWebCryptoProvider} via
+ * {@link setCryptoProvider} once at startup, before making any request.
+ */
+export interface CryptoProvider {
+    /** Raw SHA-512 digest of `data`. */
+    sha512(data: Uint8Array): Uint8Array;
+    /** Raw SHA3-512 digest of `data`. */
+    sha3_512(data: Uint8Array): Uint8Array;
+    /** AES-128 ECB decryption without padding; `key` is exactly 16 bytes. */
+    aes128EcbDecrypt(ciphertext: Uint8Array, key: Uint8Array): Uint8Array;
+    /** `length` cryptographically strong random bytes. */
+    randomBytes(length: number): Uint8Array;
+}
+/** The crypto provider currently backing every cryptographic helper. */
+export declare function getCryptoProvider(): CryptoProvider;
+/**
+ * Replace the active crypto provider. Call once at startup, before any NAV
+ * request — e.g. `setCryptoProvider(createWebCryptoProvider())` in a Worker.
+ */
+export declare function setCryptoProvider(provider: CryptoProvider): void;
+//# sourceMappingURL=provider.d.ts.map

package/dist/crypto/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/crypto/provider.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IACvC,yEAAyE;IACzE,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,UAAU,CAAC;IACtE,sDAAsD;IACtD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;CACzC;AAID,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAEhE"}

package/dist/crypto/provider.js

@@ -0,0 +1,14 @@
+import { nodeCryptoProvider } from './node-provider.js';
+let activeProvider = nodeCryptoProvider;
+/** The crypto provider currently backing every cryptographic helper. */
+export function getCryptoProvider() {
+    return activeProvider;
+}
+/**
+ * Replace the active crypto provider. Call once at startup, before any NAV
+ * request — e.g. `setCryptoProvider(createWebCryptoProvider())` in a Worker.
+ */
+export function setCryptoProvider(provider) {
+    activeProvider = provider;
+}
+//# sourceMappingURL=provider.js.map

package/dist/crypto/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/crypto/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAuBxD,IAAI,cAAc,GAAmB,kBAAkB,CAAC;AAExD,wEAAwE;AACxE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAwB;IACxD,cAAc,GAAG,QAAQ,CAAC;AAC5B,CAAC"}

package/dist/crypto/request-id.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate a `requestId` that satisfies NAV's constraints.
+ *
+ * NAV requires the value to match `[+a-zA-Z0-9_]{1,30}` and to be unique for
+ * the taxpayer across all requests ever sent — a replayed identifier is
+ * rejected with `INVALID_REQUEST_ID`. The generated value combines a
+ * millisecond timestamp with random characters, which is collision safe for
+ * practical throughput, but persisting issued identifiers is still the only
+ * way to be certain after a clock change.
+ *
+ * @param prefix optional caller prefix, useful for tracing (`[a-zA-Z0-9_+]`)
+ */
+export declare function createRequestId(prefix?: string): string;
+/** Throw unless `value` is a valid `requestId`. */
+export declare function assertRequestId(value: string): void;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/crypto/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../src/crypto/request-id.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAO,GAAG,MAAM,CAcrD;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAUnD"}

package/dist/crypto/request-id.js

@@ -0,0 +1,59 @@
+import { getCryptoProvider } from './provider.js';
+import { REQUEST_ID_MAX_LENGTH, REQUEST_ID_PATTERN } from '../constants.js';
+import { NavValidationError } from '../errors.js';
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/**
+ * Generate a `requestId` that satisfies NAV's constraints.
+ *
+ * NAV requires the value to match `[+a-zA-Z0-9_]{1,30}` and to be unique for
+ * the taxpayer across all requests ever sent — a replayed identifier is
+ * rejected with `INVALID_REQUEST_ID`. The generated value combines a
+ * millisecond timestamp with random characters, which is collision safe for
+ * practical throughput, but persisting issued identifiers is still the only
+ * way to be certain after a clock change.
+ *
+ * @param prefix optional caller prefix, useful for tracing (`[a-zA-Z0-9_+]`)
+ */
+export function createRequestId(prefix = 'ON') {
+    assertRequestIdChars(prefix, 'prefix');
+    const stamp = Date.now().toString(36).toUpperCase();
+    const available = REQUEST_ID_MAX_LENGTH - prefix.length - stamp.length;
+    if (available < 4) {
+        throw new NavValidationError('requestId prefix is too long', [
+            {
+                path: 'prefix',
+                code: 'REQUEST_ID_PREFIX_TOO_LONG',
+                message: `leaves only ${available} characters of entropy, need at least 4`,
+            },
+        ]);
+    }
+    return `${prefix}${stamp}${randomChars(Math.min(available, 8))}`;
+}
+/** Throw unless `value` is a valid `requestId`. */
+export function assertRequestId(value) {
+    if (!REQUEST_ID_PATTERN.test(value)) {
+        throw new NavValidationError('Invalid requestId', [
+            {
+                path: 'requestId',
+                code: 'INVALID_REQUEST_ID',
+                message: `must match ${REQUEST_ID_PATTERN.source}, got ${JSON.stringify(value)}`,
+            },
+        ]);
+    }
+}
+function assertRequestIdChars(value, path) {
+    if (!/^[+a-zA-Z0-9_]*$/.test(value)) {
+        throw new NavValidationError('Invalid requestId characters', [
+            { path, code: 'INVALID_REQUEST_ID', message: 'may only contain [+a-zA-Z0-9_]' },
+        ]);
+    }
+}
+function randomChars(length) {
+    const bytes = getCryptoProvider().randomBytes(length);
+    let out = '';
+    for (let i = 0; i < length; i += 1) {
+        out += ALPHABET[bytes[i] % ALPHABET.length];
+    }
+    return out;
+}
+//# sourceMappingURL=request-id.js.map

package/dist/crypto/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../../src/crypto/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,QAAQ,GAAG,gEAAgE,CAAC;AAElF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,MAAM,GAAG,IAAI;IAC3C,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,qBAAqB,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACvE,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,kBAAkB,CAAC,8BAA8B,EAAE;YAC3D;gBACE,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,4BAA4B;gBAClC,OAAO,EAAE,eAAe,SAAS,yCAAyC;aAC3E;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,kBAAkB,CAAC,mBAAmB,EAAE;YAChD;gBACE,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,cAAc,kBAAkB,CAAC,MAAM,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;aACjF;SACF,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,IAAY;IACvD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,kBAAkB,CAAC,8BAA8B,EAAE;YAC3D,EAAE,IAAI,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,gCAAgC,EAAE;SAChF,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/crypto/signature.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A single invoice (or annulment) operation as it contributes to the request
+ * signature of a `manageInvoice` / `manageAnnulment` call.
+ */
+export interface SignedOperation {
+    /** 1-based position inside the batch; operations are hashed in index order. */
+    index: number;
+    /** `CREATE`, `MODIFY`, `STORNO` or `ANNUL`. */
+    operation: string;
+    /** Base64 encoded payload exactly as it appears in the request XML. */
+    base64Payload: string;
+}
+/**
+ * Hash of one invoice operation, as consumed by {@link requestSignature} and
+ * as sent in the optional `electronicInvoiceHash` element.
+ *
+ * NAV defines it as `SHA3-512(operation || base64Payload)`, uppercase hex.
+ */
+export declare function operationHash(operation: string, base64Payload: string): string;
+/**
+ * Compute the `user/requestSignature` value.
+ *
+ * NAV specifies the signature as
+ *
+ * ```text
+ * SHA3-512( requestId || yyyyMMddHHmmss(timestamp) || signKey || hash(op1) || hash(op2) ... )
+ * ```
+ *
+ * where the per-operation hashes are only present for `manageInvoice` and
+ * `manageAnnulment` requests and must be concatenated in ascending `index`
+ * order. The timestamp must be the request header timestamp truncated to
+ * whole seconds and rendered in UTC without separators.
+ *
+ * @param requestId  the `header/requestId` of the same request
+ * @param timestamp  the `header/timestamp` of the same request
+ * @param signKey    the technical user's signature key (aláírókulcs)
+ * @param operations invoice/annulment operations of the batch, if any
+ */
+export declare function requestSignature(requestId: string, timestamp: Date | string, signKey: string, operations?: SignedOperation[]): string;
+//# sourceMappingURL=signature.d.ts.map

package/dist/crypto/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../src/crypto/signature.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,IAAI,GAAG,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,eAAe,EAAO,GACjC,MAAM,CAOR"}

package/dist/crypto/signature.js

@@ -0,0 +1,38 @@
+import { sha3_512 } from './hash.js';
+import { toSignatureTimestamp } from '../time.js';
+/**
+ * Hash of one invoice operation, as consumed by {@link requestSignature} and
+ * as sent in the optional `electronicInvoiceHash` element.
+ *
+ * NAV defines it as `SHA3-512(operation || base64Payload)`, uppercase hex.
+ */
+export function operationHash(operation, base64Payload) {
+    return sha3_512(`${operation}${base64Payload}`);
+}
+/**
+ * Compute the `user/requestSignature` value.
+ *
+ * NAV specifies the signature as
+ *
+ * ```text
+ * SHA3-512( requestId || yyyyMMddHHmmss(timestamp) || signKey || hash(op1) || hash(op2) ... )
+ * ```
+ *
+ * where the per-operation hashes are only present for `manageInvoice` and
+ * `manageAnnulment` requests and must be concatenated in ascending `index`
+ * order. The timestamp must be the request header timestamp truncated to
+ * whole seconds and rendered in UTC without separators.
+ *
+ * @param requestId  the `header/requestId` of the same request
+ * @param timestamp  the `header/timestamp` of the same request
+ * @param signKey    the technical user's signature key (aláírókulcs)
+ * @param operations invoice/annulment operations of the batch, if any
+ */
+export function requestSignature(requestId, timestamp, signKey, operations = []) {
+    const operationDigests = [...operations]
+        .sort((a, b) => a.index - b.index)
+        .map((op) => operationHash(op.operation, op.base64Payload))
+        .join('');
+    return sha3_512(`${requestId}${toSignatureTimestamp(timestamp)}${signKey}${operationDigests}`);
+}
+//# sourceMappingURL=signature.js.map

package/dist/crypto/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/crypto/signature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAelD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,aAAqB;IACpE,OAAO,QAAQ,CAAC,GAAG,SAAS,GAAG,aAAa,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,SAAwB,EACxB,OAAe,EACf,aAAgC,EAAE;IAElC,MAAM,gBAAgB,GAAG,CAAC,GAAG,UAAU,CAAC;SACrC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC;SAC1D,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,QAAQ,CAAC,GAAG,SAAS,GAAG,oBAAoB,CAAC,SAAS,CAAC,GAAG,OAAO,GAAG,gBAAgB,EAAE,CAAC,CAAC;AACjG,CAAC"}

package/dist/crypto/token.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Decrypt the `encodedExchangeToken` returned by `tokenExchange`.
+ *
+ * NAV encrypts the 16 character exchange token with AES-128 in ECB mode using
+ * the technical user's exchange key (csereklucs / "XML aláírás kulcs" pair) as
+ * the raw key, then base64 encodes the result. Padding is optional in
+ * practice: NAV historically returned an unpadded 16 byte block, while some
+ * environments return a PKCS#7 padded 32 byte block, so both are accepted.
+ *
+ * @param encodedToken base64 payload from the response
+ * @param exchangeKey  16 character exchange key of the technical user
+ */
+export declare function decodeExchangeToken(encodedToken: string, exchangeKey: string): string;
+//# sourceMappingURL=token.d.ts.map

package/dist/crypto/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/crypto/token.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA6BrF"}