Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
91 changes: 80 additions & 11 deletions aw_watcher_window/privacy_filter.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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)
Comment thread
TimeToBuildBob marked this conversation as resolved.
Resolved
continue
if rule["pattern"].search(value):
if rule["action"] == "drop":
logger.debug(
Expand Down
175 changes: 175 additions & 0 deletions tests/test_privacy_filter.py
Original file line number Diff line number Diff line change
@@ -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


Expand Down Expand Up @@ -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"
Loading