pn-new-crm/src/lib/audit.ts

import { db } from '@/lib/db';
import { auditLogs } from '@/lib/db/schema';
import { logger } from '@/lib/logger';

export type AuditAction =
  | 'create'
  | 'update'
  | 'delete'
  | 'archive'
  | 'restore'
  | 'merge'
  | 'login'
  | 'logout'
  | 'permission_denied'
  | 'revert'
  | 'revoke_invite'
  | 'resend_invite'
  | 'request_gdpr_export'
  | 'send_gdpr_export'
  | 'password_change'
  | 'portal_invite'
  | 'portal_activate'
  | 'portal_password_reset_request'
  | 'portal_password_reset'
  | 'send'
  | 'view'
  | 'request_hard_delete_code'
  | 'hard_delete'
  // Branding (port logo upload pipeline).
  | 'branding.logo.uploaded'
  | 'branding.logo.archived'
  // System / background events.
  | 'webhook_delivered'
  | 'webhook_failed'
  | 'webhook_dead_letter'
  | 'webhook_retried'
  | 'job_failed'
  | 'cron_run';

/**
 * Common shape passed to service functions so they can stamp audit logs and
 * propagate request context. Every authenticated route resolves these from
 * the session + headers; services accept them rather than reaching into
 * Next.js APIs themselves.
 */
export interface AuditMeta {
  userId: string;
  portId: string;
  ipAddress: string;
  userAgent: string;
}

export type AuditSeverity = 'info' | 'warning' | 'error' | 'critical';
export type AuditSource = 'user' | 'system' | 'auth' | 'webhook' | 'cron' | 'job';

export interface AuditLogParams {
  /** Null for system-generated events. */
  userId: string | null;
  /** Null for system-level events not tied to a port. */
  portId: string | null;
  action: AuditAction;
  entityType: string;
  entityId: string;
  fieldChanged?: string;
  oldValue?: Record<string, unknown>;
  newValue?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
  /** Optional. Services that don't have request context (e.g. background
   *  jobs, internal helpers) may omit. */
  ipAddress?: string;
  userAgent?: string;
  /** Defaults to 'info'. Bump to 'warning' for permission_denied,
   *  'error' for failed background jobs / webhook DLQ, 'critical' for
   *  hard-deletes / security-relevant events. */
  severity?: AuditSeverity;
  /** Defaults to 'user'. Use 'auth' for session lifecycle,
   *  'webhook' for delivery events, 'job' / 'cron' / 'system' for
   *  background work. The inspector filters on this column. */
  source?: AuditSource;
}

const SENSITIVE_FIELDS = new Set(['email', 'phone', 'password', 'credentials_enc', 'token']);

/**
 * Masks sensitive field values to prevent PII or secrets from being stored
 * verbatim in the audit log (SECURITY-GUIDELINES.md §5.2).
 *
 * Strings are replaced with a partial mask - first 2 chars + *** + last 2 chars.
 */
export function maskSensitiveFields(
  data?: Record<string, unknown>,
): Record<string, unknown> | undefined {
  if (!data) return undefined;
  const masked = { ...data };
  for (const key of Object.keys(masked)) {
    if (SENSITIVE_FIELDS.has(key) && typeof masked[key] === 'string') {
      const val = masked[key] as string;
      masked[key] = val.length > 4 ? `${val.slice(0, 2)}***${val.slice(-2)}` : '***';
    }
  }
  return masked;
}

/**
 * Computes a field-level diff between two records.
 * Returns one entry per changed field with the old and new values.
 */
export function diffFields(
  oldRecord: Record<string, unknown>,
  newRecord: Record<string, unknown>,
): Array<{ field: string; oldValue: unknown; newValue: unknown }> {
  const changes: Array<{ field: string; oldValue: unknown; newValue: unknown }> = [];
  for (const key of Object.keys(newRecord)) {
    if (JSON.stringify(oldRecord[key]) !== JSON.stringify(newRecord[key])) {
      changes.push({ field: key, oldValue: oldRecord[key], newValue: newRecord[key] });
    }
  }
  return changes;
}

/**
 * Inserts an audit log entry into the database.
 *
 * This function NEVER throws - errors are caught and logged so that an audit
 * failure never rolls back or disrupts the parent operation.
 */
// Some actions get a default severity bump so callers don't have to
// remember; explicit `severity` on the call still wins.
const DEFAULT_SEVERITY_BY_ACTION: Partial<Record<AuditAction, AuditSeverity>> = {
  permission_denied: 'warning',
  hard_delete: 'critical',
};
const AUTH_ACTIONS = new Set<AuditAction>(['login', 'logout', 'password_change']);

export async function createAuditLog(params: AuditLogParams): Promise<void> {
  try {
    const severity = params.severity ?? DEFAULT_SEVERITY_BY_ACTION[params.action] ?? 'info';
    const source = params.source ?? (AUTH_ACTIONS.has(params.action) ? 'auth' : 'user');

    await db.insert(auditLogs).values({
      portId: params.portId,
      userId: params.userId,
      action: params.action,
      entityType: params.entityType,
      entityId: params.entityId,
      fieldChanged: params.fieldChanged ?? null,
      oldValue: maskSensitiveFields(params.oldValue) ?? null,
      newValue: maskSensitiveFields(params.newValue) ?? null,
      // Mask metadata too — the audit found portal-auth, crm-invite,
      // hard-delete, and email-accounts services were writing raw emails
      // into this column.
      metadata: maskSensitiveFields(params.metadata) ?? null,
      ipAddress: params.ipAddress ?? null,
      userAgent: params.userAgent ?? null,
      severity,
      source,
    });
  } catch (err) {
    // Strip old/new values from the log to avoid secondary exposure of the data
    // that just failed to persist.
    logger.error(
      {
        err,
        audit: {
          userId: params.userId,
          portId: params.portId,
          action: params.action,
          entityType: params.entityType,
          entityId: params.entityId,
        },
      },
      'Failed to write audit log',
    );
  }
}