blindlog 1.1.0__py3-none-any.whl

blindlog/__init__.py

@@ -0,0 +1,6 @@
+# Fix #15: Export all public-facing classes for clean DI
+from blindlog.core import BlindLogger
+from blindlog.config import BlindLogConfig
+from blindlog.interfaces import MaskingEngine
+
+__all__ = ["BlindLogger", "BlindLogConfig", "MaskingEngine"]

blindlog/config.py

@@ -0,0 +1,58 @@
+import os
+import warnings
+import hashlib
+from dataclasses import dataclass, field
+from typing import FrozenSet, Optional
+from blindlog.rules import DEFAULT_SENSITIVE_KEYS
+
+# Fix #3: Use frozenset for sensitive_keys to prevent mutation.
+# Fix #16: Note — `object.__setattr__` is used in __post_init__ to initialize
+# computed fields on a frozen dataclass. This is a standard Python pattern.
+# Any external code can also use `object.__setattr__` to bypass frozen protection —
+# this is a Python language limitation, not a runtime-enforceable security boundary.
+@dataclass(frozen=True)
+class BlindLogConfig:
+    secret_key: str = ""
+    salt: str = ""
+    sensitive_keys: FrozenSet[str] = field(default_factory=lambda: frozenset(DEFAULT_SENSITIVE_KEYS))
+    debug_mode: bool = False
+
+    def __post_init__(self):
+        if not self.secret_key:
+            object.__setattr__(self, 'secret_key', os.environ.get("BLINDLOG_SECRET", ""))
+        if not self.salt:
+            object.__setattr__(self, 'salt', os.environ.get("BLINDLOG_SALT", ""))
+        
+        env_debug = os.environ.get("BLINDLOG_DEBUG", "").lower() in ("true", "1", "yes")
+        if env_debug and not self.debug_mode:
+            object.__setattr__(self, 'debug_mode', True)
+        
+        if not self.secret_key and not self.debug_mode:
+            raise ValueError("BlindLog: BLINDLOG_SECRET is not set. Refusing to run in non-debug mode to prevent cryptographic bypass.")
+
+        object.__setattr__(self, '_blake_key_cache', self._derive_blake_key())
+
+    def _derive_blake_key(self) -> bytes:
+        safe_secret = self.secret_key or ""
+        safe_salt = self.salt or ""
+        raw = (safe_secret + safe_salt).encode('utf-8')
+
+        if len(raw) > 64:
+            warnings.warn(
+                f"BlindLog: Combined secret+salt is {len(raw)} bytes, exceeding BLAKE2b's 64-byte key limit. "
+                "Key will be derived via BLAKE2b digest to avoid silent truncation.",
+                stacklevel=5
+            )
+            raw = hashlib.blake2b(raw, digest_size=64).digest()
+
+        if len(raw) == 0:
+            warnings.warn(
+                "BlindLog: blake_key is empty. Hashes will be unkeyed and trivially reversible.",
+                stacklevel=5
+            )
+
+        return raw
+
+    @property
+    def blake_key(self) -> bytes:
+        return self._blake_key_cache

blindlog/core.py

