DEV Community: Samir Chatwiti

Costa Rica v4.4: what's inside the 50-digit clave (and why your comprobante gets rejected)

Samir Chatwiti — Fri, 31 Jul 2026 11:53:22 +0000

Costa Rica's electronic invoicing moved to version 4.4 with Resolución MH-DGT-RES-0027-2024 — 146 changes, mandatory for all taxpayers since 1 September 2025, a brand-new document type (the Recibo Electrónico de Pago), and a new mandatory node (ProveedorSistemas, identifying the software that produced the document). If you maintain an ERP or billing integration for Costa Rica, you migrated recently, and you probably still get rejections you don't immediately understand.

Most of them trace back to one field: the clave numérica.

The 50-digit clave, decomposed
The clave isn't a random ID. It's a structured composite:

positions 1–3: country code (506)
positions 4–9: emission date as DDMMAA
positions 10–21: the issuer's cédula
positions 22–41: the consecutivo — which must equal the document's , and whose own digits encode the branch, terminal and document type (which must match the XML root element!)
position 42: situación (normal / contingencia / sin internet)
positions 43–50: security code
So the clave cross-references the emission date, the issuer, the consecutivo and the document type. Generate any of those inconsistently — a consecutivo counter that drifted, a clave built before a date rollover, a credit note wrapped in an invoice root — and the document is internally contradictory even though it validates against the XSD.

A real rejection, explained
Here's actual validator output for a signed v4.4 invoice where the consecutivo, a CABYS code and the total were altered (excerpt):

{
"valid": false,
"documentType": "FacturaElectronica",
"version": "4.4",
"signatureValid": false,
"errorCount": 5,
"findings": [
{ "level": "error", "ruleId": "CR-CLAVE-CONSECUTIVO",
"text": "Clave consecutivo segment (positions 22-41) '00100001010000000001' does not match the document's '00100001010000000009'.",
"location": "Clave / NumeroConsecutivo" },
{ "level": "error", "ruleId": "CR-CODE-CABYS",
"text": "CodigoCABYS '85110' must be exactly 13 digits (Anexos y Estructuras v4.4; national CABYS product/service catalogue code).",
"location": "CodigoCABYS" },
{ "level": "error", "ruleId": "CR-MATH-COMPROBANTE",
"text": "TotalComprobante (99999.00000) != TotalVentaNeta + TotalImpuesto + TotalOtrosCargos - TotalIVADevuelto (11300.00000).",
"location": "ResumenFactura/TotalComprobante" }
]
}
Plus a CR-SIG-DOC-DIGEST mismatch — the XAdES-EPES signature caught the tampering too, because the recomputed document digest no longer matches what was signed.

Note what the official clave lookup can't tell you: VerificaTuFactura and the ATV consultation only answer "has Hacienda received this clave?" — nothing about a document you haven't sent yet, and nothing about why it's malformed.

Pre-flight in one call
The output comes from the Costa Rica e-Invoice Validator v4.4 (Hacienda) — keyless REST API, free tier available:

curl --request POST \
--url https://costa-rica-e-invoice-validator-v4-4-hacienda.p.rapidapi.com/validate \
--header 'Content-Type: application/xml' \
--header 'x-rapidapi-host: costa-rica-e-invoice-validator-v4-4-hacienda.p.rapidapi.com' \
--header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
--data-binary @comprobante.xml
It auto-detects all 8 v4.4 document types (including the new REP), validates the official Hacienda XSDs, decomposes and cross-checks the clave, enforces the v4.4 ProveedorSistemas requirement, checks CABYS and the other code lists, reconciles totals/IVA, and verifies the XAdES-EPES signature end to end (document digest, SignedProperties digest, RSA-SHA256, EPES policy presence). Keyless and stateless — no ATV login, no certificate, in-memory validation only.

The TRIBU-CR angle
Costa Rica is migrating its platform to TRIBU-CR, so the schema/annex set will keep moving — v4.4 was itself a 146-change step. If you hand-rolled your validation, every sub-version is a rebuild. A validator whose XSDs and code lists are swappable data turns that churn into someone else's problem.

Scope note: trust-chain verification to the SINPE/MICITT roots, live CABYS catalogue existence and the clave's acceptance require Hacienda's online services — valid: true means "structurally ready", not "accepted".

I maintain validators like this for five mandated e-invoicing regimes (Malaysia, Dominican Republic, Nigeria, Bolivia, Costa Rica) — overview with links: github.com/SamirChatwiti/e-invoice-validators.

