chargeback-guard 2.0.0

package/src/evidence/storage.ts

@@ -0,0 +1,197 @@
+// ============================================================
+//  CHARGEBACK GUARD — Evidence Storage
+//  Persists, retrieves and manages evidence records securely
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import { Evidence } from '../types';
+import { encryptPIIFields, decryptPIIFields } from './encryption';
+
+const log = createLogger('EvidenceStorage');
+
+// In-memory store for standalone / testing usage.
+// Production replaces this with the DatabaseManager.
+interface EvidenceRow {
+  collectionId: string;
+  orderId: string;
+  evidenceJson: string;
+  trustScore: number;
+  riskLevel: string;
+  collectedAt: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  EVIDENCE STORAGE CLASS
+// ────────────────────────────────────────────────────────────
+
+export class EvidenceStorage {
+  // Fallback in-memory store (used when DB not yet initialised)
+  private readonly memoryStore: Map<string, EvidenceRow> = new Map();
+  private db: unknown = null;
+
+  // Allow the core to inject the DB at runtime
+  setDatabase(db: unknown): void {
+    this.db = db;
+  }
+
+  // ──────────────────────────────────────────
+  //  STORE
+  // ──────────────────────────────────────────
+
+  async store(evidence: Evidence): Promise<string> {
+    log.debug(`Storing evidence: ${evidence.collectionId}`, {
+      orderId: evidence.orderId,
+      trustScore: evidence.trustScore,
+    });
+
+    // Encrypt PII before persisting
+    const safeCopy = { ...evidence, data: encryptPIIFields(evidence.data as Record<string, unknown>) };
+    const json = JSON.stringify(safeCopy);
+
+    const row: EvidenceRow = {
+      collectionId: evidence.collectionId,
+      orderId: evidence.orderId,
+      evidenceJson: json,
+      trustScore: evidence.trustScore,
+      riskLevel: evidence.riskLevel,
+      collectedAt: evidence.timestamp,
+    };
+
+    if (this.db) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await (this.db as any).evidence.create(row);
+      } catch (err) {
+        log.warn('DB store failed, using memory fallback', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+        this.memoryStore.set(evidence.orderId, row);
+      }
+    } else {
+      this.memoryStore.set(evidence.orderId, row);
+    }
+
+    log.info(`Evidence stored: ${evidence.collectionId} for order: ${evidence.orderId}`);
+    return evidence.collectionId;
+  }
+
+  // ──────────────────────────────────────────
+  //  FIND BY ORDER ID
+  // ──────────────────────────────────────────
+
+  async findByOrderId(orderId: string): Promise<Evidence | null> {
+    log.debug(`Looking up evidence for order: ${orderId}`);
+
+    let row: EvidenceRow | null = null;
+
+    if (this.db) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        row = await (this.db as any).evidence.findByOrderId(orderId);
+      } catch {
+        row = this.memoryStore.get(orderId) ?? null;
+      }
+    } else {
+      row = this.memoryStore.get(orderId) ?? null;
+    }
+
+    if (!row) {
+      log.warn(`No evidence found for order: ${orderId}`);
+      return null;
+    }
+
+    return this._deserialize(row);
+  }
+
+  // ──────────────────────────────────────────
+  //  FIND BY COLLECTION ID
+  // ──────────────────────────────────────────
+
+  async findByCollectionId(collectionId: string): Promise<Evidence | null> {
+    if (this.db) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const row = await (this.db as any).evidence.findByCollectionId(collectionId);
+        return row ? this._deserialize(row) : null;
+      } catch {
+        // fall through to memory
+      }
+    }
+
+    for (const row of this.memoryStore.values()) {
+      if (row.collectionId === collectionId) {
+        return this._deserialize(row);
+      }
+    }
+
+    return null;
+  }
+
+  // ──────────────────────────────────────────
+  //  UPDATE
+  // ──────────────────────────────────────────
+
+  async update(orderId: string, updates: Partial<Evidence>): Promise<boolean> {
+    const existing = await this.findByOrderId(orderId);
+    if (!existing) { return false; }
+
+    const merged: Evidence = { ...existing, ...updates };
+    await this.store(merged);
+    return true;
+  }
+
+  // ──────────────────────────────────────────
+  //  DELETE (GDPR right to erasure)
+  // ──────────────────────────────────────────
+
+  async delete(orderId: string): Promise<boolean> {
+    log.info(`Deleting evidence for order: ${orderId}`);
+
+    if (this.db) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await (this.db as any).evidence.deleteByOrderId(orderId);
+      } catch {
+        this.memoryStore.delete(orderId);
+      }
+    } else {
+      this.memoryStore.delete(orderId);
+    }
+
+    return true;
+  }
+
+  // ──────────────────────────────────────────
+  //  LIST (paginated)
+  // ──────────────────────────────────────────
+
+  async list(
+    page = 1,
+    limit = 20
+  ): Promise<{ items: Evidence[]; total: number }> {
+    const all = Array.from(this.memoryStore.values());
+    const start = (page - 1) * limit;
+    const slice = all.slice(start, start + limit);
+
+    return {
+      items: slice.map(r => this._deserialize(r)).filter(Boolean) as Evidence[],
+      total: all.length,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _deserialize(row: EvidenceRow): Evidence {
+    const parsed: Evidence = JSON.parse(row.evidenceJson);
+    // Decrypt PII
+    parsed.data = decryptPIIFields(parsed.data as Record<string, unknown>) as Evidence['data'];
+    return parsed;
+  }
+
+  // Expose store size for health checks
+  get size(): number {
+    return this.memoryStore.size;
+  }
+}

package/src/evidence/validator.ts

@@ -0,0 +1,184 @@
+// ============================================================
+//  CHARGEBACK GUARD — Evidence Validator
+// ============================================================
+
+import { z } from 'zod';
+import { createLogger } from '../utils/logger';
+import { Evidence, RiskLevel } from '../types';
+
+const log = createLogger('EvidenceValidator');
+
+// ────────────────────────────────────────────────────────────
+//  VALIDATION SCHEMAS
+// ────────────────────────────────────────────────────────────
+
+const ipSchema = z.string().ip().optional().or(z.literal('0.0.0.0')).optional();
+
+const evidenceDataSchema = z.object({
+  customerData: z.object({
+    ipAddress: z.string().default('0.0.0.0'),
+    userAgent: z.string().default('Unknown'),
+    deviceId: z.string(),
+    email: z.string().email().optional(),
+    ipReputation: z.number().min(0).max(1).optional(),
+  }),
+  transactionData: z.object({
+    timestamp: z.string(),
+    amount: z.number().min(0),
+    currency: z.string().length(3),
+    transactionId: z.string(),
+  }),
+  shippingData: z.object({
+    trackingNumber: z.string().optional(),
+    address: z.any().optional(),
+  }).optional(),
+  interactionData: z.object({
+    sessionDuration: z.number().min(0),
+    pageViews: z.array(z.any()).default([]),
+    clickTracking: z.array(z.any()).default([]),
+    formInteractions: z.array(z.any()).default([]),
+    timeOnCheckout: z.number().min(0),
+  }).optional(),
+}).passthrough();
+
+const evidenceSchema = z.object({
+  collectionId: z.string().min(1),
+  orderId: z.string().min(1),
+  timestamp: z.string(),
+  trustScore: z.number().min(0).max(100),
+  riskLevel: z.nativeEnum(RiskLevel),
+  data: evidenceDataSchema,
+});
+
+// ────────────────────────────────────────────────────────────
+//  VALIDATION RESULT
+// ────────────────────────────────────────────────────────────
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  sanitizedEvidence: Evidence;
+}
+
+// ────────────────────────────────────────────────────────────
+//  EVIDENCE VALIDATOR CLASS
+// ────────────────────────────────────────────────────────────
+
+export class EvidenceValidator {
+
+  async validate(evidence: Evidence): Promise<Evidence> {
+    log.debug(`Validating evidence: ${evidence.collectionId}`);
+
+    const result = await this.validateDetailed(evidence);
+
+    if (!result.valid && result.errors.length > 0) {
+      log.warn(`Evidence validation issues: ${evidence.collectionId}`, {
+        errors: result.errors,
+        warnings: result.warnings,
+      });
+    }
+
+    return result.sanitizedEvidence;
+  }
+
+  async validateDetailed(evidence: Evidence): Promise<ValidationResult> {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // ── Schema validation ──
+    try {
+      evidenceSchema.parse(evidence);
+    } catch (err) {
+      if (err instanceof z.ZodError) {
+        err.errors.forEach(e => errors.push(`${e.path.join('.')}: ${e.message}`));
+      }
+    }
+
+    // ── Business-rule validations ──
+    this._validateBusinessRules(evidence, errors, warnings);
+
+    // ── Sanitize ──
+    const sanitizedEvidence = this._sanitize(evidence);
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      sanitizedEvidence,
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  BUSINESS RULE VALIDATION
+  // ──────────────────────────────────────────
+
+  private _validateBusinessRules(
+    ev: Evidence,
+    errors: string[],
+    warnings: string[]
+  ): void {
+    // Trust score range
+    if (ev.trustScore < 0 || ev.trustScore > 100) {
+      errors.push(`trustScore out of range: ${ev.trustScore}`);
+    }
+
+    // Timestamp must be recent (within 24 hours)
+    const ts = new Date(ev.timestamp).getTime();
+    const now = Date.now();
+    if (isNaN(ts)) {
+      errors.push('timestamp is not a valid date');
+    } else if (now - ts > 86400000 * 2) {
+      warnings.push('Evidence timestamp is older than 48 hours');
+    }
+
+    // Customer IP warning
+    const ip = ev.data?.customerData?.ipAddress;
+    if (!ip || ip === '0.0.0.0') {
+      warnings.push('No customer IP address recorded — weakens defense');
+    }
+
+    // Shipping tracking warning
+    if (!ev.data?.shippingData?.trackingNumber) {
+      warnings.push('No shipping tracking number — weakens physical delivery proof');
+    }
+
+    // Low trust score warning
+    if (ev.trustScore < 40) {
+      warnings.push(`Low trust score (${ev.trustScore}) — consider manual review`);
+    }
+
+    // Critical trust score
+    if (ev.trustScore < 20) {
+      errors.push(`Critically low trust score (${ev.trustScore}) — evidence insufficient`);
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  SANITIZER
+  // ──────────────────────────────────────────
+
+  private _sanitize(evidence: Evidence): Evidence {
+    const sanitized: Evidence = JSON.parse(JSON.stringify(evidence)); // deep clone
+
+    // Clamp score
+    sanitized.trustScore = Math.max(0, Math.min(100, sanitized.trustScore));
+
+    // Remove undefined values
+    this._removeUndefined(sanitized);
+
+    return sanitized;
+  }
+
+  private _removeUndefined(obj: unknown): void {
+    if (typeof obj !== 'object' || obj === null) { return; }
+    for (const key of Object.keys(obj as Record<string, unknown>)) {
+      const val = (obj as Record<string, unknown>)[key];
+      if (val === undefined) {
+        delete (obj as Record<string, unknown>)[key];
+      } else {
+        this._removeUndefined(val);
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// ============================================================
+//  CHARGEBACK GUARD — Public Package Entry Point
+// ============================================================
+
+export { ChargebackGuard } from './core/chargebackGuard';
+export { ChargebackEventEmitter } from './core/eventEmitter';
+export { LifecycleManager } from './core/lifecycle';
+
+// Types — everything consumers need
+export * from './types';
+
+// Config export (readonly)
+export { default as config } from './config';
+
+// Named re-exports for convenience
+export type { RegistrationResult, DisputeHandlingResult } from './core/chargebackGuard';
+export type { HealthCheck, LifecycleStatus } from './core/lifecycle';
+
+// ────────────────────────────────────────────────────────────
+//  DEFAULT FACTORY (quick-start)
+// ────────────────────────────────────────────────────────────
+
+import { ChargebackGuard } from './core/chargebackGuard';
+import { ChargebackGuardConfig } from './types';
+
+/**
+ * Create and initialize a ChargebackGuard instance in one call.
+ *
+ * @example
+ * const guard = await createChargebackGuard({
+ *   apiKey: process.env.STRIPE_SECRET_KEY!,
+ *   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+ * });
+ */
+export async function createChargebackGuard(
+  options: Partial<ChargebackGuardConfig> = {}
+): Promise<ChargebackGuard> {
+  const guard = new ChargebackGuard(options);
+  await guard.initialize();
+  return guard;
+}
+
+export default ChargebackGuard;

package/src/integrations/paypal.ts

@@ -0,0 +1,258 @@
+// ============================================================
+//  CHARGEBACK GUARD — PayPal Integration (Full)
+// ============================================================
+
+import axios, { AxiosInstance } from 'axios';
+import { createLogger } from '../utils/logger';
+import { paypalConfig } from '../config';
+import {
+  Dispute,
+  DisputeReply,
+  DisputeReason,
+  DisputeStatus,
+  PaymentProvider,
+} from '../types';
+
+const log = createLogger('PayPalIntegration');
+
+interface PayPalTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+// ────────────────────────────────────────────────────────────
+//  PAYPAL INTEGRATION CLASS
+// ────────────────────────────────────────────────────────────
+
+export class PayPalIntegration {
+  private readonly baseUrl: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private accessToken: string | null = null;
+  private tokenExpiry: number = 0;
+  private readonly http: AxiosInstance;
+
+  constructor(
+    clientId?: string,
+    clientSecret?: string,
+    mode?: 'sandbox' | 'live'
+  ) {
+    this.clientId = clientId ?? paypalConfig.clientId;
+    this.clientSecret = clientSecret ?? paypalConfig.clientSecret;
+    const env = mode ?? paypalConfig.mode;
+
+    this.baseUrl = env === 'live'
+      ? 'https://api.paypal.com'
+      : 'https://api.sandbox.paypal.com';
+
+    this.http = axios.create({
+      baseURL: this.baseUrl,
+      timeout: 30000,
+    });
+
+    log.debug(`PayPal client initialized (${env})`);
+  }
+
+  // ──────────────────────────────────────────
+  //  AUTH
+  // ──────────────────────────────────────────
+
+  async authenticate(): Promise<string> {
+    if (this.accessToken && Date.now() < this.tokenExpiry) {
+      return this.accessToken;
+    }
+
+    const response = await axios.post<PayPalTokenResponse>(
+      `${this.baseUrl}/v1/oauth2/token`,
+      'grant_type=client_credentials',
+      {
+        auth: { username: this.clientId, password: this.clientSecret },
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      }
+    );
+
+    this.accessToken = response.data.access_token;
+    this.tokenExpiry = Date.now() + (response.data.expires_in - 60) * 1000;
+    log.debug('PayPal access token refreshed');
+    return this.accessToken;
+  }
+
+  private async _authHeaders(): Promise<Record<string, string>> {
+    const token = await this.authenticate();
+    return {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  GET DISPUTE
+  // ──────────────────────────────────────────
+
+  async getDispute(disputeId: string): Promise<Dispute> {
+    log.debug(`Fetching PayPal dispute: ${disputeId}`);
+    const headers = await this._authHeaders();
+    const response = await this.http.get(`/v1/customer/disputes/${disputeId}`, { headers });
+    return this._mapDisputeResponse(response.data as Record<string, unknown>);
+  }
+
+  // ──────────────────────────────────────────
+  //  LIST DISPUTES
+  // ──────────────────────────────────────────
+
+  async listDisputes(params?: { status?: string; limit?: number }): Promise<Dispute[]> {
+    const headers = await this._authHeaders();
+    const response = await this.http.get('/v1/customer/disputes', {
+      headers,
+      params: {
+        dispute_state: params?.status ?? 'OPEN',
+        page_size: params?.limit ?? 50,
+      },
+    });
+
+    const data = response.data as Record<string, unknown>;
+    const items = (data['items'] as Record<string, unknown>[]) ?? [];
+    return items.map(item => this._mapDisputeResponse(item));
+  }
+
+  // ──────────────────────────────────────────
+  //  SUBMIT EVIDENCE
+  // ──────────────────────────────────────────
+
+  async submitDisputeEvidence(disputeId: string, reply: DisputeReply): Promise<void> {
+    log.info(`Submitting PayPal dispute evidence: ${disputeId}`);
+    const headers = await this._authHeaders();
+
+    const evidencePayload = {
+      evidences: reply.evidenceItems.map(item => ({
+        evidence_type: this._mapEvidenceType(item.type as string),
+        notes: `${item.description}\n\n${JSON.stringify(item.data, null, 2)}`,
+      })),
+      note: reply.caseArgument,
+    };
+
+    await this.http.post(
+      `/v1/customer/disputes/${disputeId}/provide-evidence`,
+      evidencePayload,
+      { headers }
+    );
+
+    log.info(`PayPal evidence submitted: ${disputeId}`);
+  }
+
+  // ──────────────────────────────────────────
+  //  ACCEPT DISPUTE (when appropriate)
+  // ──────────────────────────────────────────
+
+  async acceptDispute(disputeId: string, note?: string): Promise<void> {
+    const headers = await this._authHeaders();
+    await this.http.post(
+      `/v1/customer/disputes/${disputeId}/accept-dispute`,
+      { note: note ?? 'Accepting dispute per merchant decision.' },
+      { headers }
+    );
+  }
+
+  // ──────────────────────────────────────────
+  //  APPEAL DISPUTE
+  // ──────────────────────────────────────────
+
+  async appealDispute(disputeId: string, note: string): Promise<void> {
+    const headers = await this._authHeaders();
+    await this.http.post(
+      `/v1/customer/disputes/${disputeId}/appeal`,
+      { evidences: [{ evidence_type: 'PROOF_OF_FULFILLMENT', notes: note }] },
+      { headers }
+    );
+  }
+
+  // ──────────────────────────────────────────
+  //  WEBHOOK VERIFICATION
+  // ──────────────────────────────────────────
+
+  async verifyWebhookSignature(
+    headers: Record<string, string>,
+    body: string
+  ): Promise<boolean> {
+    const authToken = await this.authenticate();
+    try {
+      const response = await this.http.post(
+        '/v1/notifications/verify-webhook-signature',
+        {
+          auth_algo: headers['paypal-auth-algo'],
+          cert_url: headers['paypal-cert-url'],
+          transmission_id: headers['paypal-transmission-id'],
+          transmission_sig: headers['paypal-transmission-sig'],
+          transmission_time: headers['paypal-transmission-time'],
+          webhook_id: paypalConfig.webhookId,
+          webhook_event: JSON.parse(body),
+        },
+        { headers: { Authorization: `Bearer ${authToken}`, 'Content-Type': 'application/json' } }
+      );
+      return (response.data as Record<string, string>)['verification_status'] === 'SUCCESS';
+    } catch {
+      return false;
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _mapDisputeResponse(data: Record<string, unknown>): Dispute {
+    const disputeAmount = (data['dispute_amount'] as Record<string, string> | undefined);
+    const amountValue   = disputeAmount?.['value'] ? parseFloat(disputeAmount.value) * 100 : 0;
+
+    return {
+      id: String(data['dispute_id'] ?? ''),
+      orderId: this._extractOrderId(data),
+      amount: Math.round(amountValue),
+      currency: (disputeAmount?.['currency_code']) ?? 'USD',
+      reason: this._mapReason(String(data['reason'] ?? 'OTHER')),
+      status: this._mapStatus(String(data['status'] ?? 'OPEN')),
+      provider: PaymentProvider.PAYPAL,
+      createdAt: String(data['create_time'] ?? new Date().toISOString()),
+      metadata: { raw: data },
+    };
+  }
+
+  private _extractOrderId(data: Record<string, unknown>): string | undefined {
+    const txns = data['disputed_transactions'] as Array<Record<string, string>> | undefined;
+    return txns?.[0]?.['seller_transaction_id'];
+  }
+
+  private _mapReason(reason: string): DisputeReason {
+    const map: Record<string, DisputeReason> = {
+      MERCHANDISE_OR_SERVICE_NOT_RECEIVED: DisputeReason.PRODUCT_NOT_RECEIVED,
+      MERCHANDISE_OR_SERVICE_NOT_AS_DESCRIBED: DisputeReason.PRODUCT_UNACCEPTABLE,
+      UNAUTHORISED: DisputeReason.UNAUTHORIZED_TRANSACTION,
+      CREDIT_NOT_PROCESSED: DisputeReason.CREDIT_NOT_PROCESSED,
+      DUPLICATE_TRANSACTION: DisputeReason.DUPLICATE_TRANSACTION,
+      CANCELED_RECURRING_BILLING: DisputeReason.SUBSCRIPTION_CANCELLED,
+    };
+    return map[reason] ?? DisputeReason.GENERAL;
+  }
+
+  private _mapStatus(status: string): DisputeStatus {
+    const map: Record<string, DisputeStatus> = {
+      OPEN: DisputeStatus.NEEDS_RESPONSE,
+      UNDER_REVIEW: DisputeStatus.UNDER_REVIEW,
+      RESOLVED: DisputeStatus.CHARGE_REFUNDED,
+      WAITING_FOR_BUYER_RESPONSE: DisputeStatus.UNDER_REVIEW,
+      WAITING_FOR_SELLER_RESPONSE: DisputeStatus.NEEDS_RESPONSE,
+    };
+    return map[status] ?? DisputeStatus.NEEDS_RESPONSE;
+  }
+
+  private _mapEvidenceType(type: string): string {
+    const map: Record<string, string> = {
+      delivery_proof:     'PROOF_OF_FULFILLMENT',
+      device_fingerprint: 'PROOF_OF_FULFILLMENT',
+      customer_history:   'PROOF_OF_REFUND',
+      payment_log:        'PROOF_OF_FULFILLMENT',
+      email_confirmation: 'PROOF_OF_FULFILLMENT',
+    };
+    return map[type] ?? 'PROOF_OF_FULFILLMENT';
+  }
+}