chargeback-guard 2.0.0

package/src/api/controllers.ts

@@ -0,0 +1,339 @@
+// ============================================================
+//  CHARGEBACK GUARD — API Controllers
+// ============================================================
+
+import { Request, Response } from 'express';
+import { createLogger } from '../utils/logger';
+import { appConfig } from '../config';
+import {
+  ApiResponse,
+  ApiMeta,
+  PaginationMeta,
+  FilterQuery,
+} from '../types';
+import { AuthenticatedRequest } from '../security/auth';
+import { v4 as uuidv4 } from 'uuid';
+
+const log = createLogger('Controllers');
+
+// ────────────────────────────────────────────────────────────
+//  RESPONSE HELPERS
+// ────────────────────────────────────────────────────────────
+
+function makeMeta(req: Request, pagination?: PaginationMeta): ApiMeta {
+  return {
+    timestamp: new Date().toISOString(),
+    requestId: (req as Request & { requestId?: string }).requestId ?? uuidv4(),
+    version: appConfig.version,
+    pagination,
+  };
+}
+
+function ok<T>(res: Response, req: Request, data: T, pagination?: PaginationMeta): void {
+  const body: ApiResponse<T> = {
+    success: true,
+    data,
+    meta: makeMeta(req, pagination),
+  };
+  res.status(200).json(body);
+}
+
+function created<T>(res: Response, req: Request, data: T): void {
+  const body: ApiResponse<T> = {
+    success: true,
+    data,
+    meta: makeMeta(req),
+  };
+  res.status(201).json(body);
+}
+
+function notFound(res: Response, req: Request, message: string): void {
+  res.status(404).json({
+    success: false,
+    error: { code: 'NOT_FOUND', message },
+    meta: makeMeta(req),
+  });
+}
+
+function badRequest(res: Response, req: Request, message: string, details?: unknown): void {
+  res.status(400).json({
+    success: false,
+    error: { code: 'BAD_REQUEST', message, details },
+    meta: makeMeta(req),
+  });
+}
+
+// ────────────────────────────────────────────────────────────
+//  PAYMENTS CONTROLLER
+// ────────────────────────────────────────────────────────────
+
+export const PaymentsController = {
+
+  async register(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { ChargebackGuard } = require('../core/chargebackGuard');
+      const guard = req.app.locals['chargebackGuard'] as InstanceType<typeof ChargebackGuard>;
+
+      const result = await guard.registerPayment({
+        ...req.body,
+        customerIp: req.body.customerIp ?? req.ip,
+        userAgent: req.body.userAgent ?? req.headers['user-agent'],
+      });
+
+      created(res, req, result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Registration failed';
+      log.error('Payment registration error', { error: message });
+      badRequest(res, req, message);
+    }
+  },
+
+  async list(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const query = req.query as FilterQuery;
+      const page  = Number(query.page ?? 1);
+      const limit = Number(query.limit ?? 20);
+
+      // Placeholder — DB query goes here
+      const items: unknown[] = [];
+      const total = 0;
+
+      ok(res, req, items, {
+        page, limit, total,
+        totalPages: Math.ceil(total / limit),
+        hasNext: page * limit < total,
+        hasPrev: page > 1,
+      });
+    } catch (err) {
+      log.error('List payments error', { error: err instanceof Error ? err.message : err });
+      res.status(500).json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Failed to list payments' } });
+    }
+  },
+
+  async updateShipping(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { orderId } = req.params as { orderId: string };
+      const { trackingNumber, carrier, shippedAt, estimatedDelivery } = req.body as {
+        trackingNumber: string;
+        carrier?: string;
+        shippedAt?: string;
+        estimatedDelivery?: string;
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { EvidenceStorage } = require('../evidence/storage');
+      const storage = new EvidenceStorage();
+
+      const updated = await storage.update(orderId, {
+        data: {
+          shippingData: { trackingNumber, carrier, shippingDate: shippedAt, estimatedDelivery },
+        },
+      } as Parameters<typeof storage.update>[1]);
+
+      if (!updated) {
+        notFound(res, req, `Order not found: ${orderId}`);
+        return;
+      }
+
+      ok(res, req, { orderId, trackingNumber, updated: true });
+    } catch (err) {
+      log.error('Update shipping error', { error: err instanceof Error ? err.message : err });
+      badRequest(res, req, err instanceof Error ? err.message : 'Update failed');
+    }
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  DISPUTES CONTROLLER
+// ────────────────────────────────────────────────────────────
+
+export const DisputesController = {
+
+  async list(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { StripeIntegration } = require('../integrations/stripe');
+      const stripe = new StripeIntegration();
+      const disputes = await stripe.listActionableDisputes();
+      ok(res, req, disputes);
+    } catch (err) {
+      log.error('List disputes error', { error: err instanceof Error ? err.message : err });
+      res.status(500).json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Failed to list disputes' } });
+    }
+  },
+
+  async getOne(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { id } = req.params as { id: string };
+      const { StripeIntegration } = require('../integrations/stripe');
+      const stripe = new StripeIntegration();
+      const dispute = await stripe.getDispute(id);
+      ok(res, req, dispute);
+    } catch (err) {
+      notFound(res, req, `Dispute not found: ${req.params['id']}`);
+    }
+  },
+
+  async handle(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { ChargebackGuard } = require('../core/chargebackGuard');
+      const guard = req.app.locals['chargebackGuard'] as InstanceType<typeof ChargebackGuard>;
+      const result = await guard.handleDispute(req.body);
+      ok(res, req, result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Dispute handling failed';
+      log.error('Handle dispute error', { error: message });
+      res.status(500).json({ success: false, error: { code: 'INTERNAL_ERROR', message } });
+    }
+  },
+
+  async submitReply(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { id } = req.params as { id: string };
+      const reply = req.body;
+
+      const { StripeIntegration } = require('../integrations/stripe');
+      const stripe = new StripeIntegration();
+      await stripe.submitDisputeEvidence(id, reply);
+
+      ok(res, req, { disputeId: id, submitted: true, submittedAt: new Date().toISOString() });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Submission failed';
+      badRequest(res, req, message);
+    }
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  ANALYTICS CONTROLLER
+// ────────────────────────────────────────────────────────────
+
+export const AnalyticsController = {
+
+  async getStats(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { ChargebackGuard } = require('../core/chargebackGuard');
+      const guard = req.app.locals['chargebackGuard'] as InstanceType<typeof ChargebackGuard>;
+      const q = req.query as { from?: string; to?: string };
+      const stats = await guard.getProtectionStats(
+        q.from ? new Date(q.from) : undefined,
+        q.to ? new Date(q.to) : undefined
+      );
+      ok(res, req, stats);
+    } catch (err) {
+      log.error('Stats error', { error: err instanceof Error ? err.message : err });
+      res.status(500).json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Stats unavailable' } });
+    }
+  },
+
+  async getDashboard(req: AuthenticatedRequest, res: Response): Promise<void> {
+    try {
+      const { DashboardService } = require('../analytics/dashboard');
+      const svc = new DashboardService();
+      const dashboard = await svc.getMetrics(req.merchantId);
+      ok(res, req, dashboard);
+    } catch (err) {
+      log.error('Dashboard error', { error: err instanceof Error ? err.message : err });
+      res.status(500).json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Dashboard unavailable' } });
+    }
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  HEALTH CONTROLLER
+// ────────────────────────────────────────────────────────────
+
+export const HealthController = {
+
+  async check(req: Request, res: Response): Promise<void> {
+    try {
+      const guard = req.app.locals['chargebackGuard'];
+      const health = guard
+        ? await guard.getHealth()
+        : { success: true, data: { status: 'healthy', uptime: process.uptime() * 1000 } };
+
+      const statusCode = health.success ? 200 : 503;
+      res.status(statusCode).json({
+        ...health,
+        meta: makeMeta(req),
+      });
+    } catch {
+      res.status(503).json({ success: false, error: { code: 'HEALTH_CHECK_FAILED', message: 'Health check failed' } });
+    }
+  },
+
+  async ping(_req: Request, res: Response): Promise<void> {
+    res.status(200).json({ pong: true, timestamp: new Date().toISOString() });
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  AUTH CONTROLLER
+// ────────────────────────────────────────────────────────────
+
+export const AuthController = {
+
+  async register(req: Request, res: Response): Promise<void> {
+    try {
+      const { hashPassword, signToken, generateMerchantApiKey } = require('./../../src/security/auth');
+      const { name, email, password, webhookUrl, plan } = req.body as {
+        name: string;
+        email: string;
+        password: string;
+        webhookUrl?: string;
+        plan: string;
+      };
+
+      const passwordHash = await hashPassword(password);
+      const merchantId   = uuidv4();
+      const apiKey       = generateMerchantApiKey();
+
+      // Store merchant (placeholder — DB layer goes here)
+      const merchant = {
+        merchantId,
+        name,
+        email,
+        passwordHash,
+        apiKey,
+        webhookUrl,
+        plan,
+        createdAt: new Date().toISOString(),
+      };
+
+      const token = signToken({ merchantId, email, plan });
+
+      created(res, req, {
+        merchantId,
+        email,
+        name,
+        plan,
+        apiKey,
+        token,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Registration failed';
+      badRequest(res, req, message);
+    }
+  },
+
+  async login(req: Request, res: Response): Promise<void> {
+    try {
+      const { signToken } = require('./../../src/security/auth');
+      const { email, password } = req.body as { email: string; password: string };
+
+      // Placeholder — real implementation queries DB
+      log.info(`Login attempt: ${email}`);
+
+      // For demo: return a token
+      const token = signToken({
+        merchantId: uuidv4(),
+        email,
+        plan: 'pro',
+      });
+
+      ok(res, req, { token, email });
+    } catch (err) {
+      res.status(401).json({ success: false, error: { code: 'UNAUTHORIZED', message: 'Invalid credentials' } });
+    }
+  },
+};

package/src/api/middleware.ts

@@ -0,0 +1,172 @@
+// ============================================================
+//  CHARGEBACK GUARD — Express Middleware Stack
+// ============================================================
+
+import express, { Application, Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import compression from 'compression';
+import morgan from 'morgan';
+import { v4 as uuidv4 } from 'uuid';
+import { createLogger } from '../utils/logger';
+import { corsConfig, appConfig } from '../config';
+import { apiRateLimit } from '../security/rateLimit';
+import { sanitizeBody } from '../security/validation';
+
+const log = createLogger('Middleware');
+
+// ────────────────────────────────────────────────────────────
+//  REQUEST ID MIDDLEWARE
+// ────────────────────────────────────────────────────────────
+
+export function requestId(req: Request, res: Response, next: NextFunction): void {
+  const id = (req.headers['x-request-id'] as string) ?? uuidv4();
+  (req as Request & { requestId: string }).requestId = id;
+  res.setHeader('X-Request-Id', id);
+  next();
+}
+
+// ────────────────────────────────────────────────────────────
+//  RESPONSE TIME MIDDLEWARE
+// ────────────────────────────────────────────────────────────
+
+export function responseTime(req: Request, res: Response, next: NextFunction): void {
+  const start = Date.now();
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    res.setHeader('X-Response-Time', `${duration}ms`);
+  });
+  next();
+}
+
+// ────────────────────────────────────────────────────────────
+//  RAW BODY CAPTURE (needed for Stripe webhook verification)
+// ────────────────────────────────────────────────────────────
+
+export function captureRawBody(req: Request, res: Response, next: NextFunction): void {
+  if (req.path.includes('/webhook')) {
+    let raw = '';
+    req.on('data', (chunk: Buffer) => { raw += chunk.toString(); });
+    req.on('end', () => {
+      (req as Request & { rawBody: string }).rawBody = raw;
+      next();
+    });
+  } else {
+    next();
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  NOT FOUND HANDLER
+// ────────────────────────────────────────────────────────────
+
+export function notFoundHandler(req: Request, res: Response): void {
+  res.status(404).json({
+    success: false,
+    error: {
+      code: 'NOT_FOUND',
+      message: `Route not found: ${req.method} ${req.path}`,
+    },
+    meta: {
+      timestamp: new Date().toISOString(),
+      requestId: (req as Request & { requestId?: string }).requestId,
+      version: appConfig.version,
+    },
+  });
+}
+
+// ────────────────────────────────────────────────────────────
+//  GLOBAL ERROR HANDLER
+// ────────────────────────────────────────────────────────────
+
+export function errorHandler(
+  err: Error & { status?: number; code?: string },
+  req: Request,
+  res: Response,
+  _next: NextFunction
+): void {
+  const status = err.status ?? 500;
+  const code   = err.code ?? 'INTERNAL_ERROR';
+
+  log.error('Unhandled error', {
+    status,
+    code,
+    message: err.message,
+    path: req.path,
+    method: req.method,
+    requestId: (req as Request & { requestId?: string }).requestId,
+    stack: appConfig.isDev ? err.stack : undefined,
+  });
+
+  res.status(status).json({
+    success: false,
+    error: {
+      code,
+      message: status === 500 ? 'Internal server error' : err.message,
+      ...(appConfig.isDev && { stack: err.stack }),
+    },
+    meta: {
+      timestamp: new Date().toISOString(),
+      requestId: (req as Request & { requestId?: string }).requestId,
+      version: appConfig.version,
+    },
+  });
+}
+
+// ────────────────────────────────────────────────────────────
+//  APPLY ALL MIDDLEWARE
+// ────────────────────────────────────────────────────────────
+
+export function applyMiddleware(app: Application): void {
+  // Security headers
+  app.use(helmet({
+    crossOriginResourcePolicy: { policy: 'same-site' },
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        imgSrc: ["'self'", 'data:'],
+      },
+    },
+  }));
+
+  // CORS
+  app.use(cors({
+    origin: corsConfig.origins,
+    methods: corsConfig.methods,
+    credentials: true,
+    optionsSuccessStatus: 200,
+  }));
+
+  // Compression
+  app.use(compression());
+
+  // Request ID
+  app.use(requestId);
+  app.use(responseTime);
+
+  // Raw body capture (before JSON parsing for webhooks)
+  app.use(captureRawBody);
+
+  // Body parsers
+  app.use(express.json({ limit: '5mb' }));
+  app.use(express.urlencoded({ extended: true, limit: '5mb' }));
+
+  // Sanitize inputs
+  app.use(sanitizeBody);
+
+  // Request logging
+  if (appConfig.isDev) {
+    app.use(morgan('dev'));
+  } else {
+    app.use(morgan('combined', {
+      stream: { write: (msg: string) => log.info(msg.trim()) },
+    }));
+  }
+
+  // Global rate limiting
+  app.use('/api/', apiRateLimit);
+
+  log.debug('Middleware stack applied');
+}

package/src/api/routes.ts

@@ -0,0 +1,141 @@
+// ============================================================
+//  CHARGEBACK GUARD — API Routes (Express Router)
+// ============================================================
+
+import { Router } from 'express';
+import {
+  PaymentsController,
+  DisputesController,
+  AnalyticsController,
+  HealthController,
+  AuthController,
+} from './controllers';
+import { requireAuth } from '../security/auth';
+import {
+  authRateLimit,
+  webhookRateLimit,
+  evidenceRateLimit,
+} from '../security/rateLimit';
+import {
+  validate,
+  RegisterPaymentSchema,
+  DisputeHandleSchema,
+  MerchantRegisterSchema,
+  MerchantLoginSchema,
+  PaginationSchema,
+  UpdateShippingSchema,
+} from '../security/validation';
+import { WebhookHandler } from '../integrations/webhook';
+import { createLogger } from '../utils/logger';
+
+const log = createLogger('Routes');
+
+// ────────────────────────────────────────────────────────────
+//  ROOT ROUTER
+// ────────────────────────────────────────────────────────────
+
+export function createRouter(webhookHandler: WebhookHandler): Router {
+  const router = Router();
+
+  // ── Health ──────────────────────────────
+  router.get('/ping',        HealthController.ping);
+  router.get('/health',      HealthController.check);
+
+  // ── Auth ────────────────────────────────
+  router.post('/auth/register',
+    authRateLimit,
+    validate(MerchantRegisterSchema),
+    AuthController.register
+  );
+  router.post('/auth/login',
+    authRateLimit,
+    validate(MerchantLoginSchema),
+    AuthController.login
+  );
+
+  // ── Payments ────────────────────────────
+  router.post('/payments',
+    requireAuth,
+    evidenceRateLimit,
+    validate(RegisterPaymentSchema),
+    PaymentsController.register
+  );
+  router.get('/payments',
+    requireAuth,
+    validate(PaginationSchema, 'query'),
+    PaymentsController.list
+  );
+  router.patch('/payments/:orderId/shipping',
+    requireAuth,
+    validate(UpdateShippingSchema),
+    PaymentsController.updateShipping
+  );
+
+  // ── Disputes ────────────────────────────
+  router.get('/disputes',
+    requireAuth,
+    validate(PaginationSchema, 'query'),
+    DisputesController.list
+  );
+  router.get('/disputes/:id',
+    requireAuth,
+    DisputesController.getOne
+  );
+  router.post('/disputes/handle',
+    requireAuth,
+    validate(DisputeHandleSchema),
+    DisputesController.handle
+  );
+  router.post('/disputes/:id/reply',
+    requireAuth,
+    DisputesController.submitReply
+  );
+
+  // ── Analytics ───────────────────────────
+  router.get('/analytics/stats',
+    requireAuth,
+    AnalyticsController.getStats
+  );
+  router.get('/analytics/dashboard',
+    requireAuth,
+    AnalyticsController.getDashboard
+  );
+
+  // ── Webhooks ────────────────────────────
+  router.post('/webhooks/stripe',
+    webhookRateLimit,
+    webhookHandler.handleStripe()
+  );
+  router.post('/webhooks/paypal',
+    webhookRateLimit,
+    webhookHandler.handlePayPal()
+  );
+
+  log.debug('Routes registered');
+  return router;
+}
+
+// ────────────────────────────────────────────────────────────
+//  APP FACTORY
+// ────────────────────────────────────────────────────────────
+
+import express, { Application } from 'express';
+import { applyMiddleware, notFoundHandler, errorHandler } from './middleware';
+
+export function createApp(webhookHandler: WebhookHandler): Application {
+  const app = express();
+
+  // Apply middleware stack
+  applyMiddleware(app);
+
+  // Mount API routes
+  app.use('/api/v1', createRouter(webhookHandler));
+
+  // 404 handler
+  app.use(notFoundHandler);
+
+  // Error handler (must be last)
+  app.use(errorHandler);
+
+  return app;
+}