Bolivia's CUF: the invoice control code you can't fake (and how to verify it in one call)

Samir Chatwiti — Fri, 31 Jul 2026 11:40:43 +0000

Bolivia's Sistema de Facturación Electrónica en Línea (SFV/SIAT) reached full coverage on 1 October 2025 — the last taxpayer groups are now required to emit digitally signed XML invoices to the SIN. Every one of those invoices carries a CUF (Código Único de Facturación): a long hex string that most integrations treat as an opaque token.

It isn't opaque. The CUF is deterministically derived from the invoice header — NIT of the issuer, emission timestamp, branch (sucursal), invoice number, point of sale, sector, modality — run through the SIN's Módulo 11 self-check digit algorithm and encoded in Base16, with the current CUFD control code appended.

Which means two things:

If any header field and the CUF disagree, the invoice is inconsistent — even if the XML is schema-valid.
You can verify a CUF offline, by rebuilding it. Most validators just regex it. Rebuilding it is the real check.
Rebuilding a real CUF
Run the SIN's own published example invoice through a validator that reimplements the algorithm:

BO-CUF-VERIFY: CUF VERIFIES: its Base16 prefix reproduces from the header via the
SIN Modulo 11 self-check digit (modalidad=1, tipoEmision=1, tipoFactura=1);
recovered CUFD control code = '67A75AC82F24C74'.
The official example reproduces bit for bit — and the CUFD control code pops out of the decomposition.

Now tamper with one digit of that CUF and change montoTotal. Real output:

{
"valid": false,
"documentType": "facturaElectronicaCompraVenta",
"signatureValid": false,
"errorCount": 3,
"warningCount": 3,
"findings": [
{ "level": "warning", "ruleId": "BO-CUF-VERIFY",
"text": "CUF does NOT reconcile: no standard modalidad/tipoEmision/tipoFactura combination reproduces its Base16 prefix from the header (nitEmisor=1003579028, fechaEmision=20211007090124178, sucursal=0, numeroFactura=1, pos=0, sector=1) using the SIN Modulo 11 algorithm. The CUF or a header field may be inconsistent.",
"location": "cabecera/cuf" },
{ "level": "error", "ruleId": "BO-MATH-TOTAL",
"text": "montoTotal (500) != sum(subTotal) - descuentoAdicional (99).",
"location": "cabecera/montoTotal" }
]
}
The validator tells you which header fields it tried to reconcile against — that's the difference between "your CUF is wrong somewhere" and an actionable finding.

The full pre-flight in one call
The output above comes from the Bolivia SIAT e-Invoice Validator (SFV) — keyless REST API, free tier available:

curl --request POST \
--url https://bolivia-siat-e-invoice-validator-sfv.p.rapidapi.com/validate \
--header 'Content-Type: application/xml' \
--header 'x-rapidapi-host: bolivia-siat-e-invoice-validator-sfv.p.rapidapi.com' \
--header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
--data-binary @factura.xml
Layers checked: official SIN XSDs per document type (including the SignatureSchema) → SIN parametric code ranges (documento de identidad, método de pago, moneda, unidad de medida) → CUF/CUFD reconstruction → totals math per the SIN's Validaciones por Documento Sector → enveloped XML-DSig (document digest + RSA-SHA256 against the embedded certificate).

Keyless and stateless: no SIN account, no private key, nothing stored — the invoice is validated in-memory and discarded. Safe to run in CI on every generated document.

Practical takeaways
Don't regex the CUF — rebuild it. A format check passes tampered and stale CUFs alike; the Módulo 11 reconstruction doesn't.
Validate before the SIN sees it. Assert on ruleIds (BO-STRUCT-, BO-CODE-, BO-CUF-, BO-MATH-, BO-SIG-*) in your tests.
Scope honestly: whether a NIT is registered or a CUFD is currently live requires the SIN's online services; the trust chain to Bolivia's national CA (ADSIB) isn't checkable offline. valid: true means "consistent and ready", not "accepted".
I maintain validators like this for five mandated e-invoicing regimes (Malaysia, Dominican Republic, Nigeria, Bolivia, Costa Rica) — overview with links: github.com/SamirChatwiti/e-invoice-validators.

Nigeria's e-invoicing mandate: the validation layer generic Peppol tools won't give you

Samir Chatwiti — Fri, 31 Jul 2026 11:24:32 +0000

