PRODUCT TECHNICAL DOCS

Ngabantu Enterprise License Manager Backend
Technical Detail

In-depth documentation for the Ngabantu Enterprise License Manager Backend – covering core features, security, configuration, endpoints, and deployment.

This page is aimed at technical teams integrating the License Manager Backend into their infrastructure and CI/CD pipelines.

← Back to product overview Open support docs ↗
Full technical specification

Architecture, security, configuration & APIs.

Ngabantu Flutter Plugins - Enterprise License Manager Backend

🚀 Professional-grade Node.js/Express backend for enterprise Flutter plugin and app licensing with v2.0 security enhancements, code obfuscation, and production-ready deployment capabilities.

Enterprise Edition - Designed for developers and enterprise teams requiring robust licensing solutions.

Features

Core Features

  • ✅ Payment Processing - Paystack & PayPal integration for online license purchases
  • ✅ License Generation - Cryptographic license generation with AES-256-GCM + PBKDF2
  • ✅ Database Management - SQLite, MySQL, PostgreSQL, or MSSQL support
  • ✅ Email Service - Automated license delivery via SMTP
  • ✅ Device Tracking - Optional device usage monitoring (disabled by default)
  • ✅ Webhook Handling - Secure payment verification with raw body HMAC
  • ✅ Manual License CLI - Generate licenses offline via command line
  • ✅ Backend Self-Licensing - Product-based licensing with hardware fingerprinting
  • ✅ Extended Downtime Protection - 14-day grace period for server outages

Security Enhancements (v2.0)

  • 🔒 Rate Limiting - Protection against brute force and abuse
  • 🔒 Security Headers - Helmet.js integration with CSP, HSTS, XSS protection
  • 🔒 CORS Security - Environment-based origin whitelisting
  • 🔒 Timing-Safe Authentication - Protection against timing attacks
  • 🔒 Environment Validation - Production-grade configuration validation
  • 🔒 Request Tracing - UUID-based request tracking for debugging
  • 🔒 Enhanced FX Rate Handling - Fallback strategies and rate validation

Architecture Improvements (v2.0)

  • 🏗️ AdminService Module - Separated admin logic for better maintainability
  • 🏗️ Structured Logging - Request context and environment-aware logging
  • 🏗️ Service Layer Pattern - Clean separation of concerns
  • 🏗️ Enhanced Error Handling - Comprehensive error management

Quick Start

1. Initial Setup (Development) 

cd backend
./setup.sh

This will:

  • ✅ Install Node.js dependencies
  • ✅ Create .env from template
  • ✅ Guide Paystack/PayPal API key configuration
  • ✅ Initialize SQLite database
  • ✅ Verify development environment

2. Development Server

npm start
# or
PORT=3000 NODE_ENV=development node server.js

3. Enterprise Production Deployment 

# Deploy obfuscated enterprise version
./deploy.sh

Enterprise deployment includes:

  • 🛡️ Code obfuscation - Enterprise security protection
  • 🔒 Security hardening - Rate limiting, headers, validation
  • 📦 Production archive - Ready for distribution
  • 🚀 Automated deployment - Direct server deployment

4. Quick Development Start 

npm start              # Production mode
npm run dev            # Development mode (auto-reload)

Server runs at http://localhost:3000

Configuration

Environment Variables (.env) 

# ======================
#  Payment Gateway Configuration
# ======================

# Required - Paystack API Keys
PAYSTACK_SECRET_KEY=sk_test_your_key_here
PAYSTACK_PUBLIC_KEY=pk_test_your_key_here

# Required - PayPal API Keys (for PayPal integration)
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
PAYPAL_MODE=sandbox  # or 'live' for production
PAYPAL_WEBHOOK_ID=your_webhook_id

# ======================
#  Server Configuration
# ======================

# Server Settings
PORT=3000
NODE_ENV=development  # or 'production'
DEFAULT_CURRENCY=ZAR

# Security Configuration (REQUIRED for production)
ADMIN_PASSWORD=your_secure_admin_password
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

