elpaypg 0.0.0-stage → 2.0.0

package/src/vendor/core/device-security.js

@@ -0,0 +1,506 @@
+import crypto from 'node:crypto';
+import {
+  safeEqual,
+  issueDeviceCredential,
+  verifyDeviceCredential,
+  createDeviceChallenge,
+  consumeDeviceChallenge
+} from '../common/index.js';
+
+export {
+  issueDeviceCredential,
+  verifyDeviceCredential,
+  createDeviceChallenge,
+  consumeDeviceChallenge
+};
+
+/**
+ * Normalizes privacy-conscious browser/device signals into a canonical dictionary.
+ * @param {Record<string, any>} signals
+ */
+export function normalizeDeviceSignals(signals = {}) {
+  const ua = (signals.userAgent || '').toString().trim().replace(/\s+/g, ' ');
+  const platform = (signals.platform || '').toString().trim().toLowerCase();
+  const language = (signals.language || '').toString().trim().toLowerCase();
+  const timezone = (signals.timezone || '').toString().trim();
+
+  let screenSig = signals.screenSignature || '';
+  if (!screenSig && signals.screenWidth && signals.screenHeight) {
+    screenSig = `${signals.screenWidth}x${signals.screenHeight}x${signals.screenColorDepth || 24}`;
+  }
+
+  const hardwareConcurrency = Math.max(0, parseInt(signals.hardwareConcurrency, 10) || 0);
+  const deviceMemory = Math.max(0, parseFloat(signals.deviceMemory) || 0);
+  const webglRenderer = (signals.webglRenderer || signals.webgl || '').toString().trim().toLowerCase();
+  const canvasSignature = (signals.canvasSignature || '').toString().trim();
+
+  return {
+    canvasSignature,
+    deviceMemory,
+    hardwareConcurrency,
+    language,
+    platform,
+    screenSignature: screenSig,
+    timezone,
+    userAgent: ua,
+    webglRenderer
+  };
+}
+
+/**
+ * Generates a stable SHA-256 hash of normalized browser/device signals.
+ * @param {Record<string, any>} signals
+ * @returns {string} SHA-256 hexadecimal hash
+ */
+export function generateFingerprintHash(signals = {}) {
+  const normalized = normalizeDeviceSignals(signals);
+  // Canonical serialization: keys sorted deterministically
+  const canonicalString = JSON.stringify(normalized, Object.keys(normalized).sort());
+  return crypto.createHash('sha256').update(canonicalString).digest('hex');
+}
+
+/**
+ * Imports a public key from base64 SPKI, DER buffer, or JWK.
+ * @param {string|object} publicKeyInput
+ * @returns {crypto.KeyObject}
+ */
+export function importDevicePublicKey(publicKeyInput) {
+  if (!publicKeyInput) {
+    throw new Error('Public key is required');
+  }
+
+  if (typeof publicKeyInput === 'object' && publicKeyInput.kty) {
+    return crypto.createPublicKey({
+      key: publicKeyInput,
+      format: 'jwk'
+    });
+  }
+
+  const str = String(publicKeyInput).trim();
+
+  // If PEM format
+  if (str.includes('BEGIN PUBLIC KEY')) {
+    return crypto.createPublicKey(str);
+  }
+
+  // If JSON JWK string
+  if (str.startsWith('{') && str.endsWith('}')) {
+    try {
+      const parsed = JSON.parse(str);
+      return crypto.createPublicKey({ key: parsed, format: 'jwk' });
+    } catch {}
+  }
+
+  // Otherwise assume base64 SPKI (DER)
+  const derBuffer = Buffer.from(str, 'base64');
+  return crypto.createPublicKey({
+    key: derBuffer,
+    format: 'der',
+    type: 'spki'
+  });
+}
+
+const DEFAULT_SIGNATURE_MAX_AGE_MS = 5 * 60 * 1000;
+const DEFAULT_SIGNATURE_CLOCK_SKEW_MS = 60 * 1000;
+const usedSignatureNonces = new Map();
+
+function pruneSignatureNonces(now = Date.now()) {
+  if (usedSignatureNonces.size < 256) return;
+  for (const [k, exp] of usedSignatureNonces.entries()) {
+    if (exp <= now) usedSignatureNonces.delete(k);
+  }
+}
+
+/**
+ * Extracts and validates the anti-replay `{ nonce, timestamp }` metadata from a signed payload.
+ * Payloads must be a JSON string/object `{ nonce, timestamp, ... }` or `<nonce>:<timestamp>[:...]`.
+ * @param {string|Buffer|object} dataToVerify
+ * @param {{ maxAgeMs?: number, maxClockSkewMs?: number, expectedDeviceId?: string, expectedChallenge?: string }} [options]
+ * @returns {{ canonicalBuffer: Buffer, nonce: string, timestamp: number } | null}
+ */
+export function parseSignedDevicePayload(dataToVerify, options = {}) {
+  if (dataToVerify === null || dataToVerify === undefined) return null;
+
+  const maxAgeMs = Number.isFinite(options.maxAgeMs) ? options.maxAgeMs : DEFAULT_SIGNATURE_MAX_AGE_MS;
+  const maxClockSkewMs = Number.isFinite(options.maxClockSkewMs) ? options.maxClockSkewMs : DEFAULT_SIGNATURE_CLOCK_SKEW_MS;
+
+  let rawString;
+  let parsedObj = null;
+
+  if (Buffer.isBuffer(dataToVerify)) {
+    rawString = dataToVerify.toString('utf8');
+  } else if (typeof dataToVerify === 'object') {
+    parsedObj = dataToVerify;
+    rawString = JSON.stringify(dataToVerify);
+  } else if (typeof dataToVerify === 'string') {
+    rawString = dataToVerify;
+  } else {
+    return null;
+  }
+
+  if (!parsedObj && rawString.trim().startsWith('{') && rawString.trim().endsWith('}')) {
+    try {
+      parsedObj = JSON.parse(rawString);
+    } catch {
+      return null;
+    }
+  }
+
+  let nonce = null;
+  let rawTs = null;
+
+  if (parsedObj && typeof parsedObj === 'object') {
+    nonce = typeof parsedObj.nonce === 'string' ? parsedObj.nonce.trim() : null;
+    rawTs = parsedObj.timestamp ?? parsedObj.ts ?? parsedObj.issuedAt;
+    if (options.expectedDeviceId && parsedObj.deviceId && parsedObj.deviceId !== options.expectedDeviceId) {
+      return null;
+    }
+    if (options.expectedChallenge && parsedObj.challenge !== options.expectedChallenge) {
+      return null;
+    }
+  } else {
+    // Support colon-separated `<nonce>:<timestamp>[:<challenge>...]`
+    const parts = rawString.split(':');
+    if (parts.length < 2) return null;
+    nonce = parts[0].trim();
+    rawTs = parts[1].trim();
+    if (options.expectedChallenge && !parts.slice(2).includes(options.expectedChallenge)) {
+      return null;
+    }
+  }
+
+  if (!nonce || nonce.length < 8 || nonce.length > 256) {
+    return null;
+  }
+
+  let timestampMs = NaN;
+  if (typeof rawTs === 'number' && Number.isFinite(rawTs)) {
+    timestampMs = rawTs >= 1e9 && rawTs < 1e11 ? rawTs * 1000 : rawTs;
+  } else if (typeof rawTs === 'string' && rawTs.trim()) {
+    const num = Number(rawTs.trim());
+    if (Number.isFinite(num)) {
+      timestampMs = num >= 1e9 && num < 1e11 ? num * 1000 : num;
+    } else {
+      timestampMs = Date.parse(rawTs.trim());
+    }
+  }
+
+  if (!Number.isFinite(timestampMs) || timestampMs <= 0) {
+    return null;
+  }
+
+  const now = Date.now();
+  if (now - timestampMs > maxAgeMs) {
+    return null;
+  }
+  if (timestampMs - now > maxClockSkewMs) {
+    return null;
+  }
+
+  const canonicalBuffer = Buffer.isBuffer(dataToVerify)
+    ? dataToVerify
+    : Buffer.from(rawString, 'utf8');
+
+  return { canonicalBuffer, nonce, timestamp: timestampMs };
+}
+
+/**
+ * Verifies an ECDSA P-256 signature generated by browser Web Crypto.
+ * Requires a fresh timestamp and single-use nonce in the signed payload.
+ * @param {string|object} publicKey
+ * @param {string|Buffer|object} dataToVerify
+ * @param {string} signatureBase64
+ * @param {{ maxAgeMs?: number, maxClockSkewMs?: number, expectedDeviceId?: string, expectedChallenge?: string }} [options]
+ * @returns {boolean}
+ */
+export function verifyDeviceSignature(publicKey, dataToVerify, signatureBase64, options = {}) {
+  try {
+    if (!publicKey || !signatureBase64) return false;
+
+    const parsed = parseSignedDevicePayload(dataToVerify, options);
+    if (!parsed) return false;
+
+    const keyObject = importDevicePublicKey(publicKey);
+    const dataBuffer = parsed.canonicalBuffer;
+    const sigStr = String(signatureBase64).trim();
+    if (!sigStr) return false;
+    const sigBuffer = Buffer.from(sigStr, 'base64');
+    if (sigBuffer.length === 0) return false;
+
+    const keyDer = keyObject.export({ format: 'der', type: 'spki' });
+    const keyFp = crypto.createHash('sha256').update(keyDer).digest('hex').slice(0, 32);
+    const nonceKey = `${keyFp}:${parsed.nonce}`;
+    const now = Date.now();
+    pruneSignatureNonces(now);
+
+    const existingExp = usedSignatureNonces.get(nonceKey);
+    if (existingExp && existingExp > now) {
+      return false;
+    }
+
+    let verified = false;
+
+    // Try ieee-p1363 (standard Web Crypto ECDSA output: r || s, 64 bytes)
+    try {
+      verified = crypto.verify(
+        'SHA256',
+        dataBuffer,
+        { key: keyObject, dsaEncoding: 'ieee-p1363' },
+        sigBuffer
+      );
+    } catch {}
+
+    // Fallback to standard DER encoding
+    if (!verified) {
+      try {
+        verified = crypto.verify(
+          'SHA256',
+          dataBuffer,
+          keyObject,
+          sigBuffer
+        );
+      } catch {}
+    }
+
+    if (!verified) return false;
+
+    const maxAgeMs = Number.isFinite(options.maxAgeMs) ? options.maxAgeMs : DEFAULT_SIGNATURE_MAX_AGE_MS;
+    usedSignatureNonces.set(nonceKey, now + maxAgeMs);
+    return true;
+  } catch (err) {
+    console.warn('[DeviceSecurity] Signature verification error:', err.message);
+    return false;
+  }
+}
+
+/**
+ * Verifies that a device exists, is ACTIVE, is not an adhoc placeholder, and that the
+ * caller presented a valid cryptographic credential (token or ECDSA signature).
+ * @param {{
+ *   deviceId: string,
+ *   deviceToken?: string|null,
+ *   deviceSignature?: string|null,
+ *   signaturePayload?: string|object|null,
+ *   deviceRepo: any
+ * }} params
+ * @returns {{ valid: boolean, error?: string, message?: string, device?: any }}
+ */
+export function verifyRegisteredDeviceCredentials({
+  deviceId,
+  deviceToken,
+  deviceSignature,
+  signaturePayload,
+  deviceRepo
+}) {
+  if (!deviceId || typeof deviceId !== 'string') {
+    return {
+      valid: false,
+      error: 'DEVICE_ID_REQUIRED',
+      message: 'A registered deviceId is required.'
+    };
+  }
+  if (!deviceRepo) {
+    return {
+      valid: false,
+      error: 'DEVICE_REPO_UNAVAILABLE',
+      message: 'Device repository is required for device verification.'
+    };
+  }
+
+  const dev = deviceRepo.findById(deviceId);
+  if (!dev || dev.status !== 'ACTIVE' || (typeof dev.publicKey === 'string' && dev.publicKey.startsWith('adhoc_'))) {
+    return {
+      valid: false,
+      error: 'DEVICE_REVOKED',
+      message: 'The device is unregistered, revoked, or invalid.'
+    };
+  }
+
+  const hasToken = typeof deviceToken === 'string' && deviceToken.trim().length > 0;
+  const hasSig = typeof deviceSignature === 'string' && deviceSignature.trim().length > 0;
+  const hasPayload = signaturePayload !== undefined && signaturePayload !== null && String(signaturePayload).trim().length > 0;
+
+  if (!hasToken && !hasSig) {
+    return {
+      valid: false,
+      error: 'DEVICE_CREDENTIALS_REQUIRED',
+      message: 'Device authentication credential (token or cryptographic signature) is required.'
+    };
+  }
+
+  if ((hasSig && !hasPayload) || (!hasSig && hasPayload)) {
+    return {
+      valid: false,
+      error: 'DEVICE_SIGNATURE_INVALID',
+      message: 'Both device signature and signed payload are required for signature verification.'
+    };
+  }
+
+  if (hasToken) {
+    let tokenOk = false;
+    if (typeof deviceRepo.verifyToken === 'function') {
+      tokenOk = deviceRepo.verifyToken(deviceId, deviceToken.trim());
+    } else if (dev.deviceToken) {
+      tokenOk = safeEqual(dev.deviceToken, deviceToken.trim()) && verifyDeviceCredential(deviceId, deviceToken.trim());
+    } else {
+      tokenOk = verifyDeviceCredential(deviceId, deviceToken.trim());
+    }
+    if (!tokenOk) {
+      return {
+        valid: false,
+        error: 'DEVICE_TOKEN_INVALID',
+        message: 'Device token failed verification.'
+      };
+    }
+  }
+
+  if (hasSig) {
+    const sigOk = verifyDeviceSignature(dev.publicKey, signaturePayload, deviceSignature, {
+      expectedDeviceId: deviceId
+    });
+    if (!sigOk) {
+      return {
+        valid: false,
+        error: 'DEVICE_SIGNATURE_INVALID',
+        message: 'Device cryptographic signature failed verification.'
+      };
+    }
+  }
+
+  return { valid: true, device: dev };
+}
+
+/**
+ * Validates whether the requesting device matches the payment session's bound device.
+ * @param {{
+ *   session: any,
+ *   requestingDeviceId?: string|null,
+ *   deviceToken?: string|null,
+ *   deviceSignature?: string|null,
+ *   signaturePayload?: string|null,
+ *   deviceRepo?: any
+ * }} options
+ * @returns {{
+ *   allowed: boolean,
+ *   shouldBind?: boolean,
+ *   error?: string,
+ *   session_id?: string,
+ *   action?: string,
+ *   message?: string,
+ *   boundDeviceId?: string|null,
+ *   requestingDeviceId?: string|null
+ * }}
+ */
+export function validateSessionDeviceAccess(options) {
+  const { session, requestingDeviceId, deviceToken, deviceSignature, signaturePayload, deviceRepo } = options || {};
+
+  if (!session) {
+    return {
+      allowed: false,
+      error: 'SESSION_NOT_FOUND',
+      message: 'Payment session not found'
+    };
+  }
+
+  const boundDeviceId = session.deviceId;
+
+  // If session is not yet bound to any device:
+  // Only allow binding if the caller presents a registered, cryptographically verified device.
+  if (!boundDeviceId) {
+    if (!requestingDeviceId) {
+      return {
+        allowed: false,
+        error: 'DEVICE_ID_REQUIRED',
+        session_id: session.id,
+        action: 'REGISTER_DEVICE',
+        message: 'A registered device identity is required to access or bind this checkout session.',
+        boundDeviceId: null,
+        requestingDeviceId: null
+      };
+    }
+
+    const credCheck = verifyRegisteredDeviceCredentials({
+      deviceId: requestingDeviceId,
+      deviceToken,
+      deviceSignature,
+      signaturePayload,
+      deviceRepo
+    });
+
+    if (!credCheck.valid) {
+      return {
+        allowed: false,
+        error: credCheck.error === 'DEVICE_SIGNATURE_INVALID' ? 'DEVICE_SIGNATURE_INVALID' : 'DUPLICATE_SESSION_DETECTED',
+        session_id: session.id,
+        action: 'END_SESSION_AND_CREATE_NEW',
+        message: credCheck.message || 'Valid registered device credentials are required.',
+        boundDeviceId: null,
+        requestingDeviceId
+      };
+    }
+
+    return {
+      allowed: true,
+      shouldBind: true,
+      requestingDeviceId
+    };
+  }
+
+  // If requesting device ID is missing or does not match bound device
+  if (!requestingDeviceId || requestingDeviceId !== boundDeviceId) {
+    return {
+      allowed: false,
+      error: 'DUPLICATE_SESSION_DETECTED',
+      session_id: session.id,
+      action: 'END_SESSION_AND_CREATE_NEW',
+      message: 'This payment session was created on another device. For security reasons, this session cannot be continued from this device.',
+      boundDeviceId,
+      requestingDeviceId: requestingDeviceId || null
+    };
+  }
+
+  // Verify the bound device is registered, active, and that the caller supplied a valid token or signature
+  const credCheck = verifyRegisteredDeviceCredentials({
+    deviceId: boundDeviceId,
+    deviceToken,
+    deviceSignature,
+    signaturePayload,
+    deviceRepo
+  });
+
+  if (!credCheck.valid) {
+    if (credCheck.error === 'DEVICE_REVOKED') {
+      return {
+        allowed: false,
+        error: 'DEVICE_REVOKED',
+        session_id: session.id,
+        action: 'END_SESSION_AND_CREATE_NEW',
+        message: 'The device registered for this payment session has been revoked or is invalid.'
+      };
+    }
+    if (credCheck.error === 'DEVICE_SIGNATURE_INVALID') {
+      return {
+        allowed: false,
+        error: 'DEVICE_SIGNATURE_INVALID',
+        session_id: session.id,
+        action: 'END_SESSION_AND_CREATE_NEW',
+        message: 'Device cryptographic signature failed verification.'
+      };
+    }
+    return {
+      allowed: false,
+      error: 'DUPLICATE_SESSION_DETECTED',
+      session_id: session.id,
+      action: 'END_SESSION_AND_CREATE_NEW',
+      message: 'This payment session was created on another device. For security reasons, this session cannot be continued from this device.',
+      boundDeviceId,
+      requestingDeviceId
+    };
+  }
+
+  return {
+    allowed: true,
+    boundDeviceId,
+    requestingDeviceId
+  };
+}

