@wdyy/skills 0.1.23 → 0.1.24

package/.well-known/skills/wdyy-logging-standard/templates/logger.template.ts

@@ -1,8 +1,37 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { chmod, mkdir, open } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import { isIP } from 'node:net';
+
+export type LogType = 'access' | 'application' | 'security' | 'audit';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogResult = 'success' | 'failure';
+
+export type BusinessFunction = {
+  functionCode: string;
+  functionName: string;
+  action: string;
+};
+
+export type BusinessFunctionCatalogEntry = BusinessFunction & {
+  method: string;
+  route: string;
+};
+
+export type ActorContext = {
+  actorId: string;
+  actorType: string;
+};
+
 export type LogContext = {
+  logType: LogType;
   traceId?: string;
-  userId?: string;
+  spanId?: string;
+  parentSpanId?: string;
   method?: string;
-  path?: string;
+  route?: string;
+  sourceIp?: string;
+  userAgent?: string;
   statusCode?: number;
   query?: Record<string, unknown>;
   body?: unknown;
@@ -10,38 +39,167 @@ export type LogContext = {
   durationMs?: number;
   errorCode?: string;
   params?: Record<string, unknown>;
+  eventId?: string;
+  eventType?: string;
+  actorId?: string;
+  actorType?: string;
+  functionCode?: string;
+  functionName?: string;
+  action?: string;
+  targetType?: string;
+  targetId?: string;
+  result?: LogResult;
+  reason?: string;
+  before?: unknown;
+  after?: unknown;
+  [key: string]: unknown;
 };
 
 export type LogEntry = LogContext & {
   timestamp: string;
-  level: 'debug' | 'info' | 'warn' | 'error';
+  timestampEpochMs: number;
+  timezone: '+08:00';
+  level: LogLevel;
   service: string;
   instanceId: string;
   env: string;
   message: string;
-  result?: 'success' | 'failure';
 };
 
-const pad = (value: number) => String(value).padStart(2, '0');
+export type StoredLogEntry = LogEntry & {
+  chainId: string;
+  sequence: number;
+  previousHash: string | null;
+  entryHash: string;
+};
+
+export type TraceContext = {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  traceparent: string;
+};
 
 export const LOG_DIRECTORY = './logs' as const;
 export const MAX_LOG_FILE_SIZE_BYTES = 2 * 1024 * 1024;
+export const MIN_NETWORK_LOG_RETENTION_MONTHS = 6;
 
-type RuntimeEnvironment = Record<string, string | undefined>;
+const REQUIRED_BY_TYPE: Record<LogType, readonly string[]> = {
+  access: [
+    'traceId', 'method', 'route', 'sourceIp', 'actorId', 'actorType',
+    'functionCode', 'functionName', 'action', 'statusCode', 'result', 'durationMs',
+  ],
+  application: [],
+  security: ['eventId', 'eventType', 'actorId', 'actorType', 'action', 'targetType', 'targetId', 'result'],
+  audit: ['eventId', 'eventType', 'actorId', 'actorType', 'action', 'targetType', 'targetId', 'result'],
+};
 
-const getRuntimeEnvironment = (): RuntimeEnvironment => {
-  const runtime = globalThis as typeof globalThis & {
-    process?: { env?: RuntimeEnvironment };
-  };
-  return runtime.process?.env ?? {};
+const normalizeFieldName = (value: string): string => value.toLowerCase().replaceAll(/[^a-z0-9]/g, '');
+
+export const FORBIDDEN_LOG_FIELD_NAMES = new Set([
+  'password',
+  'passwd',
+  'pwd',
+  'authorization',
+  'proxyAuthorization',
+  'cookie',
+  'setCookie',
+  'sessionId',
+  'token',
+  'accessToken',
+  'refreshToken',
+  'idToken',
+  'apiKey',
+  'secret',
+  'clientSecret',
+  'privateKey',
+  'databaseUrl',
+  'databasePassword',
+  'dbPassword',
+  'connectionString',
+  'idCard',
+  'bankCard',
+  'medicalRecord',
+  'medicalRecordNumber',
+  'diagnosis',
+  'healthData',
+].map(normalizeFieldName));
+
+const omitted = Symbol('omitted-log-field');
+
+export const sanitizeLogText = (value: string): string => value
+  .replaceAll(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, 'Bearer [REMOVED]')
+  .replaceAll(/\b(password|passwd|pwd|token|secret|api[_-]?key)\s*[:=]\s*[^\s,;]+/gi, '$1=[REMOVED]')
+  .replaceAll(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REMOVED_JWT]');
+
+const sanitizeValue = (
+  value: unknown,
+  forbiddenNames: ReadonlySet<string>,
+): unknown | typeof omitted => {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => sanitizeValue(item, forbiddenNames))
+      .filter((item) => item !== omitted);
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return sanitizeLogText(value);
+  if (!value || typeof value !== 'object') return value;
+
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (forbiddenNames.has(normalizeFieldName(key))) continue;
+    const sanitizedItem = sanitizeValue(item, forbiddenNames);
+    if (sanitizedItem !== omitted) sanitized[key] = sanitizedItem;
+  }
+  return sanitized;
+};
+
+export const sanitizeLogValue = (
+  value: unknown,
+  additionalForbiddenNames: Iterable<string> = [],
+): unknown => {
+  const forbiddenNames = new Set(FORBIDDEN_LOG_FIELD_NAMES);
+  for (const name of additionalForbiddenNames) forbiddenNames.add(normalizeFieldName(name));
+  const sanitized = sanitizeValue(value, forbiddenNames);
+  return sanitized === omitted ? undefined : sanitized;
 };
 