# Callback URLs
CALLBACK_URL=http://localhost:3000/payment/callback

# ======================
#  Backend Licensing (Optional)
# ======================

# For backend self-licensing (set to 'true' for emergency bypass)
BACKEND_LICENSE_KEY=your_backend_license_key
BACKEND_BOOTSTRAP_MODE=false

# ======================
#  Email Configuration (Optional)
# ======================

# SMTP Settings for license delivery
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
NODE_ENV=development

# Optional - Email Service
SMTP_HOST=mail.yourdomain.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=licenses@yourdomain.com
SMTP_PASS=your_password
FROM_EMAIL=licenses@yourdomain.com
FROM_NAME=Ngabantu Licensing

# Optional - Callback URL
CALLBACK_URL=http://localhost:8080/payment/callback

# Optional - Database Configuration (Default: SQLite)
DB_TYPE=sqlite              # Options: sqlite, mysql, postgres, mssql
# DB_HOST=localhost         # Required for mysql/postgres/mssql
# DB_PORT=3306              # MySQL: 3306, PostgreSQL: 5432, MSSQL: 1433
# DB_NAME=license_manager
# DB_USER=your_username
# DB_PASSWORD=your_password

Get Paystack keys at: https://dashboard.paystack.com/#/settings/developer

Database Options:

  • SQLite (default): Zero configuration, perfect for getting started
  • MySQL/PostgreSQL/MSSQL: For production, multi-server deployments
  • See your backend database configuration guide for complete setup details.

Manual License Generation

For offline/manual sales or webhook recovery:

node generate-manual-license.js

Use the included CLI tooling to generate licenses offline. A complete guide is available in your backend documentation.

  • Configuration reference
  • Common use cases (demos, professional, enterprise licenses)
  • Batch generation
  • Resending licenses
  • Troubleshooting

Security Features

Production Security (v2.0)

The License Manager Backend implements enterprise-grade security features:

🔒 Rate Limiting

  • Admin Login: 10 requests per 5 minutes (prevents brute force)
  • Payment Operations: 30 requests per minute (prevents abuse)
  • Webhooks: 100 requests per minute (allows legitimate traffic)
  • Returns 429 Too Many Requests when limits exceeded

🔒 Security Headers (Helmet.js)

  • Content Security Policy (CSP): Prevents XSS attacks
  • HTTP Strict Transport Security (HSTS): Forces HTTPS
  • X-Frame-Options: Prevents clickjacking
  • X-Content-Type-Options: Prevents MIME sniffing
  • Referrer Policy: Controls referrer information
  • Express fingerprinting disabled: Hides x-powered-by header

🔒 CORS Security

  • Development: Allows all origins for flexibility
  • Production: Strict origin whitelisting via CORS_ORIGINS
  • Environment-based: Automatic security level adjustment

🔒 Authentication Security

  • Timing-safe comparisons: Prevents timing attacks on admin login
  • Secure password validation: Uses crypto.timingSafeEqual()
  • Environment validation: Fails fast on insecure production config

🔒 Webhook Security

  • Raw body HMAC verification: More reliable than JSON.stringify
  • Signature validation: Prevents webhook spoofing
  • Request body capture: Middleware captures raw body for verification

🔒 Request Tracing

  • UUID-based request IDs: Every request gets unique identifier
  • Structured logging: Context-aware error reporting
  • Environment-aware logging: Pretty print in dev, JSON in production

🔒 Enhanced FX Rate Security

  • Rate validation: Rejects unreasonable exchange rates (outside 10-30 range)
  • Fallback strategies: Uses cached rates up to 24 hours if API fails
  • Conservative fallback: 18.5 ZAR/USD rate as last resort
  • API timeouts: 5-second timeout prevents hanging requests

Security Testing

Test security features using the included test script:

# Run comprehensive security tests
node test-security-enhancements.js

Tests include:

  • Rate limiting verification
  • Security headers validation
  • Request ID tracing
  • Environment validation checks