🔐 FIRS e-Invoicing

A comprehensive Node.js package with CLI support for securely encrypting IRNs (Invoice Reference Numbers) and certificates, generating QR codes, and decrypting invoice data — specifically built for digital tax systems like Nigeria's FIRS e-Invoicing platform.

🚀 Features

• 🔒 Secure Encryption: RSA encryption for IRNs and certificates using public keys
• 🔓 Reliable Decryption: Decrypt encrypted invoice payloads with private keys
• 📱 QR Code Generation: Generate QR codes as PNG images and base64 strings
• 📦 Flexible Integration: Use as Node.js module or standalone CLI tool
• ⚡ High Performance: Optimized for production environments
• 🧪 Well Tested: Extensive test coverage for reliability

📦 Installation

Using npm

# For local/embedded use
npm install firs-einvoicing

# Global installation for CLI access
npm install -g firs-einvoicing

Using Yarn

# For local/embedded use
yarn add firs-einvoicing

# Global installation for CLI access
yarn global add firs-einvoicing

Using pnpm

# For local/embedded use
pnpm add firs-einvoicing

# Global installation for CLI access
pnpm add -g firs-einvoicing

Quick CLI Usage (No Installation Required)

npx firs-einvoicing encrypt --irn "IRN123-0FD6C95D-20250609" --certificate "..." --publicKey "..."

📖 Usage

✨ As a Node.js Library

ES Modules (ESM)

import { decryptInvoice, generateQRCode } from "firs-einvoicing";
import fs from "fs";

try {
  // Encrypt IRN and generate QR code
  const encryptionResult = await generateQRCode({
  // NOTE: You do not need to provide a timestamp manually. A timestamp is automatically generated at the time of processing.
    irn: "IRN123-0FD6C95D-20250609",
    certificate: "bEF0V3FJbmo5cVZYbEdCblB4QVpjMG9HVWFrc29GM2hiYWFkYWMyODRBUT0=",
    publicKey:
      "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUFyU0xpdDRtb1RMbFdjd1A4eEp6RQp3ZTdkRHExdC9kMi9zcXdQTlNVandablFPbklabVh4TXY4QUQxemMxdUErZ3VCc2tpUGdo",
    size: 300,
    fgColor: "#000000",
    bgColor: "#00FFFF",
      logo: "https://example.com/logo.png",
    logoSizeRatio: 0.2,
  });

    console.log("QR Code Buffer:", encryptionResult.qrCodeBuffer);
    console.log("Base64 QR Code:", encryptionResult.qrCodeDataUrl);
    console.log("Encrypted Base64:", encryptionResult.encryptedBase64);




    
  // Decrypt encrypted payload
  const decryptedData = await decryptInvoice({
    iv_hex: "4342576a6a65397a38394e6e73423478",
    pub: "Zd22h6lAZeX667t9YKQ5Teua",
    ciphertext:
      "TlrxIxmimiXXJafQztd-y5L3_vIrmHBG5YnE9vR6usrAzQm5gx3TmwKzNYr8RVIKuRBTQuEkRSReS5YbBMP_B7DXuPssTajBkpycz_Gugb7_Ro4XZLCjSRD5ckT3diPCBbbAtk8C-QNtFAR4xRT-tF9fV5e3DfmQMbO6kiARU21eeXvf4YLDwS3RlQHaGrIi2d1TqqvIxWDk8VXeFpDUw56cyH_I3340zut2-FPZ",
    api_key: "da5811ef-9c4e-42f1-ab4c-af654470c0ca",
  });

  console.log("Decrypted Invoice:", decryptedData);
} catch (error) {
  console.error("Encryption/Decryption failed:", error.message);
}

🔧 API Reference

generateQRCode(options)

Parameters:

