@africode/core 5.0.0

package/core/compliance.js

@@ -0,0 +1,628 @@
+/**
+ * Fintech Compliance Engine
+ * Tanzanian regulatory compliance for NIDA, TIPS, and AML/FIU
+ *
+ * Implements the "operating system" approach to compliance with
+ * automated identity verification, transaction monitoring, and
+ * regulatory reporting.
+ *
+ * @module core/compliance
+ */
+
+import { z } from 'zod';
+
+/**
+ * NIDA Identity Infrastructure Integration
+ * National Identification Authority verification system
+ */
+export class NIDAClient {
+    constructor(config = {}) {
+        this.baseUrl = config.baseUrl || 'https://api.nida.go.tz';
+        this.apiKey = config.apiKey;
+        this.certificate = config.certificate;
+        this.timeout = config.timeout || 30000;
+    }
+
+    /**
+     * Verify National ID Number (NIN)
+     * @param {string} nin - 20-digit NIN
+     * @param {Object} options - Verification options
+     */
+    async verifyNIN(nin, options = {}) {
+        const schema = z.string().length(20).regex(/^\d{20}$/);
+        schema.parse(nin);
+
+        const response = await this._makeRequest('/verify/nin', {
+            method: 'POST',
+            body: JSON.stringify({
+                nin,
+                includeBiometrics: options.includeBiometrics || false,
+                includeDemographics: options.includeDemographics || true
+            })
+        });
+
+        return {
+            verified: response.verified,
+            demographics: response.demographics,
+            biometrics: response.biometrics,
+            confidence: response.confidence,
+            timestamp: new Date().toISOString()
+        };
+    }
+
+    /**
+     * Perform biometric verification
+     * @param {string} nin - NIN to verify against
+     * @param {Object} biometrics - Biometric data
+     */
+    async verifyBiometrics(nin, biometrics) {
+        const response = await this._makeRequest('/verify/biometrics', {
+            method: 'POST',
+            body: JSON.stringify({
+                nin,
+                fingerprint: biometrics.fingerprint,
+                facialImage: biometrics.facialImage,
+                livenessData: biometrics.livenessData
+            })
+        });
+
+        return {
+            match: response.match,
+            confidence: response.confidence,
+            level: response.level // ISO 30107-3 PAD level
+        };
+    }
+
+    /**
+     * Extract data from ID document
+     * @param {File|Buffer} document - ID document image
+     * @param {string} type - Document type (1-7 Tanzanian ID types)
+     */
+    async extractDocumentData(document, type) {
+        const formData = new FormData();
+        formData.append('document', document);
+        formData.append('type', type);
+
+        const response = await this._makeRequest('/extract/document', {
+            method: 'POST',
+            body: formData
+        });
+
+        return {
+            extractedData: response.data,
+            confidence: response.confidence,
+            ocrText: response.ocrText
+        };
+    }
+
+    /**
+     * Make authenticated request to NIDA API
+     */
+    async _makeRequest(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            ...options.headers
+        };
+
+        // Add certificate-based authentication for production
+        if (this.certificate) {
+            headers['X-Client-Certificate'] = this.certificate;
+        }
+
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            signal: AbortSignal.timeout(this.timeout)
+        });
+
+        if (!response.ok) {
+            throw new Error(`NIDA API error: ${response.status} ${response.statusText}`);
+        }
+
+        return response.json();
+    }
+}
+
+/**
+ * TIPS Payment System Integration
+ * Tanzania Instant Payment System for real-time transactions
+ */
+export class TIPSClient {
+    constructor(config = {}) {
+        this.baseUrl = config.baseUrl || 'https://api.tips.go.tz';
+        this.apiKey = config.apiKey;
+        this.clientId = config.clientId;
+        this.privateKey = config.privateKey;
+        this.timeout = config.timeout || 10000; // TIPS requires fast responses
+    }
+
+    /**
+     * Process P2P payment
+     * @param {Object} payment - Payment details
+     */
+    async processP2P(payment) {
+        const schema = z.object({
+            fromAccount: z.string(),
+            toAccount: z.string(),
+            amount: z.number().positive(),
+            currency: z.string().default('TZS'),
+            description: z.string().optional()
+        });
+
+        const validatedPayment = schema.parse(payment);
+
+        const response = await this._makeRequest('/payments/p2p', {
+            method: 'POST',
+            body: JSON.stringify({
+                ...validatedPayment,
+                timestamp: new Date().toISOString(),
+                idempotencyKey: this._generateIdempotencyKey()
+            })
+        });
+
+        return {
+            transactionId: response.transactionId,
+            status: response.status,
+            processedAt: response.processedAt,
+            fee: response.fee
+        };
+    }
+
+    /**
+     * Process P2B payment (merchant payment)
+     * @param {Object} payment - Payment details
+     */
+    async processP2B(payment) {
+        const schema = z.object({
+            customerAccount: z.string(),
+            merchantAccount: z.string(),
+            amount: z.number().positive(),
+            reference: z.string(),
+            description: z.string().optional()
+        });
+
+        const validatedPayment = schema.parse(payment);
+
+        const response = await this._makeRequest('/payments/p2b', {
+            method: 'POST',
+            body: JSON.stringify(validatedPayment)
+        });
+
+        return {
+            transactionId: response.transactionId,
+            status: response.status,
+            confirmationCode: response.confirmationCode
+        };
+    }
+
+    /**
+     * Request to Pay (RTP) - merchant requests payment from customer
+     * @param {Object} request - RTP details
+     */
+    async requestToPay(request) {
+        const schema = z.object({
+            merchantAccount: z.string(),
+            customerAccount: z.string(),
+            amount: z.number().positive(),
+            expiryMinutes: z.number().min(1).max(60).default(15),
+            description: z.string()
+        });
+
+        const validatedRequest = schema.parse(request);
+
+        const response = await this._makeRequest('/payments/rtp', {
+            method: 'POST',
+            body: JSON.stringify(validatedRequest)
+        });
+
+        return {
+            requestId: response.requestId,
+            status: response.status,
+            expiryAt: response.expiryAt
+        };
+    }
+
+    /**
+     * Reverse transaction
+     * @param {string} transactionId - Transaction to reverse
+     * @param {string} reason - Reversal reason
+     */
+    async reverseTransaction(transactionId, reason) {
+        const response = await this._makeRequest('/payments/reverse', {
+            method: 'POST',
+            body: JSON.stringify({
+                transactionId,
+                reason,
+                timestamp: new Date().toISOString()
+            })
+        });
+
+        return {
+            reversalId: response.reversalId,
+            status: response.status,
+            reversedAt: response.reversedAt
+        };
+    }
+
+    /**
+     * Get transaction status
+     * @param {string} transactionId - Transaction ID
+     */
+    async getTransactionStatus(transactionId) {
+        const response = await this._makeRequest(`/payments/${transactionId}/status`);
+        return response;
+    }
+
+    /**
+     * Generate idempotency key for request deduplication
+     */
+    _generateIdempotencyKey() {
+        return `tips_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+
+    /**
+     * Make authenticated request to TIPS API
+     */
+    async _makeRequest(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+
+        // Create signature for request authentication
+        const timestamp = new Date().toISOString();
+        const signature = await this._createSignature(options.body || '', timestamp);
+
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'X-Client-ID': this.clientId,
+            'X-Timestamp': timestamp,
+            'X-Signature': signature,
+            'Content-Type': 'application/json',
+            ...options.headers
+        };
+
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            signal: AbortSignal.timeout(this.timeout)
+        });
+
+        if (!response.ok) {
+            throw new Error(`TIPS API error: ${response.status} ${response.statusText}`);
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Create cryptographic signature for TIPS authentication
+     */
+    async _createSignature(body, timestamp) {
+        const message = `${timestamp}${body}`;
+        const encoder = new TextEncoder();
+        const data = encoder.encode(message);
+
+        // Use Web Crypto API for signing
+        const key = await crypto.subtle.importKey(
+            'pkcs8',
+            this._base64ToArrayBuffer(this.privateKey),
+            {
+                name: 'RSASSA-PKCS1-v1_5',
+                hash: 'SHA-256'
+            },
+            false,
+            ['sign']
+        );
+
+        const signature = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, data);
+        return this._arrayBufferToBase64(signature);
+    }
+
+    _base64ToArrayBuffer(base64) {
+        const binaryString = atob(base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+            bytes[i] = binaryString.charCodeAt(i);
+        }
+        return bytes.buffer;
+    }
+
+    _arrayBufferToBase64(buffer) {
+        const bytes = new Uint8Array(buffer);
+        let binary = '';
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary);
+    }
+}
+
+/**
+ * AML/FIU Compliance Engine
+ * Automated Anti-Money Laundering and Financial Intelligence Unit integration
+ */
+export class AMLComplianceEngine {
+    constructor(config = {}) {
+        this.fiuEndpoint = config.fiuEndpoint || 'https://api.fiu.go.tz';
+        this.reportingWindow = config.reportingWindow || 24; // hours
+        this.monitoringRules = config.monitoringRules || this._defaultRules();
+    }
+
+    /**
+     * Evaluate transaction for suspicious activity
+     * @param {Object} transaction - Transaction details
+     * @param {Object} customer - Customer profile
+     */
+    async evaluateTransaction(transaction, customer) {
+        const riskScore = await this._calculateRiskScore(transaction, customer);
+        const flags = await this._checkMonitoringRules(transaction, customer);
+
+        const isSuspicious = riskScore > 0.7 || flags.length > 0;
+
+        if (isSuspicious) {
+            await this._queueForReporting(transaction, customer, riskScore, flags);
+        }
+
+        return {
+            riskScore,
+            flags,
+            suspicious: isSuspicious,
+            evaluatedAt: new Date().toISOString()
+        };
+    }
+
+    /**
+     * Submit suspicious activity report to FIU
+     * @param {Object} report - SAR details
+     */
+    async submitSAR(report) {
+        const schema = z.object({
+            transactionId: z.string(),
+            customerId: z.string(),
+            activityType: z.string(),
+            description: z.string(),
+            riskScore: z.number(),
+            flags: z.array(z.string()),
+            evidence: z.array(z.object({
+                type: z.string(),
+                data: z.any()
+            }))
+        });
+
+        const validatedReport = schema.parse(report);
+
+        const response = await fetch(`${this.fiuEndpoint}/sar`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${process.env.FIU_API_KEY}`
+            },
+            body: JSON.stringify({
+                ...validatedReport,
+                submittedAt: new Date().toISOString(),
+                reportingEntity: process.env.FINTECH_LICENSE_ID
+            })
+        });
+
+        if (!response.ok) {
+            throw new Error(`FIU submission failed: ${response.status}`);
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Calculate risk score for transaction
+     */
+    async _calculateRiskScore(transaction, customer) {
+        let score = 0;
+
+        // Amount-based scoring
+        if (transaction.amount > 1000000) {
+            score += 0.3; // > 1M TZS
+        } else if (transaction.amount > 500000) {
+            score += 0.2;
+        }
+
+        // Velocity checks
+        const recentTransactions = await this._getRecentTransactions(customer.id, 24);
+        if (recentTransactions.length > 10) {
+            score += 0.2;
+        }
+
+        // Geographic anomalies
+        if (this._isGeographicAnomaly(transaction, customer)) {
+            score += 0.3;
+        }
+
+        // Customer risk profile
+        if (customer.riskLevel === 'high') {
+            score += 0.4;
+        } else if (customer.riskLevel === 'medium') {
+            score += 0.2;
+        }
+
+        return Math.min(score, 1.0);
+    }
+
+    /**
+     * Check transaction against monitoring rules
+     */
+    async _checkMonitoringRules(transaction, customer) {
+        const flags = [];
+
+        for (const rule of this.monitoringRules) {
+            if (await rule.check(transaction, customer)) {
+                flags.push(rule.name);
+            }
+        }
+
+        return flags;
+    }
+
+    /**
+     * Queue suspicious activity for FIU reporting
+     */
+    async _queueForReporting(transaction, customer, riskScore, flags) {
+        const report = {
+            transactionId: transaction.id,
+            customerId: customer.id,
+            activityType: 'suspicious_transaction',
+            description: `High-risk transaction detected: ${flags.join(', ')}`,
+            riskScore,
+            flags,
+            evidence: [
+                { type: 'transaction', data: transaction },
+                { type: 'customer', data: customer }
+            ]
+        };
+
+        // Queue for reporting within 24-hour window
+        await this._scheduleReporting(report, this.reportingWindow);
+    }
+
+    /**
+     * Default AML monitoring rules
+     */
+    _defaultRules() {
+        return [
+            {
+                name: 'large_amount',
+                check: (tx) => tx.amount > 2000000 // > 2M TZS
+            },
+            {
+                name: 'rapid_transactions',
+                check: async (tx, customer) => {
+                    const recent = await this._getRecentTransactions(customer.id, 1);
+                    return recent.length > 5;
+                }
+            },
+            {
+                name: 'unusual_location',
+                check: (tx, customer) => this._isGeographicAnomaly(tx, customer)
+            }
+        ];
+    }
+
+    /**
+     * Check for geographic anomalies
+     */
+    _isGeographicAnomaly(transaction, customer) {
+        // Simplified geographic check
+        const customerCountry = customer.address?.country || 'TZ';
+        const transactionCountry = transaction.location?.country || 'TZ';
+
+        return customerCountry !== transactionCountry;
+    }
+
+    /**
+     * Get recent transactions for customer
+     */
+    async _getRecentTransactions(_customerId, _hours) {
+        // Implementation would query transaction database
+        // Placeholder for demo
+        void _customerId;
+        void _hours;
+        return [];
+    }
+
+    /**
+     * Schedule reporting within compliance window
+     */
+    async _scheduleReporting(report, hours) {
+        // Implementation would use job queue system
+        console.warn(`Scheduling FIU report in ${hours} hours for transaction ${report.transactionId}`);
+    }
+}
+
+/**
+ * Compliance Middleware
+ * Framework-level compliance enforcement
+ */
+export class ComplianceMiddleware {
+    constructor(config = {}) {
+        this.nida = config.nida ? new NIDAClient(config.nida) : null;
+        this.tips = config.tips ? new TIPSClient(config.tips) : null;
+        this.aml = new AMLComplianceEngine(config.aml);
+    }
+
+    /**
+     * KYC middleware for identity verification
+     */
+    kycMiddleware() {
+        return async (request, next) => {
+            if (!this.nida) {
+                return next(request);
+            }
+
+            const userId = request.session?.userId;
+            if (!userId) {
+                return next(request);
+            }
+
+            // Check if user needs KYC verification
+            const user = await this._getUser(userId);
+            if (!user.kycVerified) {
+                // Perform NIDA verification
+                try {
+                    const verification = await this.nida.verifyNIN(user.nin);
+                    if (verification.verified) {
+                        await this._updateUserKYC(userId, verification);
+                    }
+                } catch (error) {
+                    console.error('NIDA verification failed:', error);
+                    // Allow request to continue but log failure
+                }
+            }
+
+            return next(request);
+        };
+    }
+
+    /**
+     * Transaction monitoring middleware
+     */
+    transactionMiddleware() {
+        return async (transaction, next) => {
+            const customer = await this._getCustomer(transaction.customerId);
+
+            const evaluation = await this.aml.evaluateTransaction(transaction, customer);
+
+            if (evaluation.suspicious) {
+                console.warn(`Suspicious transaction detected: ${transaction.id}`);
+                // Could block transaction or flag for review
+            }
+
+            return next(transaction);
+        };
+    }
+
+    /**
+     * Get user by ID
+     */
+    async _getUser(userId) {
+        // Implementation would query user database
+        return { id: userId, kycVerified: false, nin: '12345678901234567890' };
+    }
+
+    /**
+     * Update user KYC status
+     */
+    async _updateUserKYC(userId, verification) {
+        // Implementation would update user database
+        console.warn(`Updated KYC for user ${userId}:`, verification);
+    }
+
+    /**
+     * Get customer by ID
+     */
+    async _getCustomer(customerId) {
+        // Implementation would query customer database
+        return {
+            id: customerId,
+            riskLevel: 'low',
+            address: { country: 'TZ' }
+        };
+    }
+}