fix(sanitization): custom_patterns propagation through sanitize_entry (v0.7.1) (#40)

* fix(sanitization): custom_patterns now propagates through sanitize_entry

The 0.7.0 ContextVar-scoped override was entered only by sanitize_post_data
and sanitize_html. Three detection sites in _sanitize_request /
_sanitize_response that run before either of those — header-value matching
(sanitize_header_value), structured queryString params, and URL query
params (_sanitize_url_query_params) — silently ignored custom_patterns
when callers used sanitize_entry / sanitize_har / sanitize_har_file.

Fix: enter both ContextVar scopes at sanitize_entry, so every detection
site within an entry sees the same extension set.

Adds a parallel _HeaderSets frozen dataclass + _HEADER_SETS_CTX ContextVar
+ _header_sets_scope context manager + _resolve_header_sets resolver
backed by a bounded LRU cache, mirroring the _FieldPatternSet infrastructure
shipped in 0.7.0. sanitize_header_value now reads from the ContextVar
instead of module-global sets, so custom headers.full_redact /
headers.cookie_redact entries take effect end-to-end via the top-level
entry points.

Tests: +12. Header-sets internals (compile / resolve / cache / scope-restore
on exception) + propagation through sanitize_entry and sanitize_har for
each of the three gaps + scope isolation between consecutive entries.
1845 tests pass, 85.65% coverage.

Held locally for the next release cycle (0.7.1). Not pushed.

Closes the gap the reviewer flagged after 0.7.0 shipped: once we fixed the
sanitize_html instance of "module-global predicate bypassed by custom_patterns,"
we should have swept the same class. sanitize_header_value + queryString +
URL query params were structurally identical and got deferred as
"nice-to-have" when they should have been included.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(release): bump version to 0.7.1

Cuts [Unreleased] to [0.7.1] - 2026-04-24 and adds comparison links,
following the release flow documented in CLAUDE.md. Single release PR
(feature fix + version bump).

Release notes summary: custom_patterns now propagates through sanitize_entry
to all detection sites (headers, cookies, queryString, URL-query params,
bodies, inline scripts), closing a security-adjacent gap in 0.7.0 where
top-level entry-point consumers were silently getting unredacted data.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Ken Schulz <kwschulz@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kwschulz

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-04-24
+
+### Fixed
+
+- **`custom_patterns` now propagates through `sanitize_entry` to all detection sites** — In 0.7.0 the `ContextVar`-scoped override was entered only by `sanitize_post_data` and `sanitize_html`, so three detection sites in `_sanitize_request` / `_sanitize_response` that run before either of those — header-value matching (`sanitize_header_value`), structured `queryString` params, and URL query params (`_sanitize_url_query_params`) — silently ignored `custom_patterns` when callers used the top-level entry points (`sanitize_entry`, `sanitize_har`, `sanitize_har_file`). **Security-adjacent**: consumers passing `custom_patterns={"headers": {"full_redact": ["x-modem-auth"]}}` to `sanitize_har_file` were getting unredacted auth headers in their "sanitized" HAR. Fixed by entering both scopes at `sanitize_entry`, so every detection site within an entry sees the same extension set. Adds a parallel `_HeaderSets` dataclass + `_HEADER_SETS_CTX` ContextVar + `_header_sets_scope` / `_resolve_header_sets` resolver + cache so `sanitize_header_value` picks up custom `headers.full_redact` / `headers.cookie_redact` entries the same way field detection picks up custom `fields.auto_redact_patterns`. Module-global state still never mutated.
+
 ## [0.7.0] - 2026-04-24
 
 ### Added
@@ -489,4 +495,5 @@ har-capture sanitize input.har --patterns custom-allowlist.json
 [0.6.0]: https://github.com/solentlabs/har-capture/compare/v0.5.1...v0.6.0
 [0.6.1]: https://github.com/solentlabs/har-capture/compare/v0.6.0...v0.6.1
 [0.7.0]: https://github.com/solentlabs/har-capture/compare/v0.6.1...v0.7.0
-[unreleased]: https://github.com/solentlabs/har-capture/compare/v0.7.0...HEAD
+[0.7.1]: https://github.com/solentlabs/har-capture/compare/v0.7.0...v0.7.1
+[unreleased]: https://github.com/solentlabs/har-capture/compare/v0.7.1...HEAD

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "har-capture"
-version = "0.7.0"
+version = "0.7.1"
 description = "HAR capture and PII sanitization library for network traffic analysis"
 readme = "README.md"
 license = "MIT"

src/har_capture/__init__.py

@@ -24,7 +24,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 # Re-export public API for convenience
 from har_capture.sanitization import (

src/har_capture/sanitization/har.py

@@ -285,6 +285,85 @@ def _resolve_field_patterns(
     return resolved
 
 
+# --- Header-set per-call override --------------------------------------------
+#
+# Parallel to _FieldPatternSet but for HTTP header names, which are matched by
+# lowercase exact-match against two sets (full_redact, cookie_redact) rather
+# than compiled regex. Same ContextVar / resolver / cache shape so the two
+# subsystems evolve together.
+
+
+@dataclass(frozen=True)
+class _HeaderSets:
+    """Resolved header-name sets used for one sanitization call.
+
+    Both sets are frozen and case-normalized to lowercase so callers can do
+    ``name.lower() in sets.full_redact`` without repeated normalization.
+    """
+
+    full_redact: frozenset[str]
+    cookie_redact: frozenset[str]
+
+
+def _compile_header_sets(sensitive_data: dict[str, Any]) -> _HeaderSets:
+    """Build (full_redact, cookie_redact) frozensets from a loaded sensitive-patterns dict."""
+    headers = sensitive_data.get("headers", {})
+    full = frozenset(h.lower() for h in headers.get("full_redact", []))
+    cookie = frozenset(h.lower() for h in headers.get("cookie_redact", []))
+    return _HeaderSets(full, cookie)
+
+
+_DEFAULT_HEADER_SETS = _HeaderSets(frozenset(_FULL_REDACT_HEADERS), frozenset(_COOKIE_REDACT_HEADERS))
+
+_HEADER_SETS_CTX: contextvars.ContextVar[_HeaderSets] = contextvars.ContextVar(
+    "har_capture_header_sets", default=_DEFAULT_HEADER_SETS
+)
+
+_CUSTOM_HEADER_SETS_CACHE: OrderedDict[str, _HeaderSets] = OrderedDict()
+
+
+def _resolve_header_sets(
+    custom_patterns: str | dict[str, Any] | None,
+) -> _HeaderSets:
+    """Resolve the (full_redact, cookie_redact) header sets for this call.
+
+    ``custom_patterns=None`` returns the shared default set (zero-cost).
+    Otherwise the custom patterns are merged with built-ins via the loader
+    and the compiled result is cached per canonical key.
+    """
+    if custom_patterns is None:
+        return _DEFAULT_HEADER_SETS
+
+    key = _custom_patterns_cache_key(custom_patterns)
+    if key is not None:
+        cached = _CUSTOM_HEADER_SETS_CACHE.get(key)
+        if cached is not None:
+            _CUSTOM_HEADER_SETS_CACHE.move_to_end(key)
+            return cached
+
+    resolved = _compile_header_sets(load_sensitive_patterns(custom_patterns))
+
+    if key is not None:
+        _CUSTOM_HEADER_SETS_CACHE[key] = resolved
+        while len(_CUSTOM_HEADER_SETS_CACHE) > _CUSTOM_FIELD_RE_CACHE_MAX:
+            _CUSTOM_HEADER_SETS_CACHE.popitem(last=False)
+    return resolved
+
+
+@contextmanager
+def _header_sets_scope(custom_patterns: str | dict[str, Any] | None) -> Iterator[None]:
+    """Apply ``custom_patterns`` as the active header-set for this scope.
+
+    Parallel to ``_field_patterns_scope``; public entry points that want
+    header-name extensions to take effect for the call must enter this scope.
+    """
+    token = _HEADER_SETS_CTX.set(_resolve_header_sets(custom_patterns))
+    try:
+        yield
+    finally:
+        _HEADER_SETS_CTX.reset(token)
+
+
 # Redaction placeholder - single source of truth
 REDACTED = "[REDACTED]"
 
@@ -369,6 +448,11 @@ def sanitize_header_value(
 ) -> str:
     """Sanitize a header value if it's sensitive.
 
+    Reads the active header-name set from ``_header_sets_scope`` when one is
+    entered (top-level entry points like ``sanitize_entry`` set it from
+    ``custom_patterns``); otherwise uses the module-wide defaults from
+    ``sensitive.json``.
+
     Args:
         name: Header name
         value: Header value
@@ -385,11 +469,12 @@ def sanitize_header_value(
         'text/html'
     """
     name_lower = name.lower()
+    sets = _HEADER_SETS_CTX.get()
 
-    if name_lower in _FULL_REDACT_HEADERS:
+    if name_lower in sets.full_redact:
         return _redact_value(value, hasher, "AUTH", collector)
 
-    if name_lower in _COOKIE_REDACT_HEADERS:
+    if name_lower in sets.cookie_redact:
         # Detect cookie attribute metadata (e.g., "HttpOnly: true, Secure: true")
         # that was incorrectly serialized as the header value
         if is_cookie_attribute_metadata(value):
@@ -503,7 +588,10 @@ def sanitize_post_data(
 
     result = copy.deepcopy(post_data)
 
-    with _field_patterns_scope(custom_patterns):
+    with (
+        _field_patterns_scope(custom_patterns),
+        _header_sets_scope(custom_patterns),
+    ):
         # Sanitize params array
         if "params" in result and isinstance(result["params"], list):
             for param in result["params"]:
@@ -1101,13 +1189,15 @@ def sanitize_entry(
         salt: Salt for hashed redaction (ignored if collector provided)
         custom_patterns: Optional additive custom patterns (file path or dict
             matching the ``load_sensitive_patterns`` schema). Extends the
-            built-in ``pii.patterns``, allowlist, and sensitive-field sets
-            (``fields.auto_redact_patterns`` / ``fields.flag_patterns``) for
-            this call only. Propagates end-to-end: the scope is entered by
-            ``sanitize_post_data`` and ``sanitize_html`` downstream, so
-            field-name extensions reach form params, JSON/XML bodies, and
-            inline-script scanners. Module-global state is never mutated.
-            See ``sanitize_post_data`` for the full contract.
+            built-in ``pii.patterns``, allowlist, sensitive-field sets
+            (``fields.auto_redact_patterns`` / ``fields.flag_patterns``), and
+            header sets (``headers.full_redact`` / ``headers.cookie_redact``)
+            for this call only. Both the field-pattern and header-set scopes
+            are entered at this level, so every downstream detection site —
+            request/response headers, cookies, ``queryString`` params, URL
+            query params, POST bodies (form / JSON / XML), and inline-script
+            scanners — sees the extensions. Module-global state is never
+            mutated. See ``sanitize_post_data`` for the full contract.
         collector: Optional collector for tracking redactions
         heuristics: Heuristic mode for pipe-delimited value detection
         _skip_copy: If True, skip deep copy (caller already copied). Internal use only.
@@ -1125,11 +1215,15 @@ def sanitize_entry(
         # No salt and no collector - create collector with no hashing
         collector = RedactionCollector(hasher=Hasher.create(None))
 
-    if "request" in result:
-        _sanitize_request(result["request"], collector.hasher, collector, custom_patterns, heuristics)
+    with (
+        _field_patterns_scope(custom_patterns),
+        _header_sets_scope(custom_patterns),
+    ):
+        if "request" in result:
+            _sanitize_request(result["request"], collector.hasher, collector, custom_patterns, heuristics)
 
-    if "response" in result:
-        _sanitize_response(result["response"], collector, custom_patterns, heuristics)
+        if "response" in result:
+            _sanitize_response(result["response"], collector, custom_patterns, heuristics)
 
     return result
 

src/har_capture/sanitization/html.py

@@ -275,15 +275,19 @@ def sanitize_html(
         hasher = Hasher.create(salt)
         collector = RedactionCollector(hasher=hasher)
 
-    # Enter the field-pattern scope so is_sensitive_field() calls inside the
-    # HTML scanner honor custom_patterns. Lazy import: har imports html at
-    # module level, so we'd cycle if this were top-level.
+    # Enter the field-pattern + header-set scopes so is_sensitive_field() and
+    # sanitize_header_value() calls inside the HTML scanner honor custom_patterns.
+    # Lazy import: har imports html at module level, so we'd cycle if this were
+    # top-level.
     from har_capture.sanitization.har import (
         _FIELD_PATTERNS_CTX,
+        _HEADER_SETS_CTX,
         _resolve_field_patterns,
+        _resolve_header_sets,
     )
 
-    _scope_token = _FIELD_PATTERNS_CTX.set(_resolve_field_patterns(custom_patterns))
+    _field_token = _FIELD_PATTERNS_CTX.set(_resolve_field_patterns(custom_patterns))
+    _header_token = _HEADER_SETS_CTX.set(_resolve_header_sets(custom_patterns))
     try:
         return _sanitize_html_impl(
             html,
@@ -293,7 +297,8 @@ def sanitize_html(
             heuristics=heuristics,
         )
     finally:
-        _FIELD_PATTERNS_CTX.reset(_scope_token)
+        _HEADER_SETS_CTX.reset(_header_token)
+        _FIELD_PATTERNS_CTX.reset(_field_token)
 
 
 def _sanitize_html_impl(