Signature Cryptographique ECDSA pour les Factures ZATCA UBL 2.1 en Node.js
BLUF : La conformité avec la Phase 2 de la facturation électronique ZATCA (Fatoora) en Arabie Saoudite impose la signature cryptographique systématique des factures UBL 2.1 XML. Le processus requiert la canonisation XML (C14N), le calcul d'un hash SHA-256 sur les balises obligatoires, et une signature numérique ECDSA (courbe secp256k1) adossée à un certificat X.509 (CSID). Ce guide détaille l'architecture de référence ainsi qu'un exemple illustratif de prototype Node.js pour structurer la chaîne de traitement.
Exigences Réglementaires et Spécifications Cryptographiques ZATCA
L'autorité fiscale saoudienne (ZATCA) impose des règles strictes pour l'émission de factures fiscales standard (B2B) et simplifiées (B2C) au format UBL 2.1 XML. Chaque document doit comporter une empreinte cryptographique infalsifiable pour être validé par la plateforme Fatoora.
- Hachage de Facture : Condensat SHA-256 encodé en Base64 calculé sur le XML canonisé selon la norme C14N11.
- Signature ECDSA : Signature numérique générée sur la courbe elliptique secp256k1 au format DER/ASN.1.
- Certificat X.509 (CSID) : Identifiant cryptographique émis lors de l'enregistrement de l'ERP sur le portail ZATCA.
Étapes du Pipeline de Transformation XML et Signature
- Exclusion d'Éléments : Retirer les nœuds variables et signatures selon la spécification ZATCA (
ext:UBLExtensions,cac:Signatureetcac:AdditionalDocumentReferenceaveccbc:IDégal à'QR') avant le calcul du hachage. Les balises de schéma obligatoires telles quecbc:UBLVersionIDdoivent rester intactes. - Canonisation C14N : Normaliser les espaces et déclarations de namespaces du XML.
- Hachage SHA-256 : Calculer l'empreinte SHA-256 du XML canonisé encodée en Base64.
- Signature ECDSA (secp256k1) : Signer directement le XML canonisé ou le condensat brut sans double hachage.
- Génération du QR Code TLV : Encoder les 9 champs réglementaires au format Tag-Length-Value (TLV) en Base64.
Implémentation Illustrative en TypeScript (Non Validée sur le Sandbox ZATCA)
Avertissement technique : Ce code est un exemple conceptuel illustratif. Il n'a pas été validé sur l'environnement de test officiel (ZATCA Sandbox). Il incombe aux équipes de valider leur routine cryptographique avec les outils officiels avant toute mise en production.
import crypto from "node:crypto";
/**
* ILLUSTRATIVE ONLY - NOT VALIDATED AGAINST OFFICIAL ZATCA SANDBOX.
* In production, test against the official ZATCA Java SDK / Sandbox validator
* to confirm whether your integration requires direct signing or pre-hashed digest signing.
*/
export function signZatcaInvoice(
canonicalXml: string | Buffer,
privateKeyPem: string
): { invoiceHashBase64: string; signatureBase64: string } {
const xmlBuffer = Buffer.isBuffer(canonicalXml) ? canonicalXml : Buffer.from(canonicalXml, "utf-8");
const invoiceHash = crypto.createHash("sha256").update(xmlBuffer).digest();
const signer = crypto.createSign("SHA256");
signer.update(xmlBuffer);
const signatureBase64 = signer.sign(privateKeyPem, "base64");
return { invoiceHashBase64: invoiceHash.toString("base64"), signatureBase64 };
}
/** Signature directe d'un condensat SHA-256 précalculé (32 octets) */
export function signPrecomputedDigest(digestBuffer: Buffer, privateKeyPem: string): string {
return crypto.sign(null, digestBuffer, { key: privateKeyPem, dsaEncoding: "der" }).toString("base64");
}
export function verifyZatcaSignature(
invoiceHashBase64: string,
signatureBase64: string,
publicKeyPem: string
): boolean {
const hashBuffer = Buffer.from(invoiceHashBase64, "base64");
const verify = crypto.createVerify("SHA256");
verify.update(hashBuffer);
return verify.verify(publicKeyPem, signatureBase64, "base64");
}
Métriques et Exemples de Seuils Opérationnels (SLO Internes)
Ces indicateurs constituent des exemples de seuils d'ingénierie internes (SLO), et non des plafonds réglementaires imposés par la ZATCA :
zatca_api_clearance_latency_p99 < 0.8s(Exemple de SLO interne) : Cible de réactivité pour la validation B2B synchrone.zatca_reporting_dlq_count == 0: Zéro rejet sur les factures déclarées sous 24h.
Conseil & Partenariat Ingénierie de Plateforme et Cloud
Besoin d'un accompagnement senior pour fiabiliser et faire évoluer votre infrastructure ?
Des clusters Kubernetes et Talos Linux bare-metal à la réduction substantielle de facture cloud, en passant par la résolution des verrous PostgreSQL et l'architecture IA souveraine, j'interviens directement avec vos équipes de production.