Nigeria's e-invoicing mandate is live. Under the Nigeria Tax Administration Act 2025, the NRS (formerly FIRS) runs a pre-clearance system — the Merchant-Buyer Solution (FIRSMBS) — where every invoice is submitted, validated, and only becomes a legal document once it comes back with an IRN (Invoice Reference Number), a CSID cryptographic stamp and a QR code. Large taxpayers (₦5B+ turnover) have been in since 1 November 2025; the phased rollout continues. Non-compliance costs about ₦1,000,000 up front plus ₦10,000 per day.

The format is Peppol BIS Billing 3.0-based UBL 2.1, so a common integrator reflex is: "I'll run it through a free Peppol validator, green check, ship it."

That reflex produces invoices the NRS rejects.

What the generic tools don't check
Free Peppol/EN 16931 validators stop at the European base layer. The Nigerian profile adds requirements they know nothing about:

Nigerian TIN on both parties — seller and buyer, as PartyTaxScheme/CompanyID or PartyIdentification/ID schemeID='TIN', in the FIRS format.
Per-line VAT — Nigeria expects VAT broken out at line level, not only in the document totals.
NGN expectations and local unit codes.
The IRN / CSID / QR clearance blocks — their presence and structure on cleared documents.
Every one of those is invisible to a vanilla BIS check, and every one of them is a rejection at the NRS.

A real failing invoice
Here's the actual validator output for a UBL invoice missing the buyer's TIN and the IRN block:

{
"valid": false,
"documentType": "380",
"hasIRN": false,
"hasCSID": true,
"hasQR": true,
"errorCount": 2,
"findings": [
{ "level": "error", "ruleId": "NG-RULE-BUYER-TIN",
"text": "Nigerian TIN for the customer (buyer) is missing. NRS requires a Tax Identification Number for both parties (as PartyTaxScheme/CompanyID or PartyIdentification/ID schemeID='TIN').",
"location": "cac:AccountingCustomerParty" },
{ "level": "error", "ruleId": "NG-IRN-ABSENT",
"text": "No Invoice Reference Number (IRN) found. A cleared NRS invoice carries an IRN (cbc:UUID or cac:AdditionalDocumentReference[cbc:ID='IRN']). Structure check only.",
"location": "cbc:UUID / cac:AdditionalDocumentReference" }
]
}
Note the booleans (hasIRN, hasCSID, hasQR): handy for a quick gate — "is this document post-clearance complete?" — without parsing the findings.

One call, the whole stack
The output comes from the Nigeria NRS/FIRS E-Invoice Validator (keyless REST API, free tier available). It layers the checks: official OASIS UBL 2.1 XSD → EN 16931 / Peppol BIS 3.0 base fields and ISO code lists → the Nigeria-specific rules (NG-RULE-) → IRN/CSID/QR structure (NG-IRN-, NG-CSID-, NG-QR-).

curl --request POST \
--url https://nigeria-nrs-firs-e-invoice-validator.p.rapidapi.com/validate \
--header 'Content-Type: application/xml' \
--header 'x-rapidapi-host: nigeria-nrs-firs-e-invoice-validator.p.rapidapi.com' \
--header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
--data-binary @invoice.xml
XML or JSON body, JSON verdict either way, always HTTP 200 with "valid": true|false. Keyless and stateless — no NRS login, no certificate, the invoice is validated in-memory and discarded — so it runs happily in CI or inside an Access Point Provider's onboarding flow.

Honest limits
The CSID is signed by the NRS itself; verifying its cryptographic authenticity would require the NRS signing certificate, which nobody outside the authority holds. So IRN/CSID/QR checks are structural — present and well-formed. valid: true is a pre-clearance readiness signal, not proof of clearance.

That's exactly what you want in CI though: catch the TIN you forgot, the per-line VAT you flattened, the IRN block your serializer dropped — before the NRS does, and before the daily penalties start.

Dominican Republic e-CF: how one tampered byte invalidates your invoice (and how to catch it)

Samir Chatwiti — Fri, 31 Jul 2026 11:12:16 +0000

Under Ley 32-23, the Dominican Republic requires businesses to issue Comprobantes Fiscales Electrónicos (e-CF): digitally signed XML documents transmitted to the DGII in real time. The rollout is phased by taxpayer size, and the small/medium wave is underway — which means a lot of teams are wiring e-CF generation into ERPs and billing systems right now.

Here's the thing about signed tax documents that surprises integrators: the signature freezes every byte. Touch the XML after signing — reformat it, "fix" an amount, let a proxy re-encode it — and the document is cryptographically dead, even if it still looks fine to the eye.

