diff --git a/README.md b/README.md index 0f496119..12120d6e 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,28 @@ replacement = "REDACTED" # optional; defaults to "excluded" pattern = "(?i)signal|whatsapp" field = "app" # optional; defaults to "title" action = "drop" + +# Rewrite only Firefox titles: strip the browser suffix and trailing unread +# counters, then leading counters; preserve numbers in the middle of a title +[[aw-watcher-window.privacy_filter]] +pattern = "(\\s*\\(\\d+\\+?\\)|\\s*- Mozilla Firefox)+$" +action = "rewrite" +replacement = "" +app = "firefox" # optional; restricts the rule to one application + +[[aw-watcher-window.privacy_filter]] +pattern = "^(\\(\\d+\\+?\\)\\s*)+" +action = "rewrite" +replacement = "" +app = "firefox" ``` Rule fields: - `pattern` — Python `re` regex (case-insensitive flag supported via `(?i)`) - `field` — window-event field to match against (`"title"` by default; use `"app"` to match on application name) -- `action` — `"drop"` (discard the event) or `"redact"` (replace the field value) -- `replacement` — string to use when redacting; defaults to `"excluded"` +- `action` — `"drop"` (discard the event), `"redact"` (replace the field value) or `"rewrite"` (apply `pattern.sub(replacement, value)` so the rest of the value survives) +- `replacement` — string to use when redacting (defaults to `"excluded"`); required, and may be empty, for `"rewrite"` +- `app` — optional application scope: the rule only applies to events whose `app` matches (case-insensitive) Rules are applied in order. A `"drop"` rule exits immediately — subsequent rules are not evaluated for that event. diff --git a/aw_watcher_window/privacy_filter.py b/aw_watcher_window/privacy_filter.py index e8a1d053..17d1b81c 100644 --- a/aw_watcher_window/privacy_filter.py +++ b/aw_watcher_window/privacy_filter.py @@ -1,4 +1,4 @@ -""" +r""" Watcher-side privacy filter: drop or redact sensitive events before sending. Mirrors the server-side ``privacy_filters`` engine in aw-server-rust so that @@ -19,11 +19,30 @@ action = "redact" replacement = "REDACTED" # optional; defaults to "excluded" + # Rewrite only Firefox titles: strip the browser suffix and trailing unread + # counters, then leading counters; preserve numbers in the middle of a title + [[aw-watcher-window.privacy_filter]] + pattern = "(\\s*\\(\\d+\\+?\\)|\\s*- Mozilla Firefox)+$" + action = "rewrite" + replacement = "" + app = "firefox" + + [[aw-watcher-window.privacy_filter]] + pattern = "^(\\(\\d+\\+?\\)\\s*)+" + action = "rewrite" + replacement = "" + app = "firefox" + Rule fields: pattern -- Python ``re`` regex applied to the target field value. field -- Window-event field to match against (default: ``"title"``). - action -- ``"drop"`` (discard the event) or ``"redact"`` (replace the value). - replacement -- Replacement string for ``"redact"`` action (default: ``"excluded"``). + action -- ``"drop"`` (discard the event), ``"redact"`` (replace the whole + value) or ``"rewrite"`` (apply ``pattern.sub(replacement, value)`` + so the rest of the value survives). + replacement -- Replacement string for ``"redact"`` (default: ``"excluded"``). + Required and may be empty for ``"rewrite"``. + app -- Optional application scope: the rule only touches events whose + ``app`` field matches exactly (case-insensitive). macOS note: the default ``swift`` strategy cannot apply these rules (it sends heartbeats from a separate binary). The watcher refuses to start @@ -37,7 +56,7 @@ logger = logging.getLogger(__name__) -_VALID_ACTIONS = frozenset({"drop", "redact"}) +_VALID_ACTIONS = frozenset({"drop", "redact", "rewrite"}) def compile_privacy_rules(raw_rules: list) -> list: @@ -68,33 +87,69 @@ def compile_privacy_rules(raw_rules: list) -> list: action = raw.get("action", "redact") if action not in _VALID_ACTIONS: logger.error( - "privacy_filter: unknown action %r (expected 'drop' or 'redact') — rule skipped", + "privacy_filter: unknown action %r (expected one of %s) — rule skipped", action, + "/".join(sorted(_VALID_ACTIONS)), ) continue - field = raw.get("field", "title") - if not isinstance(field, str) or not field: + app = raw.get("app") + if app is not None and (not isinstance(app, str) or not app): logger.error( - "privacy_filter: 'field' must be a non-empty string — rule skipped: %r", + "privacy_filter: 'app' must be a non-empty string — rule skipped: %r", raw, ) continue - replacement = raw.get("replacement", "excluded") - if not isinstance(replacement, str): + field = raw.get("field", "title") + if not isinstance(field, str) or not field: logger.error( - "privacy_filter: 'replacement' must be a string — rule skipped: %r", + "privacy_filter: 'field' must be a non-empty string — rule skipped: %r", raw, ) continue + if action == "rewrite": + # A rewrite must be explicit: the "excluded" default would delete + # the matched value instead of substituting it. + replacement = raw.get("replacement") + if not isinstance(replacement, str): + logger.error( + "privacy_filter: 'rewrite' action requires a string " + "'replacement' (may be empty) — rule skipped: %r", + raw, + ) + continue + # A bad group reference or escape raises inside re.sub at match + # time, i.e. in the heartbeat loop — validate it here so a malformed + # rule is skipped instead of stopping window tracking. + try: + pattern.sub(replacement, "") + except (re.error, IndexError) as exc: + logger.error( + "privacy_filter: invalid 'rewrite' replacement %r for %r — " + "%s — rule skipped", + replacement, + pattern_str, + exc, + ) + continue + else: + replacement = raw.get("replacement", "excluded") + if not isinstance(replacement, str): + logger.error( + "privacy_filter: 'replacement' must be a string — rule skipped: %r", + raw, + ) + continue + compiled.append( { "pattern": pattern, "field": field, "action": action, "replacement": replacement, + "app": app, } ) return compiled @@ -115,6 +170,20 @@ def apply_privacy_filters(window: dict, rules: list) -> Optional[dict]: value = result.get(field) if not isinstance(value, str): continue + app = rule.get("app") + if app is not None: + event_app = result.get("app") + if not isinstance(event_app, str) or event_app.lower() != app.lower(): + continue + if rule["action"] == "rewrite": + if rule["pattern"].search(value): + logger.debug( + "privacy_filter: rewriting field=%r matched %r", + field, + rule["pattern"].pattern, + ) + result[field] = rule["pattern"].sub(rule["replacement"], value) + continue if rule["pattern"].search(value): if rule["action"] == "drop": logger.debug( diff --git a/tests/test_privacy_filter.py b/tests/test_privacy_filter.py index fb7f514a..46e97c23 100644 --- a/tests/test_privacy_filter.py +++ b/tests/test_privacy_filter.py @@ -1,7 +1,12 @@ """Tests for the watcher-side privacy filter.""" +from pathlib import Path +from textwrap import dedent + import pytest +import tomlkit +from aw_watcher_window import privacy_filter from aw_watcher_window.privacy_filter import apply_privacy_filters, compile_privacy_rules @@ -207,3 +212,173 @@ def test_custom_field_does_not_affect_title(): window = {"app": "Terminal", "title": "messenger in title"} # app doesn't match; rule scoped to 'app' field assert apply_privacy_filters(window, rules) == window + + +# --------------------------------------------------------------------------- +# rewrite action (alternative to redact, for partial title cleanup) +# --------------------------------------------------------------------------- + + +@pytest.fixture +def rewrite_rule(): + return compile_privacy_rules( + [ + { + "pattern": r" - Mozilla Firefox$", + "action": "rewrite", + "replacement": "", + "app": "Firefox", + } + ] + ) + + +def test_compile_rewrite_rule(): + rules = compile_privacy_rules( + [{"pattern": r"\(\d+\)\s*", "action": "rewrite", "replacement": ""}] + ) + assert len(rules) == 1 + assert rules[0]["action"] == "rewrite" + assert rules[0]["replacement"] == "" + assert rules[0]["app"] is None + + +@pytest.mark.parametrize("source", ["readme", "module"]) +@pytest.mark.parametrize( + "title, expected", + [ + ("Inbox (3) - Mozilla Firefox", "Inbox"), + ("(3) Inbox - Mozilla Firefox", "Inbox"), + ("(3+) Inbox (12) - Mozilla Firefox", "Inbox"), + ("Inbox - Mozilla Firefox", "Inbox"), + ("Chapter (3) notes - Mozilla Firefox", "Chapter (3) notes"), + ], +) +def test_documented_rewrite_rules(source, title, expected): + # Load the actual examples so regex copies in tests cannot mask doc drift. + if source == "readme": + text = (Path(__file__).resolve().parents[1] / "README.md").read_text() + example = text.split("# Rewrite only Firefox titles", 1)[1].split("```", 1)[0] + else: + text = privacy_filter.__doc__ + example = dedent( + text.split("# Rewrite only Firefox titles", 1)[1].split("Rule fields:", 1)[0] + ) + example = example.split("\n", 1)[1] + raw = tomlkit.parse(example)["aw-watcher-window"]["privacy_filter"] + rules = compile_privacy_rules(raw) + assert rules + window = {"app": "Firefox", "title": title} + assert apply_privacy_filters(window, rules) == {"app": "Firefox", "title": expected} + other_app = {"app": "Terminal", "title": title} + assert apply_privacy_filters(other_app, rules) == other_app + assert window["title"] == title + + +def test_compile_rewrite_requires_replacement(): + # "excluded" would delete the matched text instead of substituting it, so a + # rewrite with no explicit replacement is rejected rather than defaulted. + assert compile_privacy_rules([{"pattern": "x", "action": "rewrite"}]) == [] + + +def test_compile_rewrite_rejects_invalid_replacement(): + # A dangling group reference raises inside re.sub at match time, which would + # abort heartbeat collection; it must be rejected at compile time instead. + assert ( + compile_privacy_rules( + [{"pattern": "(secret)", "action": "rewrite", "replacement": r"\9"}] + ) + == [] + ) + + +def test_rewrite_accepts_group_backreference(): + rules = compile_privacy_rules( + [{"pattern": r"^(.+) - Mozilla Firefox$", "action": "rewrite", "replacement": r"\1"}] + ) + window = {"app": "Firefox", "title": "GitHub - Mozilla Firefox"} + result = apply_privacy_filters(window, rules) + assert result is not None + assert result["title"] == "GitHub" + + +def test_rewrite_strips_leading_and_trailing_counters(): + rules = compile_privacy_rules( + [{"pattern": r"\(\d+\+?\)\s*", "action": "rewrite", "replacement": ""}] + ) + window = {"app": "Thunderbird", "title": "(3) Inbox - work (12)"} + result = apply_privacy_filters(window, rules) + assert result is not None + # Trailing whitespace is the rule author's choice; the counters are gone. + assert result["title"].strip() == "Inbox - work" + + +def test_compile_rewrite_rejects_bad_app(): + assert ( + compile_privacy_rules( + [{"pattern": "x", "action": "rewrite", "replacement": "", "app": 3}] + ) + == [] + ) + + +def test_rewrite_replaces_only_the_match(rewrite_rule): + window = {"app": "Firefox", "title": "GitHub - Mozilla Firefox"} + result = apply_privacy_filters(window, rewrite_rule) + assert result is not None + assert result["title"] == "GitHub" + assert result["app"] == "Firefox" + + +def test_rewrite_strips_unread_counter(): + rules = compile_privacy_rules( + [{"pattern": r"^\(\d+\+?\)\s*", "action": "rewrite", "replacement": ""}] + ) + window = {"app": "Thunderbird", "title": "(3) Inbox - work"} + result = apply_privacy_filters(window, rules) + assert result is not None + assert result["title"] == "Inbox - work" + + +def test_rewrite_respects_app_scope(rewrite_rule): + window = {"app": "Chromium", "title": "GitHub - Mozilla Firefox"} + result = apply_privacy_filters(window, rewrite_rule) + assert result == window + + +def test_rewrite_app_scope_is_case_insensitive(rewrite_rule): + window = {"app": "firefox", "title": "Docs - Mozilla Firefox"} + result = apply_privacy_filters(window, rewrite_rule) + assert result is not None + assert result["title"] == "Docs" + + +def test_rewrite_without_app_scope_applies_everywhere(): + rules = compile_privacy_rules( + [{"pattern": r" - Mozilla Firefox$", "action": "rewrite", "replacement": ""}] + ) + window = {"app": "Chromium", "title": "Docs - Mozilla Firefox"} + result = apply_privacy_filters(window, rules) + assert result is not None + assert result["title"] == "Docs" + + +def test_rewrite_non_matching_passes_through(rewrite_rule): + window = {"app": "Firefox", "title": "Hacker News"} + assert apply_privacy_filters(window, rewrite_rule) == window + + +def test_rewrite_never_drops_or_redacts(): + rules = compile_privacy_rules( + [{"pattern": "bank", "action": "rewrite", "replacement": "BANK"}] + ) + window = {"app": "Chrome", "title": "bank statement"} + result = apply_privacy_filters(window, rules) + assert result is not None + assert result["title"] == "BANK statement" + + +def test_rewrite_input_not_mutated(rewrite_rule): + window = {"app": "Firefox", "title": "GitHub - Mozilla Firefox"} + apply_privacy_filters(window, rewrite_rule) + assert window["title"] == "GitHub - Mozilla Firefox"