@zintrust/trace 0.4.76 → 0.4.79

package/dist/watchers/HttpWatcher.js

@@ -1,7 +1,7 @@
 import { TraceContext } from '../context.js';
 import { EntryType } from '../types.js';
 import { AuthTag } from '../utils/authTag.js';
-import { redactHeaders, redactObject } from '../utils/redact.js';
+import { redactHeaders, redactObject, redactUnknown } from '../utils/redact.js';
 import { RequestFilter } from '../utils/requestFilter.js';
 const normalizeHeaders = (headers) => {
     if (!headers)
@@ -14,16 +14,98 @@ const normalizeHeaders = (headers) => {
         return [];
     }));
 };
-const buildEntry = (req, res, start, config) => {
-    const headers = redactHeaders(normalizeHeaders(req.headers), config.redaction.headers);
-    const payload = req.body ? redactObject(req.body, config.redaction.body) : {};
+const normalizeHeaderValue = (value) => {
+    return Array.isArray(value) ? value.join(', ') : value;
+};
+const resolveRequestPayload = (req, config) => {
+    const redactFields = [...config.redaction.keys, ...config.redaction.body];
+    const requestBody = typeof req.getBody === 'function' ? req.getBody() : req.body;
+    if (requestBody === undefined || requestBody === null)
+        return {};
+    if (typeof requestBody === 'object') {
+        return redactObject(requestBody, redactFields);
+    }
+    return redactUnknown(requestBody, redactFields);
+};
+const registerCompletionHandler = (response, onComplete) => {
+    const raw = response.getRaw();
+    if (typeof raw.once !== 'function')
+        return () => undefined;
+    let completed = false;
+    const cleanup = () => {
+        if (typeof raw.off === 'function') {
+            raw.off('finish', markCompleted);
+            raw.off('close', markCompleted);
+        }
+    };
+    const markCompleted = () => {
+        if (completed)
+            return;
+        completed = true;
+        cleanup();
+        onComplete();
+    };
+    raw.once('finish', markCompleted);
+    raw.once('close', markCompleted);
+    return cleanup;
+};
+const captureResponse = (response, config) => {
+    const headers = {};
+    const redactFields = [...config.redaction.keys, ...config.redaction.body];
+    const originalSetHeader = response.setHeader;
+    const originalJson = response.json;
+    const originalText = response.text;
+    const originalHtml = response.html;
+    const originalSend = response.send;
+    const capture = {
+        headers,
+        body: undefined,
+        restore() {
+            response.setHeader = originalSetHeader;
+            response.json = originalJson;
+            response.text = originalText;
+            response.html = originalHtml;
+            response.send = originalSend;
+        },
+    };
+    response.setHeader = function setHeader(name, value) {
+        headers[name] = normalizeHeaderValue(value);
+        return originalSetHeader.call(this, name, value);
+    };
+    response.json = function json(data) {
+        capture.body = redactUnknown(data, redactFields);
+        originalJson.call(this, data);
+    };
+    response.text = function text(value) {
+        capture.body = value;
+        originalText.call(this, value);
+    };
+    response.html = function html(value) {
+        capture.body = value;
+        originalHtml.call(this, value);
+    };
+    response.send = function send(data) {
+        capture.body = typeof data === 'string' ? data : `[binary ${data.length} bytes]`;
+        originalSend.call(this, data);
+    };
+    return capture;
+};
+const buildEntry = (req, res, start, config, responseCapture) => {
+    const headers = redactHeaders(normalizeHeaders(req.headers), [
+        ...config.redaction.keys,
+        ...config.redaction.headers,
+    ]);
     return {
         method: req.getMethod(),
         uri: req.getPath(),
         headers,
-        payload,
+        payload: resolveRequestPayload(req, config),
         responseStatus: res.getStatus(),
-        responseHeaders: {},
+        responseHeaders: redactHeaders(responseCapture.headers, [
+            ...config.redaction.keys,
+            ...config.redaction.headers,
+        ]),
+        responseBody: responseCapture.body,
         duration: Date.now() - start,
         memory: TraceContext.getMemory(),
         middleware: [],
@@ -48,22 +130,31 @@ export const HttpWatcher = Object.freeze({
                 return next();
             const start = TraceContext.now();
             const batchId = TraceContext.getBatchId();
+            const responseCapture = captureResponse(response, config);
+            let didPersist = false;
+            const persistEntry = () => {
+                if (didPersist)
+                    return;
+                didPersist = true;
+                const content = buildEntry(request, response, start, config, responseCapture);
+                const tags = AuthTag.append([]);
+                if (content.responseStatus >= 500)
+                    tags.push('failed');
+                responseCapture.restore();
+                storage
+                    .writeEntry({
+                    uuid: crypto.randomUUID(),
+                    batchId,
+                    type: EntryType.REQUEST,
+                    content,
+                    tags,
+                    isLatest: true,
+                    createdAt: TraceContext.now(),
+                })
+                    .catch(() => undefined); // fire-and-forget
+            };
+            registerCompletionHandler(response, persistEntry);
             await next();
-            const content = buildEntry(request, response, start, config);
-            const tags = AuthTag.append([]);
-            if (content.responseStatus >= 500)
-                tags.push('failed');
-            storage
-                .writeEntry({
-                uuid: crypto.randomUUID(),
-                batchId,
-                type: EntryType.REQUEST,
-                content,
-                tags,
-                isLatest: true,
-                createdAt: TraceContext.now(),
-            })
-                .catch(() => undefined); // fire-and-forget
         };
         registerMiddleware(middleware);
         return () => undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.4.76",
+  "version": "0.4.79",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.4.74"
+    "@zintrust/core": "^0.4.77"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -1,7 +1,107 @@
 /**
  * TraceConfig — defaults and merge helper for @zintrust/trace
  */
-import type { ITraceConfig, TraceConfigOverrides } from './types';
+import type {
+  ITraceConfig,
+  TraceConfigOverrides,
+  TraceFilterRule,
+  TraceRequestWatcherConfig,
+  TraceWatcherToggle,
+} from './types';
+
+const mergeStringLists = (base: string[], override?: string[]): string[] => {
+  const merged = new Set<string>();
+
+  for (const value of [...base, ...(override ?? [])]) {
+    if (typeof value !== 'string') continue;
+    const normalized = value.trim();
+    if (normalized !== '') merged.add(normalized);
+  }
+
+  return [...merged];
+};
+
+const isObjectValue = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+const mergeFilterRule = (
+  base?: TraceFilterRule,
+  override?: TraceFilterRule
+): TraceFilterRule | undefined => {
+  const include = mergeStringLists(base?.include ?? [], override?.include);
+  const exclude = mergeStringLists(base?.exclude ?? [], override?.exclude);
+
+  if (include.length === 0 && exclude.length === 0) return undefined;
+
+  return Object.freeze({
+    ...(include.length > 0 ? { include } : {}),
+    ...(exclude.length > 0 ? { exclude } : {}),
+  });
+};
+
+const mergeWatcherToggle = (
+  base?: TraceWatcherToggle,
+  override?: TraceWatcherToggle
+): TraceWatcherToggle | undefined => {
+  if (override === undefined) return base;
+  if (override === false || override === true) return override;
+
+  const baseRule = isObjectValue(base) ? base : undefined;
+  return mergeFilterRule(baseRule, override);
+};
+
+const REQUEST_METHOD_KEYS = ['all', 'get', 'post', 'put', 'patch', 'delete'] as const;
+
+const mergeRequestWatcherToggle = (
+  base?: ITraceConfig['watchers']['request'],
+  override?: ITraceConfig['watchers']['request']
+): ITraceConfig['watchers']['request'] | undefined => {
+  if (override === undefined) return base;
+  if (override === false || override === true) return override;
+
+  const baseConfig = isObjectValue(base) ? base : undefined;
+  const merged: TraceRequestWatcherConfig = mergeFilterRule(baseConfig, override) ?? {};
+
+  for (const key of REQUEST_METHOD_KEYS) {
+    const rule = mergeFilterRule(baseConfig?.[key], override[key]);
+    if (rule !== undefined) merged[key] = rule;
+  }
+
+  return merged;
+};
+
+const mergeWatchers = (
+  base: ITraceConfig['watchers'],
+  override?: TraceConfigOverrides['watchers']
+): ITraceConfig['watchers'] => {
+  if (override === undefined) return { ...base };
+
+  return {
+    ...base,
+    ...override,
+    request: mergeRequestWatcherToggle(base.request, override.request),
+    query: mergeWatcherToggle(base.query, override.query),
+    exception: mergeWatcherToggle(base.exception, override.exception),
+    log: mergeWatcherToggle(base.log, override.log),
+    job: mergeWatcherToggle(base.job, override.job),
+    cache: mergeWatcherToggle(base.cache, override.cache),
+    schedule: mergeWatcherToggle(base.schedule, override.schedule),
+    mail: mergeWatcherToggle(base.mail, override.mail),
+    auth: mergeWatcherToggle(base.auth, override.auth),
+    event: mergeWatcherToggle(base.event, override.event),
+    model: mergeWatcherToggle(base.model, override.model),
+    notification: mergeWatcherToggle(base.notification, override.notification),
+    redis: mergeWatcherToggle(base.redis, override.redis),
+    gate: mergeWatcherToggle(base.gate, override.gate),
+    middleware: mergeWatcherToggle(base.middleware, override.middleware),
+    command: mergeWatcherToggle(base.command, override.command),
+    batch: mergeWatcherToggle(base.batch, override.batch),
+    dump: mergeWatcherToggle(base.dump, override.dump),
+    view: mergeWatcherToggle(base.view, override.view),
+    clientRequest: mergeWatcherToggle(base.clientRequest, override.clientRequest),
+  };
+};
 
 const DEFAULTS: ITraceConfig = Object.freeze({
   enabled: false,
@@ -12,6 +112,37 @@ const DEFAULTS: ITraceConfig = Object.freeze({
   logMinLevel: 'info',
   watchers: {},
   redaction: {
+    keys: [
+      'password',
+      'pass',
+      'passwd',
+      'token',
+      'accessToken',
+      'access_token',
+      'refreshToken',
+      'refresh_token',
+      'secret',
+      'secretKey',
+      'secret_key',
+      'apiKey',
+      'api_key',
+      'auth',
+      'authToken',
+      'auth_token',
+      'authorization',
+      'cookie',
+      'session',
+      'sessionId',
+      'session_id',
+      'card',
+      'cardNumber',
+      'card_number',
+      'cardToken',
+      'card_token',
+      'cvv',
+      'cvc',
+      'pan',
+    ],
     headers: ['authorization', 'cookie', 'x-api-key', 'x-auth-token'],
     body: ['password', 'token', 'secret', 'apiKey', 'api_key', 'jwt', 'bearer'],
     query: [],
@@ -20,7 +151,20 @@ const DEFAULTS: ITraceConfig = Object.freeze({
 
 const isWatcherEnabled = (config: ITraceConfig, key: keyof ITraceConfig['watchers']): boolean => {
   const override = config.watchers[key];
-  return override !== false; // undefined = enabled by default; explicit false = disabled
+  if (override === false) return false;
+  if (isObjectValue(override) && override.enabled === false) return false;
+  return true; // undefined = enabled by default; explicit false = disabled
+};
+
+const getRedactionFields = (
+  config: ITraceConfig,
+  key: keyof ITraceConfig['redaction']
+): string[] => {
+  if (key === 'keys') {
+    return mergeStringLists([], config.redaction.keys);
+  }
+
+  return mergeStringLists(config.redaction.keys, config.redaction[key]);
 };
 
 export const TraceConfig = Object.freeze({
@@ -33,14 +177,17 @@ export const TraceConfig = Object.freeze({
     return Object.freeze({
       ...DEFAULTS,
       ...overrides,
-      watchers: { ...DEFAULTS.watchers, ...(overrides.watchers ?? {}) },
+      watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
       redaction: {
-        ...DEFAULTS.redaction,
-        ...(overrides.redaction ?? {}),
+        keys: mergeStringLists(DEFAULTS.redaction.keys, overrides.redaction?.keys),
+        headers: mergeStringLists(DEFAULTS.redaction.headers, overrides.redaction?.headers),
+        body: mergeStringLists(DEFAULTS.redaction.body, overrides.redaction?.body),
+        query: mergeStringLists(DEFAULTS.redaction.query, overrides.redaction?.query),
       },
       ignoreRoutes: overrides.ignoreRoutes ?? DEFAULTS.ignoreRoutes,
     });
   },
 
+  getRedactionFields,
   isWatcherEnabled,
 });

package/src/dashboard/routes.ts

@@ -20,6 +20,10 @@ import {
 } from './handlers';
 import { buildDashboardHtml } from './ui';
 
+type HtmlResponse = {
+  html(body: string): void;
+};
+
 export type TraceDashboardOptions = {
   /** Base path for the dashboard, e.g. '/trace'. Defaults to '/trace'. */
   basePath?: string;
@@ -61,7 +65,7 @@ export const registerTraceRoutes = (
   Router.get(
     router,
     base,
-    (_req, res) => {
+    (_req: unknown, res: HtmlResponse) => {
       res.html(buildDashboardHtml(base, appConfig.name));
     },
     routeOptions
@@ -70,7 +74,7 @@ export const registerTraceRoutes = (
   Router.get(
     router,
     `${base}/*`,
-    (_req, res) => {
+    (_req: unknown, res: HtmlResponse) => {
       res.html(buildDashboardHtml(base, appConfig.name));
     },
     routeOptions