chargeback-guard 2.0.0

package/src/evidence/collector.ts

@@ -0,0 +1,426 @@
+// ============================================================
+//  CHARGEBACK GUARD — Evidence Collector
+//  Gathers all data points to build an airtight chargeback defense
+// ============================================================
+
+import crypto from 'crypto';
+import { createLogger } from '../utils/logger';
+import {
+  Evidence,
+  EvidenceData,
+  CustomerEvidenceData,
+  TransactionEvidenceData,
+  ShippingEvidenceData,
+  InteractionEvidenceData,
+  DeviceEvidenceData,
+  EmailEvidenceData,
+  CustomerHistoryData,
+  PaymentLogData,
+  GeolocationData,
+  RiskLevel,
+} from '../types';
+
+const log = createLogger('EvidenceCollector');
+
+// ────────────────────────────────────────────────────────────
+//  COLLECTION CONTEXT (input to the collector)
+// ────────────────────────────────────────────────────────────
+
+export interface CollectionContext {
+  orderId: string;
+  customerIp?: string;
+  userAgent?: string;
+  acceptLanguage?: string;
+  referer?: string;
+  sessionData?: {
+    sessionId?: string;
+    duration?: number;
+    pageViews?: Array<{ url: string; title?: string; duration: number; timestamp: string }>;
+    clickTracking?: Array<{ element: string; x: number; y: number; timestamp: string }>;
+    formInteractions?: Array<{ field: string; action: string; timestamp: string }>;
+    mouseTracking?: Array<{ x: number; y: number; timestamp: string }>;
+    scrollDepth?: number;
+    timeOnCheckout?: number;
+    referrer?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+  };
+  deviceFingerprint?: {
+    screenResolution?: string;
+    timezone?: string;
+    language?: string;
+    plugins?: string[];
+    fonts?: string[];
+    webgl?: string;
+    canvas?: string;
+    cookiesEnabled?: boolean;
+    doNotTrack?: string;
+    platform?: string;
+    hardwareConcurrency?: number;
+    deviceMemory?: number;
+    touchPoints?: number;
+  };
+  amount?: number;
+  currency?: string;
+  transactionId?: string;
+  paymentMethod?: string;
+  cardLastFour?: string;
+  cardBrand?: string;
+  shippingAddress?: Record<string, string>;
+  billingAddress?: Record<string, string>;
+  customerEmail?: string;
+  customerId?: string;
+  trackingNumber?: string;
+  estimatedDelivery?: string;
+  emailConfirmation?: {
+    sentAt: string;
+    opened?: boolean;
+    openedAt?: string;
+    clickedLinks?: string[];
+  };
+  customerHistory?: {
+    accountCreatedAt?: string;
+    previousPurchases?: number;
+    previousDisputes?: number;
+    riskScore?: number;
+    trustScore?: number;
+  };
+}
+
+// ────────────────────────────────────────────────────────────
+//  EVIDENCE COLLECTOR CLASS
+// ────────────────────────────────────────────────────────────
+
+export class EvidenceCollector {
+
+  private readonly strategies: {
+    [key: string]: (ctx: CollectionContext) => Promise<unknown>;
+  };
+
+  constructor() {
+    this.strategies = {
+      customerData:     this._collectCustomerData.bind(this),
+      transactionData:  this._collectTransactionData.bind(this),
+      shippingData:     this._collectShippingData.bind(this),
+      interactionData:  this._collectInteractionData.bind(this),
+      deviceFingerprint: this._collectDeviceFingerprint.bind(this),
+      emailConfirmation: this._collectEmailConfirmation.bind(this),
+      customerHistory:  this._collectCustomerHistory.bind(this),
+      paymentLog:       this._collectPaymentLog.bind(this),
+      geolocation:      this._collectGeolocation.bind(this),
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  MAIN COLLECT METHOD
+  // ──────────────────────────────────────────
+
+  async collect(ctx: CollectionContext): Promise<Evidence> {
+    log.debug(`Collecting evidence for order: ${ctx.orderId}`);
+
+    const collectionId = this._generateId();
+    const data: Partial<EvidenceData> = {};
+    const errors: string[] = [];
+
+    for (const [key, strategy] of Object.entries(this.strategies)) {
+      try {
+        (data as Record<string, unknown>)[key] = await strategy(ctx);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errors.push(`${key}: ${msg}`);
+        log.warn(`Evidence strategy failed: ${key}`, { error: msg });
+      }
+    }
+
+    const trustScore = this._calculateTrustScore(data as EvidenceData);
+    const riskLevel  = this._trustToRiskLevel(trustScore);
+
+    if (errors.length > 0) {
+      log.warn(`Evidence collection completed with ${errors.length} partial failures`, { errors });
+    }
+
+    const evidence: Evidence = {
+      collectionId,
+      orderId: ctx.orderId,
+      timestamp: new Date().toISOString(),
+      trustScore,
+      riskLevel,
+      data: data as EvidenceData,
+      metadata: {
+        collectionErrors: errors,
+        strategiesRun: Object.keys(this.strategies).length,
+        strategiesSucceeded: Object.keys(this.strategies).length - errors.length,
+      },
+    };
+
+    log.info(`Evidence collected for order: ${ctx.orderId}`, {
+      trustScore,
+      riskLevel,
+      collectionId,
+    });
+
+    return evidence;
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Customer Data
+  // ──────────────────────────────────────────
+
+  private async _collectCustomerData(ctx: CollectionContext): Promise<CustomerEvidenceData> {
+    return {
+      ipAddress: ctx.customerIp ?? '0.0.0.0',
+      userAgent: ctx.userAgent ?? 'Unknown',
+      acceptLanguage: ctx.acceptLanguage ?? 'Unknown',
+      referer: ctx.referer ?? 'direct',
+      deviceId: this._generateDeviceId(ctx),
+      email: ctx.customerEmail,
+      ipReputation: await this._getIpReputation(ctx.customerIp),
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Transaction Data
+  // ──────────────────────────────────────────
+
+  private async _collectTransactionData(ctx: CollectionContext): Promise<TransactionEvidenceData> {
+    return {
+      timestamp: new Date().toISOString(),
+      amount: ctx.amount ?? 0,
+      currency: ctx.currency ?? 'USD',
+      paymentMethod: ctx.paymentMethod,
+      cardLastFour: ctx.cardLastFour
+        ? this._maskCard(ctx.cardLastFour)
+        : undefined,
+      transactionId: ctx.transactionId ?? this._generateId(),
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Shipping Data
+  // ──────────────────────────────────────────
+
+  private async _collectShippingData(ctx: CollectionContext): Promise<ShippingEvidenceData> {
+    return {
+      address: ctx.shippingAddress as ShippingEvidenceData['address'],
+      country: (ctx.shippingAddress?.country) ?? undefined,
+      zip: ctx.shippingAddress?.postalCode,
+      trackingNumber: ctx.trackingNumber,
+      estimatedDelivery: ctx.estimatedDelivery,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Interaction Data
+  // ──────────────────────────────────────────
+
+  private async _collectInteractionData(ctx: CollectionContext): Promise<InteractionEvidenceData> {
+    const session = ctx.sessionData ?? {};
+    return {
+      sessionDuration: session.duration ?? 0,
+      pageViews: session.pageViews ?? [],
+      clickTracking: (session.clickTracking ?? []) as InteractionEvidenceData['clickTracking'],
+      formInteractions: (session.formInteractions ?? []) as InteractionEvidenceData['formInteractions'],
+      timeOnCheckout: session.timeOnCheckout ?? 0,
+      mouseTracking: session.mouseTracking,
+      scrollDepth: session.scrollDepth,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Device Fingerprint
+  // ──────────────────────────────────────────
+
+  private async _collectDeviceFingerprint(ctx: CollectionContext): Promise<DeviceEvidenceData> {
+    const fp = ctx.deviceFingerprint ?? {};
+    const fingerprintStr = JSON.stringify({
+      ua: ctx.userAgent,
+      screen: fp.screenResolution,
+      tz: fp.timezone,
+      lang: fp.language,
+      platform: fp.platform,
+    });
+
+    return {
+      screenResolution: fp.screenResolution,
+      timezone: fp.timezone,
+      language: fp.language,
+      plugins: fp.plugins,
+      fonts: fp.fonts,
+      webgl: fp.webgl,
+      canvas: fp.canvas,
+      fingerprint: crypto.createHash('sha256').update(fingerprintStr).digest('hex'),
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Email Confirmation
+  // ──────────────────────────────────────────
+
+  private async _collectEmailConfirmation(ctx: CollectionContext): Promise<EmailEvidenceData> {
+    const ec = ctx.emailConfirmation;
+    return {
+      sentTo: ctx.customerEmail ?? '',
+      sentAt: ec?.sentAt ?? new Date().toISOString(),
+      opened: ec?.opened,
+      openedAt: ec?.openedAt,
+      clickedLinks: ec?.clickedLinks ?? [],
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Customer History
+  // ──────────────────────────────────────────
+
+  private async _collectCustomerHistory(ctx: CollectionContext): Promise<CustomerHistoryData> {
+    const history = ctx.customerHistory ?? {};
+    const createdAt = history.accountCreatedAt ?? new Date().toISOString();
+    const accountAgeDays = Math.floor(
+      (Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24)
+    );
+
+    return {
+      accountCreatedAt: createdAt,
+      accountAge: accountAgeDays,
+      previousPurchases: history.previousPurchases ?? 0,
+      previousDisputes: history.previousDisputes ?? 0,
+      riskScore: history.riskScore ?? 0.1,
+      trustScore: history.trustScore ?? 0.8,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Payment Log
+  // ──────────────────────────────────────────
+
+  private async _collectPaymentLog(ctx: CollectionContext): Promise<PaymentLogData> {
+    return {
+      attempts: 1,
+      successful: 1,
+      failed: 0,
+      lastAttemptAt: new Date().toISOString(),
+      methods: [ctx.paymentMethod ?? 'card'],
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  STRATEGY: Geolocation
+  // ──────────────────────────────────────────
+
+  private async _collectGeolocation(ctx: CollectionContext): Promise<GeolocationData | null> {
+    if (!ctx.customerIp) { return null; }
+
+    try {
+      // geoip-lite provides offline lookup — no external API calls
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const geoip = require('geoip-lite');
+      const geo = geoip.lookup(ctx.customerIp);
+
+      if (!geo) { return null; }
+
+      return {
+        ip: ctx.customerIp,
+        country: geo.country ?? 'Unknown',
+        city: geo.city ?? 'Unknown',
+        timezone: geo.timezone ?? 'Unknown',
+        latitude: geo.ll?.[0],
+        longitude: geo.ll?.[1],
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  TRUST SCORE CALCULATOR
+  // ──────────────────────────────────────────
+
+  private _calculateTrustScore(data: EvidenceData): number {
+    let score = 40; // baseline
+
+    // Customer data quality (+15 max)
+    const cd = data.customerData;
+    if (cd?.ipAddress && cd.ipAddress !== '0.0.0.0') { score += 5; }
+    if (cd?.userAgent && cd.userAgent !== 'Unknown')  { score += 4; }
+    if (cd?.deviceId)                                  { score += 6; }
+
+    // Transaction quality (+10 max)
+    const td = data.transactionData;
+    if (td?.timestamp)     { score += 5; }
+    if (td?.transactionId) { score += 5; }
+
+    // Shipping quality (+20 max)
+    const sd = data.shippingData;
+    if (sd?.trackingNumber) { score += 15; }
+    if (sd?.address)         { score += 5; }
+
+    // Interaction quality (+20 max)
+    const id = data.interactionData;
+    if (id) {
+      if (id.sessionDuration > 60)    { score += 8; }
+      if (id.sessionDuration > 300)   { score += 4; }
+      if (id.pageViews?.length > 3)   { score += 5; }
+      if (id.timeOnCheckout > 30)     { score += 3; }
+    }
+
+    // Email confirmation (+10 max)
+    const ec = data.emailConfirmation;
+    if (ec?.sentTo)            { score += 5; }
+    if (ec?.opened === true)   { score += 5; }
+
+    // Customer history (+15 max)
+    const ch = data.customerHistory;
+    if (ch) {
+      if (ch.accountAge > 90)         { score += 5; }
+      if (ch.previousPurchases > 2)   { score += 5; }
+      if (ch.previousDisputes === 0)  { score += 5; }
+    }
+
+    // IP reputation adjustment
+    if (cd?.ipReputation !== undefined) {
+      if (cd.ipReputation < 0.3)      { score -= 15; }
+      else if (cd.ipReputation < 0.5) { score -= 8; }
+    }
+
+    return Math.max(0, Math.min(100, Math.round(score)));
+  }
+
+  private _trustToRiskLevel(trust: number): RiskLevel {
+    if (trust >= 90) { return RiskLevel.VERY_LOW; }
+    if (trust >= 75) { return RiskLevel.LOW; }
+    if (trust >= 55) { return RiskLevel.MEDIUM; }
+    if (trust >= 35) { return RiskLevel.HIGH; }
+    return RiskLevel.CRITICAL;
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _generateId(): string {
+    return crypto.randomBytes(16).toString('hex');
+  }
+
+  private _generateDeviceId(ctx: CollectionContext): string {
+    const str = JSON.stringify({
+      ua:       ctx.userAgent,
+      screen:   ctx.deviceFingerprint?.screenResolution,
+      tz:       ctx.deviceFingerprint?.timezone,
+      lang:     ctx.deviceFingerprint?.language,
+      platform: ctx.deviceFingerprint?.platform,
+    });
+    return crypto.createHash('sha256').update(str).digest('hex');
+  }
+
+  private _maskCard(card: string): string {
+    if (card.length <= 4) { return card; }
+    return card.slice(-4).padStart(card.length, '*');
+  }
+
+  private async _getIpReputation(ip?: string): Promise<number> {
+    // In production this would call an IP reputation service
+    // For now return a safe default
+    if (!ip || ip === '127.0.0.1' || ip === '0.0.0.0') { return 0.9; }
+    return 0.75; // neutral score
+  }
+}

package/src/evidence/encryption.ts

@@ -0,0 +1,168 @@
+// ============================================================
+//  CHARGEBACK GUARD — Evidence Encryption Module
+// ============================================================
+
+import crypto from 'crypto';
+import { createLogger } from '../utils/logger';
+import { securityConfig } from '../config';
+
+const log = createLogger('Encryption');
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;   // GCM recommended
+const TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+
+// ────────────────────────────────────────────────────────────
+//  KEY DERIVATION
+// ────────────────────────────────────────────────────────────
+
+function deriveKey(secret: string): Buffer {
+  return crypto.scryptSync(secret, 'chargebackguard-salt-v2', KEY_LENGTH);
+}
+
+// ────────────────────────────────────────────────────────────
+//  ENCRYPT
+// ────────────────────────────────────────────────────────────
+
+export function encrypt(plaintext: string, secret?: string): string {
+  const key = deriveKey(secret ?? securityConfig.encryptionKey);
+  const iv  = crypto.randomBytes(IV_LENGTH);
+
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv) as crypto.CipherGCM;
+  const encrypted = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  // Format: iv:tag:ciphertext (all hex)
+  return `${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+
+// ────────────────────────────────────────────────────────────
+//  DECRYPT
+// ────────────────────────────────────────────────────────────
+
+export function decrypt(ciphertext: string, secret?: string): string {
+  const key  = deriveKey(secret ?? securityConfig.encryptionKey);
+  const parts = ciphertext.split(':');
+
+  if (parts.length !== 3) {
+    throw new Error('Invalid ciphertext format');
+  }
+
+  const [ivHex, tagHex, encHex] = parts;
+  const iv        = Buffer.from(ivHex, 'hex');
+  const tag       = Buffer.from(tagHex, 'hex');
+  const encrypted = Buffer.from(encHex, 'hex');
+
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv) as crypto.DecipherGCM;
+  decipher.setAuthTag(tag);
+
+  return decipher.update(encrypted).toString('utf8') + decipher.final('utf8');
+}
+
+// ────────────────────────────────────────────────────────────
+//  HASH (one-way, for indexing sensitive fields)
+// ────────────────────────────────────────────────────────────
+
+export function hashField(value: string): string {
+  return crypto
+    .createHmac('sha256', securityConfig.encryptionKey)
+    .update(value.toLowerCase().trim())
+    .digest('hex');
+}
+
+// ────────────────────────────────────────────────────────────
+//  ENCRYPT OBJECT (encrypts PII fields in place)
+// ────────────────────────────────────────────────────────────
+
+const PII_FIELDS = [
+  'ipAddress', 'email', 'customerEmail', 'cardLastFour',
+  'phone', 'line1', 'line2', 'postalCode',
+];
+
+export function encryptPIIFields(
+  obj: Record<string, unknown>,
+  depth = 0
+): Record<string, unknown> {
+  if (depth > 5) { return obj; } // guard against deep nesting
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (PII_FIELDS.includes(key) && typeof value === 'string' && value) {
+      result[key] = encrypt(value);
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      result[key] = encryptPIIFields(value as Record<string, unknown>, depth + 1);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+export function decryptPIIFields(
+  obj: Record<string, unknown>,
+  depth = 0
+): Record<string, unknown> {
+  if (depth > 5) { return obj; }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (PII_FIELDS.includes(key) && typeof value === 'string' && value.includes(':')) {
+      try {
+        result[key] = decrypt(value);
+      } catch {
+        log.warn(`Failed to decrypt field: ${key}`);
+        result[key] = value; // leave as-is
+      }
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      result[key] = decryptPIIFields(value as Record<string, unknown>, depth + 1);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+// ────────────────────────────────────────────────────────────
+//  GENERATE SECURE TOKENS
+// ────────────────────────────────────────────────────────────
+
+export function generateApiKey(prefix = 'cbg_'): string {
+  const random = crypto.randomBytes(32).toString('base64url');
+  return `${prefix}${random}`;
+}
+
+export function generateWebhookSecret(): string {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+export function generateSecureToken(length = 32): string {
+  return crypto.randomBytes(length).toString('base64url');
+}
+
+// ────────────────────────────────────────────────────────────
+//  HMAC SIGNATURE (for webhooks)
+// ────────────────────────────────────────────────────────────
+
+export function signPayload(payload: string, secret: string): string {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+}
+
+export function verifySignature(payload: string, signature: string, secret: string): boolean {
+  const expected = signPayload(payload, secret);
+  const expectedBuf = Buffer.from(expected, 'hex');
+  const receivedBuf = Buffer.from(signature.replace('sha256=', ''), 'hex');
+
+  if (expectedBuf.length !== receivedBuf.length) { return false; }
+  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
+}