feat(logging): add comprehensive API request/response logging with structured winston logs

- Add dedicated API logger (api-logger.ts) with winston daily rotation
- Create Fastify plugin (api-logging.plugin.ts) to intercept all API requests/responses
- Log request start, body, response, errors, and summary with precise timestamps
- Auto-mask sensitive data using existing sanitizeObject utility
- Register API logging plugin in NestJS bootstrap (server/main.ts)
- Add npm run dev script with cross-env for automatic DEBUG on Windows
- Install cross-env as devDependency for cross-platform env vars

src/server/logging/api-logger.ts

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
+import { getAgentDir } from '../../utils/paths';
+import { sanitizeObject } from '../../utils/sensitiveDataMasking';
+
+const LOG_RETENTION = '30d';
+const LOG_MAX_SIZE = '50m';
+
+const agentDir = getAgentDir();
+
+if (!fs.existsSync(agentDir)) {
+  try {
+    fs.mkdirSync(agentDir, { recursive: true });
+  } catch (e) {
+    console.error('Failed to create agent directory for API logs', e);
+  }
+}
+
+const fileFormat = winston.format.combine(
+  winston.format.timestamp(),
+  winston.format.printf(({ timestamp, level, message, ...meta }) => {
+    const logEntry = {
+      timestamp,
+      level,
+      message,
+      ...meta,
+    };
+    return JSON.stringify(logEntry);
+  }),
+);
+
+const consoleFormat = winston.format.combine(
+  winston.format.colorize({ all: true }),
+  winston.format.printf(({ timestamp, level, message, ...meta }) => {
+    const logEntry = {
+      timestamp,
+      level,
+      message,
+      ...meta,
+    };
+    return JSON.stringify(logEntry);
+  }),
+);
+
+const rotateTransport = new DailyRotateFile({
+  filename: path.join(agentDir, 'api-%DATE%.log'),
+  datePattern: 'YYYY-MM-DD-HH',
+  maxSize: LOG_MAX_SIZE,
+  maxFiles: LOG_RETENTION,
+  zippedArchive: false,
+  auditFile: path.join(agentDir, '.api-log-audit.json'),
+  level: 'debug',
+  format: fileFormat,
+});
+
+rotateTransport.on('error', (error) => {
+  console.error('DailyRotateFile API transport error', error);
+});
+
+const consoleTransport = new winston.transports.Console({
+  level: 'debug',
+  format: consoleFormat,
+});
+
+consoleTransport.on('error', (error) => {
+  console.error('Console API transport error', error);
+});
+
+export const apiLogger = winston.createLogger({
+  level: 'debug',
+  transports: [consoleTransport, rotateTransport],
+  exitOnError: false,
+});
+
+/**
+ * Safely serialize a value for API logging.
+ * Truncates very large bodies to avoid excessive log sizes.
+ */
+export function safeApiLogValue(value: unknown, maxLength = 50_000): unknown {
+  const sanitized = sanitizeObject(value);
+
+  if (typeof sanitized === 'string' && sanitized.length > maxLength) {
+    return sanitized.substring(0, maxLength) + `... [truncated ${sanitized.length - maxLength} chars]`;
+  }
+
+  const stringified = JSON.stringify(sanitized);
+  if (stringified.length > maxLength) {
+    return stringified.substring(0, maxLength) + `... [truncated ${stringified.length - maxLength} chars]`;
+  }
+
+  return sanitized;
+}

src/server/logging/api-logging.plugin.ts

