mcp-server-framework 1.0.0

package/build/telemetry/tracing.js

@@ -0,0 +1,257 @@
+/**
+ * OpenTelemetry Tracing Utilities
+ *
+ * Provides convenient helpers for creating and managing spans.
+ * All OTEL imports are lazy-loaded (see DD-020). Synchronous functions
+ * gracefully no-op when the API hasn't been loaded yet.
+ *
+ * @module server/telemetry/tracing
+ */
+import { getTelemetryConfig, } from "./core/index.js";
+let otelApi = null;
+/**
+ * Lazily load and cache the @opentelemetry/api value exports.
+ * Called on every async path; returns instantly after first load.
+ */
+async function loadOtelApi() {
+    if (otelApi)
+        return otelApi;
+    const api = await import("@opentelemetry/api");
+    otelApi = {
+        trace: api.trace,
+        context: api.context,
+        SpanStatusCode: api.SpanStatusCode,
+        SpanKind: api.SpanKind,
+    };
+    return otelApi;
+}
+/**
+ * Synchronous access to the cached API. Returns null when the module
+ * hasn't been loaded yet — callers must handle the noop path.
+ */
+function getCachedOtelApi() {
+    return otelApi;
+}
+// ============================================================================
+// Framework-level SpanKind / SpanStatusCode constants
+// ============================================================================
+// These mirror the OTEL enum values so that consumers can import them from
+// the framework without triggering a static @opentelemetry/api import.
+// They are numeric-compatible with the OTEL enums.
+/** @public SpanKind constants — numeric-compatible with `@opentelemetry/api.SpanKind` */
+export const FrameworkSpanKind = {
+    INTERNAL: 0,
+    SERVER: 1,
+    CLIENT: 2,
+    PRODUCER: 3,
+    CONSUMER: 4,
+};
+/** @public SpanStatusCode constants — numeric-compatible with `@opentelemetry/api.SpanStatusCode` */
+export const FrameworkSpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+/**
+ * Get the tracer instance for the MCP Server.
+ * Returns a noop tracer proxy when the OTEL API hasn't been loaded yet.
+ */
+export function getTracer() {
+    const tracer = getTracerOrNull();
+    if (tracer)
+        return tracer;
+    // Return a minimal noop tracer when OTEL API isn't loaded yet.
+    // All methods are safe to call — spans are discarded.
+    return {
+        startSpan: () => noopSpan,
+        startActiveSpan: (_name, ...args) => {
+            // startActiveSpan has multiple overloads; the last arg is always the callback
+            const fn = args[args.length - 1];
+            return fn(noopSpan);
+        },
+        // @ts-limitation — object literal satisfies Tracer contract but TS cannot infer structural compatibility
+    };
+}
+/** Minimal noop span for the noop tracer fallback */
+const noopSpan = {
+    spanContext: () => ({ traceId: "", spanId: "", traceFlags: 0 }),
+    setAttribute: () => noopSpan,
+    setAttributes: () => noopSpan,
+    addEvent: () => noopSpan,
+    addLink: () => noopSpan,
+    addLinks: () => noopSpan,
+    setStatus: () => noopSpan,
+    updateName: () => noopSpan,
+    end: () => { },
+    isRecording: () => false,
+    recordException: () => { },
+    // @ts-limitation — object literal satisfies Span contract but TS cannot infer structural compatibility
+};
+/**
+ * Get the tracer instance for the MCP Server.
+ * Returns undefined when the OTEL API hasn't been loaded yet.
+ * @internal
+ */
+function getTracerOrNull() {
+    const api = getCachedOtelApi();
+    if (!api)
+        return undefined;
+    const config = getTelemetryConfig();
+    return api.trace.getTracer(config.serviceName, config.serviceVersion);
+}
+/**
+ * Get the tracer instance (async — loads OTEL API if needed).
+ */
+async function getTracerAsync() {
+    const api = await loadOtelApi();
+    const config = getTelemetryConfig();
+    return api.trace.getTracer(config.serviceName, config.serviceVersion);
+}
+/**
+ * Execute a function within a new span.
+ * Automatically handles errors and sets span status.
+ *
+ * @param name - Name of the span
+ * @param fn - Function to execute within the span
+ * @param options - Span options
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withSpan('processRequest', async (span) => {
+ *   span.setAttribute('request.id', requestId);
+ *   return await processRequest();
+ * });
+ * ```
+ */
+export async function withSpan(name, fn, options = {}) {
+    const api = await loadOtelApi();
+    const tracer = await getTracerAsync();
+    const parentContext = options.parentContext ?? api.context.active();
+    return tracer.startActiveSpan(name, {
+        kind: options.kind ?? api.SpanKind.INTERNAL,
+        ...(options.attributes !== undefined && {
+            attributes: options.attributes,
+        }),
+    }, parentContext, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: api.SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            // Record the error on the span
+            if (error instanceof Error) {
+                span.recordException(error);
+                span.setStatus({
+                    code: api.SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+            }
+            else {
+                span.setStatus({
+                    code: api.SpanStatusCode.ERROR,
+                    message: String(error),
+                });
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Execute a synchronous function within a new span.
+ *
+ * @param name - Name of the span
+ * @param fn - Function to execute within the span
+ * @param options - Span options
+ * @returns The result of the function
+ */
+export function withSpanSync(name, fn, options = {}) {
+    const api = getCachedOtelApi();
+    const tracer = getTracerOrNull();
+    // When OTEL hasn't been loaded yet, run fn without tracing
+    if (!api || !tracer) {
+        return fn(noopSpan);
+    }
+    const parentContext = options.parentContext ?? api.context.active();
+    const span = tracer.startSpan(name, {
+        kind: options.kind ?? api.SpanKind.INTERNAL,
+        ...(options.attributes !== undefined && {
+            attributes: options.attributes,
+        }),
+    }, parentContext);
+    try {
+        const ctx = api.trace.setSpan(parentContext, span);
+        const result = api.context.with(ctx, () => fn(span));
+        span.setStatus({ code: api.SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            span.recordException(error);
+            span.setStatus({
+                code: api.SpanStatusCode.ERROR,
+                message: error.message,
+            });
+        }
+        else {
+            span.setStatus({
+                code: api.SpanStatusCode.ERROR,
+                message: String(error),
+            });
+        }
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Get the currently active span.
+ * Returns undefined if no span is active or OTEL API is not loaded.
+ */
+export function getActiveSpan() {
+    const api = getCachedOtelApi();
+    if (!api)
+        return undefined;
+    return api.trace.getActiveSpan();
+}
+/**
+ * Add attributes to the active span.
+ * Does nothing if no span is active.
+ */
+export function addSpanAttributes(attributes) {
+    const span = getActiveSpan();
+    if (span) {
+        span.setAttributes(attributes);
+    }
+}
+/**
+ * Add an event to the active span.
+ * Does nothing if no span is active.
+ */
+export function addSpanEvent(name, attributes) {
+    const span = getActiveSpan();
+    if (span) {
+        span.addEvent(name, attributes);
+    }
+}
+/**
+ * Get the current trace context for propagation.
+ * Useful for passing context to external services.
+ */
+export function getTraceContext() {
+    const span = getActiveSpan();
+    if (!span) {
+        return undefined;
+    }
+    const spanContext = span.spanContext();
+    return {
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId,
+    };
+}
+//# sourceMappingURL=tracing.js.map

package/build/telemetry/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/telemetry/tracing.ts"],"names":[],"mappings":"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"}

package/build/utils/env-helpers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Environment Variable Helpers
+ *
+ * Utilities for parsing and handling environment variables.
+ *
+ * @module utils/env-helpers
+ */
+/**
+ * Parse an environment variable as a boolean.
+ *
+ * Environment variables are always strings, so this helper provides
+ * consistent boolean parsing across the codebase. Also handles
+ * the case where a boolean is passed through directly (e.g., from
+ * a pre-parsed config object).
+ *
+ * @param value - The environment variable value
+ * @returns true if value equals 'true' (case-insensitive) or is boolean true, false otherwise
+ *
+ * @example
+ * ```typescript
+ * parseEnvBoolean('true')   // true
+ * parseEnvBoolean('TRUE')   // true
+ * parseEnvBoolean('True')   // true
+ * parseEnvBoolean('false')  // false
+ * parseEnvBoolean('1')      // false
+ * parseEnvBoolean(undefined) // false
+ * parseEnvBoolean(true)     // true (passthrough)
+ * ```
+ */
+export declare function parseEnvBoolean(value: string | boolean | undefined): boolean;
+/**
+ * Get an environment variable with a default value.
+ *
+ * @param name - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns The environment variable value or default
+ */
+export declare function getEnvString(name: string, defaultValue: string): string;
+/**
+ * Get an optional environment variable.
+ *
+ * @param name - Environment variable name
+ * @returns The environment variable value or undefined
+ */
+export declare function getEnvOptional(name: string): string | undefined;
+//# sourceMappingURL=env-helpers.d.ts.map

package/build/utils/env-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/env-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAG5E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D"}

package/build/utils/env-helpers.js

@@ -0,0 +1,54 @@
+/**
+ * Environment Variable Helpers
+ *
+ * Utilities for parsing and handling environment variables.
+ *
+ * @module utils/env-helpers
+ */
+/**
+ * Parse an environment variable as a boolean.
+ *
+ * Environment variables are always strings, so this helper provides
+ * consistent boolean parsing across the codebase. Also handles
+ * the case where a boolean is passed through directly (e.g., from
+ * a pre-parsed config object).
+ *
+ * @param value - The environment variable value
+ * @returns true if value equals 'true' (case-insensitive) or is boolean true, false otherwise
+ *
+ * @example
+ * ```typescript
+ * parseEnvBoolean('true')   // true
+ * parseEnvBoolean('TRUE')   // true
+ * parseEnvBoolean('True')   // true
+ * parseEnvBoolean('false')  // false
+ * parseEnvBoolean('1')      // false
+ * parseEnvBoolean(undefined) // false
+ * parseEnvBoolean(true)     // true (passthrough)
+ * ```
+ */
+export function parseEnvBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    return value?.toLowerCase() === "true";
+}
+/**
+ * Get an environment variable with a default value.
+ *
+ * @param name - Environment variable name
+ * @param defaultValue - Default value if not set
+ * @returns The environment variable value or default
+ */
+export function getEnvString(name, defaultValue) {
+    return process.env[name] || defaultValue;
+}
+/**
+ * Get an optional environment variable.
+ *
+ * @param name - Environment variable name
+ * @returns The environment variable value or undefined
+ */
+export function getEnvOptional(name) {
+    return process.env[name];
+}
+//# sourceMappingURL=env-helpers.js.map

package/build/utils/env-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-helpers.js","sourceRoot":"","sources":["../../src/utils/env-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmC;IACjE,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,MAAM,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,YAAoB;IAC7D,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/build/utils/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Server Framework Utilities
+ *
+ * Generic utilities for the MCP server framework.
+ * Re-exports shared utilities from the main utils module.
+ *
+ * @module utils
+ */
+export { parseEnvBoolean, getEnvString, getEnvOptional } from "./env-helpers.js";
+export { validateName, validateNonEmptyString, validateFunction, validateZodSchema, validateObject, validateEnum, validateDefinitionBase, } from "./validation.js";
+export { isSensitiveKey, SENSITIVE_KEYS, SENSITIVE_KEY_BLOCKLIST } from "./sensitive-keys.js";
+export { splitCommaSeparated, interpolate, type MessageParams, truncateId, isLocalHost, parseByteSize, BYTE_SIZE_REGEX, } from "./string-helpers.js";
+export { booleanFromEnv, commaSeparatedList, optionalCommaSeparatedList, byteSizeSchema } from "./zod-helpers.js";
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAG9F,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,KAAK,aAAa,EAClB,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/build/utils/index.js

@@ -0,0 +1,19 @@
+/**
+ * Server Framework Utilities
+ *
+ * Generic utilities for the MCP server framework.
+ * Re-exports shared utilities from the main utils module.
+ *
+ * @module utils
+ */
+// Re-export shared env helpers from main utils
+export { parseEnvBoolean, getEnvString, getEnvOptional } from "./env-helpers.js";
+// Re-export validation helpers
+export { validateName, validateNonEmptyString, validateFunction, validateZodSchema, validateObject, validateEnum, validateDefinitionBase, } from "./validation.js";
+// Re-export sensitive key detection
+export { isSensitiveKey, SENSITIVE_KEYS, SENSITIVE_KEY_BLOCKLIST } from "./sensitive-keys.js";
+// Re-export string helpers
+export { splitCommaSeparated, interpolate, truncateId, isLocalHost, parseByteSize, BYTE_SIZE_REGEX, } from "./string-helpers.js";
+// Re-export Zod schema helpers
+export { booleanFromEnv, commaSeparatedList, optionalCommaSeparatedList, byteSizeSchema } from "./zod-helpers.js";
+//# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+CAA+C;AAC/C,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEjF,+BAA+B;AAC/B,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9F,2BAA2B;AAC3B,OAAO,EACL,mBAAmB,EACnB,WAAW,EAEX,UAAU,EACV,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,+BAA+B;AAC/B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/build/utils/sensitive-keys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sensitive Key Detection
+ *
+ * Shared utility for detecting sensitive field names across the framework.
+ * Used by both the error serializer and the logger scrubber to ensure
+ * consistent redaction behavior.
+ *
+ * Uses a segment-based algorithm with a blocklist to minimize false positives:
+ * - "password" → sensitive
+ * - "keyboard" → NOT sensitive (blocklisted)
+ * - "monkey_password" → sensitive ("password" segment is genuinely sensitive)
+ *
+ * @module utils/sensitive-keys
+ */
+/**
+ * Keys that are considered sensitive and should be redacted.
+ * Includes common authentication and security-related terms.
+ */
+export declare const SENSITIVE_KEYS: readonly ["password", "passwd", "apiKey", "api_key", "apiSecret", "api_secret", "token", "secret", "authorization", "auth_token", "access_token", "refresh_token", "id_token", "jwt", "bearer", "private_key", "privateKey", "secret_key", "secretKey", "passphrase", "key", "credential", "sessionSecret", "session_secret", "sessionToken", "session_token", "oauth_token", "oauth_secret", "oauth_code", "client_secret", "clientSecret"];
+/**
+ * Words that should NOT trigger sensitive key detection even if they
+ * contain sensitive key patterns. Prevents false positives.
+ */
+export declare const SENSITIVE_KEY_BLOCKLIST: readonly ["tokenizer", "tokenize", "tokenization", "keyboard", "keyframe", "keynote", "monkey", "passthrough", "passenger", "passage"];
+/**
+ * Check if a field/key name is sensitive and should be redacted.
+ *
+ * Algorithm (4 steps):
+ * 1. Check if the key contains any sensitive pattern (substring match)
+ * 2. If the entire key is an exact blocklist word → not sensitive
+ * 3. For compound keys (segments): only sensitive if at least one segment
+ *    is genuinely sensitive (not fully explained by blocklist)
+ * 4. Single-segment keys: check blocklist patterns
+ *
+ * @param key - The field name to check
+ * @returns true if the key should be redacted
+ *
+ * @example
+ * ```typescript
+ * isSensitiveKey('password')         // true
+ * isSensitiveKey('api_key')          // true
+ * isSensitiveKey('keyboard')         // false (blocklisted)
+ * isSensitiveKey('monkey')           // false (blocklisted)
+ * isSensitiveKey('monkey_password')  // true  ("password" is genuine)
+ * ```
+ */
+export declare function isSensitiveKey(key: string): boolean;
+//# sourceMappingURL=sensitive-keys.d.ts.map

package/build/utils/sensitive-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-keys.d.ts","sourceRoot":"","sources":["../../src/utils/sensitive-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;GAGG;AACH,eAAO,MAAM,cAAc,8aAgCjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,uBAAuB,wIAW1B,CAAC;AAsBX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA2BnD"}

package/build/utils/sensitive-keys.js

@@ -0,0 +1,131 @@
+/**
+ * Sensitive Key Detection
+ *
+ * Shared utility for detecting sensitive field names across the framework.
+ * Used by both the error serializer and the logger scrubber to ensure
+ * consistent redaction behavior.
+ *
+ * Uses a segment-based algorithm with a blocklist to minimize false positives:
+ * - "password" → sensitive
+ * - "keyboard" → NOT sensitive (blocklisted)
+ * - "monkey_password" → sensitive ("password" segment is genuinely sensitive)
+ *
+ * @module utils/sensitive-keys
+ */
+// ============================================================================
+// Sensitive Key Lists
+// ============================================================================
+/**
+ * Keys that are considered sensitive and should be redacted.
+ * Includes common authentication and security-related terms.
+ */
+export const SENSITIVE_KEYS = [
+    "password",
+    "passwd",
+    "apiKey",
+    "api_key",
+    "apiSecret",
+    "api_secret",
+    "token",
+    "secret",
+    "authorization",
+    "auth_token",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "jwt",
+    "bearer",
+    "private_key",
+    "privateKey",
+    "secret_key",
+    "secretKey",
+    "passphrase",
+    "key",
+    "credential",
+    "sessionSecret",
+    "session_secret",
+    "sessionToken",
+    "session_token",
+    "oauth_token",
+    "oauth_secret",
+    "oauth_code",
+    "client_secret",
+    "clientSecret",
+];
+/**
+ * Words that should NOT trigger sensitive key detection even if they
+ * contain sensitive key patterns. Prevents false positives.
+ */
+export const SENSITIVE_KEY_BLOCKLIST = [
+    "tokenizer",
+    "tokenize",
+    "tokenization",
+    "keyboard",
+    "keyframe",
+    "keynote",
+    "monkey",
+    "passthrough",
+    "passenger",
+    "passage",
+];
+// ============================================================================
+// Separator & Blocklist Pattern Cache
+// ============================================================================
+/** Separator pattern for splitting compound keys into segments */
+const SEGMENT_SEPARATORS = /[_\-.\s]+/;
+/** Pre-compiled blocklist patterns for word-boundary matching */
+const BLOCKLIST_PATTERNS = SENSITIVE_KEY_BLOCKLIST.map((word) => new RegExp(`(?:^|[_\\-.\\s])${escapeRegex(word.toLowerCase())}(?:$|[_\\-.\\s])`, "i"));
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Check if a field/key name is sensitive and should be redacted.
+ *
+ * Algorithm (4 steps):
+ * 1. Check if the key contains any sensitive pattern (substring match)
+ * 2. If the entire key is an exact blocklist word → not sensitive
+ * 3. For compound keys (segments): only sensitive if at least one segment
+ *    is genuinely sensitive (not fully explained by blocklist)
+ * 4. Single-segment keys: check blocklist patterns
+ *
+ * @param key - The field name to check
+ * @returns true if the key should be redacted
+ *
+ * @example
+ * ```typescript
+ * isSensitiveKey('password')         // true
+ * isSensitiveKey('api_key')          // true
+ * isSensitiveKey('keyboard')         // false (blocklisted)
+ * isSensitiveKey('monkey')           // false (blocklisted)
+ * isSensitiveKey('monkey_password')  // true  ("password" is genuine)
+ * ```
+ */
+export function isSensitiveKey(key) {
+    const lowerKey = key.toLowerCase();
+    // Step 1: Check if the key matches any sensitive pattern
+    const hasSensitiveMatch = SENSITIVE_KEYS.some((sensitiveKey) => lowerKey.includes(sensitiveKey.toLowerCase()));
+    if (!hasSensitiveMatch)
+        return false;
+    // Step 2: Exact blocklist match exemption
+    for (const blocked of SENSITIVE_KEY_BLOCKLIST) {
+        if (lowerKey === blocked.toLowerCase())
+            return false;
+    }
+    // Step 3: Compound key analysis
+    const segments = lowerKey.split(SEGMENT_SEPARATORS).filter(Boolean);
+    if (segments.length > 1) {
+        return segments.some((segment) => {
+            const isSensitive = SENSITIVE_KEYS.some((sk) => segment.includes(sk.toLowerCase()));
+            if (!isSensitive)
+                return false;
+            const isBlocked = SENSITIVE_KEY_BLOCKLIST.some((blocked) => segment === blocked.toLowerCase());
+            return isSensitive && !isBlocked;
+        });
+    }
+    // Step 4: Single segment — check blocklist patterns
+    return !BLOCKLIST_PATTERNS.some((pattern) => pattern.test(lowerKey));
+}
+//# sourceMappingURL=sensitive-keys.js.map

package/build/utils/sensitive-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-keys.js","sourceRoot":"","sources":["../../src/utils/sensitive-keys.ts"],"names":[],"mappings":"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"}