blindlog 1.1.0__tar.gz

blindlog-1.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,196 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blindlog"
+version = "1.1.0"
+description = "Deterministic privacy-preserving logger for Python."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    # Zero dependencies for core!
+    # We use standard lib: json, logging, hashlib, os, re
+]
+
+[project.urls]
+Repository = "https://github.com/A-P-Shukla/Blind-Log"
+"Bug Tracker" = "https://github.com/A-P-Shukla/Blind-Log/issues"
+
+[project.optional-dependencies]
+fastapi = ["fastapi", "starlette"]  # Users only install this if they need it
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["blindlog", "blindlog.integrations"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

blindlog-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blindlog-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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)