An experiment: falsify a real e-CF
Take a genuinely signed e-CF (type 31, Factura de Crédito Fiscal Electrónica), then do two small things a buggy pipeline could do:

change the e-NCF prefix from E31… to E32…
bump MontoTotal to a different number
Then run it through a validator that recomputes everything. Real output:

{
"valid": false,
"documentType": "31",
"signatureValid": false,
"errorCount": 2,
"warningCount": 2,
"findings": [
{ "level": "error", "ruleId": "DO-NCF-TYPE",
"text": "e-NCF type digits '32' do not match TipoeCF '31'.",
"location": "IdDoc/eNCF" },
{ "level": "error", "ruleId": "DO-MATH-TOTAL",
"text": "MontoTotal (999999.99) != MontoGravadoTotal + MontoExento + TotalITBIS + MontoImpuestoAdicional (637.2).",
"location": "Totales/MontoTotal" },
{ "level": "warning", "ruleId": "DO-SIG-DOC-DIGEST",
"text": "Document digest MISMATCH: signed DigestValue cBg59omGSW41xtQT7Q4nL54/Ueq6UObAEfP+/gf1aYg= does not match the recomputed SHA-256. The document content differs from what was signed, or a different canonicalization was used.",
"location": "ds:Reference[@uri='']" }
]
}
Three independent layers caught it: the e-NCF consistency rule, the ITBIS/totals math, and the signature digest — the recomputed SHA-256 of the document no longer matches what was signed.

That last one is the check most homemade validators skip, because it requires re-canonicalizing the XML exactly as the signer did (enveloped transform, inclusive C14N) before hashing. Skip it, and your pipeline will happily emit documents the DGII will reject.

Running the check yourself
The output above comes from the Dominican Republic e-CF Validator (DGII) — a keyless REST API (free tier available). One call:

curl --request POST \
--url https://dominican-republic-e-cf-validator-dgii.p.rapidapi.com/validate \
--header 'Content-Type: application/xml' \
--header 'x-rapidapi-host: dominican-republic-e-cf-validator-dgii.p.rapidapi.com' \
--header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
--data-binary @ecf.xml
It checks the e-CF v1.0 structure (XSD), DGII code lists, the e-NCF number and its consistency with the document type, ITBIS/totals reconciliation, and the full enveloped signature — document digest and RSA-SHA256 SignatureValue against the embedded certificate. On an untampered, genuinely signed e-CF it returns "valid": true, "signatureValid": true.

Keyless and stateless: no DGII account, no certificate upload, the document is validated in-memory and discarded. That makes it safe to run from CI on every generated document, not just in production.

Practical takeaways
Sign last. Any serialization step after signing (pretty-printing, encoding changes, namespace "cleanup") kills the digest.
Validate at generation time — assert on ruleIds (DO-STRUCT-, DO-NCF-, DO-MATH-, DO-SIG-) in your test suite.
Don't trust "it parses" as "it's valid". XML well-formedness says nothing about e-NCF consistency, ITBIS math, or the signature.
Scope note: a keyless pre-flight can't verify the trust chain to a DGII/INDOTEL-recognized CA or perform the real-time submission — valid: true means "ready to submit", not "accepted by the DGII".

Why MyInvois rejects your e-invoice — and how to catch it before LHDN does

Samir Chatwiti — Fri, 31 Jul 2026 11:00:22 +0000

Malaysia's MyInvois mandate is now real for most businesses — Phase 4 pulled companies with RM1-5M turnover into the system in January 2026. If you build or integrate the software that emits those e-invoices (an ERP, a POS, a SaaS billing module), you have discovered the painful part: LHDN rejects documents, and it rejects them after you submit them.

This post walks through the most common rejection causes I've seen, and a way to catch all of them in CI before anything reaches LHDN.

The usual suspects
A MyInvois document (UBL 2.1, XML or JSON) fails for a handful of recurring reasons:

Structure — the document doesn't validate against the official OASIS UBL 2.1 XSD: wrong element order, missing wrappers, bad namespaces.
Missing mandatory fields — invoice type code, issue date/time, currency, supplier or buyer TIN, MSIC code, line items, TaxTotal, LegalMonetaryTotal.
Code-list violations — a currency that isn't ISO-4217, an MSIC code that doesn't exist, a state code or unit code outside the LHDN tables.
Totals that don't add up — TaxInclusiveAmount ≠ TaxExclusiveAmount + tax, line extensions that don't sum.
A broken XAdES signature — the enveloped signature's document digest doesn't match (the document was touched after signing), the SignedProperties digest is wrong, or the signing certificate is expired / lacks the Document Signing EKU.
The first four are boring but frequent. The fifth is the sneaky one: serialize your XML differently after signing — pretty-print it, re-encode it, let a middleware "fix" a namespace — and the digest no longer matches.

