@superblocksteam/telemetry 2.0.83-next.1

package/dist-esm/common/log-sanitizer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Log Sanitizer for Application-Level Secret Protection
+ *
+ * Sanitizes secrets from log messages while preserving debugging information.
+ * This operates at the APPLICATION layer and only removes secrets that should
+ * NEVER appear in any log, anywhere.
+ *
+ * ARCHITECTURE:
+ * - Application layer (this file): Secrets-only sanitization (unconditional)
+ * - Pipeline layer (OTel Collector): Tier-based filtering for export
+ *
+ * Stack traces, emails, file paths are preserved for debugging. The pipeline
+ * layer handles redacting these for Tier 2 export in cloud-prem deployments.
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+/**
+ * Fields that contain secrets and should be stripped from log objects.
+ * Only includes actual secret field names - NOT debugging info.
+ *
+ * Pipeline-layer concerns (AI content, stack traces, PII) are NOT included here.
+ * Those are handled by the OTel Collector for tier-based export filtering.
+ */
+export declare const SECRET_FIELDS: Set<string>;
+/**
+ * Check if a field name contains secrets using word boundary matching.
+ */
+export declare function isSecretField(fieldName: string): boolean;
+/**
+ * @deprecated Use SECRET_FIELDS instead. This export is kept for backward
+ * compatibility but now only contains secret fields, not Tier 1 content fields.
+ */
+export declare const TIER1_FORBIDDEN_LOG_FIELDS: Set<string>;
+/**
+ * Sanitizes secrets from a log message string.
+ * Preserves debugging info (emails, file paths, etc.) for troubleshooting.
+ *
+ * @param message - The log message to sanitize
+ * @returns Message with secrets redacted
+ */
+export declare function sanitizeLogMessage(message: string): string;
+/**
+ * Sanitizes secrets within a stack trace while preserving the full trace.
+ * Stack traces are essential for debugging - only redact secrets within them.
+ *
+ * @param stack - The stack trace string
+ * @returns Stack trace with secrets redacted but structure preserved
+ */
+export declare function redactStackTrace(stack: string): string;
+/**
+ * Recursively sanitizes secrets from an object.
+ * Strips secret fields entirely, sanitizes secrets in string values.
+ * Preserves debugging info (stack traces, file paths, emails).
+ *
+ * @param obj - The object to sanitize
+ * @param depth - Current recursion depth (default: 0)
+ * @returns Object with secrets removed
+ */
+export declare function sanitizeLogObject<T>(obj: T, depth?: number): T;
+/**
+ * Sanitizes secrets from an error object.
+ * Preserves full stack traces for debugging.
+ *
+ * @param error - The error to sanitize
+ * @returns Error object with secrets redacted
+ */
+export declare function sanitizeLogError(error: unknown): unknown;
+/**
+ * Safe JSON stringify with secret sanitization.
+ * Handles circular references and non-serializable types.
+ * Preserves debugging info (stack traces, file paths, emails).
+ *
+ * @param obj - Object to stringify
+ * @param space - Indentation (optional)
+ * @returns JSON string with secrets redacted
+ */
+export declare function safeJsonStringify(obj: unknown, space?: string | number): string;
+//# sourceMappingURL=log-sanitizer.d.ts.map

package/dist-esm/common/log-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-sanitizer.d.ts","sourceRoot":"","sources":["../../src/common/log-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmFH;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,aAqBxB,CAAC;AA+BH;;GAEG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAMxD;AAMD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,aAAgB,CAAC;AAMxD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,SAAI,GAAG,CAAC,CAyCzD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAsCxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,CA6DR"}

package/dist-esm/common/log-sanitizer.js