package/src/vendor/core/index.js

@@ -0,0 +1,13 @@
+export * from './state-machine.js';
+export * from './normalizer.js';
+export * from './attribution-engine.js';
+export * from './queue-engine.js';
+export * from './timing-engine.js';
+export * from './recovery-engine.js';
+export * from './webhook-engine.js';
+export * from './bank-sms-parser.js';
+export * from './bank-email-parser.js';
+export * from './qr.js';
+export * from './verification-pipeline.js';
+export * from './device-security.js';
+

package/src/vendor/core/normalizer.js

@@ -0,0 +1,165 @@
+import { ObserverSource, ObservationAttributionStatus, toPaise, calculateObservationFingerprint } from '../common/index.js';
+
+/**
+ * Intelligent Monetary Amount Extractor.
+ * Extracts amounts with prefix (Rs. 20.00, INR 500), suffix (20.00 Rs),
+ * proximity words ("20.00 received", "received 20.00", "credited 20"),
+ * or clean standalone decimal amounts ("20.00").
+ * @param {string} text
+ * @returns {bigint | null}
+ */
+export function extractIntelligentPaise(text) {
+  if (!text || typeof text !== 'string') return null;
+
+  // Pattern 1: Standard currency prefix (e.g. Rs. 20.00, Rs 200, INR 500.00, ₹1,200.50, ₹20)
+  const prefixMatch = text.match(/(?:rs\.?|inr|₹)\s*([\d,]+(?:\.\d{1,2})?)/i);
+  if (prefixMatch && prefixMatch[1]) {
+    const clean = prefixMatch[1].replace(/,/g, '');
+    try { return toPaise(clean); } catch {}
+  }
+
+  // Pattern 2: Standard currency suffix (e.g. 20.00 Rs, 20.00 INR, 20rs, 500 inr)
+  const suffixMatch = text.match(/([\d,]+(?:\.\d{1,2})?)\s*(?:rs\.?|inr|₹)/i);
+  if (suffixMatch && suffixMatch[1]) {
+    const clean = suffixMatch[1].replace(/,/g, '');
+    try { return toPaise(clean); } catch {}
+  }
+
+  // Pattern 3: Number in proximity to credit keywords (e.g. "20.00 received", "received 20.00", "credited 20", "20.00 credited")
+  const creditProximityMatch = text.match(/(?:credited|received|deposit|payment|paid|transferred|upi|cr)[\s\w:]*?([\d,]+(?:\.\d{1,2})?)|([\d,]+(?:\.\d{1,2})?)[\s\w:]*?(?:credited|received|deposit|payment|paid|transferred|upi|cr)/i);
+  if (creditProximityMatch) {
+    const rawVal = creditProximityMatch[1] || creditProximityMatch[2];
+    if (rawVal) {
+      const clean = rawVal.replace(/,/g, '');
+      if (/^\d+(\.\d{1,2})?$/.test(clean) && Number(clean) < 10000000 && Number(clean) > 0) {
+        try { return toPaise(clean); } catch {}
+      }
+    }
+  }
+
+  // Pattern 4: Standalone decimal currency number (e.g. 20.00, 150.50, 449.00)
+  const standaloneDecimal = text.match(/\b(\d{1,6}\.\d{2})\b/);
+  if (standaloneDecimal && standaloneDecimal[1]) {
+    try { return toPaise(standaloneDecimal[1]); } catch {}
+  }
+
+  return null;
+}
+
+/**
+ * Regex for extracting bank UTR / Reference numbers.
+ * Matches: UTR: 123456789012, Ref 123456789012, Txn: ABC123XYZ, RRN: 987654
+ */
+const REFERENCE_REGEX = /(?:utr|ref(?:\s*no\.?)?|txn(?:\s*(?:id|#))?|transaction\s*id|rrn|reference(?:\s*no\.?)?|upi(?:\s*(?:ref|reference|txn))?)[:\s#]+([a-zA-Z0-9\-_]{6,35})/i;
+
+/**
+ * Regex for extracting sender VPA if present in notification text.
+ * Matches: from user@upi, from 9876543210@paytm, from Rahul (UPI ID: rahul@fam), etc.
+ */
+const SENDER_VPA_REGEX = /(?:from|by|vpa|upi\s*id)[\s:]+(?:[a-zA-Z\s]+[\(\[])?([a-zA-Z0-9.\-_]{2,100}@[a-zA-Z0-9.\-_]{2,64})/i;
+
+export class ObservationNormalizer {
+  /**
+   * Normalizes raw incoming data from any observation source into a canonical observation record.
+   * @param {{
+   *   source: string,
+   *   receivingAccountId: string,
+   *   rawPayload: Record<string, any>,
+   *   amountPaise?: bigint | number | string,
+   *   amount?: string | number,
+   *   observedAt?: Date | string,
+   *   senderVpa?: string,
+   *   bankReferenceNumber?: string
+   * }} input
+   * @returns {{
+   *   receivingAccountId: string,
+   *   source: string,
+   *   amountPaise: bigint,
+   *   observedAt: Date,
+   *   senderVpa?: string,
+   *   bankReferenceNumber?: string,
+   *   fingerprintHash: string,
+   *   attributionStatus: string,
+   *   rawPayload: Record<string, any>
+   * }}
+   */
+  static normalize(input) {
+    if (!input.receivingAccountId) {
+      throw new Error('Observation normalization failed: receivingAccountId is required.');
+    }
+    if (!input.source || !Object.values(ObserverSource).includes(input.source)) {
+      throw new Error(`Observation normalization failed: invalid or unknown source '${input.source}'.`);
+    }
+
+    const payload = input.rawPayload || {};
+    const textContent = (payload.text || payload.body || payload.notificationText || payload.snippet || '').toString();
+
+    // 1. Resolve Amount using priority resolution: explicit paise -> explicit amount -> intelligent multi-pattern extraction
+    let finalAmountPaise;
+    if (input.amountPaise !== undefined && input.amountPaise !== null && input.amountPaise !== '') {
+      finalAmountPaise = BigInt(input.amountPaise);
+    } else if (input.amount !== undefined && input.amount !== null && input.amount !== '') {
+      finalAmountPaise = toPaise(input.amount);
+    } else {
+      const extracted = extractIntelligentPaise(textContent);
+      if (!extracted) {
+        throw new Error(`Observation normalization failed: could not extract valid monetary amount from payload text: "${textContent}"`);
+      }
+      finalAmountPaise = extracted;
+    }
+
+    // 2. Resolve Observed Timestamp
+    let observedAtDate;
+    if (input.observedAt) {
+      observedAtDate = input.observedAt instanceof Date ? input.observedAt : new Date(input.observedAt);
+    } else if (payload.timestamp || payload.postTime || payload.date) {
+      const rawTs = payload.timestamp || payload.postTime || payload.date;
+      observedAtDate = new Date(typeof rawTs === 'number' ? rawTs : rawTs.toString());
+    } else {
+      observedAtDate = new Date();
+    }
+
+    if (isNaN(observedAtDate.getTime())) {
+      observedAtDate = new Date();
+    }
+
+    // 3. Resolve Reference Number / UTR
+    let bankRef = input.bankReferenceNumber;
+    if (!bankRef && textContent) {
+      const refMatch = textContent.match(REFERENCE_REGEX);
+      if (refMatch && refMatch[1]) {
+        bankRef = refMatch[1].trim();
+      }
+    }
+
+    // 4. Resolve Sender VPA
+    let senderVpa = input.senderVpa;
+    if (!senderVpa && textContent) {
+      const vpaMatch = textContent.match(SENDER_VPA_REGEX);
+      if (vpaMatch && vpaMatch[1]) {
+        senderVpa = vpaMatch[1].trim().replace(/[.,;]+$/, '');
+      }
+    }
+
+    // 5. Compute Deterministic Fingerprint
+    const fingerprintHash = calculateObservationFingerprint({
+      receivingAccountId: input.receivingAccountId,
+      amountPaise: finalAmountPaise,
+      source: input.source,
+      bankReferenceNumber: bankRef,
+      observedAt: observedAtDate
+    });
+
+    return {
+      receivingAccountId: input.receivingAccountId,
+      source: input.source,
+      amountPaise: finalAmountPaise,
+      observedAt: observedAtDate,
+      senderVpa: senderVpa || undefined,
+      bankReferenceNumber: bankRef || undefined,
+      fingerprintHash,
+      attributionStatus: ObservationAttributionStatus.UNATTRIBUTED,
+      rawPayload: payload
+    };
+  }
+}