fix: tighten pii filter behavior and rust masking strategy

[lucarlig]

🔗 Related Issue

Closes #3724
Closes #3738

---

📝 Summary

This PR tightens the PII filter behavior across both the plugin layer and the Rust detector.

At the plugin level, it preserves the current enforcement/permissive flow while making the fallback path clearer: when the Rust detector is unavailable, the legacy Python detector now emits a one-time deprecation warning instead of silently taking over. The branch also expands test coverage around plugin configuration behavior, including masking modes, whitelist handling, detection metadata, and Python-fallback signaling.

At the Rust layer, it fixes the core masking bug where built-in detections were ignoring the configured default_mask_strategy and forcing hardcoded partial masks. Built-in SSN/email/AWS detections now honor the configured default strategy, while custom patterns still keep their explicit mask-strategy overrides.

The PII filter README is also updated to match current reality: correct test paths, current prompt invocation examples, and the correct local/compose ports for manual verification.

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Lint suite	make --no-print-directory pre-commit	✅
Unit tests	cargo test and pytest tests/unit/mcpgateway/plugins/plugins/pii_filter/test_pii_filter.py -q	✅
Coverage ≥ 80%	Not run	N/A

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (if applicable)
• No secrets or credentials committed

---

📓 Notes (optional)

• Local compose verification reproduced the original Rust masking issue before the fix: with default_mask_strategy=redact, built-in detections still returned partial.
• After the fix, built-in detections honor the configured default strategy and custom patterns still preserve explicit overrides.
• A separate local database-state issue surfaced during compose verification: an old Postgres volume was stamped to an Alembic revision no longer present in the branch. Resetting the local dev DB volume resolved that environment-specific problem.

[crivetimihai]

Review Notes

Rebased onto current main (clean, no conflicts).

Code Review

The core fix is correct and well-designed. Changing CompiledPattern.mask_strategy from MaskingStrategy to Option<MaskingStrategy> cleanly separates the two cases:

• Built-in patterns: None → falls back to config.default_mask_strategy via unwrap_or
• Custom patterns: Some(strategy) → respects the user's explicit per-pattern override

Applied consistently in both detect_pii() (public benchmark API) and detect_internal() (PyO3-bound detector).

Security

This is a security improvement. Before this fix, even with default_mask_strategy=redact, built-in detections (SSN, email, credit card, etc.) leaked partial data (e.g. ***-**-6789). Now Redact properly produces [REDACTED] as configured.

Tests

• Python tests: 86 passed, 88 skipped (Rust not compiled in test env)
• Rust tests: 16 passed, 0 failed
• New differential code has 100% test coverage (deprecation warning, Rust strategy propagation, custom pattern override)
• The removed REMOVE strategy test was correctly removed — it was a latent bug (asserted partial-masking output while configuring REMOVE strategy; only passed because the old code ignored default_mask_strategy)

Observations (non-blocking)

• Python/Rust behavioral divergence during deprecation: The legacy Python PIIDetector still hardcodes per-pattern mask_strategy (e.g. MaskingStrategy.PARTIAL for SSN), so it continues to ignore default_mask_strategy for built-in patterns. Users on the Python fallback will see different masking behavior than Rust users. Acceptable given the Python path is now formally deprecated, but worth noting.

[crivetimihai]

Reviewed and approved. Rebased cleanly onto main, all tests pass, logic is correct, and the fix improves security posture for PII masking.