@@ -0,0 +1,141 @@
+import { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { apiLogger, safeApiLogValue } from './api-logger';
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    apiLogContext?: {
+      startTime: number;
+      requestId: string;
+    };
+  }
+}
+
+const MAX_BODY_LOG_LENGTH = 100_000;
+
+function truncateBody(body: unknown): unknown {
+  return safeApiLogValue(body, MAX_BODY_LOG_LENGTH);
+}
+
+function isStreamResponse(reply: FastifyReply): boolean {
+  const contentType = reply.getHeader('content-type');
+  if (typeof contentType === 'string') {
+    return (
+      contentType.includes('text/event-stream') || contentType.includes('application/octet-stream')
+    );
+  }
+  return false;
+}
+
+export async function registerApiLogging(fastify: FastifyInstance): Promise<void> {
+  fastify.addHook('onRequest', async (request: FastifyRequest) => {
+    request.apiLogContext = {
+      startTime: Date.now(),
+      requestId: request.id,
+    };
+
+    apiLogger.debug({
+      type: 'request-start',
+      requestId: request.id,
+      method: request.method,
+      url: request.url,
+      query: safeApiLogValue(request.query),
+      headers: safeApiLogValue(request.headers),
+      ip: request.ip,
+      remoteAddress: request.socket?.remoteAddress,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  fastify.addHook('preHandler', async (request: FastifyRequest) => {
+    if (request.body) {
+      apiLogger.debug({
+        type: 'request-body',
+        requestId: request.id,
+        method: request.method,
+        url: request.url,
+        body: truncateBody(request.body),
+        timestamp: new Date().toISOString(),
+      });
+    }
+  });
+
+  fastify.addHook(
+    'onSend',
+    async (request: FastifyRequest, reply: FastifyReply, payload: unknown) => {
+      const duration = Date.now() - (request.apiLogContext?.startTime || Date.now());
+
+      if (isStreamResponse(reply)) {
+        apiLogger.debug({
+          type: 'response-stream',
+          requestId: request.id,
+          method: request.method,
+          url: request.url,
+          statusCode: reply.statusCode,
+          headers: safeApiLogValue(reply.getHeaders()),
+          durationMs: duration,
+          note: 'Streaming response body not logged',
+          timestamp: new Date().toISOString(),
+        });
+        return payload;
+      }
+
+      let parsedPayload: unknown = payload;
+      if (typeof payload === 'string') {
+        try {
+          parsedPayload = JSON.parse(payload);
+        } catch {
+          parsedPayload = payload;
+        }
+      }
+
+      apiLogger.debug({
+        type: 'response',
+        requestId: request.id,
+        method: request.method,
+        url: request.url,
+        statusCode: reply.statusCode,
+        headers: safeApiLogValue(reply.getHeaders()),
+        body: truncateBody(parsedPayload),
+        durationMs: duration,
+        timestamp: new Date().toISOString(),
+      });
+
+      return payload;
+    },
+  );
+
+  fastify.addHook('onResponse', async (request: FastifyRequest, reply: FastifyReply) => {
+    const duration = Date.now() - (request.apiLogContext?.startTime || Date.now());
+
+    apiLogger.info({
+      type: 'request-summary',
+      requestId: request.id,
+      method: request.method,
+      url: request.url,
+      statusCode: reply.statusCode,
+      durationMs: duration,
+      ip: request.ip,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  fastify.addHook('onError', async (request: FastifyRequest, reply: FastifyReply, error: Error) => {
+    const duration = Date.now() - (request.apiLogContext?.startTime || Date.now());
+
+    apiLogger.error({
+      type: 'error',
+      requestId: request.id,
+      method: request.method,
+      url: request.url,
+      statusCode: reply.statusCode,
+      error: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+        code: (error as any).code,
+      },
+      durationMs: duration,
+      timestamp: new Date().toISOString(),
+    });
+  });
+}

src/server/main.ts

@@ -7,6 +7,7 @@ import { TokenManagerService } from './modules/proxy/token-manager.service';
 
 import { ProxyConfig } from '../types/config';
 import { setServerConfig } from './server-config';
+import { registerApiLogging } from './logging/api-logging.plugin';
 
 let app: NestFastifyApplication | null = null;
 let currentPort: number = 0;
@@ -28,6 +29,10 @@ export async function bootstrapNestServer(config: ProxyConfig): Promise<boolean>
     // Enable CORS
     app.enableCors();
 
+    // Register detailed API request/response logging
+    const fastifyInstance = app.getHttpAdapter().getInstance();
+    await registerApiLogging(fastifyInstance);
+
     await app.listen(port, '0.0.0.0');
     currentPort = port;
     logger.info(`NestJS Proxy Server running on http://localhost:${port}`);