elpaypg 0.0.0-stage → 2.0.0

package/src/vendor/common/contracts.ts

@@ -0,0 +1,188 @@
+import { PaymentStatus, PublicPaymentOutcome, PaymentMethod, ObserverSource, TicketStatus, SenderType } from './enums.js';
+
+// --- Merchant API Contracts ---
+export interface CreatePaymentRequest {
+  orderId: string;
+  amount: string | number; // e.g. "200.00" or 200
+  currency?: string;
+  returnUrl?: string;
+  method?: PaymentMethod;
+  customer?: {
+    phoneNumber: string;
+    fullName?: string;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreatePaymentResponse {
+  paymentId: string;
+  orderId: string;
+  amount: string;
+  amountPaise: string;
+  currency: string;
+  status: PaymentStatus;
+  checkoutUrl: string;
+}
+
+export interface QueryPaymentResponse {
+  paymentId: string;
+  orderId: string;
+  amount: string;
+  currency: string;
+  status: PublicPaymentOutcome | PaymentStatus;
+  method: PaymentMethod;
+  completedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// --- Checkout Portal Contracts ---
+export interface CheckoutStateResponse {
+  paymentId: string;
+  orderId: string;
+  merchantName: string;
+  amount: string;
+  amountPaise: string;
+  currency: string;
+  status: PaymentStatus;
+  method: PaymentMethod;
+  queuePosition: number;
+  timeRemainingSeconds: number;
+  upiUri?: string;
+  payeeVpa?: string;
+  payeeName?: string;
+  canClickPaymentDone: boolean;
+  branding: {
+    appName: string;
+    primaryColor: string;
+    logoUrl?: string;
+  };
+}
+
+// --- Webhook Payload Contract ---
+export interface WebhookEventPayload {
+  event: PublicPaymentOutcome;
+  paymentId: string;
+  orderId: string;
+  amount: string;
+  amountPaise: number;
+  currency: string;
+  method: PaymentMethod;
+  completedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+// --- Observer Payload Contracts ---
+export interface AndroidObservationPayload {
+  deviceId: string;
+  source: ObserverSource.ANDROID_OBSERVER;
+  amountPaise: number;
+  observedAt: string;
+  observationId?: string;
+  senderVpa?: string;
+  bankReferenceNumber?: string;
+  rawNotification?: Record<string, unknown>;
+}
+
+export interface AndroidHeartbeatPayload {
+  deviceId: string;
+  timestamp: string;
+  batteryLevel?: number;
+  appVersion?: string;
+}
+
+// --- Customer & Support Contracts ---
+export interface CustomerProfile {
+  id: string;
+  name: string;
+  email: string;
+  mobileNumber: string;
+  status: string;
+  lastLoginAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CustomerRegisterRequest {
+  name: string;
+  email: string;
+  mobileNumber: string;
+  password: string;
+}
+
+export interface CustomerLoginRequest {
+  identifier?: string;
+  email?: string;
+  mobileNumber?: string;
+  password: string;
+}
+
+export interface CustomerSessionDto {
+  id: string;
+  customerId: string;
+  token: string;
+  expiresAt: string;
+  isActive: boolean;
+  createdAt: string;
+}
+
+/**
+ * Normalizes an email address to trimmed lowercase.
+ */
+export function normalizeEmail(email: string | null | undefined): string {
+  if (!email || typeof email !== 'string') return '';
+  return email.trim().toLowerCase();
+}
+
+/**
+ * Validates email format with standard requirements.
+ */
+export function isValidEmail(email: string | null | undefined): boolean {
+  const norm = normalizeEmail(email);
+  if (!norm) return false;
+  return /^[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}$/.test(norm);
+}
+
+/**
+ * Normalizes a mobile number to canonical 10 digits (stripping prefixes and country codes).
+ */
+export function normalizeMobile(mobile: string | null | undefined): string {
+  if (!mobile) return '';
+  const cleaned = String(mobile).replace(/\D/g, '');
+  if (cleaned.length >= 10) {
+    return cleaned.slice(-10);
+  }
+  return cleaned;
+}
+
+/**
+ * Validates canonical Indian 10-digit mobile number format.
+ */
+export function isValidMobile(mobile: string | null | undefined): boolean {
+  const norm = normalizeMobile(mobile);
+  return /^[6-9]\d{9}$/.test(norm);
+}
+
+/**
+ * Validates password strength (minimum 6 characters).
+ */
+export function isValidPassword(password: string | null | undefined): boolean {
+  return typeof password === 'string' && password.length >= 6;
+}
+
+export interface SupportTicketSummary {
+  id: string;
+  subject: string;
+  status: TicketStatus;
+  paymentId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TicketMessageDto {
+  id: string;
+  ticketId: string;
+  senderType: SenderType;
+  senderId: string;
+  message: string;
+  createdAt: string;
+}

package/src/vendor/common/crypto.js

@@ -0,0 +1,132 @@
+import crypto from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // 96-bit IV recommended for GCM
+const AUTH_TAG_LENGTH = 16; // 128-bit auth tag
+
+/**
+ * Encrypts plaintext string using AES-256-GCM.
+ * Output format: iv_hex:authTag_hex:cipher_hex
+ * @param {string} plaintext
+ * @param {string} masterKeyHex
+ * @returns {string}
+ */
+export function encrypt(plaintext, masterKeyHex) {
+  const key = Buffer.from(masterKeyHex, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be a 32-byte (64 hex characters) string.');
+  }
+
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final()
+  ]);
+
+  const authTag = cipher.getAuthTag();
+
+  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+
+/**
+ * Decrypts an AES-256-GCM ciphertext payload.
+ * @param {string} encryptedPayload
+ * @param {string} masterKeyHex
+ * @returns {string}
+ */
+export function decrypt(encryptedPayload, masterKeyHex) {
+  const key = Buffer.from(masterKeyHex, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be a 32-byte (64 hex characters) string.');
+  }
+
+  const parts = encryptedPayload.split(':');
+  if (parts.length !== 3) {
+    throw new Error('Invalid encrypted payload format. Expected iv:authTag:cipher.');
+  }
+
+  const iv = Buffer.from(parts[0], 'hex');
+  const authTag = Buffer.from(parts[1], 'hex');
+  const encryptedText = Buffer.from(parts[2], 'hex');
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([
+    decipher.update(encryptedText),
+    decipher.final()
+  ]);
+
+  return decrypted.toString('utf8');
+}
+
+/**
+ * Generates an HMAC-SHA256 signature for webhooks and device authentication.
+ * @param {string} data
+ * @param {string} secret
+ * @returns {string}
+ */
+export function generateHmac(data, secret) {
+  return crypto.createHmac('sha256', secret).update(data, 'utf8').digest('hex');
+}
+
+/**
+ * Timing-safe HMAC signature verification.
+ * @param {string} data
+ * @param {string} secret
+ * @param {string} expectedSignature
+ * @returns {boolean}
+ */
+export function verifyHmac(data, secret, expectedSignature) {
+  const actualSignature = generateHmac(data, secret);
+  const actualBuffer = Buffer.from(actualSignature, 'hex');
+  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
+
+  if (actualBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+/**
+ * Generates a cryptographically secure random hex string.
+ * @param {number} [bytes=32]
+ * @returns {string}
+ */
+export function generateRandomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('hex');
+}
+
+/**
+ * Hashes a password using PBKDF2 with SHA-512 and salt.
+ * Format: iterations:salt_hex:hash_hex
+ * @param {string} password
+ * @returns {string}
+ */
+export function hashPassword(password) {
+  const salt = crypto.randomBytes(16).toString('hex');
+  const iterations = 100000;
+  const hash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha512').toString('hex');
+  return `${iterations}:${salt}:${hash}`;
+}
+
+/**
+ * Verifies a password against a stored PBKDF2 hash.
+ * @param {string} password
+ * @param {string} storedHash
+ * @returns {boolean}
+ */
+export function verifyPassword(password, storedHash) {
+  const parts = storedHash.split(':');
+  if (parts.length !== 3) return false;
+
+  const iterations = parseInt(parts[0], 10);
+  const salt = parts[1];
+  const originalHash = parts[2];
+
+  const checkHash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha512').toString('hex');
+  return crypto.timingSafeEqual(Buffer.from(checkHash, 'hex'), Buffer.from(originalHash, 'hex'));
+}

package/src/vendor/common/crypto.ts

@@ -0,0 +1,112 @@
+import crypto from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12; // 96-bit IV recommended for GCM
+const AUTH_TAG_LENGTH = 16; // 128-bit auth tag
+
+/**
+ * Encrypts plaintext string using AES-256-GCM.
+ * Output format: iv_hex:authTag_hex:cipher_hex
+ */
+export function encrypt(plaintext: string, masterKeyHex: string): string {
+  const key = Buffer.from(masterKeyHex, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be a 32-byte (64 hex characters) string.');
+  }
+
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final()
+  ]);
+
+  const authTag = cipher.getAuthTag();
+
+  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+
+/**
+ * Decrypts an AES-256-GCM ciphertext payload.
+ */
+export function decrypt(encryptedPayload: string, masterKeyHex: string): string {
+  const key = Buffer.from(masterKeyHex, 'hex');
+  if (key.length !== 32) {
+    throw new Error('Master key must be a 32-byte (64 hex characters) string.');
+  }
+
+  const parts = encryptedPayload.split(':');
+  if (parts.length !== 3) {
+    throw new Error('Invalid encrypted payload format. Expected iv:authTag:cipher.');
+  }
+
+  const iv = Buffer.from(parts[0]!, 'hex');
+  const authTag = Buffer.from(parts[1]!, 'hex');
+  const encryptedText = Buffer.from(parts[2]!, 'hex');
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+  decipher.setAuthTag(authTag);
+
+  const decrypted = Buffer.concat([
+    decipher.update(encryptedText),
+    decipher.final()
+  ]);
+
+  return decrypted.toString('utf8');
+}
+
+/**
+ * Generates an HMAC-SHA256 signature for webhooks and device authentication.
+ */
+export function generateHmac(data: string, secret: string): string {
+  return crypto.createHmac('sha256', secret).update(data, 'utf8').digest('hex');
+}
+
+/**
+ * Timing-safe HMAC signature verification.
+ */
+export function verifyHmac(data: string, secret: string, expectedSignature: string): boolean {
+  const actualSignature = generateHmac(data, secret);
+  const actualBuffer = Buffer.from(actualSignature, 'hex');
+  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
+
+  if (actualBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+
+/**
+ * Generates a cryptographically secure random hex string.
+ */
+export function generateRandomToken(bytes: number = 32): string {
+  return crypto.randomBytes(bytes).toString('hex');
+}
+
+/**
+ * Hashes a password using PBKDF2 with SHA-512 and salt.
+ * Format: iterations:salt_hex:hash_hex
+ */
+export function hashPassword(password: string): string {
+  const salt = crypto.randomBytes(16).toString('hex');
+  const iterations = 100000;
+  const hash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha512').toString('hex');
+  return `${iterations}:${salt}:${hash}`;
+}
+
+/**
+ * Verifies a password against a stored PBKDF2 hash.
+ */
+export function verifyPassword(password: string, storedHash: string): boolean {
+  const parts = storedHash.split(':');
+  if (parts.length !== 3) return false;
+
+  const iterations = parseInt(parts[0]!, 10);
+  const salt = parts[1]!;
+  const originalHash = parts[2]!;
+
+  const checkHash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha512').toString('hex');
+  return crypto.timingSafeEqual(Buffer.from(checkHash, 'hex'), Buffer.from(originalHash, 'hex'));
+}

package/src/vendor/common/enums.js

@@ -0,0 +1,91 @@
+/**
+ * Internal high-resolution payment session lifecycle states.
+ */
+export const PaymentStatus = Object.freeze({
+  INITIATED: 'INITIATED',
+  QUEUED: 'QUEUED',
+  ACTIVE: 'ACTIVE',
+  PROCESSING: 'PROCESSING',
+  SUCCESS: 'SUCCESS',
+  FAILED: 'FAILED',
+  EXPIRED: 'EXPIRED',
+  CANCELLED: 'CANCELLED'
+});
+
+/**
+ * Public-facing payment outcomes consumed by external merchants.
+ */
+export const PublicPaymentOutcome = Object.freeze({
+  SUCCESS: 'SUCCESS',
+  FAILED: 'FAILED',
+  EXPIRED: 'EXPIRED',
+  CANCELLED: 'CANCELLED'
+});
+
+/**
+ * Supported payment modalities.
+ */
+export const PaymentMethod = Object.freeze({
+  UPI: 'UPI',
+  COD: 'COD',
+  CASH_COUNTER: 'CASH_COUNTER',
+  CARD_COUNTER: 'CARD_COUNTER'
+});
+
+/**
+ * Merchant gateway selling modes.
+ */
+export const SellingMode = Object.freeze({
+  ONLINE: 'ONLINE',
+  OFFLINE: 'OFFLINE'
+});
+
+/**
+ * Observation channel sources feeding the payment detection engine (2-Layer: SMS + Gmail).
+ * Android observer layer is completely removed.
+ */
+export const ObserverSource = Object.freeze({
+  GMAIL: 'GMAIL',
+  GOOGLE_MESSAGES: 'GOOGLE_MESSAGES',
+  ANDROID_OBSERVER: 'ANDROID_OBSERVER',
+  SMS_GATEWAY: 'SMS_GATEWAY',
+  MANUAL_COUNTER: 'MANUAL_COUNTER'
+});
+
+/**
+ * Attribution status for raw observations.
+ */
+export const ObservationAttributionStatus = Object.freeze({
+  UNATTRIBUTED: 'UNATTRIBUTED',
+  ATTRIBUTED: 'ATTRIBUTED',
+  LATE_UNMATCHED: 'LATE_UNMATCHED',
+  DUPLICATE_IGNORED: 'DUPLICATE_IGNORED'
+});
+
+/**
+ * Support ticket lifecycle states.
+ */
+export const TicketStatus = Object.freeze({
+  OPEN: 'OPEN',
+  IN_PROGRESS: 'IN_PROGRESS',
+  RESOLVED: 'RESOLVED',
+  CLOSED: 'CLOSED'
+});
+
+/**
+ * Live chat message sender identity type.
+ */
+export const SenderType = Object.freeze({
+  CUSTOMER: 'CUSTOMER',
+  ADMIN: 'ADMIN'
+});
+
+/**
+ * Audit log actor classifications.
+ */
+export const AuditActorType = Object.freeze({
+  SYSTEM: 'SYSTEM',
+  CUSTOMER: 'CUSTOMER',
+  ADMIN: 'ADMIN',
+  OBSERVER: 'OBSERVER'
+});

package/src/vendor/common/enums.ts

@@ -0,0 +1,91 @@
+/**
+ * Internal high-resolution payment session lifecycle states.
+ */
+export enum PaymentStatus {
+  INITIATED = 'INITIATED',
+  QUEUED = 'QUEUED',
+  ACTIVE = 'ACTIVE',
+  PROCESSING = 'PROCESSING',
+  SUCCESS = 'SUCCESS',
+  FAILED = 'FAILED',
+  EXPIRED = 'EXPIRED',
+  CANCELLED = 'CANCELLED'
+}
+
+/**
+ * Public-facing payment outcomes consumed by external merchants.
+ */
+export enum PublicPaymentOutcome {
+  SUCCESS = 'SUCCESS',
+  FAILED = 'FAILED',
+  EXPIRED = 'EXPIRED',
+  CANCELLED = 'CANCELLED'
+}
+
+/**
+ * Supported payment modalities.
+ */
+export enum PaymentMethod {
+  UPI = 'UPI',
+  COD = 'COD',
+  CASH_COUNTER = 'CASH_COUNTER',
+  CARD_COUNTER = 'CARD_COUNTER'
+}
+
+/**
+ * Merchant gateway selling modes.
+ */
+export enum SellingMode {
+  ONLINE = 'ONLINE',
+  OFFLINE = 'OFFLINE'
+}
+
+/**
+ * Observation channel sources feeding the payment detection engine (2-Layer: SMS + Gmail).
+ * Android observer layer is completely removed.
+ */
+export enum ObserverSource {
+  GMAIL = 'GMAIL',
+  GOOGLE_MESSAGES = 'GOOGLE_MESSAGES',
+  ANDROID_OBSERVER = 'ANDROID_OBSERVER',
+  SMS_GATEWAY = 'SMS_GATEWAY',
+  MANUAL_COUNTER = 'MANUAL_COUNTER'
+}
+
+/**
+ * Attribution status for raw observations.
+ */
+export enum ObservationAttributionStatus {
+  UNATTRIBUTED = 'UNATTRIBUTED',
+  ATTRIBUTED = 'ATTRIBUTED',
+  LATE_UNMATCHED = 'LATE_UNMATCHED',
+  DUPLICATE_IGNORED = 'DUPLICATE_IGNORED'
+}
+
+/**
+ * Support ticket lifecycle states.
+ */
+export enum TicketStatus {
+  OPEN = 'OPEN',
+  IN_PROGRESS = 'IN_PROGRESS',
+  RESOLVED = 'RESOLVED',
+  CLOSED = 'CLOSED'
+}
+
+/**
+ * Live chat message sender identity type.
+ */
+export enum SenderType {
+  CUSTOMER = 'CUSTOMER',
+  ADMIN = 'ADMIN'
+}
+
+/**
+ * Audit log actor classifications.
+ */
+export enum AuditActorType {
+  SYSTEM = 'SYSTEM',
+  CUSTOMER = 'CUSTOMER',
+  ADMIN = 'ADMIN',
+  OBSERVER = 'OBSERVER'
+}

package/src/vendor/common/index.js

@@ -0,0 +1,12 @@
+export * from './enums.js';
+export * from './state-transitions.js';
+export * from './money.js';
+export * from './crypto.js';
+export * from './observation.js';
+export * from './upi.js';
+export * from './upi-providers.js';
+export * from './contracts.js';
+export * from './runtime-config.js';
+export * from './secrets.js';
+export * from './tunnel-command.js';
+export * from './state-machine.js';

package/src/vendor/common/index.ts

@@ -0,0 +1,8 @@
+export * from './enums.js';
+export * from './money.js';
+export * from './crypto.js';
+export * from './observation.js';
+export * from './upi.js';
+export * from './upi-providers.js';
+export * from './contracts.js';
+export * from './state-machine.js';

package/src/vendor/common/money.js

@@ -0,0 +1,62 @@
+/**
+ * Financial utilities enforcing integer minor units (paise).
+ * Floating-point representation is strictly forbidden in financial calculations.
+ * 1 INR = 100 paise.
+ */
+
+/**
+ * Converts a rupee amount (string or number) into integer paise (bigint).
+ * Throws an error if invalid, negative, zero, or exceeds 2 decimal places.
+ * @param {string | number} rupees
+ * @returns {bigint}
+ */
+export function toPaise(rupees) {
+  if (typeof rupees === 'number') {
+    if (!Number.isFinite(rupees) || Number.isNaN(rupees)) {
+      throw new Error(`Invalid monetary amount: ${rupees}`);
+    }
+    rupees = rupees.toString();
+  }
+
+  const clean = String(rupees).trim();
+  if (!/^\d+(\.\d{1,2})?$/.test(clean)) {
+    throw new Error(`Invalid INR rupee format: "${rupees}". Must be non-negative with max 2 decimals.`);
+  }
+
+  const parts = clean.split('.');
+  const whole = BigInt(parts[0] || '0');
+  const fractionStr = parts[1] || '';
+  const fraction = BigInt(fractionStr.padEnd(2, '0'));
+
+  const totalPaise = whole * 100n + fraction;
+  if (totalPaise <= 0n) {
+    throw new Error(`Monetary amount must be strictly greater than 0: ${rupees}`);
+  }
+
+  return totalPaise;
+}
+
+/**
+ * Formats integer paise into a standard decimal string ("200.00").
+ * @param {bigint | number} paise
+ * @returns {string}
+ */
+export function toRupeesString(paise) {
+  const p = typeof paise === 'number' ? BigInt(Math.floor(paise)) : BigInt(paise);
+  if (p < 0n) {
+    throw new Error(`Negative paise value not permitted: ${p}`);
+  }
+
+  const whole = p / 100n;
+  const fraction = p % 100n;
+  return `${whole}.${fraction.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Formats integer paise into a localized INR display string ("₹200.00").
+ * @param {bigint | number} paise
+ * @returns {string}
+ */
+export function formatINR(paise) {
+  return `₹${toRupeesString(paise)}`;
+}