+export const findForbiddenLogFieldPath = (
+  value: unknown,
+  path = '$',
+): string | undefined => {
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const found = findForbiddenLogFieldPath(item, `${path}[${index}]`);
+      if (found) return found;
+    }
+    return undefined;
+  }
+  if (!value || typeof value !== 'object') return undefined;
+  for (const [key, item] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    if (FORBIDDEN_LOG_FIELD_NAMES.has(normalizeFieldName(key))) return childPath;
+    const found = findForbiddenLogFieldPath(item, childPath);
+    if (found) return found;
+  }
+  return undefined;
+};
+
+const pad = (value: number, length = 2): string => String(value).padStart(length, '0');
+
 export const formatLocalTimestamp = (date = new Date()): string => (
   [date.getFullYear(), pad(date.getMonth() + 1), pad(date.getDate())].join('-')
   + ' '
   + [pad(date.getHours()), pad(date.getMinutes()), pad(date.getSeconds())].join(':')
 );
 
+export const formatTimezoneOffset = (date = new Date()): string => {
+  const totalMinutes = -date.getTimezoneOffset();
+  const sign = totalMinutes >= 0 ? '+' : '-';
+  const absoluteMinutes = Math.abs(totalMinutes);
+  return `${sign}${pad(Math.floor(absoluteMinutes / 60))}:${pad(absoluteMinutes % 60)}`;
+};
+
 export const createLogFileName = (date = new Date(), collisionIndex = 0): string => {
   const baseName = formatLocalTimestamp(date).replace(' ', '_').replaceAll(':', '-');
   return `${baseName}${collisionIndex > 0 ? `_${collisionIndex}` : ''}.log`;
@@ -51,25 +209,282 @@ export const createLogFilePath = (date = new Date(), collisionIndex = 0): string
   `${LOG_DIRECTORY}/${createLogFileName(date, collisionIndex)}`
 );
 
