/** * Structured, single-line JSON logging with defensive redaction. * * Two invariants hold for everything in this module: * 1. Secrets never reach the sink: credential-looking keys, URL query * parameters, JSON string fields and Bearer/Basic headers are redacted at * any nesting depth. * 2. Logging never throws. A hostile `meta` object (throwing getter, proxy, * BigInt, circular graph, throwing `toJSON`) must not be able to break a * request or a WebSocket frame handler. */ export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent' export const LOG_LEVEL_SEVERITY: Record = { debug: 10, info: 20, warn: 30, error: 40, silent: 50, } /** Normalized (lowercase, separators stripped) key suffixes treated as secret. */ export const SENSITIVE_KEYS: readonly string[] = [ 'accesstoken', 'refreshtoken', 'token', 'password', 'passwd', 'secret', 'sdp', 'ciphertext', 'authorization', 'cookie', 'apikey', ] export function isSensitiveKey(key: string): boolean { if (typeof key !== 'string' || key === '') return false const normalized = key.toLowerCase().replace(/[-_\s]/g, '') return SENSITIVE_KEYS.some(sensitive => normalized === sensitive || normalized.endsWith(sensitive)) } const REDACTED = '[REDACTED]' const CIRCULAR = '[CIRCULAR]' const DEPTH_LIMIT = '[DEPTH_LIMIT]' const UNSERIALIZABLE = '[UNSERIALIZABLE]' const MAX_DEPTH = 8 // Key vocabulary shared by every string pattern below: snake_case, kebab-case // and camelCase spellings all match, while substrings of longer identifiers // ("tokens", "mytokenizer") do not. const KEY_VOCABULARY = 'access[_-]?token|refresh[_-]?token|token|password|passwd|secret|sdp|ciphertext|authorization|cookie|api[_-]?key' const KEY_START = '(?(read: () => T, fallback: T): T { try { const value = read() return value === undefined || value === null ? fallback : value } catch { return fallback } } /** * Deep-copy `data` with secrets replaced. Never throws: unserializable input * degrades to the `[UNSERIALIZABLE]` marker instead of propagating. */ export function redactSensitive(data: unknown, seen: WeakSet = new WeakSet(), depth = 0): unknown { try { if (data === null || data === undefined) return data switch (typeof data) { case 'string': return redactString(data) case 'number': return Number.isFinite(data) ? data : String(data) case 'boolean': return data case 'bigint': return data.toString() case 'symbol': return data.toString() case 'function': return '[FUNCTION]' default: break } if (depth >= MAX_DEPTH) return DEPTH_LIMIT const object = data as object if (seen.has(object)) return CIRCULAR seen.add(object) if (Array.isArray(object)) { return object.map(item => redactSensitive(item, seen, depth + 1)) } if (object instanceof Error) { const name = readSafely(() => (typeof object.name === 'string' ? object.name : 'Error'), 'Error') const message = readSafely(() => redactString(typeof object.message === 'string' ? object.message : ''), '') const stack = readSafely(() => (typeof object.stack === 'string' ? redactString(object.stack) : undefined), undefined) return { name, message, ...(stack ? { stack } : {}) } } const result: Record = {} // Enumerate keys first (no getter runs), then read each value through a // guard: a throwing getter degrades that one field instead of the entry. for (const key of Object.keys(object)) { if (isSensitiveKey(key)) { // Never touch the value of a secret field, not even to copy it. result[key] = REDACTED continue } const value = readSafely(() => (object as Record)[key], UNSERIALIZABLE) result[key] = redactSensitive(value, seen, depth + 1) } return result } catch { return UNSERIALIZABLE } } export interface LogEntry { ts: string level: LogLevel scope: string event: string meta: Record } export type LogSink = (line: string, entry: LogEntry) => void const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9:_.-]*$/ /** Event names and scopes are controlled constants; reject anything else. */ function safeLabel(value: unknown, fallback: string): string { if (typeof value !== 'string' || value.length === 0 || value.length > 80 || !LABEL_PATTERN.test(value)) return fallback return value } function isLogLevel(value: unknown): value is LogLevel { return typeof value === 'string' && Object.prototype.hasOwnProperty.call(LOG_LEVEL_SEVERITY, value) } function severityOf(level: string): number { return isLogLevel(level) ? LOG_LEVEL_SEVERITY[level] : LOG_LEVEL_SEVERITY.info } export class Logger { readonly scope: string readonly level: LogLevel private readonly sink?: LogSink constructor(scope: string = 'server', level: LogLevel = 'info', sink?: LogSink) { this.scope = safeLabel(scope, 'server') this.level = isLogLevel(level) ? level : 'info' this.sink = sink } child(subScope: string): Logger { return new Logger(`${this.scope}:${safeLabel(subScope, 'child')}`, this.level, this.sink) } debug(event: string, meta?: Record): void { this.log('debug', event, meta) } info(event: string, meta?: Record): void { this.log('info', event, meta) } warn(event: string, meta?: Record): void { this.log('warn', event, meta) } error(event: string, meta?: Record): void { this.log('error', event, meta) } private buildEntry(level: LogLevel, event: unknown, meta: unknown): LogEntry { const ts = new Date().toISOString() let cleanMeta: Record = {} try { const redacted = meta === undefined ? {} : redactSensitive(meta) cleanMeta = redacted !== null && typeof redacted === 'object' && !Array.isArray(redacted) ? redacted as Record : { value: redacted } } catch { cleanMeta = { redactionFailed: true } } return { ts, level, scope: this.scope, event: safeLabel(event, 'invalid_event'), meta: cleanMeta } } private log(level: LogLevel, event: unknown, meta?: unknown): void { try { if (severityOf(level) < severityOf(this.level)) return const entry = this.buildEntry(level, event, meta) let line = '' try { const serialized = JSON.stringify(entry) if (typeof serialized !== 'string') throw new TypeError('log entry is not serializable') line = serialized } catch { // Fixed, self-describing shape: no attacker-controlled content at all. line = JSON.stringify({ ts: new Date().toISOString(), level, scope: this.scope, event: safeLabel(event, 'invalid_event'), meta: { serializationFailed: true }, }) } if (this.sink) { try { this.sink(line, entry) } catch { /* a broken sink must not break the caller */ } return } if (level === 'error') console.error(line) else if (level === 'warn') console.warn(line) else console.info(line) } catch { // Logging is best-effort: it must never alter control flow. } } } export function parseLogLevel(val: string | undefined, fallback: LogLevel = 'info'): LogLevel { const effectiveFallback = isLogLevel(fallback) ? fallback : 'info' if (typeof val !== 'string' || val.trim() === '') return effectiveFallback const normalized = val.trim().toLowerCase() // hasOwnProperty guards against prototype members ('constructor', '__proto__', // 'toString') being accepted as log levels. if (Object.prototype.hasOwnProperty.call(LOG_LEVEL_SEVERITY, normalized)) return normalized as LogLevel console.warn(`[config] Invalid DSH_SERVER_LOG_LEVEL. Must be one of ${Object.keys(LOG_LEVEL_SEVERITY).join(', ')}. Falling back to ${effectiveFallback}.`) return effectiveFallback }