@@ -0,0 +1,331 @@
+/**
+ * Log Sanitizer for Application-Level Secret Protection
+ *
+ * Sanitizes secrets from log messages while preserving debugging information.
+ * This operates at the APPLICATION layer and only removes secrets that should
+ * NEVER appear in any log, anywhere.
+ *
+ * ARCHITECTURE:
+ * - Application layer (this file): Secrets-only sanitization (unconditional)
+ * - Pipeline layer (OTel Collector): Tier-based filtering for export
+ *
+ * Stack traces, emails, file paths are preserved for debugging. The pipeline
+ * layer handles redacting these for Tier 2 export in cloud-prem deployments.
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+// ============================================================================
+// Secret Patterns - These should NEVER appear in any log
+// ============================================================================
+/**
+ * Patterns that indicate tokens, keys, and secrets in log messages.
+ * These use capture groups to preserve prefixes while redacting values.
+ */
+const SECRET_PATTERNS = [
+    // Tokens and keys with prefixes
+    {
+        pattern: /(\bbearer\s+)[a-zA-Z0-9\-._~+/]+=*/gi,
+        replacement: "$1[REDACTED]",
+    },
+    { pattern: /(\bbasic\s+)\S+/gi, replacement: "$1[REDACTED]" },
+    { pattern: /(\bjwt\s+)[a-zA-Z0-9\-._~+/]+=*/gi, replacement: "$1[REDACTED]" },
+    {
+        pattern: /(\btoken[:\s=]+)[a-zA-Z0-9\-._~+/]+=*/gi,
+        replacement: "$1[REDACTED]",
+    },
+    {
+        pattern: /(\bapi[_\s]?key[:\s=]+)[a-zA-Z0-9\-._~+/]+=*/gi,
+        replacement: "$1[REDACTED]",
+    },
+    {
+        pattern: /(\baccess[_\s]?token[:\s=]+)[a-zA-Z0-9\-._~+/]+=*/gi,
+        replacement: "$1[REDACTED]",
+    },
+    {
+        pattern: /(\brefresh[_\s]?token[:\s=]+)[a-zA-Z0-9\-._~+/]+=*/gi,
+        replacement: "$1[REDACTED]",
+    },
+    // JWT pattern (base64.base64.base64) - standalone tokens
+    {
+        pattern: /\b[A-Za-z0-9-_]{20,}\.[A-Za-z0-9-_]{20,}\.[A-Za-z0-9-_]{20,}\b/g,
+        replacement: "[JWT_REDACTED]",
+    },
+    // OpenAI API keys
+    { pattern: /\bsk-[A-Za-z0-9]{48}\b/g, replacement: "[OPENAI_KEY_REDACTED]" },
+    // Anthropic API keys
+    {
+        pattern: /\bsk-ant-[A-Za-z0-9-]{32,}\b/g,
+        replacement: "[ANTHROPIC_KEY_REDACTED]",
+    },
+    // AWS access key IDs
+    { pattern: /\bAKIA[A-Z0-9]{16}\b/g, replacement: "[AWS_KEY_REDACTED]" },
+    // GitHub tokens
+    {
+        pattern: /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/g,
+        replacement: "[GITHUB_TOKEN_REDACTED]",
+    },
+    // Generic API key patterns
+    {
+        pattern: /\b(sk|pk)-[a-zA-Z0-9]{32,}\b/g,
+        replacement: "[API_KEY_REDACTED]",
+    },
+    // Connection strings with credentials
+    {
+        pattern: /\b(postgres|mysql|mongodb|redis):\/\/[^\s]+:[^\s]+@[^\s]+/gi,
+        replacement: "[CONNECTION_STRING_REDACTED]",
+    },
+    // PEM blocks
+    {
+        pattern: /-----BEGIN\s+(RSA\s+)?(PRIVATE|PUBLIC)\s+KEY-----[\s\S]*?-----END\s+(RSA\s+)?(PRIVATE|PUBLIC)\s+KEY-----/g,
+        replacement: "[PEM_KEY_REDACTED]",
+    },
+];
+// ============================================================================
+// Secret Fields - Field names that contain secrets
+// ============================================================================
+/**
+ * Fields that contain secrets and should be stripped from log objects.
+ * Only includes actual secret field names - NOT debugging info.
+ *
+ * Pipeline-layer concerns (AI content, stack traces, PII) are NOT included here.
+ * Those are handled by the OTel Collector for tier-based export filtering.
+ */
+export const SECRET_FIELDS = new Set([
+    // Auth/secrets
+    "password",
+    "passwd",
+    "secret",
+    "private_key",
+    "privatekey",
+    "credentials",
+    "token",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "jwt",
+    "bearer",
+    "apikey",
+    "api_key",
+    "auth_token",
+    "authorization",
+    "cookie",
+    "x-api-key",
+]);
+/**
+ * Patterns for compound field names that contain secrets.
+ * Uses word boundary matching to avoid false positives.
+ */
+const SECRET_FIELD_PATTERNS = [
+    // Password patterns
+    /(?:^|[._-])password(?:[._-]|$)/i,
+    /(?:^|[._-])passwd(?:[._-]|$)/i,
+    // Secret patterns
+    /(?:^|[._-])secret(?:[._-]|$)/i,
+    /(?:^|[._-])private[._-]?key(?:[._-]|$)/i,
+    // Token patterns
+    /(?:^|[._-])token(?:[._-]|$)/i,
+    /(?:^|[._-])jwt(?:[._-]|$)/i,
+    /(?:^|[._-])bearer(?:[._-]|$)/i,
+    // Credential patterns
+    /(?:^|[._-])credentials?(?:[._-]|$)/i,
+    // API key patterns
+    /api[._-]?key/i,
+    /x[._-]api[._-]key/i,
+    // Auth token patterns
+    /auth[._-]token/i,
+];
+/**
+ * Check if a field name contains secrets using word boundary matching.
+ */
+export function isSecretField(fieldName) {
+    const lowerKey = fieldName.toLowerCase();
+    if (SECRET_FIELDS.has(lowerKey)) {
+        return true;
+    }
+    return SECRET_FIELD_PATTERNS.some((pattern) => pattern.test(lowerKey));
+}
+// ============================================================================
+// Legacy exports for backward compatibility
+// ============================================================================
+/**
+ * @deprecated Use SECRET_FIELDS instead. This export is kept for backward
+ * compatibility but now only contains secret fields, not Tier 1 content fields.
+ */
+export const TIER1_FORBIDDEN_LOG_FIELDS = SECRET_FIELDS;
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Sanitizes secrets from a log message string.
+ * Preserves debugging info (emails, file paths, etc.) for troubleshooting.
+ *
+ * @param message - The log message to sanitize
+ * @returns Message with secrets redacted
+ */
+export function sanitizeLogMessage(message) {
+    if (!message || typeof message !== "string") {
+        return message;
+    }
+    let sanitized = message;
+    // Only apply secret patterns - preserve debugging info
+    for (const { pattern, replacement } of SECRET_PATTERNS) {
+        pattern.lastIndex = 0; // Reset regex state for global patterns
+        sanitized = sanitized.replace(pattern, replacement);
+    }
+    return sanitized;
+}
+/**
+ * Sanitizes secrets within a stack trace while preserving the full trace.
+ * Stack traces are essential for debugging - only redact secrets within them.
+ *
+ * @param stack - The stack trace string
+ * @returns Stack trace with secrets redacted but structure preserved
+ */
+export function redactStackTrace(stack) {
+    if (!stack || typeof stack !== "string") {
+        return stack;
+    }
+    // Preserve full stack trace, only sanitize secrets within
+    return sanitizeLogMessage(stack);
+}
+/**
+ * Recursively sanitizes secrets from an object.
+ * Strips secret fields entirely, sanitizes secrets in string values.
+ * Preserves debugging info (stack traces, file paths, emails).
+ *
+ * @param obj - The object to sanitize
+ * @param depth - Current recursion depth (default: 0)
+ * @returns Object with secrets removed
+ */
+export function sanitizeLogObject(obj, depth = 0) {
+    // Prevent infinite recursion
+    if (depth > 10) {
+        return "[MAX_DEPTH_REACHED]";
+    }
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === "string") {
+        return sanitizeLogMessage(obj);
+    }
+    if (typeof obj === "number" || typeof obj === "boolean") {
+        return obj;
+    }
+    if (typeof obj !== "object") {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => sanitizeLogObject(item, depth + 1));
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(obj)) {
+        // Skip secret fields entirely
+        if (isSecretField(key)) {
+            continue;
+        }
+        // Recursively sanitize all other fields
+        sanitized[key] = sanitizeLogObject(value, depth + 1);
+    }
+    return sanitized;
+}
+/**
+ * Sanitizes secrets from an error object.
+ * Preserves full stack traces for debugging.
+ *
+ * @param error - The error to sanitize
+ * @returns Error object with secrets redacted
+ */
+export function sanitizeLogError(error) {
+    if (!error) {
+        return error;
+    }
+    // Check if already sanitized
+    const errorWithSanitized = error;
+    if (errorWithSanitized._sanitized) {
+        return error;
+    }
+    if (error instanceof Error) {
+        const sanitized = {
+            name: error.name,
+            message: sanitizeLogMessage(error.message),
+            // Preserve full stack trace, only sanitize secrets within
+            stack: sanitizeLogMessage(error.stack || ""),
+            _sanitized: true,
+        };
+        // Copy and sanitize enumerable properties
+        for (const [key, value] of Object.entries(error)) {
+            if (key !== "name" && key !== "message" && key !== "stack") {
+                // Skip secret fields
+                if (isSecretField(key)) {
+                    continue;
+                }
+                sanitized[key] = sanitizeLogObject(value);
+            }
+        }
+        return sanitized;
+    }
+    // For non-Error objects, sanitize the entire object
+    const sanitized = sanitizeLogObject(error);
+    sanitized._sanitized = true;
+    return sanitized;
+}
+/**
+ * Safe JSON stringify with secret sanitization.
+ * Handles circular references and non-serializable types.
+ * Preserves debugging info (stack traces, file paths, emails).
+ *
+ * @param obj - Object to stringify
+ * @param space - Indentation (optional)
+ * @returns JSON string with secrets redacted
+ */
+export function safeJsonStringify(obj, space) {
+    if (obj === null || obj === undefined) {
+        return "{}";
+    }
+    if (typeof obj === "string") {
+        return sanitizeLogMessage(obj);
+    }
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (key, value) => {
+        // Skip secret fields
+        if (key && isSecretField(key)) {
+            return undefined;
+        }
+        // Handle null/undefined
+        if (value === null || value === undefined) {
+            return value;
+        }
+        // Handle circular references
+        if (typeof value === "object") {
+            if (seen.has(value)) {
+                return "[Circular Reference]";
+            }
+            seen.add(value);
+            // Handle Error objects - preserve full stack trace
+            if (value instanceof Error) {
+                return {
+                    name: value.name,
+                    message: sanitizeLogMessage(value.message),
+                    stack: sanitizeLogMessage(value.stack || ""),
+                };
+            }
+        }
+        // Sanitize string values
+        if (typeof value === "string") {
+            return sanitizeLogMessage(value);
+        }
+        // Handle non-serializable types
+        if (typeof value === "function") {
+            return `[Function: ${value.name || "anonymous"}]`;
+        }
+        if (typeof value === "symbol") {
+            return `[Symbol: ${value.toString()}]`;
+        }
+        if (typeof value === "bigint") {
+            return `[BigInt: ${value.toString()}]`;
+        }
+        return value;
+    }, space);
+}
+//# sourceMappingURL=log-sanitizer.js.map