-const resultForStatusCode = (statusCode: number): LogEntry['result'] => {
+const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const NON_ZERO_TRACE_ID = /[1-9a-f]/;
+
+export const parseTraceParent = (value: string | undefined): TraceContext | undefined => {
+  if (!value) return undefined;
+  const match = TRACEPARENT_PATTERN.exec(value);
+  if (!match || !NON_ZERO_TRACE_ID.test(match[1]) || !NON_ZERO_TRACE_ID.test(match[2])) return undefined;
+  const spanId = randomBytes(8).toString('hex');
+  return {
+    traceId: match[1],
+    spanId,
+    parentSpanId: match[2],
+    traceparent: `00-${match[1]}-${spanId}-${match[3]}`,
+  };
+};
+
+export const createTraceContext = (incomingTraceParent?: string): TraceContext => {
+  const continued = parseTraceParent(incomingTraceParent);
+  if (continued) return continued;
+  const traceId = randomBytes(16).toString('hex');
+  const spanId = randomBytes(8).toString('hex');
+  return { traceId, spanId, traceparent: `00-${traceId}-${spanId}-01` };
+};
+
+const getRuntimeEnvironment = (): Record<string, string | undefined> => {
+  const runtime = globalThis as typeof globalThis & {
+    process?: { env?: Record<string, string | undefined> };
+  };
+  return runtime.process?.env ?? {};
+};
+
+const isPresent = (value: unknown): boolean => (
+  value !== undefined && value !== null && (typeof value !== 'string' || value.trim() !== '')
+);
+
+const BUSINESS_IDENTIFIER_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const UNRESOLVED_BUSINESS_VALUES = new Set(['unknown', 'unresolved', '未知', '待确认']);
+
+const isUnresolvedBusinessValue = (value: string): boolean => (
+  UNRESOLVED_BUSINESS_VALUES.has(value.trim().toLowerCase())
+);
+
+const assertRouteTemplate = (route: unknown): void => {
+  if (typeof route !== 'string' || route.trim() === '' || route.includes('?') || route.includes('#')) {
+    throw new Error('route must be a route template without query parameters or fragments');
+  }
+};
+
+const assertSourceIp = (sourceIp: unknown): void => {
+  if (typeof sourceIp !== 'string' || isIP(sourceIp) === 0) {
+    throw new Error('sourceIp must be a valid IPv4 or IPv6 address');
+  }
+};
+
+const assertBusinessFunction = (value: Partial<BusinessFunction>): void => {
+  if (
+    typeof value.functionCode !== 'string'
+    || !BUSINESS_IDENTIFIER_PATTERN.test(value.functionCode)
+    || isUnresolvedBusinessValue(value.functionCode)
+  ) {
+    throw new Error('functionCode must be a stable lowercase business identifier');
+  }
+  if (
+    typeof value.functionName !== 'string'
+    || !isPresent(value.functionName)
+    || isUnresolvedBusinessValue(value.functionName)
+  ) {
+    throw new Error('functionName must be a resolved non-empty business name');
+  }
+  if (
+    typeof value.action !== 'string'
+    || !BUSINESS_IDENTIFIER_PATTERN.test(value.action)
+    || isUnresolvedBusinessValue(value.action)
+  ) {
+    throw new Error('action must be a lowercase business action identifier');
+  }
+};
+
+export class BusinessFunctionCatalog {
+  private readonly entries = new Map<string, BusinessFunction>();
+
+  constructor(entries: readonly BusinessFunctionCatalogEntry[]) {
+    for (const entry of entries) {
+      const method = entry.method.trim().toUpperCase();
+      assertRouteTemplate(entry.route);
+      assertBusinessFunction(entry);
+      const key = `${method} ${entry.route}`;
+      if (this.entries.has(key)) throw new Error(`Duplicate business function mapping: ${key}`);
+      this.entries.set(key, {
+        functionCode: entry.functionCode,
+        functionName: entry.functionName,
+        action: entry.action,
+      });
+    }
+  }
+
+  resolve(method: string, route: string): BusinessFunction {
+    const key = `${method.trim().toUpperCase()} ${route}`;
+    const value = this.entries.get(key);
+    if (!value) throw new Error(`Missing business function mapping: ${key}`);
+    return { ...value };
+  }
+}
+
+export const resolveActorContext = (actor?: { id?: string; type?: string }): ActorContext => {
+  if (!actor?.id && !actor?.type) return { actorId: 'anonymous', actorType: 'anonymous' };
+  if (!isPresent(actor.id) || !isPresent(actor.type)) {
+    throw new Error('Authenticated actor requires both id and type');
+  }
+  return { actorId: actor.id as string, actorType: actor.type as string };
+};
+
+export const requireSourceIp = (sourceIp: string | undefined): string => {
+  assertSourceIp(sourceIp);
+  return sourceIp as string;
+};
+
+const resultForStatusCode = (statusCode: number): LogResult | undefined => {
   if (statusCode >= 100 && statusCode <= 399) return 'success';
   if (statusCode >= 400 && statusCode <= 599) return 'failure';
   return undefined;
 };
 
-export const toLogEntry = (level: LogEntry['level'], message: string, context: LogContext): LogEntry => {
+const assertTraceId = (traceId: unknown): void => {
+  if (typeof traceId !== 'string' || !/^[0-9a-f]{32}$/.test(traceId) || !NON_ZERO_TRACE_ID.test(traceId)) {
+    throw new Error('traceId must be 32 non-zero lowercase hexadecimal characters');
+  }
+};
+
+export const assertLogEntry = (entry: LogEntry): void => {
+  const commonRequired = [
+    'timestamp', 'timestampEpochMs', 'timezone', 'level', 'service', 'instanceId', 'env', 'logType', 'message',
+  ];
+  const missing = commonRequired.filter((key) => !isPresent(entry[key]));
+  if (missing.length) throw new Error(`Missing log fields: ${missing.join(', ')}`);
+  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(entry.timestamp)) {
+    throw new Error('timestamp must use local YYYY-MM-DD HH:mm:ss format');
+  }
+  if (!Number.isSafeInteger(entry.timestampEpochMs) || entry.timestampEpochMs <= 0) {
+    throw new Error('timestampEpochMs must be a positive safe integer');
+  }
+  if (entry.timezone !== '+08:00') throw new Error('timezone must be +08:00');
+  if (!Object.hasOwn(REQUIRED_BY_TYPE, entry.logType)) throw new Error('Unknown logType');
+
+  const typeMissing = REQUIRED_BY_TYPE[entry.logType].filter((key) => !isPresent(entry[key]));
+  if (typeMissing.length) throw new Error(`Missing ${entry.logType} log fields: ${typeMissing.join(', ')}`);
+  if (entry.logType === 'access') {
+    assertTraceId(entry.traceId);
+    assertRouteTemplate(entry.route);
+    assertSourceIp(entry.sourceIp);
+    assertBusinessFunction(entry);
+    const expectedResult = resultForStatusCode(Number(entry.statusCode));
+    if (!expectedResult || entry.result !== expectedResult) {
+      throw new Error('statusCode and result must match');
+    }
+    if (typeof entry.durationMs !== 'number' || entry.durationMs < 0) {
+      throw new Error('durationMs must be a non-negative number');
+    }
+  }
+  if (entry.logType === 'security' || entry.logType === 'audit') {
+    const requestFields = ['traceId', 'sourceIp', 'route', 'functionCode', 'functionName'] as const;
+    const presentRequestFields = requestFields.filter((key) => isPresent(entry[key]));
+    if (presentRequestFields.length > 0 && presentRequestFields.length !== requestFields.length) {
+      throw new Error(`Request-triggered ${entry.logType} logs require traceId, sourceIp, route, functionCode and functionName`);
+    }
+    if (presentRequestFields.length === requestFields.length) {
+      assertSourceIp(entry.sourceIp);
+      assertRouteTemplate(entry.route);
+      assertBusinessFunction(entry);
+    }
+  }
+  if ((entry.logType === 'security' || entry.logType === 'audit') && entry.result === 'failure' && !isPresent(entry.reason)) {
+    throw new Error('Failed security and audit logs require reason');
+  }
+  if (entry.traceId !== undefined) assertTraceId(entry.traceId);
+  const forbiddenPath = findForbiddenLogFieldPath(entry);
+  if (forbiddenPath) throw new Error(`Forbidden log field: ${forbiddenPath}`);
+};
+
+export const toLogEntry = (
+  level: LogLevel,
+  message: string,
+  context: LogContext,
+  date = new Date(),
+  additionalForbiddenNames: Iterable<string> = [],
+): LogEntry => {
   const environment = getRuntimeEnvironment();
-  const result = context.statusCode === undefined
-    ? undefined
-    : resultForStatusCode(context.statusCode);
-  return {
-    timestamp: formatLocalTimestamp(),
+  const sanitizedContext = sanitizeLogValue(context, additionalForbiddenNames) as LogContext;
+  const statusResult = sanitizedContext.logType === 'access' && typeof sanitizedContext.statusCode === 'number'
+    ? resultForStatusCode(sanitizedContext.statusCode)
+    : undefined;
+  const entry = {
+    timestamp: formatLocalTimestamp(date),
+    timestampEpochMs: date.getTime(),
+    timezone: formatTimezoneOffset(date),
     level,
     service: environment.SERVICE_NAME ?? 'backend',
     instanceId: environment.INSTANCE_ID ?? 'local',
     env: environment.NODE_ENV ?? 'development',
-    message,
-    ...context,
-    ...(result ? { result } : {}),
-  };
+    message: sanitizeLogText(message).replaceAll('\r', '\\r').replaceAll('\n', '\\n'),
+    ...sanitizedContext,
+    ...(statusResult ? { result: statusResult } : {}),
+  } as LogEntry;
+  assertLogEntry(entry);
+  return entry;
 };
+
+const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+export class SecureLogWriter {
+  private currentHandle?: FileHandle;
+  private currentSize = 0;
+  private sequence = 0;
+  private previousHash: string | null = null;
+  private pending: Promise<void> = Promise.resolve();
+  private readonly chainId = randomUUID();
+  private readonly now: () => Date;
+
+  constructor(now: () => Date = () => new Date()) {
+    this.now = now;
+  }
+
+  write(entry: LogEntry): Promise<StoredLogEntry> {
+    let storedEntry: StoredLogEntry | undefined;
+    const operation = this.pending.then(async () => {
+      storedEntry = await this.writeNow(entry);
+    });
+    this.pending = operation;
+    return operation.then(() => storedEntry as StoredLogEntry);
+  }
+
+  async close(): Promise<void> {
+    await this.pending;
+    if (this.currentHandle) {
+      await this.currentHandle.close();
+      this.currentHandle = undefined;
+    }
+  }
+
+  private async writeNow(entry: LogEntry): Promise<StoredLogEntry> {
+    assertLogEntry(entry);
+    const sequence = this.sequence + 1;
+    const unsigned = { ...entry, chainId: this.chainId, sequence, previousHash: this.previousHash };
+    const entryHash = sha256(JSON.stringify(unsigned));
+    const storedEntry: StoredLogEntry = { ...unsigned, entryHash };
+    const serialized = `${JSON.stringify(storedEntry)}\n`;
+    const serializedBytes = Buffer.byteLength(serialized);
+
+    await this.ensureWritableFile(serializedBytes);
+    const handle = this.currentHandle;
+    if (!handle) throw new Error('Log file is not open after initialization');
+    await handle.appendFile(serialized, 'utf8');
+    this.currentSize += serializedBytes;
+    this.sequence = sequence;
+    this.previousHash = entryHash;
+    return storedEntry;
+  }
+
+  private async ensureWritableFile(nextEntryBytes: number): Promise<void> {
+    if (!this.currentHandle || this.currentSize + nextEntryBytes > MAX_LOG_FILE_SIZE_BYTES) {
+      if (this.currentHandle) await this.currentHandle.close();
+      this.currentHandle = undefined;
+      await mkdir(LOG_DIRECTORY, { recursive: true, mode: 0o700 });
+      await chmod(LOG_DIRECTORY, 0o700);
+      const date = this.now();
+      let collisionIndex = 0;
+      while (!this.currentHandle) {
+        const candidate = createLogFilePath(date, collisionIndex);
+        try {
+          this.currentHandle = await open(candidate, 'wx', 0o600);
+        } catch (error) {
+          if ((error as { code?: string }).code !== 'EEXIST') throw error;
+          collisionIndex += 1;
+        }
+      }
+      this.currentSize = 0;
+    }
+  }
+}

package/.well-known/skills/wdyy-logging-standard/templates/nestjs-http-logging.middleware.template.ts

@@ -0,0 +1,68 @@
+import { Inject, Injectable, type NestMiddleware } from '@nestjs/common';
+import type { NextFunction, Request, Response } from 'express';
+import {
+  BusinessFunctionCatalog,
+  createTraceContext,
+  requireSourceIp,
+  resolveActorContext,
+  SecureLogWriter,
+  toLogEntry,
+  type TraceContext,
+} from './logger';
+
+export const BUSINESS_FUNCTION_CATALOG = Symbol('BUSINESS_FUNCTION_CATALOG');
+
+type LoggedRequest = Request & {
+  traceContext?: TraceContext;
+  user?: { id?: string; type?: string };
+};
+
+@Injectable()
+export class HttpLoggingMiddleware implements NestMiddleware {
+  constructor(
+    private readonly writer: SecureLogWriter,
+    @Inject(BUSINESS_FUNCTION_CATALOG)
+    private readonly functionCatalog: BusinessFunctionCatalog,
+  ) {}
+
+  use(request: LoggedRequest, response: Response, next: NextFunction): void {
+    const incomingTraceParent = request.header('traceparent');
+    const trace = createTraceContext(incomingTraceParent);
+    request.traceContext = trace;
+    response.setHeader('traceparent', trace.traceparent);
+    response.setHeader('x-trace-id', trace.traceId);
+    const startedAt = performance.now();
+
+    response.once('finish', () => {
+      const routePath = request.route?.path;
+      const route = typeof routePath === 'string'
+        ? `${request.baseUrl}${routePath}`
+        : '';
+      const businessFunction = this.functionCatalog.resolve(request.method, route);
+      const actor = resolveActorContext(request.user);
+      const sourceIp = requireSourceIp(request.ip || request.socket.remoteAddress);
+      const entry = toLogEntry('info', 'http request completed', {
+        logType: 'access',
+        traceId: trace.traceId,
+        spanId: trace.spanId,
+        parentSpanId: trace.parentSpanId,
+        ...actor,
+        ...businessFunction,
+        method: request.method,
+        route,
+        sourceIp,
+        userAgent: request.header('user-agent'),
+        query: request.query as Record<string, unknown>,
+        body: request.body,
+        statusCode: response.statusCode,
+        durationMs: Math.max(0, performance.now() - startedAt),
+      });
+
+      this.writer.write(entry).catch((error: unknown) => {
+        queueMicrotask(() => { throw error; });
+      });
+    });
+
+    next();
+  }
+}

package/.well-known/skills/wdyy-logging-standard/templates/security-audit-logger.template.ts

@@ -0,0 +1,61 @@
+import { randomUUID } from 'node:crypto';
+import { SecureLogWriter, toLogEntry, type LogResult } from './logger';
+
+export const REQUIRED_SECURITY_EVENTS = [
+  'auth.login.success',
+  'auth.login.failure',
+  'auth.logout',
+  'account.locked',
+  'access.denied',
+  'input.rejected',
+] as const;
+
+export const REQUIRED_AUDIT_EVENTS = [
+  'account.changed',
+  'role.changed',
+  'permission.changed',
+  'configuration.changed',
+  'sensitive-data.read',
+  'sensitive-data.export',
+  'sensitive-data.delete',
+  'audit.configuration.changed',
+  'audit.log.accessed',
+  'audit.integrity.failed',
+] as const;
+
+export type SecurityAuditEvent = {
+  logType: 'security' | 'audit';
+  eventType: string;
+  actorId: string;
+  actorType: string;
+  action: string;
+  targetType: string;
+  targetId: string;
+  result: LogResult;
+  reason?: string;
+  traceId?: string;
+  sourceIp?: string;
+  route?: string;
+  functionCode?: string;
+  functionName?: string;
+  before?: unknown;
+  after?: unknown;
+};
+
+export class SecurityAuditLogger {
+  constructor(private readonly writer: SecureLogWriter) {}
+
+  async record(event: SecurityAuditEvent): Promise<void> {
+    const requestFields = ['traceId', 'sourceIp', 'route', 'functionCode', 'functionName'] as const;
+    const presentRequestFields = requestFields.filter((field) => event[field] !== undefined && event[field] !== '');
+    if (presentRequestFields.length > 0 && presentRequestFields.length !== requestFields.length) {
+      throw new Error('Request-triggered security and audit events require traceId, sourceIp, route, functionCode and functionName');
+    }
+    const entry = toLogEntry(
+      event.result === 'failure' ? 'warn' : 'info',
+      event.eventType,
+      { ...event, eventId: randomUUID() },
+    );
+    await this.writer.write(entry);
+  }
+}