Pre-flight, not post-mortem
The pattern that works: validate every document at the moment it's generated, not when LHDN bounces it. Keyless validation (no certificate, no MyInvois account, no token) means you can run it anywhere — CI pipelines, a pre-submit hook, a partner-onboarding gate.

Here's the whole check as one HTTP call, using the Malaysia MyInvois E-Invoice Validator (free tier available):

curl --request POST \
--url https://malaysia-myinvois-e-invoice-validator.p.rapidapi.com/validate \
--header 'Content-Type: application/xml' \
--header 'x-rapidapi-host: malaysia-myinvois-e-invoice-validator.p.rapidapi.com' \
--header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
--data-binary @invoice.xml
You always get HTTP 200 with a JSON verdict. Here is a real response for an invoice with a missing supplier TIN and a bogus currency:

{
"valid": false,
"documentType": "01",
"errorCount": 3,
"warningCount": 5,
"findings": [
{ "level": "error", "ruleId": "MY-CORE-SUPPLIER-TIN",
"text": "Supplier TIN (PartyIdentification schemeID='TIN') is missing.",
"location": "cac:AccountingSupplierParty" },
{ "level": "error", "ruleId": "MY-CODE-CURRENCY",
"text": "DocumentCurrencyCode 'XYZ' is not an ISO-4217 code.",
"location": "cbc:DocumentCurrencyCode" }
]
}
Every finding has a stable ruleId (MY-STRUCT-, MY-CORE-, MY-CODE-, MY-MATH-, MY-SIG-*), so you can assert on specific rules in tests, or map them to user-facing messages in your product.

The signature layer goes deep for a keyless check: document digest recomputation (with the exact canonicalization MyInvois expects), SignedProperties digest, RSA-SHA256 SignatureValue against the embedded X.509, certificate validity window, Document Signing EKU, and the XAdES SigningCertificate binding.

What a pre-flight can't do
Honesty matters in compliance tooling. A keyless validator cannot: verify the trust chain to the LHDNM / Pos Digicert CA, confirm a TIN actually exists, or perform the submission itself (the unique ID and QR come back from LHDN). valid: true means "structurally ready to submit", not "accepted".

Wrap-up
Validate at generation time, not at submission time.
Assert on ruleIds in CI so regressions in your invoice generator are caught by the build.
Treat the XAdES signature as part of your test surface — most "mystery" rejections are digest mismatches introduced after signing.
I maintain validators like this for five mandated e-invoicing regimes (Malaysia, Dominican Republic, Nigeria, Bolivia, Costa Rica) — overview with links here: github.com/SamirChatwiti/e-invoice-validators.

Why I’m finally open-sourcing my architectural work after 20 years building private enterprise systems

Samir Chatwiti — Fri, 10 Apr 2026 23:17:01 +0000

Hey everyone! 👋

I'm Samir, a Principal Software Architect and Tech Lead based in Casablanca, Morocco 🇲🇦.

With over 20 years in software engineering (including 7 years as a Director of Operations), I've spent most of my career building private, enterprise-grade systems and internal client platforms. Recently, I've shifted into independent consulting and decided to start open-sourcing my architectural work!

Currently, I'm heavily focused on Zero-Trust Architectures and Proof-of-Presence protocols. I'm building out the WITI ecosystem, and I recently open-sourced its core module: QRPruf (a high-security cryptographic certifier built with Flutter/Dart and Riverpod 3.0). My other technical loves are Laravel (PHP) and AI integrations (Gemini/Replicate).

I joined DEV to connect with other senior engineers, share some deep dives into Clean Architecture, and learn from this amazing community.

Feel free to say hi, I’m always open to talking about mobile architecture, security, or just geeking out over code!

Check out what I'm building here: github.com/sanadidari (Stars are always appreciated! ⭐)

Building a Zero-Trust Proof-of-Presence Protocol with Flutter & Supabase

Samir Chatwiti — Thu, 09 Apr 2026 23:02:59 +0000

Building a Zero-Trust Proof-of-Presence Protocol with Flutter & Supabase

How I designed a cryptographic certification system for judicial officers — GPS, AES-GCM, SHA-256, and Mocktail tests.

The Problem

