chargeback-guard 2.0.0

package/src/notifications/email.ts

@@ -0,0 +1,161 @@
+// ============================================================
+//  CHARGEBACK GUARD — Email Notifications (Nodemailer)
+// ============================================================
+
+import nodemailer from 'nodemailer';
+import { createLogger } from '../utils/logger';
+import { emailConfig } from '../config';
+
+const log = createLogger('Email');
+
+// ────────────────────────────────────────────────────────────
+//  EMAIL SERVICE
+// ────────────────────────────────────────────────────────────
+
+export class EmailService {
+  private transporter: nodemailer.Transporter;
+
+  constructor() {
+    this.transporter = nodemailer.createTransport({
+      host: emailConfig.host,
+      port: emailConfig.port,
+      secure: emailConfig.secure,
+      auth: {
+        user: emailConfig.user,
+        pass: emailConfig.pass,
+      },
+    });
+  }
+
+  // ──────────────────────────────────────────
+  //  DISPUTE DETECTED
+  // ──────────────────────────────────────────
+
+  async sendDisputeAlert(opts: {
+    to: string;
+    disputeId: string;
+    orderId?: string;
+    amount: number;
+    reason: string;
+    dueBy?: string;
+  }): Promise<void> {
+    const subject = `⚠️ New Chargeback Dispute: ${opts.disputeId}`;
+    const html = `
+      <div style="font-family:Arial,sans-serif;max-width:600px;margin:0 auto;">
+        <div style="background:#c0392b;padding:20px;border-radius:8px 8px 0 0;">
+          <h2 style="color:white;margin:0;">⚠️ New Chargeback Dispute</h2>
+        </div>
+        <div style="background:#f9f9f9;padding:24px;border-radius:0 0 8px 8px;border:1px solid #ddd;">
+          <p>A new chargeback dispute has been filed. ChargebackGuard is processing it automatically.</p>
+          <table style="width:100%;border-collapse:collapse;margin:16px 0;">
+            <tr><td style="padding:8px;font-weight:bold;background:#eee;">Dispute ID</td><td style="padding:8px;">${opts.disputeId}</td></tr>
+            <tr><td style="padding:8px;font-weight:bold;background:#eee;">Order ID</td><td style="padding:8px;">${opts.orderId ?? 'N/A'}</td></tr>
+            <tr><td style="padding:8px;font-weight:bold;background:#eee;">Amount</td><td style="padding:8px;">$${(opts.amount / 100).toFixed(2)}</td></tr>
+            <tr><td style="padding:8px;font-weight:bold;background:#eee;">Reason</td><td style="padding:8px;">${opts.reason}</td></tr>
+            ${opts.dueBy ? `<tr><td style="padding:8px;font-weight:bold;background:#eee;">Evidence Due</td><td style="padding:8px;color:#c0392b;">${new Date(opts.dueBy).toLocaleDateString()}</td></tr>` : ''}
+          </table>
+          <p style="color:#666;font-size:12px;">ChargebackGuard is building your defense automatically. You will receive an update when the reply is submitted.</p>
+        </div>
+      </div>
+    `;
+
+    await this._send({ to: opts.to, subject, html });
+  }
+
+  // ──────────────────────────────────────────
+  //  DISPUTE WON
+  // ──────────────────────────────────────────
+
+  async sendDisputeWon(opts: {
+    to: string;
+    disputeId: string;
+    amount: number;
+  }): Promise<void> {
+    const subject = `🏆 Chargeback WON: $${(opts.amount / 100).toFixed(2)} Recovered`;
+    const html = `
+      <div style="font-family:Arial,sans-serif;max-width:600px;margin:0 auto;">
+        <div style="background:#27ae60;padding:20px;border-radius:8px 8px 0 0;">
+          <h2 style="color:white;margin:0;">🏆 Chargeback Won!</h2>
+        </div>
+        <div style="background:#f9f9f9;padding:24px;border-radius:0 0 8px 8px;border:1px solid #ddd;">
+          <p style="font-size:18px;">ChargebackGuard successfully defended dispute <strong>${opts.disputeId}</strong>.</p>
+          <p style="font-size:24px;color:#27ae60;text-align:center;font-weight:bold;">$${(opts.amount / 100).toFixed(2)} Recovered</p>
+        </div>
+      </div>
+    `;
+    await this._send({ to: opts.to, subject, html });
+  }
+
+  // ──────────────────────────────────────────
+  //  WEEKLY REPORT
+  // ──────────────────────────────────────────
+
+  async sendWeeklyReport(opts: {
+    to: string;
+    totalOrders: number;
+    disputes: number;
+    won: number;
+    recovered: number;
+  }): Promise<void> {
+    const winRate = opts.disputes > 0 ? ((opts.won / opts.disputes) * 100).toFixed(1) : '0';
+    const subject = `📊 ChargebackGuard Weekly Report`;
+    const html = `
+      <div style="font-family:Arial,sans-serif;max-width:600px;margin:0 auto;">
+        <div style="background:#2c3e50;padding:20px;border-radius:8px 8px 0 0;">
+          <h2 style="color:white;margin:0;">📊 Weekly Report</h2>
+        </div>
+        <div style="background:#f9f9f9;padding:24px;border-radius:0 0 8px 8px;border:1px solid #ddd;">
+          <div style="display:flex;gap:16px;justify-content:space-around;text-align:center;margin:16px 0;">
+            <div style="background:white;padding:16px;border-radius:8px;border:1px solid #ddd;flex:1;">
+              <div style="font-size:28px;font-weight:bold;color:#2c3e50;">${opts.totalOrders}</div>
+              <div style="color:#666;">Orders Protected</div>
+            </div>
+            <div style="background:white;padding:16px;border-radius:8px;border:1px solid #ddd;flex:1;">
+              <div style="font-size:28px;font-weight:bold;color:#e74c3c;">${opts.disputes}</div>
+              <div style="color:#666;">Disputes Filed</div>
+            </div>
+            <div style="background:white;padding:16px;border-radius:8px;border:1px solid #ddd;flex:1;">
+              <div style="font-size:28px;font-weight:bold;color:#27ae60;">${winRate}%</div>
+              <div style="color:#666;">Win Rate</div>
+            </div>
+            <div style="background:white;padding:16px;border-radius:8px;border:1px solid #ddd;flex:1;">
+              <div style="font-size:28px;font-weight:bold;color:#27ae60;">$${(opts.recovered / 100).toFixed(0)}</div>
+              <div style="color:#666;">Recovered</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    `;
+    await this._send({ to: opts.to, subject, html });
+  }
+
+  // ──────────────────────────────────────────
+  //  GENERIC SEND
+  // ──────────────────────────────────────────
+
+  private async _send(opts: { to: string; subject: string; html: string }): Promise<void> {
+    try {
+      await this.transporter.sendMail({
+        from: `"${emailConfig.fromName}" <${emailConfig.fromAddress}>`,
+        to: opts.to,
+        subject: opts.subject,
+        html: opts.html,
+      });
+      log.info(`Email sent to ${opts.to}: ${opts.subject}`);
+    } catch (err) {
+      log.error(`Email failed to ${opts.to}`, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
+    }
+  }
+
+  async verifyConnection(): Promise<boolean> {
+    try {
+      await this.transporter.verify();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/notifications/inApp.ts

@@ -0,0 +1,319 @@
+// ============================================================
+//  CHARGEBACK GUARD — Notification Service (Unified)
+//  Dispatches email, SMS, webhook, and in-app notifications
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import {
+  NotificationPayload,
+  NotificationResult,
+  NotificationChannel,
+  NotificationEvent,
+} from '../types';
+import axios from 'axios';
+import { webhookConfig } from '../config';
+import { signPayload } from '../evidence/encryption';
+
+const log = createLogger('NotificationService');
+
+// ────────────────────────────────────────────────────────────
+//  IN-APP NOTIFICATION STORE
+// ────────────────────────────────────────────────────────────
+
+export interface InAppNotification {
+  id: string;
+  merchantId?: string;
+  event: string;
+  title: string;
+  message: string;
+  severity: 'info' | 'warning' | 'success' | 'error';
+  read: boolean;
+  data?: Record<string, unknown>;
+  createdAt: string;
+}
+
+const inAppStore: InAppNotification[] = [];
+
+// ────────────────────────────────────────────────────────────
+//  NOTIFICATION SERVICE
+// ────────────────────────────────────────────────────────────
+
+export class NotificationService {
+  private registeredWebhooks: Array<{ url: string; secret?: string; events?: string[] }> = [];
+
+  registerWebhook(url: string, secret?: string, events?: string[]): void {
+    this.registeredWebhooks.push({ url, secret, events });
+    log.debug(`Webhook registered: ${url}`);
+  }
+
+  // ──────────────────────────────────────────
+  //  DISPATCH (routes to correct channel)
+  // ──────────────────────────────────────────
+
+  async dispatch(payload: NotificationPayload): Promise<NotificationResult[]> {
+    const results: NotificationResult[] = [];
+    const channels = payload.channel ? [payload.channel] : [NotificationChannel.IN_APP];
+
+    for (const channel of channels) {
+      let result: NotificationResult;
+
+      switch (channel) {
+        case NotificationChannel.EMAIL:
+          result = await this._sendEmail(payload);
+          break;
+        case NotificationChannel.SMS:
+          result = await this._sendSMS(payload);
+          break;
+        case NotificationChannel.WEBHOOK:
+          result = await this._sendWebhook(payload);
+          break;
+        case NotificationChannel.IN_APP:
+        default:
+          result = this._storeInApp(payload);
+          break;
+      }
+
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  // ──────────────────────────────────────────
+  //  EMAIL
+  // ──────────────────────────────────────────
+
+  private async _sendEmail(payload: NotificationPayload): Promise<NotificationResult> {
+    try {
+      const { EmailService } = await import('./email');
+      const emailSvc = new EmailService();
+
+      const to = payload.recipient.email;
+      if (!to) {
+        return this._fail(NotificationChannel.EMAIL, 'No email address provided');
+      }
+
+      if (payload.event === NotificationEvent.DISPUTE_DETECTED) {
+        await emailSvc.sendDisputeAlert({
+          to,
+          disputeId: String(payload.data['disputeId'] ?? ''),
+          orderId: payload.data['orderId'] as string,
+          amount: Number(payload.data['amount'] ?? 0),
+          reason: String(payload.data['reason'] ?? 'unknown'),
+          dueBy: payload.data['dueBy'] as string,
+        });
+      } else if (payload.event === NotificationEvent.DISPUTE_WON) {
+        await emailSvc.sendDisputeWon({
+          to,
+          disputeId: String(payload.data['disputeId'] ?? ''),
+          amount: Number(payload.data['amount'] ?? 0),
+        });
+      }
+
+      return { success: true, channel: NotificationChannel.EMAIL, sentAt: new Date().toISOString() };
+    } catch (err) {
+      return this._fail(NotificationChannel.EMAIL, err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  SMS (Twilio)
+  // ──────────────────────────────────────────
+
+  private async _sendSMS(payload: NotificationPayload): Promise<NotificationResult> {
+    try {
+      const { smsConfig } = await import('../config');
+      const phone = payload.recipient.phone;
+      if (!phone) {
+        return this._fail(NotificationChannel.SMS, 'No phone number provided');
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const twilio = require('twilio')(smsConfig.accountSid, smsConfig.authToken);
+      const body   = this._buildSMSMessage(payload);
+
+      await twilio.messages.create({
+        body,
+        from: smsConfig.phoneNumber,
+        to: phone,
+      });
+
+      return { success: true, channel: NotificationChannel.SMS, sentAt: new Date().toISOString() };
+    } catch (err) {
+      return this._fail(NotificationChannel.SMS, err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  // ──────────────────────────────────────────
+  //  WEBHOOK
+  // ──────────────────────────────────────────
+
+  private async _sendWebhook(payload: NotificationPayload): Promise<NotificationResult> {
+    const url = payload.recipient.webhookUrl;
+    if (!url) {
+      return this._fail(NotificationChannel.WEBHOOK, 'No webhook URL configured');
+    }
+
+    const bodyStr = JSON.stringify({
+      event: payload.event,
+      timestamp: new Date().toISOString(),
+      data: payload.data,
+    });
+
+    let retries = webhookConfig.maxRetries;
+
+    while (retries > 0) {
+      try {
+        const headers: Record<string, string> = {
+          'Content-Type': 'application/json',
+          'X-ChargebackGuard-Event': payload.event,
+          'X-ChargebackGuard-Version': '2.0',
+        };
+
+        // Sign payload if secret configured
+        const secret = (payload.data['webhookSecret'] as string) ?? undefined;
+        if (secret) {
+          headers['X-ChargebackGuard-Signature'] = `sha256=${signPayload(bodyStr, secret)}`;
+        }
+
+        await axios.post(url, bodyStr, {
+          headers,
+          timeout: webhookConfig.timeout,
+        });
+
+        return {
+          success: true,
+          channel: NotificationChannel.WEBHOOK,
+          sentAt: new Date().toISOString(),
+        };
+      } catch (err) {
+        retries--;
+        if (retries === 0) {
+          return this._fail(NotificationChannel.WEBHOOK, err instanceof Error ? err.message : String(err));
+        }
+        await new Promise(r => setTimeout(r, webhookConfig.retryDelay));
+      }
+    }
+
+    return this._fail(NotificationChannel.WEBHOOK, 'Max retries exceeded');
+  }
+
+  // ──────────────────────────────────────────
+  //  IN-APP
+  // ──────────────────────────────────────────
+
+  private _storeInApp(payload: NotificationPayload): NotificationResult {
+    const notification: InAppNotification = {
+      id: `notif-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+      merchantId: payload.recipient.userId,
+      event: payload.event,
+      title: this._buildTitle(payload),
+      message: this._buildMessage(payload),
+      severity: this._getSeverity(payload.event),
+      read: false,
+      data: payload.data,
+      createdAt: new Date().toISOString(),
+    };
+
+    inAppStore.unshift(notification);
+    if (inAppStore.length > 1000) { inAppStore.pop(); }
+
+    return {
+      success: true,
+      channel: NotificationChannel.IN_APP,
+      messageId: notification.id,
+      sentAt: new Date().toISOString(),
+    };
+  }
+
+  // ──────────────────────────────────────────
+  //  IN-APP GETTERS
+  // ──────────────────────────────────────────
+
+  getNotifications(merchantId?: string, unreadOnly = false): InAppNotification[] {
+    let list = merchantId
+      ? inAppStore.filter(n => n.merchantId === merchantId || !n.merchantId)
+      : inAppStore;
+
+    if (unreadOnly) { list = list.filter(n => !n.read); }
+    return list;
+  }
+
+  markAsRead(notificationId: string): boolean {
+    const n = inAppStore.find(n => n.id === notificationId);
+    if (!n) { return false; }
+    n.read = true;
+    return true;
+  }
+
+  markAllAsRead(merchantId?: string): void {
+    inAppStore.forEach(n => {
+      if (!merchantId || n.merchantId === merchantId) { n.read = true; }
+    });
+  }
+
+  getUnreadCount(merchantId?: string): number {
+    return inAppStore.filter(n =>
+      !n.read && (!merchantId || n.merchantId === merchantId)
+    ).length;
+  }
+
+  // ──────────────────────────────────────────
+  //  HELPERS
+  // ──────────────────────────────────────────
+
+  private _buildTitle(payload: NotificationPayload): string {
+    switch (payload.event) {
+      case NotificationEvent.DISPUTE_DETECTED: return '⚠️ New Dispute Detected';
+      case NotificationEvent.DISPUTE_REPLIED:  return '📤 Reply Submitted';
+      case NotificationEvent.DISPUTE_WON:      return '🏆 Dispute Won!';
+      case NotificationEvent.DISPUTE_LOST:     return '❌ Dispute Lost';
+      case NotificationEvent.FRAUD_DETECTED:   return '🔴 Fraud Alert';
+      case NotificationEvent.PAYMENT_REGISTERED: return '✅ Payment Protected';
+      default: return 'Notification';
+    }
+  }
+
+  private _buildMessage(payload: NotificationPayload): string {
+    const d = payload.data;
+    switch (payload.event) {
+      case NotificationEvent.DISPUTE_DETECTED:
+        return `Dispute ${d['disputeId']} filed for $${((Number(d['amount']) || 0) / 100).toFixed(2)}. Auto-reply in progress.`;
+      case NotificationEvent.DISPUTE_WON:
+        return `Chargeback for $${((Number(d['amount']) || 0) / 100).toFixed(2)} successfully defended!`;
+      case NotificationEvent.FRAUD_DETECTED:
+        return `High fraud probability (${((Number(d['probability']) || 0) * 100).toFixed(0)}%) detected on order ${d['orderId']}.`;
+      default:
+        return JSON.stringify(d);
+    }
+  }
+
+  private _buildSMSMessage(payload: NotificationPayload): string {
+    const d = payload.data;
+    switch (payload.event) {
+      case NotificationEvent.DISPUTE_DETECTED:
+        return `ChargebackGuard Alert: New dispute ${d['disputeId']} for $${((Number(d['amount']) || 0) / 100).toFixed(2)}. Auto-handling...`;
+      case NotificationEvent.DISPUTE_WON:
+        return `ChargebackGuard: You WON dispute ${d['disputeId']}! $${((Number(d['amount']) || 0) / 100).toFixed(2)} recovered.`;
+      default:
+        return `ChargebackGuard: ${payload.event}`;
+    }
+  }
+
+  private _getSeverity(event: string): InAppNotification['severity'] {
+    const severityMap: Record<string, InAppNotification['severity']> = {
+      [NotificationEvent.DISPUTE_DETECTED]:  'warning',
+      [NotificationEvent.DISPUTE_WON]:       'success',
+      [NotificationEvent.DISPUTE_LOST]:      'error',
+      [NotificationEvent.FRAUD_DETECTED]:    'error',
+      [NotificationEvent.PAYMENT_REGISTERED]: 'info',
+      [NotificationEvent.ERROR]:             'error',
+    };
+    return severityMap[event] ?? 'info';
+  }
+
+  private _fail(channel: NotificationChannel, error: string): NotificationResult {
+    log.warn(`Notification failed: ${channel}`, { error });
+    return { success: false, channel, error, sentAt: new Date().toISOString() };
+  }
+}

package/src/notifications/sms.ts

@@ -0,0 +1,58 @@
+// ============================================================
+//  CHARGEBACK GUARD — SMS Service (Twilio)
+// ============================================================
+
+import { createLogger } from '../utils/logger';
+import { smsConfig } from '../config';
+
+const log = createLogger('SMS');
+
+export class SMSService {
+  private client: unknown;
+
+  constructor() {
+    if (smsConfig.accountSid && smsConfig.authToken) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        this.client = require('twilio')(smsConfig.accountSid, smsConfig.authToken);
+      } catch {
+        log.warn('Twilio not available — SMS disabled');
+      }
+    }
+  }
+
+  async send(to: string, message: string): Promise<boolean> {
+    if (!this.client) {
+      log.warn('SMS client not initialized');
+      return false;
+    }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await (this.client as any).messages.create({
+        body: message,
+        from: smsConfig.phoneNumber,
+        to,
+      });
+      log.info(`SMS sent to ${to}`);
+      return true;
+    } catch (err) {
+      log.error('SMS send failed', { error: err instanceof Error ? err.message : String(err) });
+      return false;
+    }
+  }
+
+  async sendDisputeAlert(to: string, disputeId: string, amount: number): Promise<boolean> {
+    return this.send(
+      to,
+      `[ChargebackGuard] ⚠️ New dispute ${disputeId} for $${(amount / 100).toFixed(2)}. Auto-reply in progress. Check dashboard.`
+    );
+  }
+
+  async sendDisputeWon(to: string, disputeId: string, amount: number): Promise<boolean> {
+    return this.send(
+      to,
+      `[ChargebackGuard] 🏆 Dispute ${disputeId} WON! $${(amount / 100).toFixed(2)} recovered to your account.`
+    );
+  }
+}

package/src/security/auth.ts

@@ -0,0 +1,153 @@
+// ============================================================
+//  CHARGEBACK GUARD — Authentication & Authorization
+// ============================================================
+
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import bcrypt from 'bcryptjs';
+import { createLogger } from '../utils/logger';
+import { securityConfig } from '../config';
+import { generateApiKey } from '../evidence/encryption';
+
+const log = createLogger('Auth');
+
+// ────────────────────────────────────────────────────────────
+//  TYPES
+// ────────────────────────────────────────────────────────────
+
+export interface JwtPayload {
+  merchantId: string;
+  email: string;
+  plan: string;
+  iat?: number;
+  exp?: number;
+}
+
+export interface AuthenticatedRequest extends Request {
+  merchant?: JwtPayload;
+  merchantId?: string;
+}
+
+// ────────────────────────────────────────────────────────────
+//  TOKEN UTILITIES
+// ────────────────────────────────────────────────────────────
+
+export function signToken(payload: Omit<JwtPayload, 'iat' | 'exp'>): string {
+  return jwt.sign(payload, securityConfig.jwtSecret, {
+    expiresIn: securityConfig.jwtExpiresIn,
+    issuer: 'chargeback-guard',
+    audience: 'cbg-api',
+  });
+}
+
+export function verifyToken(token: string): JwtPayload {
+  return jwt.verify(token, securityConfig.jwtSecret, {
+    issuer: 'chargeback-guard',
+    audience: 'cbg-api',
+  }) as JwtPayload;
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, securityConfig.bcryptRounds);
+}
+
+export async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+
+export function generateMerchantApiKey(): string {
+  return generateApiKey(securityConfig.apiKeyPrefix);
+}
+
+// ────────────────────────────────────────────────────────────
+//  JWT MIDDLEWARE
+// ────────────────────────────────────────────────────────────
+
+export function requireAuth(req: AuthenticatedRequest, res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    res.status(401).json({
+      success: false,
+      error: { code: 'UNAUTHORIZED', message: 'Bearer token required' },
+    });
+    return;
+  }
+
+  const token = authHeader.slice(7);
+
+  try {
+    const payload = verifyToken(token);
+    req.merchant   = payload;
+    req.merchantId = payload.merchantId;
+    next();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Invalid token';
+    log.warn('JWT verification failed', { error: message });
+    res.status(401).json({
+      success: false,
+      error: { code: 'TOKEN_INVALID', message },
+    });
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  API KEY MIDDLEWARE
+// ────────────────────────────────────────────────────────────
+
+export function requireApiKey(
+  lookupFn: (key: string) => Promise<JwtPayload | null>
+): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void {
+  return (req: AuthenticatedRequest, res: Response, next: NextFunction): void => {
+    const key =
+      (req.headers['x-api-key'] as string) ??
+      (req.query['api_key'] as string);
+
+    if (!key) {
+      res.status(401).json({
+        success: false,
+        error: { code: 'API_KEY_MISSING', message: 'API key required' },
+      });
+      return;
+    }
+
+    lookupFn(key)
+      .then(merchant => {
+        if (!merchant) {
+          res.status(401).json({
+            success: false,
+            error: { code: 'API_KEY_INVALID', message: 'Invalid API key' },
+          });
+          return;
+        }
+        req.merchant   = merchant;
+        req.merchantId = merchant.merchantId;
+        next();
+      })
+      .catch(err => {
+        log.error('API key lookup failed', { error: err.message });
+        res.status(500).json({
+          success: false,
+          error: { code: 'INTERNAL_ERROR', message: 'Authentication failed' },
+        });
+      });
+  };
+}
+
+// ────────────────────────────────────────────────────────────
+//  OPTIONAL AUTH (sets merchant if token present)
+// ────────────────────────────────────────────────────────────
+
+export function optionalAuth(req: AuthenticatedRequest, _res: Response, next: NextFunction): void {
+  const authHeader = req.headers.authorization;
+  if (authHeader?.startsWith('Bearer ')) {
+    try {
+      const payload = verifyToken(authHeader.slice(7));
+      req.merchant   = payload;
+      req.merchantId = payload.merchantId;
+    } catch {
+      // silently ignore
+    }
+  }
+  next();
+}