chargeback-guard 2.0.0

package/src/security/rateLimit.ts

@@ -0,0 +1,77 @@
+// ============================================================
+//  CHARGEBACK GUARD — Rate Limiting
+// ============================================================
+
+import rateLimit from 'express-rate-limit';
+import { Request, Response } from 'express';
+import { securityConfig } from '../config';
+
+// ────────────────────────────────────────────────────────────
+//  STANDARD API RATE LIMITER
+// ────────────────────────────────────────────────────────────
+
+export const apiRateLimit = rateLimit({
+  windowMs: securityConfig.rateLimit.windowMs,
+  max: securityConfig.rateLimit.maxRequests,
+  standardHeaders: true,
+  legacyHeaders: false,
+  skipFailedRequests: securityConfig.rateLimit.skipFailedRequests,
+  message: {
+    success: false,
+    error: {
+      code: 'RATE_LIMIT_EXCEEDED',
+      message: `Too many requests. Limit: ${securityConfig.rateLimit.maxRequests} per ${securityConfig.rateLimit.windowMs / 60000} minutes`,
+    },
+  },
+});
+
+// ────────────────────────────────────────────────────────────
+//  STRICT LIMITER (for auth endpoints)
+// ────────────────────────────────────────────────────────────
+
+export const authRateLimit = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: {
+    success: false,
+    error: {
+      code: 'AUTH_RATE_LIMIT_EXCEEDED',
+      message: 'Too many authentication attempts. Try again in 15 minutes.',
+    },
+  },
+  skipSuccessfulRequests: true,
+});
+
+// ────────────────────────────────────────────────────────────
+//  WEBHOOK LIMITER
+// ────────────────────────────────────────────────────────────
+
+export const webhookRateLimit = rateLimit({
+  windowMs: 60 * 1000, // 1 minute
+  max: 500, // webhooks can be high-volume
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: {
+    success: false,
+    error: { code: 'WEBHOOK_RATE_LIMIT_EXCEEDED', message: 'Webhook rate limit exceeded' },
+  },
+});
+
+// ────────────────────────────────────────────────────────────
+//  EVIDENCE SUBMISSION LIMITER
+// ────────────────────────────────────────────────────────────
+
+export const evidenceRateLimit = rateLimit({
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 200,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req: Request) =>
+    (req as Request & { merchantId?: string }).merchantId ?? req.ip ?? 'unknown',
+  message: {
+    success: false,
+    error: { code: 'EVIDENCE_RATE_LIMIT_EXCEEDED', message: 'Evidence submission rate limit exceeded' },
+  },
+});

package/src/security/validation.ts