Imagine you are a judicial officer (huissier de justice) in Morocco. Your job requires you to physically appear at a location — a home, a court, a business — and serve a legal document. That act of presence is legally binding.

The question: how do you prove, with cryptographic certainty, that you were physically present at a specific location, at a specific time, and that the evidence you captured was not tampered with afterward?

This is the problem I solved building QRPruf — a zero-trust proof-of-presence protocol embedded in a Flutter mobile app.

What "Zero-Trust" Means in This Context

Zero-trust doesn't mean "trust nothing from the network." Here it means:

No server is trusted to compute the proof — all hashing and encryption happens on-device, in an Isolate
No timestamp can be faked — GPS coordinates and device time are cryptographically bound to the file hash at capture time
No file can be silently replaced — AES-GCM authentication tags detect any tampering
No identity can be assumed — every proof payload is signed with a canonical SHA-256 that includes the user's subject ID

Architecture Overview

[Camera / Mic / GPS]
        │
        ▼
[ProofCryptoService]          ← On-device, runs in Dart Isolate
  • SHA-256 hash of raw file
  • AES-GCM encryption (256-bit key)
  • IV prepended to ciphertext
        │
        ▼
[Proof Payload]
  • proof_id, subject_id, timestamp
  • GPS coordinates
  • item hashes + sizes
  • canonical_hash (SHA-256 of sorted JSON)
        │
        ▼
[Supabase Edge Function]      ← Server-side verification only
  • Verifies canonical hash
  • Issues signed proof certificate
  • Stores encrypted blobs in Storage
        │
        ▼
[QR Code]                     ← Shareable proof certificate

The critical design decision: the server never sees the original files, only the encrypted blobs and their hashes.

The Crypto Layer: ProofCryptoService

This service runs entirely inside a Dart Isolate via compute() — no UI thread blocking, no memory spikes on large video files.

import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:crypto/crypto.dart' as crypto;
import 'package:encrypt/encrypt.dart' as encrypt;
import 'package:path_provider/path_provider.dart';

class ProofCryptoService {
  static final ProofCryptoService _instance = ProofCryptoService._internal();
  factory ProofCryptoService() => _instance;
  ProofCryptoService._internal();

  /// Runs in a background Isolate — safe for large files
  static Map<String, dynamic> _encryptIsolate(Map<String, dynamic> args) {
    final bytes = File(args['inputPath']).readAsBytesSync();

    // 1. Hash the original (before encryption)
    final sha256 = crypto.sha256.convert(bytes).toString();

    // 2. AES-GCM encryption — 256-bit key, 96-bit IV
    final key = encrypt.Key.fromBase64(args['keyBase64']);
    final iv  = encrypt.IV.fromSecureRandom(12);
    final enc = encrypt.Encrypter(encrypt.AES(key, mode: encrypt.AESMode.gcm));
    final encrypted = enc.encryptBytes(bytes, iv: iv);

    // 3. Write [IV (12 bytes) | ciphertext] to disk — avoids RAM duplication
    final out = File(args['outputPath']).openSync(mode: FileMode.write);
    out.writeFromSync(iv.bytes);
    out.writeFromSync(encrypted.bytes);
    out.closeSync();

    return {'sha256': sha256, 'size': bytes.length};
  }

  Future<Map<String, dynamic>?> encryptFile(
    String inputPath,
    encrypt.Key key, {
    bool skipEncryption = false, // Videos: hash-only to avoid OOM
  }) async {
    if (skipEncryption) {
      return compute(_hashOnlyIsolate, {'inputPath': inputPath});
    }

    final dir      = await getApplicationDocumentsDirectory();
    final tempPath = '${dir.path}/enc_${DateTime.now().microsecondsSinceEpoch}.bin';

    final result = await compute(_encryptIsolate, {
      'inputPath':  inputPath,
      'outputPath': tempPath,
      'keyBase64':  key.base64,
    });

    return {'path': tempPath, ...result};
  }
}

Why AES-GCM specifically?

GCM (Galois/Counter Mode) provides both confidentiality and authentication. If a single byte of the encrypted file is changed after encryption, decryption throws an exception — the authentication tag fails. This is what makes the proof tamper-evident.

Why compute() for the Isolate?

Flutter's compute() runs a top-level function in a separate Isolate. For a 50MB video file, this means:

The main thread stays responsive
Memory is not duplicated between threads (Dart Isolates don't share heap)
AES operation on large files won't trigger OOM kills

The Verification Layer: ProofVerifier

A proof is only useful if anyone can verify it independently. The verification logic is intentionally pure — no network, no platform dependencies.

import 'dart:convert';
import 'package:crypto/crypto.dart';
import 'package:qrpruf/models/proof.dart';

class ProofVerifier {
  static bool verify(Proof proof) {
    final canonical = _canonicalize({
      'proof_id':            proof.proofId,
      'proof_version':       proof.proofVersion,
      'status':              proof.status,
      'created_at':          proof.createdAt.toIso8601String(),
      'timestamp_primary':   proof.timestampPrimary.toIso8601String(),
      'timezone':            proof.timezone,
      'subject_id':          proof.subjectId,
      'items_count':         proof.itemsCount,
      'hash_algorithm':      proof.hashAlgorithm,
      'signature_algorithm': proof.signatureAlgorithm,
      'public_key_id':       proof.publicKeyId,
      'auth_method':         proof.authMethod,
      'confidence_level':    proof.confidenceLevel,
      'purpose_type':        proof.purposeType,
      'purposes':            proof.purposes,
    });

    final computed = sha256.convert(utf8.encode(canonical)).toString();
    return computed == proof.proofHash;
  }

  /// Sort all keys recursively before JSON encoding.
  /// This makes the hash key-order independent.
  static String _canonicalize(Map<String, dynamic> data) =>
      jsonEncode(_sortValue(data));

  static dynamic _sortValue(dynamic value) {
    if (value is List) return value.map(_sortValue).toList();
    if (value is Map) {
      final keys = value.keys.toList()..sort();
      return {for (final k in keys) k: _sortValue(value[k])};
    }
    return value;
  }
}

The canonical hash is key-order independent. This matters because JSON serializers across platforms (Dart, JavaScript, Python) don't guarantee key ordering. By sorting keys before hashing, the same proof verifies correctly regardless of which platform serialized it.

Testing with Mocktail

Testing cryptographic code requires determinism. Mocktail (the Dart mocking library — no code generation) lets us test the full stack without hitting real Supabase endpoints.

Testing ProofVerifier — pure logic, no mocks needed

import 'dart:convert';
import 'package:crypto/crypto.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:qrpruf/models/proof.dart';
import 'package:qrpruf/utils/proof_verifier.dart';

// Replicate the canonicalization in the test — independently
String _computeExpectedHash(Proof proof) {
  dynamic sort(dynamic v) {
    if (v is List) return v.map(sort).toList();
    if (v is Map) {
      final keys = v.keys.toList()..sort();
      return {for (final k in keys) k: sort(v[k])};
    }
    return v;
  }

  final data = {
    'proof_id': proof.proofId,
    'auth_method': proof.authMethod,
    // ... all fields
  };
  return sha256.convert(utf8.encode(jsonEncode(sort(data)))).toString();
}

void main() {
  group('ProofVerifier', () {
    test('returns true for correct hash', () {
      final proof = buildTestProof(hash: _computeExpectedHash(baseProof));
      expect(ProofVerifier.verify(proof), isTrue);
    });

    test('returns false for tampered hash', () {
      final proof = buildTestProof(hash: 'a' * 64);
      expect(ProofVerifier.verify(proof), isFalse);
    });

    test('is deterministic — same proof verifies twice', () {
      final proof = buildTestProof(hash: _computeExpectedHash(baseProof));
      expect(ProofVerifier.verify(proof), isTrue);
      expect(ProofVerifier.verify(proof), isTrue);
    });
  });
}

Testing ProofCryptoService — file system + Isolate

import 'dart:io';
import 'dart:convert';
import 'package:flutter_test/flutter_test.dart';
import 'package:crypto/crypto.dart' as crypto;
import 'package:encrypt/encrypt.dart' as encrypt;
import 'package:qrpruf/features/proofs/data/proof_crypto_service.dart';

void main() {
  group('AES-GCM roundtrip', () {
    test('encrypt then decrypt returns original bytes', () {
      final key       = encrypt.Key.fromSecureRandom(32);
      final iv        = encrypt.IV.fromSecureRandom(12);
      final encrypter = encrypt.Encrypter(
        encrypt.AES(key, mode: encrypt.AESMode.gcm)
      );

      final original  = utf8.encode('preuve judiciaire confidentielle');
      final encrypted = encrypter.encryptBytes(original, iv: iv);
      final decrypted = encrypter.decryptBytes(encrypted, iv: iv);

      expect(decrypted, equals(original));
    });

    test('wrong key throws — GCM auth tag mismatch', () {
      final key1 = encrypt.Key.fromSecureRandom(32);
      final key2 = encrypt.Key.fromSecureRandom(32);
      final iv   = encrypt.IV.fromSecureRandom(12);

      final enc1      = encrypt.Encrypter(encrypt.AES(key1, mode: encrypt.AESMode.gcm));
      final enc2      = encrypt.Encrypter(encrypt.AES(key2, mode: encrypt.AESMode.gcm));
      final encrypted = enc1.encryptBytes(utf8.encode('secret'), iv: iv);

      expect(() => enc2.decryptBytes(encrypted, iv: iv), throwsA(anything));
    });
  });

  group('ProofCryptoService.encryptFile — skipEncryption', () {
    late Directory tempDir;

    setUp(() async {
      tempDir = await Directory.systemTemp.createTemp('qrpruf_test_');
    });
    tearDown(() async => tempDir.delete(recursive: true));

    test('returns correct SHA-256 for known content', () async {
      final content = utf8.encode('contenu connu');
      final file    = File('${tempDir.path}/sample.jpg')
        ..writeAsBytesSync(content);

      final result = await ProofCryptoService().encryptFile(
        file.path,
        encrypt.Key.fromSecureRandom(32),
        skipEncryption: true,
      );

      expect(
        result?['sha256'],
        equals(crypto.sha256.convert(content).toString()),
      );
    });

    test('throws when file does not exist', () {
      expect(
        () => ProofCryptoService().encryptFile(
          '/nonexistent/file.jpg',
          encrypt.Key.fromSecureRandom(32),
          skipEncryption: true,
        ),
        throwsA(isA<Exception>()),
      );
    });
  });
}

The CI Pipeline

Every push to main runs this GitHub Actions workflow:

name: QRPruf Flutter CI

on:
  push:
    branches: [ main ]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
          cache: true

      - run: flutter pub get

      # Generate Riverpod annotations BEFORE tests
      - run: dart run build_runner build --delete-conflicting-outputs

      - run: flutter analyze
      - run: flutter test --coverage

The key insight: build_runner runs before flutter test. Generated code (Riverpod annotations) must exist before tests can import it. This is a common CI mistake that makes the green badge meaningless.

What I Learned

1. Isolates are not optional for crypto on mobile.
AES-256 on a 30MB video on a mid-range Android device takes ~800ms. On the main thread, that freezes the UI. In an Isolate, the user sees a progress indicator.

2. Canonical hashing is the hardest part to get right.
The first version of ProofVerifier failed intermittently because JSON key ordering differed between the app (Dart) and the verification server (Node.js). Sorting keys recursively before hashing fixed it permanently.

3. skipEncryption for video is a pragmatic tradeoff.
Dart's pure AES engine runs out of RAM on files larger than ~100MB. For large videos, we hash the original and upload a non-encrypted stream with TLS. The hash still proves tamper-evidence — only confidentiality is reduced, and large video files in court contexts are less sensitive than text documents.

4. Mocktail > Mockito for Flutter.
No build_runner, no @GenerateMocks, no code generation step to maintain. Just class MockX extends Mock implements X {} — one line.

The Result

A judicial officer opens QRPruf, selects the act type, captures images/audio/video on-site. Within seconds, a QR code is generated that encodes a cryptographic proof — verifiable by any court system without trusting the officer's device, the network, or the server.

The proof survives even if Supabase is compromised: the canonical hash computed on-device will not match a server-generated replacement.

That is what zero-trust means in practice.

DEV Community: Samir Chatwiti

Costa Rica v4.4: what's inside the 50-digit clave (and why your comprobante gets rejected)

Bolivia's CUF: the invoice control code you can't fake (and how to verify it in one call)

Nigeria's e-invoicing mandate: the validation layer generic Peppol tools won't give you

Dominican Republic e-CF: how one tampered byte invalidates your invoice (and how to catch it)

Why MyInvois rejects your e-invoice — and how to catch it before LHDN does

Why I’m finally open-sourcing my architectural work after 20 years building private enterprise systems

Building a Zero-Trust Proof-of-Presence Protocol with Flutter & Supabase

Building a Zero-Trust Proof-of-Presence Protocol with Flutter & Supabase

The Problem

What "Zero-Trust" Means in This Context

Architecture Overview

The Crypto Layer: ProofCryptoService

The Verification Layer: ProofVerifier

Testing with Mocktail

Testing ProofVerifier — pure logic, no mocks needed

Testing ProofCryptoService — file system + Isolate

The CI Pipeline

What I Learned

The Result

Links