package/dist-esm/common/log-sanitizer.js.map

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

package/dist-esm/common/policy-evaluator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Policy Evaluator
+ *
+ * Evaluates telemetry routing decisions based on policy configuration.
+ */
+import { TelemetryPolicy, TelemetryTier } from "../types/policy.js";
+/**
+ * Result of a policy evaluation.
+ */
+export interface PolicyDecision {
+    /** Should this data be retained locally? */
+    retainLocal: boolean;
+    /** Should this data be exported? */
+    export: boolean;
+    /** Sampling decision */
+    sampled: boolean;
+    /** If blocked, the reason */
+    blockReason?: string;
+}
+/**
+ * Evaluator for telemetry policy decisions.
+ *
+ * IMPORTANT: This evaluator determines ROUTING eligibility, not trace sampling.
+ *
+ * For TRACES: Sampling must be handled by the OTel SDK Sampler (parent-based,
+ * trace-ID ratio) to ensure trace consistency.
+ *
+ * For METRICS/LOGS: sampleRate applies with deterministic trace-ID-based logic.
+ */
+export declare class TelemetryPolicyEvaluator {
+    private readonly policy;
+    constructor(policy: TelemetryPolicy);
+    /**
+     * Get the current policy.
+     */
+    getPolicy(): TelemetryPolicy;
+    /**
+     * Evaluate whether a telemetry signal should be processed/exported.
+     *
+     * @param tier - The tier this signal belongs to
+     * @param orgId - Optional org ID for org-specific overrides
+     * @param traceId - Optional trace ID for deterministic sampling
+     * @returns PolicyDecision
+     */
+    evaluate(tier: TelemetryTier, orgId?: string, traceId?: string): PolicyDecision;
+    /**
+     * Check if export infrastructure should be created for a tier.
+     *
+     * This checks ONLY whether export is enabled in policy configuration.
+     * It does NOT apply sampling - use this for SDK initialization decisions.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @returns true if export infrastructure should be created
+     */
+    isExportEnabled(tier: TelemetryTier, orgId?: string): boolean;
+    /**
+     * Check if an export attempt is allowed (includes sampling).
+     *
+     * This applies sampling logic and should be used for per-span/per-signal
+     * decisions at runtime, NOT for infrastructure initialization.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @param traceId - Optional trace ID for deterministic sampling
+     * @returns true if export is allowed for this specific signal
+     */
+    canExport(tier: TelemetryTier, orgId?: string, traceId?: string): boolean;
+    /**
+     * Assert export is allowed, throwing or logging based on enforcement mode.
+     *
+     * @param tier - The tier to check
+     * @param orgId - Optional org ID for org-specific overrides
+     * @throws Error if in ENFORCE mode and export is blocked
+     */
+    assertCanExport(tier: TelemetryTier, orgId?: string): void;
+    /**
+     * Check if Tier 3 content export is enabled.
+     *
+     * @returns true if Tier 3 prompts/responses can be exported
+     */
+    canExportTier3Content(): boolean;
+    /**
+     * Get the effective policy for an org (applying overrides if present).
+     *
+     * Performs deep merge for nested objects (tiers, tier3Content) to ensure
+     * partial overrides don't clobber unspecified configurations.
+     *
+     * @param orgId - Optional org ID
+     * @returns Effective policy
+     */
+    private getEffectivePolicy;
+    /**
+     * Deterministic sampling based on trace ID (W3C TraceContext recommendation).
+     * Uses last 8 hex chars for uniform distribution in [0, 1).
+     *
+     * @param traceId - The trace ID (must be at least 8 hex characters)
+     * @param sampleRate - Sample rate (0.0 - 1.0)
+     * @returns true if sampled
+     */
+    private traceIdBasedSample;
+}
+//# sourceMappingURL=policy-evaluator.d.ts.map

package/dist-esm/common/policy-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-evaluator.d.ts","sourceRoot":"","sources":["../../src/common/policy-evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EAEd,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,wBAAwB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAwB;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAEpD;;OAEG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;;;;OAOG;IACH,QAAQ,CACN,IAAI,EAAE,aAAa,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,cAAc;IAoCjB;;;;;;;;;OASG;IACH,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO;IAM7D;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAKzE;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAW1D;;;;OAIG;IACH,qBAAqB,IAAI,OAAO;IAOhC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IA2C1B;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;CAwB3B"}