@@ -0,0 +1,85 @@
+import hashlib
+import logging
+from typing import Any, Dict, List, Optional
+from blindlog.rules import EMAIL_REGEX, CREDIT_CARD_REGEX, IPV4_REGEX, API_KEY_REGEX, PHONE_REGEX, SSN_REGEX
+from blindlog.utils import walk_and_mask
+from blindlog.config import BlindLogConfig
+from blindlog.registry import RuleRegistry
+from blindlog.interfaces import MaskingEngine, Payload
+
+_log = logging.getLogger("blindlog.core")
+
+class BlindLogger(MaskingEngine):
+    """
+    Core engine for Deterministic Pseudonymization and Structure-Preserving Masking.
+    """
+    def __init__(
+        self, 
+        config: Optional[BlindLogConfig] = None,
+        **kwargs
+    ):
+        self.config = config if config else BlindLogConfig(**kwargs)
+        
+        self.registry = RuleRegistry(keyed_hash_fn=lambda v: f"blind:{self._hash(v, length=10)}")
+        self.registry.register(EMAIL_REGEX, self._mask_email)
+        self.registry.register(CREDIT_CARD_REGEX, self._mask_cc)
+        self.registry.register(IPV4_REGEX, lambda v: f"blnd_ip_{self._hash(v, length=10)}")
+        self.registry.register(API_KEY_REGEX, lambda v: f"blnd_key_{self._hash(v, length=10)}")
+        self.registry.register(PHONE_REGEX, lambda v: f"blnd_ph_{self._hash(v, length=10)}")
+        self.registry.register(SSN_REGEX, lambda v: f"blnd_ssn_{self._hash(v, length=10)}")
+        
+    def _hash(self, value: str, length: int = 12) -> str:
+        if length < 1:
+            raise ValueError(f"BlindLog: hash length must be >= 1, got {length}")
+
+        if not isinstance(value, str):
+            value = str(value)
+            
+        digest_bytes = max(1, (length + 1) // 2)
+        h = hashlib.blake2b(value.encode('utf-8'), key=self.config.blake_key, digest_size=digest_bytes)
+        
+        return h.hexdigest()[:length]
+
+    def _mask_email(self, email: str) -> str:
+        """Structure-preserving mask for emails: blnd_ref_HASH...@masked.com"""
+        try:
+            local, domain = email.rsplit('@', 1)
+            hash_val = self._hash(email, length=12)
+            return f"blnd_ref_{hash_val}...@masked.com"
+        except ValueError:
+            return f"blnd_ref_{self._hash(email)}...@masked.com"
+
+    def _mask_cc(self, cc: str) -> str:
+        """Structure-preserving mask for credit cards: 4111-abcdef-abcdef-1234"""
+        clean_cc = cc.replace("-", "").replace(" ", "")
+        if len(clean_cc) >= 12:
+            first_4 = clean_cc[:4]
+            last_4 = clean_cc[-4:]
+            hash_val = self._hash(clean_cc, length=12)
+            return f"{first_4}-{hash_val[:6]}-{hash_val[6:12]}-{last_4}"
+        return self._hash(cc)
+
+    def _mask_value(self, value: str) -> str:
+        if len(value) > 10000:
+            return "<Skipped due to length: ReDoS Protection>"
+            
+        fallback_hash = lambda v: f"blind:{self._hash(v, length=10)}"
+        return self.registry.process_value(value, fallback_hash)
+
+    def _mask_slow_path(self, text: str) -> str:
+        if len(text) > 10000:
+            return "<Skipped due to length: ReDoS Protection>"
+            
+        return self.registry.process_text(text)
+
+    def mask(self, payload: Payload) -> Payload:
+        """Public endpoint to mask a payload."""
+        if self.config.debug_mode:
+            return payload
+            
+        return walk_and_mask(
+            data=payload, 
+            sensitive_keys=self.config.sensitive_keys,
+            mask_value_fn=self._mask_value,
+            mask_text_fn=self._mask_slow_path
+        )

blindlog/formatters.py

@@ -0,0 +1,65 @@
+import logging
+import copy
+from typing import Optional
+from blindlog.interfaces import MaskingEngine
+
+_log = logging.getLogger("blindlog.formatter")
+
+class BlindLogFormatter(logging.Formatter):
+    """
+    A custom logging formatter that intercepts and pseudonymizes sensitive data 
+    before it is written to the log stream.
+    """
+    def __init__(self, fmt: Optional[str] = None, datefmt: Optional[str] = None, style: str = '%', blind_logger: Optional[MaskingEngine] = None):
+        super().__init__(fmt, datefmt, style)
+        self._blind_logger = blind_logger
+        self._initialized = blind_logger is not None
+
+    @property
+    def blind_logger(self):
+        if not self._initialized:
+            from blindlog.core import BlindLogger
+            self._blind_logger = BlindLogger()
+            self._initialized = True
+        return self._blind_logger
+
+    def format(self, record: logging.LogRecord) -> str:
+        record_copy = copy.copy(record)
+        
+        try:
+            # Mask the message body
+            if isinstance(record_copy.msg, (dict, list)):
+                record_copy.msg = self.blind_logger.mask(copy.deepcopy(record_copy.msg))
+            elif isinstance(record_copy.msg, str):
+                record_copy.msg = self.blind_logger.mask(record_copy.msg)
+                
+            # Fix #1: Handle both tuple and dict-style log args
+            if record_copy.args:
+                args_copy = copy.deepcopy(record_copy.args)
+                if isinstance(args_copy, dict):
+                    # Mapping style: logger.info("%(name)s logged in", {"name": "user@example.com"})
+                    record_copy.args = {
+                        k: self.blind_logger.mask(v) if isinstance(v, (str, dict, list)) else v
+                        for k, v in args_copy.items()
+                    }
+                elif isinstance(args_copy, tuple):
+                    # Positional style: logger.info("Hello %s", "user@example.com")
+                    record_copy.args = tuple(
+                        self.blind_logger.mask(arg) if isinstance(arg, (str, dict, list)) else arg
+                        for arg in args_copy
+                    )
+
+            # Fix #2: Mask exception info to prevent PII leaks in stack traces
+            if record_copy.exc_info and record_copy.exc_info[0] is not None:
+                exc_text = self.formatException(record_copy.exc_info)
+                record_copy.exc_text = self.blind_logger.mask(exc_text)
+                record_copy.exc_info = None  # Prevent super() from re-formatting unmasked
+
+        except Exception as e:
+            _log.error("BlindLog: Masking failed. Reason: %s", e)
+            record_copy.msg = "[BLINDLOG MASKING FAILED - RECORD SUPPRESSED]"
+            record_copy.args = None
+            record_copy.exc_info = None
+            record_copy.exc_text = None
+            
+        return super().format(record_copy)

blindlog/integrations/fastapi.py

@@ -0,0 +1,116 @@
+import json
+import logging
+from blindlog.core import BlindLogger
+from blindlog.interfaces import MaskingEngine
+
+_log = logging.getLogger("blindlog.middleware")
+
+class BlindLogFastAPIMiddleware:
+    """
+    Pure ASGI Middleware to intercept and mask request/response bodies and metadata.
+    
+    Known Limitation: Streaming responses (SSE, chunked transfer) may have PII split
+    across multiple body chunks. Chunk-by-chunk inspection cannot detect PII that spans
+    chunk boundaries.
+    """
+    def __init__(self, app, blind_logger: MaskingEngine = None):
+        self.app = app
+        self._blind_logger = blind_logger
+        self._initialized = blind_logger is not None
+
+    @property
+    def blind_logger(self):
+        if not self._initialized:
+            self._blind_logger = BlindLogger()
+            self._initialized = True
+        return self._blind_logger
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        raw_headers = scope.get("headers", [])
+        
+        # Extract content-length for OOM check
+        headers_dict = dict(raw_headers)
+        content_length_str = headers_dict.get(b"content-length", b"0").decode("utf-8", errors="ignore")
+        content_length = int(content_length_str) if content_length_str.isdigit() else 0
+        
+        if content_length > 5_000_000:
+            _log.warning("BlindLog: Payload omitted from logging due to exceeding 5MB safety limit.")
+            return await self.app(scope, receive, send)
+
+        body_bytes = b""
+        more_body = True
+        messages = []
+        
+        async def send_proxy(message):
+            if message["type"] == "http.response.start":
+                _log.info(f"BlindLog [Response Status]: {message['status']}")
+            elif message["type"] == "http.response.body":
+                resp_body = message.get("body", b"")
+                if resp_body and len(resp_body) < 5_000_000:
+                    try:
+                        parsed_resp = json.loads(resp_body)
+                        masked_resp = self.blind_logger.mask(parsed_resp)
+                        _log.info(f"BlindLog [Response Body]: {json.dumps(masked_resp)}")
+                    except (json.JSONDecodeError, UnicodeDecodeError):
+                        _log.debug("BlindLog [Response Body]: <non-JSON response, skipped>")
+                elif resp_body:
+                    _log.warning("BlindLog: Response body exceeds 5MB, skipping masking.")
+            await send(message)
+
+        while more_body:
+            message = await receive()
+            messages.append(message)
+            if message["type"] == "http.request":
+                body_bytes += message.get("body", b"")
+                
+                if len(body_bytes) > 5_000_000:
+                    _log.warning("BlindLog: OOM Protection Tripped! Chunked stream exceeds 5MB. Logging aborted.")
+                    body_bytes = b""
+                    
+                    async def dynamic_receive_proxy():
+                        if messages:
+                            return messages.pop(0)
+                        return await receive()
+                        
+                    return await self.app(scope, dynamic_receive_proxy, send_proxy)
+
+                more_body = message.get("more_body", False)
+            else:
+                more_body = False
+
+        if body_bytes:
+            try:
+                parsed_body = json.loads(body_bytes)
+                masked_request_body = self.blind_logger.mask(parsed_body)
+                _log.info(f"BlindLog [Request Body]: {json.dumps(masked_request_body)}")
+            except json.JSONDecodeError:
+                if len(body_bytes) < 5_000_000:
+                    masked_string = self.blind_logger.mask(body_bytes.decode('utf-8', errors='ignore'))
+                    _log.info(f"BlindLog [Request Body]: {masked_string}")
+
+        # Fix #8: Use list-of-tuples to preserve duplicate headers
+        # Fix #9: Use errors='replace' for non-UTF-8 header values
+        decoded_headers = [
+            (k.decode('utf-8', errors='replace'), v.decode('utf-8', errors='replace'))
+            for k, v in raw_headers
+        ]
+        # Mask each header value individually using the key context, logging as list of pairs
+        masked_headers = []
+        for k, v in decoded_headers:
+            if isinstance(v, str):
+                masked_dict = self.blind_logger.mask({k: v})
+                masked_headers.append((k, masked_dict.get(k, v)))
+            else:
+                masked_headers.append((k, v))
+        _log.info(f"BlindLog [Headers]: {json.dumps(masked_headers)}")
+
+        # Forward real receive() (including http.disconnect) after buffer is exhausted
+        async def receive_proxy():
+            if messages:
+                return messages.pop(0)
+            return await receive()
+
+        await self.app(scope, receive_proxy, send_proxy)

blindlog/interfaces.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+from typing import Any, Union
+
+# Fix #14: Payload type alias — now applied to the abstract method signature
+Payload = Union[str, int, float, bool, None, dict, list]
+
+class MaskingEngine(ABC):
+    """
+    Formal Interface contract for Privacy-Preserving Observability engines.
+    Enforces standardized execution methods to allow developers to safely substitute
+    the default deterministic hash engine with proprietary ones (like AWS KMS or HashiCorp Vault)
+    without disrupting downstream middleware plugins.
+    """
+    
+    @abstractmethod
+    def mask(self, payload: Payload) -> Payload:
+        """
+        Recursively process a payload (String, Dictionary, or List)
+        and securely blind all matched sensitive nodes.
+        """
+        pass

blindlog/registry.py

@@ -0,0 +1,69 @@
+from typing import Callable, List, Tuple, Optional
+import re
+import logging
+
+_log = logging.getLogger("blindlog.registry")
+
+MaskCallback = Callable[[str], str]
+
+class RuleRegistry:
+    """
+    Extensible configuration registry supporting mapping of deterministic 
+    cryptographic functions to custom user-provided Regex patterns.
+    """
+    def __init__(self, keyed_hash_fn: Optional[MaskCallback] = None):
+        self._rules: List[Tuple[re.Pattern, MaskCallback]] = []
+        self._keyed_hash_fn = keyed_hash_fn
+        
+    def register(self, pattern: re.Pattern, callback: MaskCallback):
+        """Registers a customized fallback regex structure."""
+        self._rules.append((pattern, callback))
+
+    def _is_already_masked(self, value: str) -> bool:
+        """Check if a value has already been masked to ensure idempotency."""
+        from blindlog.rules import MASKED_PATTERN
+        return bool(MASKED_PATTERN.match(value))
+
+    def _secure_fallback(self, value: str) -> str:
+        """Produce a keyed fallback hash."""
+        if self._keyed_hash_fn:
+            return self._keyed_hash_fn(value)
+        import hashlib
+        _log.warning("BlindLog: Using unkeyed fallback hash — keyed_hash_fn not configured.")
+        return f"blind:{hashlib.blake2b(value.encode(), digest_size=5).hexdigest()}"
+        
+    def process_value(self, value: str, fallback_callback: MaskCallback) -> str:
+        """
+        Executes strict Format Preserving matching. Escapes early if matched.
+        Wraps callbacks in try/except. Skips already-masked values.
+        """
+        # Fix #10: More precise idempotency check — require sentinel + hex pattern
+        if self._is_already_masked(value):
+            return value
+
+        for pattern, callback in self._rules:
+            if pattern.fullmatch(value):
+                try:
+                    return callback(value)
+                except Exception as e:
+                    _log.warning(f"BlindLog: Callback failed for pattern {pattern.pattern}: {e}. Using fallback.")
+                    return fallback_callback(value)
+        return fallback_callback(value)
+        
+    def process_text(self, text: str) -> str:
+        """
+        Cumulatively masks all recognized embedded objects within a standard string block.
+        On callback failure, applies a keyed fallback hash.
+        """
+        for pattern, callback in self._rules:
+            def safe_sub(match, cb=callback):
+                matched = match.group(0)
+                if self._is_already_masked(matched):
+                    return matched
+                try:
+                    return cb(matched)
+                except Exception as e:
+                    _log.warning(f"BlindLog: Callback failed during text scan: {e}. Applying keyed fallback.")
+                    return self._secure_fallback(matched)
+            text = pattern.sub(safe_sub, text)
+        return text

blindlog/rules.py

@@ -0,0 +1,102 @@
+import re
+from functools import lru_cache
+
+# Optimized regular expressions for identifying PII within free-form text
+
+# Email regex — no TLD upper bound, fixed character class
+EMAIL_REGEX = re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b')
+
+# Credit Card: Standard 16 digit cards (Visa, Mastercard, Discover), optional separators
+# Note: Pure regex CC detection cannot perform Luhn validation. This will match any
+# 16-digit number in groups of 4. For environments with heavy numeric IDs, consider
+# disabling this rule or adding Luhn validation via a custom callback.
+CREDIT_CARD_REGEX = re.compile(r'\b(?:\d{4}[-\s]?){3}\d{4}\b')
+
+# IPv4 with proper octet range validation (0-255)
+IPV4_REGEX = re.compile(
+    r'\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b'
+)
+
+# Expanded API key regex covering major real-world formats
+API_KEY_REGEX = re.compile(
+    r'\b(?:'
+    r'sk-[a-zA-Z0-9]{20,80}'            # OpenAI
+    r'|sk_(?:live|test)_[a-zA-Z0-9]+'   # Stripe
+    r'|ghp_[a-zA-Z0-9]{36}'             # GitHub PAT classic
+    r'|github_pat_[a-zA-Z0-9_]{80,100}' # GitHub fine-grained
+    r'|AKIA[A-Z0-9]{16}'                # AWS Access Key ID
+    r'|xox[bpas]-[a-zA-Z0-9-]{20,}'     # Slack tokens (min 20 chars)
+    r')\b'
+)
+
+# Fix #5 + #6 + #14: Phone regex with improved international support
+# Uses lookbehind/lookahead instead of \b to properly capture the + prefix
+# Note: 10-digit standalone numbers may false-positive (inherent regex limitation, documented)
+PHONE_REGEX = re.compile(
+    r'(?<!\w)(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}(?!\w)'
+    r'|'
+    r'\+\d{1,3}(?:[-.\s]\d+){1,5}(?!\w)'
+)
+
+# Fix #12: SSN regex (US format)
+SSN_REGEX = re.compile(r'\b\d{3}-\d{2}-\d{4}\b')
+
+# Collision-resistant sentinel prefixes for idempotency
+MASKED_PREFIXES = ("blnd_ref_", "blind:", "blnd_ip_", "blnd_key_", "blnd_ph_", "blnd_ssn_")
+
+# Strict idempotency validation pattern matching generated masks exactly
+MASKED_PATTERN = re.compile(
+    r'^('
+    r'blnd_ref_[0-9a-f]{12}\.\.\.@masked\.com'
+    r'|blind:[0-9a-f]{10}'
+    r'|blnd_ip_[0-9a-f]{10}'
+    r'|blnd_key_[0-9a-f]{10}'
+    r'|blnd_ph_[0-9a-f]{10}'
+    r'|blnd_ssn_[0-9a-f]{10}'
+    r')$'
+)
+
+# Fix #7: Removed generic 'key' — replaced with specific sensitive key variants
+# Fix #11: Removed 'cell' and 'telephone' — too many false positives (fuel_cell, etc.)
+# Fix #15: Added 'auth_code' for OAuth2 coverage
+DEFAULT_SENSITIVE_KEYS = frozenset({
+    "password",
+    "secret",
+    "token",
+    "api_key",
+    "ssn",
+    "credit_card",
+    "cc_number",
+    "email",
+    "authorization",
+    "credentials",
+    "phone",
+    "mobile",
+    "authorization_code",
+    "auth_code",
+    "private_key",
+    "secret_key",
+    "signing_key",
+    "encryption_key",
+    "ssn_number",
+    "cookie",
+    "set_cookie",
+})
+
+# Fix #4: Two-pass camelCase normalization for acronyms
+_CAMEL_RE1 = re.compile(r'([A-Z]+)([A-Z][a-z])')   # XMLParser → XML_Parser
+_CAMEL_RE2 = re.compile(r'([a-z\d])([A-Z])')         # camelCase → camel_Case
+
+# Fix #13: Cache normalized keys for performance
+@lru_cache(maxsize=2048)
+def normalize_key(k: str) -> str:
+    """
+    Normalize a key to snake_case for sensitive key matching.
+    'refreshToken' -> 'refresh_token'
+    'APIKey' -> 'api_key'
+    'OAuth2Token' -> 'oauth2_token'
+    'user.password' -> 'user.password'
+    """
+    k = _CAMEL_RE1.sub(r'\1_\2', k)
+    k = _CAMEL_RE2.sub(r'\1_\2', k)
+    return k.replace('-', '_').lower()

blindlog/utils.py

@@ -0,0 +1,109 @@
+from typing import Any, Dict, List, Set, Callable
+from blindlog.rules import normalize_key
+
+def walk_and_mask(
+    data: Any, 
+    sensitive_keys: Set[str], 
+    mask_value_fn: Callable[[str], str],
+    mask_text_fn: Callable[[str], str],
+    visited: set = None,
+    force_mask: bool = False
+) -> Any:
+    """
+    Recursively walks through dictionaries and lists to mask sensitive data.
+    Implements DFS with cycle detection to prevent infinite recursion on self-referencing objects.
+    
+    Hybrid Strategy:
+    - Fast Path: If key matches (exact, suffix with _/-./ delimiters, or camelCase normalized), mask value.
+    - Slow Path: If string value, scans using regex via mask_text_fn.
+    """
+    if visited is None:
+        visited = set()
+
+    # Fix #6: Use null byte sentinel for type-prefixed masking (cannot appear in JSON)
+    if data is None:
+        if force_mask:
+            return mask_value_fn("\x00NoneType\x00")
+        return data
+
+    if isinstance(data, bool) and not force_mask:
+        return data
+    if isinstance(data, bool) and force_mask:
+        return mask_value_fn(f"\x00bool\x00{data}")
+
+    if isinstance(data, (int, float)) and not force_mask:
+        return data
+
+    # Cycle detection
+    obj_id = id(data)
+    if obj_id in visited:
+        return "<CircularReference>"
+        
+    visited.add(obj_id)
+
+    if isinstance(data, dict):
+        masked_dict = {}
+        for k, v in data.items():
+            # Fix #3 + #4: Normalize camelCase to snake_case before matching
+            k_normalized = normalize_key(str(k))
+            
+            # Exact match, suffix match (with _, -, . delimiters)
+            is_sensitive = (
+                force_mask
+                or k_normalized in sensitive_keys
+                or any(
+                    k_normalized.endswith("_" + s) 
+                    or k_normalized.endswith("-" + s) 
+                    or k_normalized.endswith("." + s)
+                    for s in sensitive_keys
+                )
+            )
+            
+            if is_sensitive:
+                if isinstance(v, str):
+                    masked_dict[k] = mask_value_fn(v)
+                elif isinstance(v, (int, float)):
+                    masked_dict[k] = mask_value_fn(str(v))
+                elif isinstance(v, bool):
+                    masked_dict[k] = mask_value_fn(f"\x00bool\x00{v}")
+                elif v is None:
+                    masked_dict[k] = mask_value_fn("\x00NoneType\x00")
+                else:
+                    masked_dict[k] = walk_and_mask(v, sensitive_keys, mask_value_fn, mask_text_fn, visited, force_mask=True)
+            else:
+                masked_dict[k] = walk_and_mask(v, sensitive_keys, mask_value_fn, mask_text_fn, visited, force_mask=False)
+                
+        visited.remove(obj_id)
+        return masked_dict
+
+    elif isinstance(data, list):
+        masked_list = [walk_and_mask(item, sensitive_keys, mask_value_fn, mask_text_fn, visited, force_mask=force_mask) for item in data]
+        visited.remove(obj_id)
+        return masked_list
+
+    elif isinstance(data, bytes):
+        try:
+            decoded = data.decode('utf-8', errors='ignore')
+            result = mask_value_fn(decoded) if force_mask else mask_text_fn(decoded)
+            visited.remove(obj_id)
+            return result
+        except Exception:
+            visited.remove(obj_id)
+            return data
+        
+    elif isinstance(data, str):
+        if force_mask:
+            result = mask_value_fn(data)
+        else:
+            result = mask_text_fn(data)
+        visited.remove(obj_id)
+        return result
+
+    # Fallback for primitive types forced to be masked
+    if force_mask and isinstance(data, (int, float)):
+        result = mask_value_fn(str(data))
+        visited.remove(obj_id)
+        return result
+
+    visited.remove(obj_id)
+    return data

blindlog-1.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: blindlog
+Version: 1.1.0
+Summary: Deterministic privacy-preserving logger for Python.
+Project-URL: Repository, https://github.com/A-P-Shukla/Blind-Log
+Project-URL: Bug Tracker, https://github.com/A-P-Shukla/Blind-Log/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastapi
+Requires-Dist: fastapi; extra == "fastapi"
+Requires-Dist: starlette; extra == "fastapi"
+Dynamic: license-file
+
+# BlindLog v1.1
+
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717.svg?style=for-the-badge&logo=github)](https://github.com/A-P-Shukla/Blind-Log)
+
+BlindLog is a **zero-dependency, production-ready Privacy-Preserving Observability SDK** for Python.
+
+It solves the fundamental conflict in backend engineering: The developer needs to see everything to fix bugs, but compliance constraints (GDPR/HIPAA/SOC2) dictate that you cannot see anything personal. 
+
+By replacing raw Personal Identifiable Information (PII) with consistent, structure-preserving deterministic hashes, developers retain perfect system observability without leaking actual identities into application logs.
+
+---
+
+## 💡 The "Why": Why Use BlindLog?
+
+### The Problem with Redaction
+Legacy redaction tools look for emails or credit cards and replace them with static text like `*****` or `[REDACTED]`. The fatal flaw here is **context destruction**. If your logs show `[REDACTED] failed to purchase order [REDACTED]`, you cannot trace a specific user's journey through your microservices when every trace of their identity maps to the exact same generic string.
+
+### The BlindLog Solution: Deterministic Pseudonymization
+BlindLog uses natively-keyed **BLAKE2b cryptography** to consistently map data:
+- `user1@gmail.com` **always** logs as `blnd_ref_8ax92bfac000...@masked.com`.
+- `user2@gmail.com` **always** logs as `blnd_ref_1c89f81ba000...@masked.com`.
+
+You instantly know if the *same* user triggered 50 errors across 4 microservices over a week, while remaining legally compliant because the raw identity is cryptographically destroyed.
+
+---
+
+## 🚀 Installation
+
+BlindLog has zero external dependencies and runs natively on Python 3.8+.
+
+```bash
+pip install blindlog
+```
+
+---
+
+## 🛠️ Exactly How to Use It
+
+BlindLog is built on an extensible architecture that operates automatically once plugged into your existing application. It intercepts data, traverses JSON payloads recursively, and masks strings without breaking schema.
+
+### 1. Mandatory Security Configuration
+BlindLog operates on keyed hashes. To prevent rainbow-table reverse-engineering, you **must** supply a cryptographic secret.
+
+Set the following environment variables on your production servers:
+```bash
+export BLINDLOG_SECRET="your-super-strong-random-secret-key"
+export BLINDLOG_SALT="optional-additional-salt"
+```
+
+> **Warning:** If `BLINDLOG_SECRET` is missing, BlindLog will violently crash on boot to protect your system from generating reversible, unkeyed hashes. For local development, you can set `export BLINDLOG_DEBUG="true"` to bypass this crash.
+
+---
+
+### 2. Standard Python Logging Interception
+
+BlindLog ships with a `logging.Formatter` that hooks directly into Python's native `logging` module. It intercepts all string messages, dictionary `args`, and even `Exception` tracebacks to scrub PII before it hits your terminal or logging aggregator (like Datadog/Elasticsearch).
+
+```python
+import logging
+from blindlog.formatters import BlindLogFormatter
+
+# 1. Initialize your logger
+logger = logging.getLogger("my_application")
+logger.setLevel(logging.INFO)
+
+# 2. Create a handler
+handler = logging.StreamHandler()
+
+# 3. Attach the BlindLogFormatter!
+handler.setFormatter(BlindLogFormatter())
+logger.addHandler(handler)
+
+# Usage A: Standard Strings (Slow Path - Regex Scanning)
+logger.info("Failed login for akhand@gmail.com on card 4111-2222-3333-4444")
+# Output: Failed login for blnd_ref_8a9df2c00000...@masked.com on card 4111-c918a2-f8b1c4-4444
+
+# Usage B: Dictionary Arguments (Fast Path - Key Matching)
+# BlindLog detects keys like 'password' or 'email' instantly.
+logger.info("User created", {"email": "ceo@corp.com", "password": "super-secret"})
+# Output: User created {'email': 'blnd_ref_9bf... masked', 'password': 'blind:838ab...'}
+
+# Usage C: Safe Exceptions
+try:
+    raise ValueError("User akhand@gmail.com exhausted their API quota")
+except ValueError:
+    logger.exception("A system error occurred")
+    # Output: The stack trace is fully processed, and akhand@gmail.com is masked inside the Traceback!
+```
+
+---
+
+### 3. FastAPI & Starlette Middleware
+
+BlindLog acts as a **Pure ASGI Middleware**. It intercepts raw HTTP traffic *before* it hits your application routers. It safely buffers HTTP payloads (up to 5MB to prevent OOM DOS) and logs masked Request Bodies, Response Bodies, and Headers.
+
+```python
+from fastapi import FastAPI
+from blindlog.integrations.fastapi import BlindLogFastAPIMiddleware
+
+app = FastAPI()
+
+# Attach the middleware
+app.add_middleware(BlindLogFastAPIMiddleware)
+
+@app.post("/checkout")
+async def checkout(payload: dict):
+    # If the user sends {"credit_card": "4111-...", "cookie": "session_123"},
+    # The middleware automatically logs the sanitized payload to standard out.
+    return {"status": "success"}
+```
+
+**What the Middleware handles automatically:**
+- **Request/Response Bodies:** Deeply nested JSON is recursively traversed and masked.
+- **HTTP Headers:** Sensitive context headers (like `Authorization`, `Cookie`, `X-API-Key`) are extracted and encrypted without losing duplicate associations.
+- **Streaming Protections:** Safe passage for WebSockets and SSE pipelines.
+
+---
+
+### 4. Customizing the Configuration (`BlindLogConfig`)
+
+You can tune BlindLog's rules by defining a `BlindLogConfig`. Once created, the config is `frozen` (immutable) to prevent runtime tampering.
+
+```python
+from blindlog.core import BlindLogger
+from blindlog.config import BlindLogConfig
+
+# 1. Define custom sensitive keys. 
+# Note: This overwrites the defaults, so add your specific database fields.
+custom_keys = frozenset({"internal_db_id", "auth_token", "email"})
+
+config = BlindLogConfig(
+    secret_key="my-custom-key", # Will fall back to ENV var if omitted
+    sensitive_keys=custom_keys,
+    debug_mode=False
+)
+
+logger = BlindLogger(config=config)
+```
+
+**Key Matching Engine (Fast Path):**
+BlindLog checks dictionary keys via:
+1. **Exact Match:** e.g., `"email"` == `"email"`.
+2. **Suffix Match:** e.g., `"user_password"` ends with `"_password"`.
+3. **Normalization:** Hyphens (`x-api-key`) and camelCase (`APIKey`) are normalized to `snake_case` before matching, ensuring maximum coverage across varying schemas.
+
+---
+
+### 5. Custom Format Registration (Adding Regex)
+
+BlindLog implements a **Registry Pattern**. If you have custom internal tokens (e.g., specific AWS KMS IDs or internal Employee IDs) you can teach BlindLog to find and format them dynamically in free-text.
+
+```python
+import re
+from blindlog.core import BlindLogger
+
+logger = BlindLogger()
+
+# 1. Define a regex pattern
+aws_pattern = re.compile(r"AWS-KMS-\d{6}")
+
+# 2. Define a callback function that takes the matched string and returns a safe string
+# Note: You can also hash it dynamically inside the callback if you wish!
+def mask_aws(matched_string: str) -> str:
+    return "blnd_aws_TOKEN_REDACTED"
+
+# 3. Register the rule
+logger.registry.register(aws_pattern, mask_aws)
+
+masked = logger.mask("Exception: AWS-KMS-123456 failed to load.")
+# Output: "Exception: blnd_aws_TOKEN_REDACTED failed to load."
+```
+
+---
+
+## 🛡️ Default Out-Of-The-Box Protections
+
+BlindLog actively protects the following data types automatically via RegEx and Key-discovery:
+
+- **Emails:** Truncated and hashed (`blnd_ref_HASH...@masked.com`)
+- **Credit Cards:** Preserves major industry format (`4111-HASH-HASH-1234`)
+- **API Keys & Tokens:** Covers OpenAI, Stripe, AWS, Slack, and GitHub PATs natively.
+- **Phone Numbers:** International and NANP routing.
+- **Social Security Numbers (SSN):** US Formats.
+- **IPv4 Addresses:** Validated octet arrays.
+- **HTTP/Web Standard Keys:** `cookie`, `set_cookie`, `authorization`, `password`, `secret`, `private_key`, `credentials`.
+
+---
+
+## 🧮 Idempotency & System Guarantees
+
+- **Idempotent Masking Guarantees:** BlindLog uses strict structural RegEx evaluations (`MASKED_PATTERN`). If you pass already-masked data into the engine multiple times, it skips it instantly. You will never double-hash a log.
+- **ReDoS Mitigation:** Slow-path Regex execution cuts off after 10,000 characters, averting CPU exhaustion DOS attacks.
+- **OOM Prevention:** Middlewares strictly cap at 5MB buffer payloads.
+- **Type Sabotage Checks:** Gracefully handles `None`, `True`, and circular nested dictionary references without crashing or returning unmasked memory addresses.
+
+For further exploration, please review our [Architecture Guide](./ARCHITECTURE.md) and the `CHANGELOG.md`!

blindlog-1.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+blindlog/__init__.py,sha256=4pDU5eCF7e3EJcQkL00sb7y-pN7ThNgeDB3556DYQX8,246
+blindlog/config.py,sha256=ebgT6FsQf3S827f5ewCGW_iAjnvr2PeL61uIiXUMD3U,2365
+blindlog/core.py,sha256=VHuVxH7TPq37RO5SfvD4zSBFjpM0GV9aZegb0ciiJ5E,3490
+blindlog/formatters.py,sha256=TbHQs0ax-Xa5JzpNNJHmrm2CJCRbgjf0pUh9TIs6Yu4,2915
+blindlog/interfaces.py,sha256=GMv-81qPDtiQnTYv-6Ua9d67Ng9cTsu3YjXMTgdtWJE,794
+blindlog/registry.py,sha256=M9NPgB2rpB1hRxJZkblycIVPXpo9IQoezhDKO2NSHcw,2915
+blindlog/rules.py,sha256=LzHXV-dK3pOHEMZ_KnikgDQ4t1RTJwD5NDVVLSe3-i4,3484
+blindlog/utils.py,sha256=j9FpFx6uKBw603nfwTrPxRccC-QqFAhs2i1Rml4xwSM,3856
+blindlog/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+blindlog/integrations/fastapi.py,sha256=MdxUVqxhMwVb2R-_C91kHD3gcgM6HxYTYYhclQ-DkzM,4970
+blindlog-1.1.0.dist-info/licenses/LICENSE,sha256=JuDRkpJ1tG2YXCjsW0iF9Ob8IH0K2Sd3c9WMTBPfO7o,1055
+blindlog-1.1.0.dist-info/METADATA,sha256=8YA1xIUXOU5eJFzuUcXJOdrzh4H6RDSsU731mJQ1m0I,9166
+blindlog-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+blindlog-1.1.0.dist-info/top_level.txt,sha256=0xWLShRA7WflARBOnJVGJymE_rVx-CJJEkfArjrjPDY,9
+blindlog-1.1.0.dist-info/RECORD,,

blindlog-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blindlog-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blindlog-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+blindlog