@@ -0,0 +1,166 @@
+// ============================================================
+//  CHARGEBACK GUARD — Request Validation Schemas (Zod)
+// ============================================================
+
+import { z } from 'zod';
+import { Request, Response, NextFunction } from 'express';
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('Validation');
+
+// ────────────────────────────────────────────────────────────
+//  SCHEMAS
+// ────────────────────────────────────────────────────────────
+
+export const RegisterPaymentSchema = z.object({
+  orderId:       z.string().min(1).max(255),
+  amount:        z.number().positive(),
+  currency:      z.string().length(3).toUpperCase(),
+  customerEmail: z.string().email(),
+  customerName:  z.string().max(255).optional(),
+  customerIp:    z.string().ip().optional(),
+  userAgent:     z.string().max(512).optional(),
+  transactionId: z.string().max(255).optional(),
+  paymentMethod: z.string().max(50).optional(),
+  cardLastFour:  z.string().max(4).optional(),
+  cardBrand:     z.string().max(50).optional(),
+  provider:      z.enum(['stripe', 'paypal', 'square', 'braintree']).optional(),
+  shippingAddress: z.object({
+    line1:      z.string().max(255),
+    line2:      z.string().max(255).optional(),
+    city:       z.string().max(100),
+    state:      z.string().max(100).optional(),
+    postalCode: z.string().max(20),
+    country:    z.string().length(2).toUpperCase(),
+  }).optional(),
+  sessionData: z.object({
+    sessionId:    z.string().optional(),
+    duration:     z.number().min(0).optional(),
+    pageViews:    z.array(z.any()).optional(),
+    clickTracking: z.array(z.any()).optional(),
+    timeOnCheckout: z.number().min(0).optional(),
+    referrer:     z.string().url().optional(),
+  }).optional(),
+  deviceFingerprint: z.object({
+    screenResolution: z.string().optional(),
+    timezone:         z.string().optional(),
+    language:         z.string().optional(),
+    platform:         z.string().optional(),
+  }).optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+export const DisputeHandleSchema = z.object({
+  id:       z.string().min(1),
+  orderId:  z.string().optional(),
+  amount:   z.number().min(0),
+  currency: z.string().optional(),
+  reason:   z.string().min(1),
+  status:   z.string().min(1),
+  provider: z.enum(['stripe', 'paypal', 'square', 'braintree']),
+  evidenceDueBy: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+export const PaginationSchema = z.object({
+  page:      z.coerce.number().int().positive().default(1),
+  limit:     z.coerce.number().int().min(1).max(100).default(20),
+  sortBy:    z.string().optional(),
+  sortOrder: z.enum(['asc', 'desc']).default('desc'),
+  from:      z.string().optional(),
+  to:        z.string().optional(),
+  status:    z.string().optional(),
+  reason:    z.string().optional(),
+  provider:  z.string().optional(),
+  search:    z.string().max(255).optional(),
+});
+
+export const MerchantRegisterSchema = z.object({
+  name:        z.string().min(2).max(255),
+  email:       z.string().email(),
+  password:    z.string().min(8).max(128),
+  webhookUrl:  z.string().url().optional(),
+  plan:        z.enum(['free', 'starter', 'pro', 'enterprise']).default('free'),
+});
+
+export const MerchantLoginSchema = z.object({
+  email:    z.string().email(),
+  password: z.string().min(1),
+});
+
+export const UpdateShippingSchema = z.object({
+  orderId:        z.string().min(1),
+  trackingNumber: z.string().min(1),
+  carrier:        z.string().optional(),
+  shippedAt:      z.string().optional(),
+  estimatedDelivery: z.string().optional(),
+});
+
+// ────────────────────────────────────────────────────────────
+//  VALIDATION MIDDLEWARE FACTORY
+// ────────────────────────────────────────────────────────────
+
+type SchemaSource = 'body' | 'query' | 'params';
+
+export function validate<T extends z.ZodTypeAny>(
+  schema: T,
+  source: SchemaSource = 'body'
+): (req: Request, res: Response, next: NextFunction) => void {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const result = schema.safeParse(req[source]);
+
+    if (!result.success) {
+      const errors = result.error.errors.map(e => ({
+        field: e.path.join('.'),
+        message: e.message,
+        code: e.code,
+      }));
+
+      log.debug('Validation failed', { source, errors });
+
+      res.status(422).json({
+        success: false,
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Request validation failed',
+          details: { errors },
+        },
+      });
+      return;
+    }
+
+    // Attach parsed & coerced data
+    if (source === 'body') { req.body = result.data; }
+    else if (source === 'query') { req.query = result.data as typeof req.query; }
+
+    next();
+  };
+}
+
+// ────────────────────────────────────────────────────────────
+//  SANITIZE MIDDLEWARE (removes XSS risk from strings)
+// ────────────────────────────────────────────────────────────
+
+export function sanitizeBody(req: Request, _res: Response, next: NextFunction): void {
+  if (req.body && typeof req.body === 'object') {
+    req.body = sanitizeObject(req.body as Record<string, unknown>);
+  }
+  next();
+}
+
+function sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'string') {
+      result[key] = value
+        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+        .replace(/on\w+="[^"]*"/gi, '')
+        .trim();
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      result[key] = sanitizeObject(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/src/server.ts

@@ -0,0 +1,122 @@
+// ============================================================
+//  CHARGEBACK GUARD — HTTP Server Entry Point
+// ============================================================
+
+import dotenv from 'dotenv';
+dotenv.config();
+
+import http from 'http';
+import { createChargebackGuard } from './index';
+import { WebhookHandler } from './integrations/webhook';
+import { createApp } from './api/routes';
+import { createLogger } from './utils/logger';
+import { appConfig } from './config';
+import { DisputeStatus, NotificationEvent } from './types';
+
+const log = createLogger('Server');
+
+async function bootstrap(): Promise<void> {
+  // ── 1. Initialize ChargebackGuard ────────────────────────
+  log.info('Bootstrapping ChargebackGuard...');
+
+  const guard = await createChargebackGuard({
+    autoReply: true,
+    evidenceCollection: true,
+  });
+
+  // ── 2. Setup Webhook Handler ─────────────────────────────
+  const webhookHandler = new WebhookHandler();
+
+  webhookHandler.onDisputeDetected(async (dispute) => {
+    log.info(`Processing dispute: ${dispute.id}`);
+    try {
+      await guard.handleDispute(dispute);
+    } catch (err) {
+      log.error('Dispute handling error', {
+        error: err instanceof Error ? err.message : String(err),
+        disputeId: dispute.id,
+      });
+    }
+  });
+
+  webhookHandler.onDisputeResolved(async (disputeId, status, provider) => {
+    const event = status === DisputeStatus.WON
+      ? NotificationEvent.DISPUTE_WON
+      : NotificationEvent.DISPUTE_LOST;
+
+    guard.events.emitEvent(event, { disputeId, status, provider });
+  });
+
+  // ── 3. Create Express app ────────────────────────────────
+  const app = createApp(webhookHandler);
+  app.locals['chargebackGuard'] = guard;
+
+  // ── 4. Start HTTP server ─────────────────────────────────
+  const server = http.createServer(app);
+
+  server.listen(appConfig.port, () => {
+    log.info(`🛡️  ChargebackGuard API running`, {
+      url: `http://localhost:${appConfig.port}`,
+      environment: appConfig.env,
+      version: appConfig.version,
+    });
+
+    console.log(`
+╔══════════════════════════════════════════════════╗
+║     🛡️  CHARGEBACK GUARD v${appConfig.version}              ║
+╠══════════════════════════════════════════════════╣
+║  Server: http://localhost:${appConfig.port}               ║
+║  Env:    ${appConfig.env.padEnd(38)}  ║
+╠══════════════════════════════════════════════════╣
+║  API ENDPOINTS                                   ║
+║  POST /api/v1/auth/register  — Register merchant ║
+║  POST /api/v1/auth/login     — Login             ║
+║  POST /api/v1/payments       — Register payment  ║
+║  GET  /api/v1/disputes       — List disputes     ║
+║  POST /api/v1/webhooks/stripe — Stripe webhook   ║
+║  POST /api/v1/webhooks/paypal — PayPal webhook   ║
+║  GET  /api/v1/analytics/stats — Stats            ║
+║  GET  /api/v1/health          — Health check     ║
+╚══════════════════════════════════════════════════╝
+`);
+  });
+
+  // ── 5. Graceful shutdown ─────────────────────────────────
+  const shutdown = async (signal: string): Promise<void> => {
+    log.info(`Received ${signal} — shutting down gracefully`);
+
+    server.close(async () => {
+      try {
+        await guard.shutdown();
+        log.info('Shutdown complete');
+        process.exit(0);
+      } catch (err) {
+        log.error('Shutdown error', { error: err instanceof Error ? err.message : String(err) });
+        process.exit(1);
+      }
+    });
+
+    // Force shutdown after 30s
+    setTimeout(() => {
+      log.error('Forced shutdown after timeout');
+      process.exit(1);
+    }, 30000);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT',  () => shutdown('SIGINT'));
+
+  process.on('uncaughtException', (err) => {
+    log.error('Uncaught exception', { error: err.message, stack: err.stack });
+    shutdown('uncaughtException').catch(console.error);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    log.error('Unhandled promise rejection', { reason: String(reason) });
+  });
+}
+
+bootstrap().catch(err => {
+  console.error('Bootstrap failed:', err);
+  process.exit(1);
+});