Encrypts IRN and certificate data, then generates a QR code. | Name | Type | Required | Description | | --------------- | -------- | -------- | ---------------------------------------------------------------------------- | | irn | string | ✅ Yes | The Invoice Reference Number to encrypt and embed in the QR code. | | certificate | string | ✅ Yes | X.509 certificate in PEM format (used for validation or signing, if needed). | | publicKey | string | ✅ Yes | RSA public key in PEM format used for encrypting the IRN. | | size | number | ❌ No | Size of the QR code in pixels (default: 200). | | fgColor | string | ❌ No | Foreground (QR pattern) color in HEX format (default: '#000000'). | | bgColor | string | ❌ No | Background color in HEX format (default: '#FFFFFF'). | | logo | string | ❌ No | Optional URL or local path to a logo image to embed at the center. | | logoSizeRatio | number | ❌ No | Ratio (0–1) of the logo size relative to the QR code size (default: 0.2). |

Returns: Promise<EncryptionResult>

• encryptedBase64 (Buffer): Encrypted payload
• qrCodeDataUrl (string): QR code as base64 string
• qrCodeBuffer (Buffer): QR code as PNG buffer

decryptInvoice(options)

Decrypts encrypted invoice payload.

Parameters:

• options (Object)
  • invoice_schema (Buffer): Encrypted data buffer

Returns: Promise<Object> - Decrypted invoice data

🛠 Requirements

System Requirements

• Node.js: v16.0.0 or higher
• OpenSSL: Must be installed and available in your system PATH
• Operating System:
  • ✅ Linux (Ubuntu, CentOS, etc.)
  • ✅ macOS (Intel & Apple Silicon)
  • ✅ Windows (with WSL2 recommended for CLI)

Dependencies

The package automatically handles all required dependencies. No additional setup needed.

🚦 Environment Setup

Verify Prerequisites

# Check Node.js version
node --version  # Should be v16+

# Check OpenSSL availability
openssl version  # Should return OpenSSL version info

# Check npm/yarn version
npm --version
yarn --version

For Windows Users

We recommend using WSL2 (Windows Subsystem for Linux) for the best CLI experience:

# Install WSL2 (if not already installed)
wsl --install

# Or use Windows Terminal with PowerShell
# Most features work on Windows, but WSL2 provides better compatibility

📋 Examples

Complete Example: E-Invoice Processing

Generate QR Code

import { generateQRCode } from "firs-einvoicing";

async function createQRCode() {
  try {
    const { encryptedBase64, qrCodeDataUrl, qrCodeBuffer } = await generateQRCode({
// NOTE: You do not need to provide a timestamp manually. A timestamp is automatically generated at the time of processing.
      irn: "IRN123-0FD6C95D-20250609",
      certificate:
        "bEF0V3FJbmo5cVZYbEdCblB4QVpjMG9HVWFrc29GM2hiYWFkYWMyODRBUT0=",
      publicKey:
        "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQ",
      size: 300,
      fgColor: "#000000",
      bgColor: "#00FFFF",
      logo: "https://example.com/logo.png",
      logoSizeRatio: 0.2,
    });
    console.log("QR Code Buffer:", qrCodeBuffer);
    console.log("Base64 QR Code:", qrCodeDataUrl);
    console.log("Encrypted Base64:", encryptedBase64);

  } catch (error) {
    console.error("Error:", error.message);
  }
}

createQRCode();

Decrypt e-invoice

import { decryptInvoice } from "firs-einvoicing";

async function decryptInvoicePayload() {
  try {
    // Decrypt encrypted payload
    const encrypted = {
      iv_hex: "4342576a6a65397a38394e6e73423478",
      pub: "Zd22h6lAZeX667t9YKQ5Teua",
      ciphertext: "Encrypted invoice",
      api_key: "da5811ef-9c4e-42f1-ab4c-af654470c0ca",
    };
    const decryptedData = decryptInvoice(encrypted);

    console.log("Decrypted Invoice:", decryptedData);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

decryptInvoicePayload();

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏷️ Keywords

firs, e-invoicing, nigeria, tax, encryption, qr-code, irn, rsa, digital-signature, invoice, cli, nodejs