fix: harden syft-restrict against verifier and obfuscator bypasses

[pjwerneck]

Summary

Closes a series of bypasses in syft-restrict's static verifier and obfuscator, found through
iterative adversarial review. Update documentation.

Changes

• Ban additional dynamic-escape/reflection builtins: type, __build_class__, print, and the
  dunder-proxy builtins repr/str/ascii/format/bytes.
• Fix multiple aliasing bypasses: bare names imported via from X import name, homoglyph identifiers, and
  common identifier-aliasing patterns that evaded the call-target checks.
• Fix f-string handling: conversion flags (!r/!s/!a), the {x=} debug form, and plain
  interpolation (f"{x}") all invoke __format__/__repr__/__str__ with no Call node — all
  are now rejected instead of only the conversion-flag forms.
• Harden self/cls parameter vetting: reassigning self/cls, reusing them as an unrelated
  parameter name, and non-first-parameter/nested-function/lambda cases no longer grant the
  self.<name> trust exemption.
• Close self.<attr> trust bypasses: tuple-unpack and for-loop assignment targets are now tracked
  by the safety table, and local-variable aliasing (including multi-hop copies) is tracked so
  tmp = self.fn; tmp(x) is checked the same way self.fn(x) is.
• Ban def/class statements whose name shadows a trusted import alias or visible wrapper name
  (previously only rebinding via assignment was checked).
• Fix the obfuscator to correctly blank f-string literal text under Python 3.12+'s PEP 701
  tokenizer (previously left un-obfuscated on 3.12+).
• Rewrite docs/disallowed-ast-examples.md as per-construct subheadings instead of a wide table;
  add docs/code-layout.md; simplify README.md.
• Extract shared AST helpers into astutil.py and refactor verifier.py/obfuscator.py for
  readability (central violation-code registry, _SelfAttrTrust helper, split obfuscator passes),
  with no behavior change.
• Raise on a malformed/inverted private-line range instead of silently verifying nothing in it.

Testing

• Added tests/verify/test_bypasses.py with a regression test per bypass class
• Added tests/verify/test_ranges.py for the range-validation fix.

Asana task

https://app.asana.com/1/1185126988600652/project/1216249688888494/task/1216266561077080?focus=true

[Copilot]

Pull request overview

This PR strengthens syft-restrict’s static verification and obfuscation layers to close multiple identified bypass techniques, adds regression tests for each bypass class, and refreshes the documentation to match the evolved threat model and implementation.

Changes:

• Harden verifier rules around call-target resolution, aliasing, self/cls trust, and f-string interpolation to prevent reflection/dynamic-escape bypasses.
• Update obfuscation to correctly blank f-string literal text under Python 3.12+ (PEP 701 tokenization), plus refactor shared AST/range utilities into astutil.py.
• Add targeted regression tests (bypasses + range validation) and restructure docs/README for clarity.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/syft-restrict/tests/verify/test_whitelist.py	Updates whitelist expectations for f-strings to reflect new interpolation rejection behavior.
packages/syft-restrict/tests/verify/test_ranges.py	Adds regression test ensuring malformed private ranges raise instead of silently passing.
packages/syft-restrict/tests/verify/test_bypasses.py	Adds comprehensive regression coverage for verifier bypass classes (aliasing, reflection, f-strings, self/cls trust, etc.).
packages/syft-restrict/tests/obfuscate/test_obfuscate.py	Adds a test ensuring f-string literal text is blanked across tokenizer variants (incl. Python 3.12+).
packages/syft-restrict/src/syft_restrict/verifier.py	Major verifier hardening + refactor: central violation codes, stronger call/name checks, self-attr trust tracking, and f-string interpolation rejection.
packages/syft-restrict/src/syft_restrict/runner.py	Switches to shared astutil helpers for range normalization and scanning.
packages/syft-restrict/src/syft_restrict/policy.py	Expands banned builtins and improves documentation/comments; minor cleanup.
packages/syft-restrict/src/syft_restrict/obfuscator.py	Refactors passes; adds PEP 701 f-string token handling; uses shared astutil.
packages/syft-restrict/src/syft_restrict/astutil.py	New shared helper module for AST and range utilities (scan, dotted paths, range normalization).
packages/syft-restrict/src/syft_restrict/init.py	Updates package-level docs/pointers to new docs structure.
packages/syft-restrict/README.md	Simplifies and reorients README toward usage + docs pointers.
packages/syft-restrict/docs/verify.md	New/expanded explanation of verifier behavior, edge cases, and limitations.
packages/syft-restrict/docs/code-layout.md	New short guide to module responsibilities.
packages/syft-restrict/docs/blacklist.md	New consolidated “what is rejected” doc with violation codes.
packages/syft-restrict/disallowed-ast-examples.md	Removes legacy table-style doc (replaced by new docs structure).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.