~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
security: architecture fences (per-user isolation, reports-dir serving) + pre-commit hooks (#6634)
LearningCircuit89c797408b7c
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 2bf705c9cd..2fa5b8afb9 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -167,6 +167,26 @@ repos:files: \.py$description: "Prevent usage of shared ldr.db database - all data must useper-user encrypted databases"+ - id: check-per-user-isolation+ name: Check user-data services are passed a username+ entry: .pre-commit-hooks/check-per-user-isolation.py+ language: script+ files: \.py$+ description: "Smoke check - user-data services/sessions under+ web/routers/, research_library/ and web/services/ must be passed a+ username argument explicitly; username provenance at router call+ sites is enforced by tests/security/test_cross_user_isolation_census.py"+ - id: check-reports-dir-not-served+ name: Check web/ file-serving references stay fenced+ entry: .pre-commit-hooks/check-reports-dir-not-served.py+ language: script+ files: \.py$+ description: "Under web/ - FileResponse/StaticFiles/StreamingResponse+ references and star imports only in per-file allowlisted files;+ LDR streaming-response wrappers only with a call to a same-module+ yielding generator function as body; no serving call referencing the outputs directory inline.+ In-memory bodies (Response(read_bytes())) and generators that read+ files themselves are not covered"- id: check-journal-quality-readonlyname: Check journal_quality.db opens are read-onlyentry: .pre-commit-hooks/check-journal-quality-readonly.pydiff --git a/.pre-commit-hooks/check-per-user-isolation.py b/.pre-commit-hooks/check-per-user-isolation.pynew file mode 100755index 0000000000..27be4f006a--- /dev/null+++ b/.pre-commit-hooks/check-per-user-isolation.py@@ -0,0 +1,857 @@+#!/usr/bin/env python3+"""+Pre-commit hook: user-data constructions pass a username.++Scope: this hook is a syntax fence against ACCIDENTAL or IDIOMATIC+code -- the shapes a contributor writes without meaning to bypass+anything. Deliberate evasion by a contributor is out of scope and is+left to code review (CODEOWNERS); the hook does not try to be a+sandbox. Examples of deliberate evasion it does NOT catch (the list is+not exhaustive): a default supplied from outside the class body or+signature -- by a metaclass, decorator or ``__init_subclass__``, or set+after the class body (``Cls.attr = Depends()``, ``f.__defaults__ =+...``); walrus bindings in subscript targets or in+other annotations; module-level string or type aliases of a fenced name+(``Svc = "NoteService"`` then ``svc: Svc = Depends()``); and the known+gaps listed below.++LDR's cross-user object isolation is architectural: notes, documents,+downloads and research rows live in per-user *encrypted* databases, so+IDOR is impossible only while every access goes through a+service/session constructed for the requesting user.++What this hook checks is deliberately shallow -- a fast pre-commit+smoke check: every call to a constructor in ``USER_DATA_CONSTRUCTORS``+(by bare name, under an import alias such as ``from ... import+LibraryService as LS``, or as a module attribute ``mod.NoteService``)+under ``ISOLATION_SCAN_DIRS`` (the routers, ``research_library/`` and+``web/services/``) must pass a username explicitly: a positional+``username`` / ``self.username``-style name, or a keyword whose name+contains ``username`` (``username=``, ``owner_username=``). Any keyword+whose name contains ``username`` bound to a literal constant (``None``,+``"alice"``, a placeholder-free ``f"alice"``) is flagged, whatever the+other arguments are. A username-named *value* under another keyword+(``NoteService(owner=username)``) does not count. It catches a+defaulted or shared-session construction. Any non-literal ``username=``+expression is accepted, so constant-valued expressions such as+``username=str(None)`` or ``username=None or x`` are NOT flagged; nor+are dynamic lookups (``getattr``, ``importlib``).++A constructor must not leave a scanned file under a name this hook+does not recognise, since no rule follows a name across modules: an+import alias that is not itself a constructor name (``from x import+get_user_db_session as open_session``; leading underscores are+ignored, so ``as _get_user_db_session`` is fine and its calls are+checked) and any loaded non-call reference (``make = NoteService``,+``partial(get_user_db_session, ...)``, ``class Mine(NoteService)``)+are flagged, except in a type-only annotation. An annotation is NOT+type-only -- it counts as a reference, and a constructor quoted in a+string inside it counts too -- when it is evaluated into more than a+type: a parameter or class-body field annotation (wherever the field+sits in the class body, also under ``if`` / ``try``, and whatever+binds its name there: ``svc: NoteService`` then ``svc = Depends()``)+whose default is not a constant (``svc: NoteService = Depends()``, ``= Depends(None)``,+``= dep``: FastAPI then constructs the annotated class itself, with+``username`` filled from the request, e.g. ``?username=``), an+``Annotated[...]`` with a non-constant metadata element+(``Annotated[NoteService, Depends()]``, ``Annotated[T,+Depends(get_user_db_session)]``), a starred element+(``Annotated[*(NoteService, dep)]``) or a non-tuple slice, any call,+walrus or lambda inside it (``x: (s := get_user_db_session) = 1`` binds+the constructor in the enclosing scope), a class field with no binding+in its own class body on a class with a base other than ``object`` /+``Generic`` / ``Protocol`` (it may inherit a ``Depends()`` default), or+a string that does not parse. A string in a type position that does+not parse as an expression (``"*[NoteService]"`` is a valid ForwardRef+but not an expression) or nests deeper than ``_MAX_QUOTE_DEPTH`` is+also reported on its own, as an annotation string that cannot be+checked (strings that are plain values -- call arguments, ``Literal``+members, ``Annotated`` metadata -- are not). Every string in a type position is+parsed and checked like unquoted code, recursively, since FastAPI+evaluates it: a wholly quoted ``"Annotated[NoteService, Depends()]"``+is as live as the unquoted form (``Annotated`` metadata strings are+plain values and are not parsed). An attribute read off a+constructor is a non-call reference too (``NoteService.__call__``,+``get_user_db_session.__wrapped__``, ``NoteService.__new__(...)``,+``FollowUpResearchService.__call__()``, ``NoteService.some_method``),+since the attribute can be, or can produce, the unchecked constructor;+the only exemptions are an ALL_CAPS constant (``^[A-Z][A-Z0-9_]*$``,+e.g. ``NoteAIService.MAX_CLAIMS_PER_NOTE``) and the+(constructor, attribute) pairs pinned in ``ALLOWED_ATTRIBUTE_READS``.+An ALL_CAPS attribute is exempt by its name alone, whatever it holds+(a callable bound to ``NoteService.FACTORY`` would not be seen).+Known gaps (NOT fenced): a rename, re-export, wrapper or dependency+factory in a module OUTSIDE ISOLATION_SCAN_DIRS (e.g. one in+``web/dependencies/`` that builds a ``NoteService`` from a request+parameter; for the routers, injecting such an identity-taking callable+via ``Depends`` is caught by the census test+``test_no_dependency_takes_a_user_identity_from_the_request``); dynamic+lookups (``getattr``, ``importlib``, ``__import__``, ``globals()`` /+``module.__dict__[...]``, ``eval``); ``Annotated`` reached through an+assignment alias (``A = Annotated``) with non-call metadata+(``svc: A[NoteService, dep]``; an ``import ... as`` alias is+recognised); and constant-valued non-literal ``username=`` expressions+(above). It+does NOT check where that username came from: ``NoteService(+victim_username)`` or ``get_user_db_session(username=request.+query_params["u"])`` pass here. Provenance (the value must be the+``require_auth``-derived username) is enforced by the census in+tests/security/test_cross_user_isolation_census.py+(``test_identity_sinks_only_ever_receive_the_authenticated_username``,+``test_every_get_user_db_session_call_is_passed_an_auth_username``)+for call sites in ``web/routers/*.py`` only; outside the routers this+hook's shape check is the only fence.++A file that cannot be read or parsed (syntax error, undecodable bytes,+nesting too deep for the parser, an OS error) is reported as an+offender, never skipped, and never crashes the run. Files are parsed+from bytes, so a UTF-8 BOM or a PEP 263 coding cookie is honoured.++The companion contract (tests/security/test_architecture_fences.py)+runs this same scanner over ISOLATION_SCAN_DIRS, pre-commit style+(repo-root cwd, repo-relative paths). Every path argument is made+absolute (relative ones against the cwd) and taken relative to the+repository root twice -- lexically (``..`` collapsed, symlinks not+followed) and resolved (symlinks followed) -- and the file is scanned+if EITHER form is in ISOLATION_SCAN_DIRS, so ``..`` segments, a+non-root cwd, or a symlink inside a scanned dir pointing elsewhere+cannot move a file out of scope. Repo files outside+ISOLATION_SCAN_DIRS (both forms) are skipped; files outside the+repository (mutation fixtures) are always scanned.+"""++import ast+import re+import sys+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parent.parent++#: Constructors whose instances mediate per-user data. The deletion+#: services are destructive; ``FollowUpResearchService`` defaults its+#: ``username`` to None, so a bare ``FollowUpResearchService()`` is+#: exactly the defaulted construction this hook exists to catch.+USER_DATA_CONSTRUCTORS = frozenset(+ {+ "NoteService",+ "LibraryService",+ "DownloadService",+ "get_user_db_session",+ "DocumentDeletionService",+ "CollectionDeletionService",+ "BulkDeletionService",+ "NoteAIService",+ "FollowUpResearchService",+ }+)++#: Attribute reads off a constructor that are NOT ALL_CAPS constants+#: but are known not to construct anything, as (constructor, attribute).+#: Every other non-constant attribute read off a constructor is flagged+#: (fail closed): a dunder (``__call__``, ``__wrapped__``, ``__new__``,+#: ``__init__``, ``__func__``) or a classmethod could build the object+#: without a username under a name no rule checks.+ALLOWED_ATTRIBUTE_READS = frozenset(+ {+ # staticmethod taking an existing session; constructs nothing.+ ("NoteService", "_rollback_quietly"),+ }+)++#: Attribute names read as plain constants (``MAX_CLAIMS_PER_NOTE``).+#: No leading underscore, so no dunder ever matches.+_CONSTANT_ATTRIBUTE = re.compile(r"[A-Z][A-Z0-9_]*")++#: Trees (repo-relative, trailing slash) where user-data constructions+#: must pass a username: the routers plus the service layers they call.+ISOLATION_SCAN_DIRS = (+ "src/local_deep_research/web/routers/",+ "src/local_deep_research/research_library/",+ "src/local_deep_research/web/services/",+)+++def _names_username(node: ast.AST) -> bool:+ # Bare names (username, alice_username) and bound attributes+ # (self.username) both count as a username-named value.+ if isinstance(node, ast.Name):+ return "username" in node.id+ if isinstance(node, ast.Attribute):+ return "username" in node.attr+ return False+++def _is_literal(node: ast.AST) -> bool:+ # A constant, or an f-string with no placeholder (f"alice").+ if isinstance(node, ast.Constant):+ return True+ return isinstance(node, ast.JoinedStr) and not any(+ isinstance(part, ast.FormattedValue) for part in node.values+ )+++def _mentions_username(call: ast.Call) -> bool:+ username_kws = [+ kw for kw in call.keywords if kw.arg and "username" in kw.arg+ ]+ # username=None / username="alice" / username=f"alice" is flagged+ # even if another argument names a username.+ if any(_is_literal(kw.value) for kw in username_kws):+ return False+ return bool(username_kws) or any(_names_username(arg) for arg in call.args)+++def _constructor(name: str | None) -> str | None:+ """The constructor ``name`` denotes, ignoring leading underscores+ (``_get_user_db_session`` -> ``get_user_db_session``), or None."""+ if name is None:+ return None+ stripped = name.lstrip("_")+ return stripped if stripped in USER_DATA_CONSTRUCTORS else None+++def _constructor_aliases(tree: ast.AST) -> dict[str, str]:+ """Local alias -> constructor name (``LS`` -> ``LibraryService``)."""+ aliases: dict[str, str] = {}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ real = _constructor(alias.name)+ if alias.asname and real:+ aliases[alias.asname] = real+ return aliases+++def _resolve(node: ast.AST, aliases: dict[str, str]) -> str | None:+ if isinstance(node, ast.Name):+ return aliases.get(node.id) or _constructor(node.id)+ if isinstance(node, ast.Attribute):+ return _constructor(node.attr)+ return None+++#: Annotation content that is evaluated into something other than a+#: type (see ``_annotations``): a call (``Depends(get_user_db_session)``), a walrus (binds in+#: the enclosing scope, since annotations are evaluated eagerly) or a+#: lambda.+_EVALUATED = (ast.Call, ast.NamedExpr, ast.Lambda)+++def _annotated_names(tree: ast.AST) -> set[str]:+ """``Annotated`` plus every local name it is imported as."""+ names = {"Annotated"}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ names.update(+ alias.asname+ for alias in node.names+ if alias.name == "Annotated" and alias.asname+ )+ return names+++#: Nesting bound for quoted annotations (a string inside a string ...):+#: a string nested deeper than this counts as evaluated (fail closed)+#: and, in a type position, is reported as unchecked.+_MAX_QUOTE_DEPTH = 8++#: Offender text for a string in a type position the hook cannot check.+_UNCHECKED_STRING = (+ "annotation string that cannot be checked (it does not parse as an "+ "expression, or quotes nest deeper than "+ f"{_MAX_QUOTE_DEPTH}); write the annotation unquoted or as a valid "+ "forward reference"+)+++def _is_literal_head(node: ast.AST) -> bool:+ """True if ``node`` is ``Literal[...]`` (bare or qualified): its+ strings are values, never evaluated as types."""+ if not isinstance(node, ast.Subscript):+ return False+ head = node.value+ return (isinstance(head, ast.Name) and head.id == "Literal") or (+ isinstance(head, ast.Attribute) and head.attr == "Literal"+ )+++def _is_annotated_head(node: ast.AST, annotated: set[str]) -> bool:+ """True if ``node`` is a subscript of ``Annotated`` (under any import+ alias, or qualified as ``typing.Annotated``)."""+ if not isinstance(node, ast.Subscript):+ return False+ head = node.value+ return (isinstance(head, ast.Name) and head.id in annotated) or (+ isinstance(head, ast.Attribute) and head.attr == "Annotated"+ )+++def _annotation_nodes(+ root: ast.AST, annotated: set[str]+) -> tuple[list[tuple[ast.AST, int | None]], bool, list[int]]:+ """Every node of an annotation, quoted parts included.++ Returns ``(nodes, unparsable, unchecked)``. ``nodes`` holds+ ``(node, line)``+ pairs: ``line`` is None for a node of ``root`` itself and, for a node+ parsed out of a string, the line of the outermost string literal+ holding it. FastAPI (via ``typing.get_type_hints``) evaluates a+ quoted annotation, so every string in a type position is parsed as+ an expression, recursively (``"Annotated[NoteService, Depends()]"``,+ ``Optional["NoteService"]``), and the parsed tree is inspected+ exactly like an unquoted one. ``unparsable`` is True if any such+ string does not parse or nests deeper than ``_MAX_QUOTE_DEPTH`` (fail+ closed: the caller treats the annotation as evaluated).+ ``unchecked`` lists, by the line of its outermost string literal,+ each such string that sits in a type position, which the caller+ reports as an offender: a string that is a plain value -- anywhere+ inside ``Annotated`` metadata, a ``Literal[...]`` or the arguments+ of a call (``Query(description="...")``) -- is never evaluated as a+ type, so it is not reported. ``"*[NoteService]"`` is valid as a+ ``ForwardRef`` but not as an expression, so it is unchecked.++ Not parsed: the metadata strings of an ``Annotated[T, "doc"]``+ (elements after the first), which are kept as plain values and+ never evaluated.+ """+ nodes: list[tuple[ast.AST, int | None]] = []+ unparsable = False+ unchecked: list[int] = []+ values: set[int] = set()+ # ids of every node in a value (non-type) position.+ plain: set[int] = set()+ pending: list[tuple[ast.AST, int, int | None, bool]] = [+ (root, 0, None, False)+ ]+ while pending:+ current, depth, line, in_value = pending.pop()+ for node in ast.walk(current):+ nodes.append((node, line))+ if _is_annotated_head(node, annotated) and isinstance(+ node.slice, ast.Tuple+ ):+ values.update(id(meta) for meta in node.slice.elts[1:])+ for meta in node.slice.elts[1:]:+ plain.update(id(n) for n in ast.walk(meta))+ if _is_literal_head(node):+ plain.update(id(n) for n in ast.walk(node.slice))+ if isinstance(node, ast.Call):+ for arg in [*node.args, *node.keywords]:+ plain.update(id(n) for n in ast.walk(arg))+ if (+ not (+ isinstance(node, ast.Constant)+ and isinstance(node.value, str)+ )+ or id(node) in values+ ):+ continue+ here = node.lineno if line is None else line+ is_value = in_value or id(node) in plain+ if depth >= _MAX_QUOTE_DEPTH:+ unparsable = True+ if not is_value:+ unchecked.append(here)+ continue+ try:+ parsed = ast.parse(node.value.strip(), mode="eval")+ except (SyntaxError, ValueError, RecursionError, MemoryError):+ unparsable = True+ if not is_value:+ unchecked.append(here)+ continue+ pending.append((parsed.body, depth + 1, here, is_value))+ return nodes, unparsable, unchecked+++def _has_evaluated_metadata(+ nodes: list[tuple[ast.AST, int | None]], annotated: set[str]+) -> bool:+ """True if an ``Annotated[...]`` among ``nodes`` is anything but+ ``Annotated[T, constant, ...]``: a non-constant metadata element+ (``Annotated[T, dep]`` with ``dep = Depends()`` hands FastAPI a+ dependency without a call), a starred element (``Annotated[*(T,+ dep)]`` unpacks to the same thing) or a slice that is not a tuple+ (``Annotated[args]`` with ``args = (T, dep)``)."""+ for node, _line in nodes:+ if not _is_annotated_head(node, annotated):+ continue+ if not isinstance(node.slice, ast.Tuple):+ return True+ elements = node.slice.elts+ if any(isinstance(element, ast.Starred) for element in elements):+ return True+ if any(not isinstance(meta, ast.Constant) for meta in elements[1:]):+ return True+ return False+++#: Nodes that open their own scope: a store inside them never binds a+#: class attribute.+_NEW_SCOPES = (+ ast.FunctionDef,+ ast.AsyncFunctionDef,+ ast.ClassDef,+ ast.Lambda,+ ast.ListComp,+ ast.SetComp,+ ast.DictComp,+ ast.GeneratorExp,+)+_BLOCKS = (ast.stmt, ast.excepthandler, ast.match_case)+++def _class_body_blocks(cls: ast.ClassDef) -> list[ast.AST]:+ """Every statement (and ``except`` / ``case`` clause) executed in+ ``cls``'s own body, including those nested under ``if`` / ``try`` /+ ``with`` / ``for`` / ``while`` / ``match``, but not the bodies of a+ nested def or class (the def or class statement itself is+ included: it binds its name)."""+ blocks: list[ast.AST] = []+ pending: list[ast.AST] = list(cls.body)+ while pending:+ block = pending.pop()+ blocks.append(block)+ if not isinstance(block, _NEW_SCOPES):+ pending.extend(+ child+ for child in ast.iter_child_nodes(block)+ if isinstance(child, _BLOCKS)+ )+ return blocks+++def _own_expressions(block: ast.AST) -> list[ast.AST]:+ """The expression nodes of one statement or clause, not descending+ into nested statements or into a nested scope."""+ nodes: list[ast.AST] = []+ pending = [+ child+ for child in ast.iter_child_nodes(block)+ if not isinstance(child, _BLOCKS)+ ]+ while pending:+ node = pending.pop()+ nodes.append(node)+ if not isinstance(node, _NEW_SCOPES):+ pending.extend(ast.iter_child_nodes(node))+ return nodes+++#: Bases that never supply a class attribute (a field default).+_PLAIN_BASES = frozenset({"object", "Generic", "Protocol"})+++def _may_inherit_defaults(cls: ast.ClassDef) -> bool:+ """True if ``cls`` has a base other than ``object`` / ``Generic`` /+ ``Protocol`` (bare, qualified or subscripted), so a field it leaves+ without a default may inherit one from that base."""+ for base in cls.bases:+ head = base.value if isinstance(base, ast.Subscript) else base+ if isinstance(head, ast.Name):+ name = head.id+ elif isinstance(head, ast.Attribute):+ name = head.attr+ else:+ return True+ if name not in _PLAIN_BASES:+ return True+ return False+++def _class_field_defaults(cls: ast.ClassDef) -> dict[int, ast.AST]:+ """``id(field)`` -> its default, for every annotated assignment in+ ``cls``'s own body (see ``_class_body_blocks``).++ A dataclass (or FastAPI, via the generated ``__init__``) reads a+ field's default from the class attribute, so EVERY binding of the+ field's name in the class body counts, not just ``x: T = value``:+ ``svc: NoteService`` followed by ``svc = Depends()`` defaults the+ field to ``Depends()``. A plain ``name = value`` contributes+ ``value``; any other binding (augmented or unpacking assignment,+ loop / ``with`` / ``except`` / ``case`` target, import, def, class,+ walrus) contributes the binding statement itself, which is never a+ constant (fail closed). The default is the first non-constant+ contribution, else the field's own value. A field with no binding+ at all in the class body of a class with any base other than+ ``object`` / ``Generic`` / ``Protocol`` may inherit its default+ from that base, so its default is the class itself, which is never+ a constant (fail closed).+ """+ blocks = _class_body_blocks(cls)+ bound: dict[str, list[ast.AST]] = {}++ def bind(name: str | None, value: ast.AST) -> None:+ if name:+ bound.setdefault(name, []).append(value)++ fields: list[ast.AnnAssign] = []+ for block in blocks:+ if isinstance(block, ast.AnnAssign):+ fields.append(block)+ if block.value is not None and isinstance(block.target, ast.Name):+ bind(block.target.id, block.value)+ if block.value is not None:+ for node in ast.walk(block.value):+ if isinstance(node, ast.NamedExpr):+ bind(node.target.id, block)+ continue+ if (+ isinstance(block, ast.Assign)+ and len(block.targets) == 1+ and isinstance(block.targets[0], ast.Name)+ ):+ bind(block.targets[0].id, block.value)+ for node in ast.walk(block.value):+ if isinstance(node, ast.NamedExpr):+ bind(node.target.id, block)+ continue+ if isinstance(block, _NEW_SCOPES):+ bind(block.name, block)+ elif isinstance(block, (ast.Import, ast.ImportFrom)):+ for alias in block.names:+ bind(alias.asname or alias.name.split(".")[0], block)+ elif isinstance(block, ast.excepthandler):+ bind(block.name, block)+ for node in _own_expressions(block):+ if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):+ bind(node.id, block)+ elif isinstance(node, (ast.MatchAs, ast.MatchStar)):+ bind(node.name, block)+ elif isinstance(node, ast.MatchMapping):+ bind(node.rest, block)+ defaults: dict[int, ast.AST] = {}+ inherits = _may_inherit_defaults(cls)+ for field in fields:+ values = (+ bound.get(field.target.id, [])+ if isinstance(field.target, ast.Name)+ else []+ )+ chosen = next(+ (v for v in values if not isinstance(v, ast.Constant)),+ field.value,+ )+ if chosen is None and inherits:+ chosen = cls+ if chosen is not None:+ defaults[id(field)] = chosen+ return defaults+++def _annotations(tree: ast.AST) -> list[tuple[ast.AST, bool]]:+ """Every annotation as ``(annotation, type_only)``.++ An annotation is type-only -- never a rebinding -- unless:++ * it contains a call, walrus or lambda anywhere+ (``Annotated[T, Depends(get_user_db_session)]`` hands the callable to+ FastAPI; ``x: (s := get_user_db_session) = 1`` binds it in the enclosing+ scope, since annotations are evaluated eagerly before 3.14);+ * it is a parameter's or a class-body field's annotation (a+ dataclass field becomes an ``__init__`` parameter) whose default+ is not a constant: ``svc: NoteService = Depends()``, ``= Depends(None)``+ or ``= dep`` with ``dep = Depends()`` makes FastAPI CALL the+ annotated class, filling its parameters from the request;+ * an ``Annotated[...]`` in it (under any import alias) carries a+ non-constant metadata element (``Annotated[class, dep]``), a+ starred element (``Annotated[*(class, dep)]``) or a slice that is+ not a tuple (``Annotated[args]``);+ * a string in it does not parse as an expression, or nests too+ deep (fail closed; one in a type position is also reported+ itself, see ``_string_annotation_hits``);+ * it is a class field with no binding in its own class body, on a+ class with a base other than ``object`` / ``Generic`` /+ ``Protocol``: the field may inherit a non-constant default.++ Every string in a type position is parsed and checked like unquoted+ code, recursively (see ``_annotation_nodes``), so a wholly quoted+ ``"Annotated[class, Depends()]"`` is not type-only either. A class+ field counts wherever it sits in the class body, also under ``if`` /+ ``try`` / ``with`` / loops, and its default is any binding of its+ name there (``svc: T`` then ``svc = Depends()``; see+ ``_class_field_defaults``).++ Callee names are not matched, so ``Depends`` imported under another+ name cannot hide a dependency (fail closed). Return annotations and+ module- or function-level variable annotations have no default.+ """+ annotated = _annotated_names(tree)+ defaults: dict[int, ast.AST] = {}+ for node in ast.walk(tree):+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):+ args = node.args+ positional = args.posonlyargs + args.args+ offset = len(positional) - len(args.defaults)+ for arg, default in zip(positional[offset:], args.defaults):+ defaults[id(arg)] = default+ for arg, default in zip(args.kwonlyargs, args.kw_defaults):+ if default is not None:+ defaults[id(arg)] = default+ elif isinstance(node, ast.ClassDef):+ defaults.update(_class_field_defaults(node))+ found: list[tuple[ast.AST, bool]] = []+ for node in ast.walk(tree):+ if (+ isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))+ and node.returns is not None+ ):+ root, default = node.returns, None+ elif isinstance(node, ast.arg) and node.annotation is not None:+ root, default = node.annotation, defaults.get(id(node))+ elif isinstance(node, ast.AnnAssign):+ root, default = node.annotation, defaults.get(id(node))+ else:+ continue+ nodes, unparsable, _unchecked = _annotation_nodes(root, annotated)+ type_only = (+ (default is None or isinstance(default, ast.Constant))+ and not unparsable+ and not any(isinstance(n, _EVALUATED) for n, _line in nodes)+ and not _has_evaluated_metadata(nodes, annotated)+ )+ found.append((root, type_only))+ return found+++def _annotation_ids(tree: ast.AST) -> set[int]:+ """ids of every node inside a type-only annotation (see+ ``_annotations``), which is never a rebinding."""+ return {+ id(child)+ for root, type_only in _annotations(tree)+ if type_only+ for child in ast.walk(root)+ }+++def _string_annotation_hits(+ tree: ast.AST, aliases: dict[str, str]+) -> list[tuple[int, str]]:+ """Constructors named inside a STRING in a non-type-only annotation.++ FastAPI resolves a forward reference (``svc: "NoteService" =+ Depends()``, or a wholly quoted ``"Annotated[NoteService,+ Depends()]"``) in the module globals, so a quoted constructor name+ is as live there as a bare one. Strings are parsed recursively (see+ ``_annotation_nodes``); one in a type position that does not parse+ (or nests too deep) is reported itself, as an annotation string that+ cannot be checked."""+ annotated = _annotated_names(tree)+ hits: list[tuple[int, str]] = []+ for root, type_only in _annotations(tree):+ if type_only:+ continue+ nodes, _unparsable, unchecked = _annotation_nodes(root, annotated)+ hits.extend((line, _UNCHECKED_STRING) for line in unchecked)+ for inner, line in nodes:+ if line is None:+ continue+ real = _resolve(inner, aliases)+ if real:+ hits.append(+ (+ line,+ f"non-call reference to {real} (quoted in an "+ "evaluated annotation; user-data constructors "+ "must be called directly)",+ )+ )+ return hits+++def _rebindings(+ tree: ast.AST, aliases: dict[str, str], callees: set[int]+) -> list[tuple[int, str]]:+ """Ways a constructor escapes under a name this hook does not know.++ * ``from x import get_user_db_session as open_session``: any module+ importing ``open_session`` from here would call it unchecked, so+ an import alias must itself be a constructor name (leading+ underscores allowed: ``as _get_user_db_session``).+ * A loaded non-call reference (``make = NoteService``,+ ``partial(get_user_db_session, ...)``, ``return NoteService``,+ ``class Mine(NoteService)``), including the object of an+ attribute read (``NoteService.__call__``, ``get_user_db_session.+ __wrapped__``), whether or not that attribute is then called. Not+ counted: the callee of a call, a type-only annotation (see+ ``_annotations``: e.g. one with a non-constant default, or holding+ a call, walrus or lambda, still counts), and the object of+ an ALL_CAPS constant read (``NoteAIService.MAX_CLAIMS_PER_NOTE``)+ or of an ``ALLOWED_ATTRIBUTE_READS`` pair.+ * A constructor quoted in a non-type-only annotation+ (``svc: "NoteService" = Depends()``).+ """+ hits: list[tuple[int, str]] = _string_annotation_hits(tree, aliases)+ exempt = _annotation_ids(tree) | callees+ # id(constructor node) -> the non-exempt attribute read off it.+ read_attr: dict[int, str] = {}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ real = _constructor(alias.name)+ if real and alias.asname and not _constructor(alias.asname):+ hits.append(+ (+ node.lineno,+ f"{real} imported as {alias.asname} (an alias "+ "must keep a constructor name, e.g. "+ f"_{real})",+ )+ )+ elif isinstance(node, ast.Attribute):+ owner = _resolve(node.value, aliases)+ if owner is None:+ continue+ if (+ _CONSTANT_ATTRIBUTE.fullmatch(node.attr)+ or (owner, node.attr) in ALLOWED_ATTRIBUTE_READS+ ):+ exempt.add(id(node.value))+ else:+ read_attr[id(node.value)] = node.attr+ for node in ast.walk(tree):+ if not isinstance(node, (ast.Name, ast.Attribute)):+ continue+ if not isinstance(node.ctx, ast.Load) or id(node) in exempt:+ continue+ real = _resolve(node, aliases)+ if real:+ via = (+ f" (via .{read_attr[id(node)]}: only ALL_CAPS constants "+ "and ALLOWED_ATTRIBUTE_READS may be read off a constructor)"+ if id(node) in read_attr+ else ""+ )+ hits.append(+ (+ node.lineno,+ f"non-call reference to {real}{via} (user-data "+ "constructors must be called directly)",+ )+ )+ return hits+++def _parse(path: Path) -> tuple[ast.AST | None, str]:+ """Parse ``path``, or return ``(None, offender line)``.++ Fail closed: an unreadable or unparsable file is reported, never+ skipped, and a parser failure (too-deep nesting raises RecursionError+ or MemoryError) never crashes the run.+ """+ try:+ source = path.read_bytes()+ except OSError as exc:+ return None, f"{path}:1: could not read ({type(exc).__name__}: {exc})"+ try:+ # Bytes, not text: ast.parse then honours a UTF-8 BOM and a PEP+ # 263 coding cookie exactly as the interpreter does.+ return ast.parse(source, filename=str(path)), ""+ except (SyntaxError, ValueError, RecursionError, MemoryError) as exc:+ lineno = getattr(exc, "lineno", None) or 1+ return (+ None,+ f"{path}:{lineno}: could not parse ({type(exc).__name__}: {exc})",+ )+++def scan_file(path: Path) -> list[str]:+ offenders: list[str] = []+ tree, error = _parse(path)+ if tree is None:+ return [error]+ aliases = _constructor_aliases(tree)+ callees: set[int] = set()+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ callees.add(id(node.func))+ name = _resolve(node.func, aliases)+ if name and not _mentions_username(node):+ offenders.append(+ f"{path}:{node.lineno}: {name}(...) without an explicit "+ "username argument"+ )+ for lineno, what in _rebindings(tree, aliases, callees):+ offenders.append(f"{path}:{lineno}: {what}")+ return offenders+++def _repo_relative(path: Path) -> tuple[str | None, str | None]:+ """``(lexical, resolved)`` repo-relative posix paths of ``path``;+ each is None if that form of the path lies outside the repo.++ Both are absolute-ised against the cwd, so ``..`` segments and a cwd+ other than the repo root still yield the true repo-relative path.+ The lexical form only normalises ``..`` textually (symlinks are not+ followed); the resolved form follows symlinks. The caller scans a+ file if EITHER form is in scope, so a symlink inside a scanned dir+ whose target lies elsewhere is still scanned (fail closed).+ """++ def rel(candidate: Path) -> str | None:+ try:+ return candidate.relative_to(REPO_ROOT).as_posix()+ except ValueError:+ return None++ # Collapse ``..`` textually (pathlib keeps it; resolve() would+ # follow symlinks): ``a/link/../b`` -> ``a/b``.+ parts: list[str] = []+ for part in path.absolute().parts:+ if part == "..":+ if len(parts) > 1:+ parts.pop()+ elif part != ".":+ parts.append(part)+ lexical = rel(Path(*parts))+ return lexical, rel(path.resolve())+++def _safe_print(line: str) -> None:+ """Print ``line`` without crashing on undecodable path bytes.++ Argv path arguments are decoded with surrogateescape, so an+ offender line built from a non-UTF-8 filename can carry lone+ surrogates that a strict stdout encoder refuses to write+ (``UnicodeEncodeError``). Round-tripping through the+ ``backslashreplace`` error handler turns any such surrogate into a+ literal, printable escape instead of crashing the hook.+ """+ encoding = sys.stdout.encoding or "utf-8"+ print(+ line.encode(encoding, "backslashreplace").decode(+ encoding, "backslashreplace"+ )+ )+++def main(argv: list[str]) -> int:+ offenders: list[str] = []+ for arg in argv:+ path = Path(arg)+ if not path.suffix == ".py" or not path.is_file():+ continue+ in_repo = [r for r in _repo_relative(path) if r is not None]+ if in_repo and not any(+ r.startswith(ISOLATION_SCAN_DIRS) for r in in_repo+ ):+ continue+ offenders.extend(scan_file(path))+ if offenders:+ _safe_print(+ "Per-user isolation fence: user-data access without username:"+ )+ for offender in offenders:+ _safe_print(f" {offender}")+ _safe_print(+ "Construct user-data services/sessions with the require_auth "+ "username (per-user encrypted DBs are the isolation boundary)."+ )+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main(sys.argv[1:]))diff --git a/.pre-commit-hooks/check-reports-dir-not-served.py b/.pre-commit-hooks/check-reports-dir-not-served.pynew file mode 100755index 0000000000..a14f11af8d--- /dev/null+++ b/.pre-commit-hooks/check-reports-dir-not-served.py@@ -0,0 +1,1180 @@+#!/usr/bin/env python3+"""+Pre-commit hook: fence the web layer's HTTP file-serving references.++Report artifacts land in a single directory shared by the whole+install. Their cross-user safety posture rests on three facts: writes+are confined to the root, absolute paths are never disclosed, and --+what this hook fences -- **no HTTP handler streams files from that+directory**. A future "download the generated report file" feature+that hands a user-controlled or guessable path to ``FileResponse`` /+``StaticFiles`` would turn the shared directory into a cross-user read+primitive.++Scope: this hook is a syntax fence against ACCIDENTAL or IDIOMATIC+code -- the shapes a contributor writes without meaning to bypass+anything. Deliberate evasion by a contributor is out of scope and is+left to code review (CODEOWNERS); the hook does not try to be a+sandbox. Examples of deliberate evasion it does NOT catch (the list is+not exhaustive): a default supplied from outside the class body or+signature -- by a metaclass, decorator or ``__init_subclass__``, or set+after the class body (``Cls.attr = Depends()``, ``f.__defaults__ =+...``); walrus bindings in subscript targets or in+other annotations; module-level string or type aliases of a fenced name+(``R = "FileResponse"`` then ``r: R = Depends()``); and the gaps listed+under "Out of scope" below.++Tracking where a path value came from (local bindings, attributes,+return values) is not something a pre-commit AST check can do+reliably, so the fence is deliberately coarse. Under+``src/local_deep_research/web/`` it flags:++1. Any reference to a file-serving primitive (``FileResponse``,+ ``StaticFiles``, ``StreamingResponse`` -- imported under any alias,+ or reached as a module attribute such as ``responses.FileResponse``)+ and any star import, except in the files listed in+ ``ALLOWED_FILES``. The allowlist is per *file*: everything in an+ allowlisted file is exempt from this rule (all of+ ``web/fastapi_app.py``, not only its static-asset routes).+2. Any call to LDR's own serving wrappers -- a name ending in+ ``StreamingResponse`` / ``FileResponse`` that is not itself a+ primitive, e.g. ``WorkerCleanupStreamingResponse`` from the+ allowlisted ``web/dependencies/threadpool.py``, under any import+ alias or as a module attribute -- whose content argument (first+ positional or ``content=``) is not a direct call, by bare name, to a+ *same-module generator*: an undecorated ``def`` / ``async def``+ defined at module level or nested in another function -- NOT one+ anywhere inside a class body, so a method or a function nested in a+ method never qualifies (fail closed) -- whose own body contains+ ``yield`` / ``yield from`` (yields inside its nested functions,+ lambdas or classes do not count). The name qualifies only if EVERY+ ``def`` of it anywhere in the module (methods and defs nested in+ methods included) is an undecorated generator -- a decorator can+ replace the function, so a decorated def disqualifies its name --+ nothing else in the module binds it (assignment incl. a lambda,+ walrus, ``for``/``with`` target, ``del``, import or import alias,+ parameter, class, ``except`` target, ``global``/``nonlocal``, match+ capture) and it is not a Python builtin, so ``open`` or ``iter``+ never qualifies by colliding with a local function or method. A+ ``from x import *`` anywhere in the module disqualifies EVERY+ candidate, since a star import can rebind any name without the+ scanner being able to tell which ones statically.+ ``open(p)``, ``iter(open(p))``, a helper that returns ``open(p)``, a+ path, a variable or an attribute read are flagged. The *arguments*+ of the accepted generator call are not inspected:+ ``W(passthru(open(p)))`` with a same-module generator ``passthru``+ is accepted. This applies in every scanned file, allowlisted ones+ included.+ Outside the allowlist, any non-call reference to such a wrapper or+ to a ``SERVING_HELPERS`` helper (rebinding it to another name,+ subclassing it, passing it as a value) is flagged too.+3. Any serving call (primitive, wrapper, or a serving helper named in+ ``SERVING_HELPERS`` such as ``static_file_response`` -- under any+ import alias or as a module attribute) whose arguments reference the+ outputs directory inline (``OUTPUT_DIR``,+ ``get_research_outputs_directory()``, ``.outputs_dir``, or a name+ they are imported as, e.g. ``from x import OUTPUT_DIR as OD``). This+ also applies in every scanned file, allowlisted ones included. The+ helper arm is defensive: ``static_file_response`` lives in an+ allowlisted file, so rule 1 never sees the primitive it calls, and+ although its current signature takes only ``path`` (the root is+ always ``STATIC_DIR``), a call handing it the outputs directory in+ any position or keyword is still flagged, so a future signature+ that grows a directory parameter cannot silently serve the shared+ directory from a router.++4. Re-export under an unrecognised name, in every scanned file+ (allowlisted ones included): ``from x import <primitive or+ wrapper> as <alias>`` unless the alias is itself a serving name+ (a primitive, or ends in ``StreamingResponse`` / ``FileResponse``),+ and ``from x import <helper> as <alias>`` unless the alias is a+ serving or helper name. Otherwise a second module could import the+ alias (``from ..utils.streaming import CleanupStream``) and call it+ with no rule applying, since no rule follows a name across modules.+ Leading underscores are ignored when matching a helper name+ (``as _static_file_response`` keeps the role). Inside an allowlisted+ file, any loaded non-call reference to a primitive, wrapper or+ helper is flagged (``Download = WorkerCleanupStreamingResponse``,+ ``return FileResponse``, ``partial(static_file_response, ...)``),+ except in a type-only annotation, and a class may subclass one only if its+ own name ends in ``StreamingResponse`` / ``FileResponse`` (so the+ wrapper rules follow it into every importer). With rule 2's+ non-call rule outside the allowlist, a serving callable can reach+ another module of the fenced tree only under a name the rules+ recognise.+5. Evaluated annotations, in every scanned file. An annotation is not+ type-only when FastAPI or the interpreter evaluates it into more+ than a type: a parameter or class-body field annotation (wherever+ the field sits in the class body, also under ``if`` / ``try``, and+ whatever binds its name there: ``f: T`` then ``f = Depends()``)+ whose default is not a constant (``= Depends()`` makes FastAPI itself+ call the annotated class, filling its parameters from the request;+ FastAPI refuses some response classes, ``FileResponse`` among them,+ at route registration, but the hook does not rely on which classes+ it accepts and flags ``r: FileResponse = Depends()`` all the same),+ an ``Annotated[...]`` with a non-constant metadata element+ (``Annotated[T, Depends(static_file_response)]`` calls the helper+ with a request-supplied ``path``), a starred element or a non-tuple+ slice, any call, walrus or lambda inside it, a class field with no+ binding in its own class body on a class with a base other than+ ``object`` / ``Generic`` / ``Protocol`` (it may inherit a+ ``Depends()`` default), or a string that does not parse. In every+ scanned file, a string in a type position that does not parse as an+ expression (``"*[FileResponse]"`` is a valid ForwardRef but not an+ expression) or nests deeper than ``_MAX_QUOTE_DEPTH`` is reported on+ its own, as an annotation string that cannot be checked (strings+ that are plain values -- call arguments, ``Literal`` members,+ ``Annotated`` metadata -- are not). Every string in a type position is+ parsed and checked like unquoted code, recursively, since FastAPI+ evaluates it (a wholly quoted ``"Annotated[T,+ Depends(static_file_response)]"`` is as live as the unquoted form).+ In an allowlisted file a serving name in+ such an annotation is a non-call reference (rule 4); outside the+ allowlist every reference is already flagged by rules 1 and 2. In+ every scanned file, a serving name QUOTED inside such an annotation+ (``r: "WorkerCleanupStreamingResponse" = Depends()``, which FastAPI+ resolves by name) is flagged.++Aliases are resolved file-wide with no scope tracking: a local name+imported as several serving names anywhere in the file (in different+functions, or once under ``if TYPE_CHECKING:``) is checked against+every rule that applies to ANY of them, and a local name that is+itself a wrapper name stays a wrapper whatever it is imported as, so+a ``SERVING_HELPERS`` alias can never mask a wrapper (fail closed).++A file that cannot be read or parsed (syntax error, undecodable bytes,+nesting too deep for the parser, an OS error) is reported as an+offender, never skipped, and never crashes the run. Files are parsed+from bytes, so a UTF-8 BOM or a PEP 263 coding cookie is honoured.++Out of scope, so NOT fenced: responses that carry file *content*+already read into memory (``Response(content=p.read_bytes())``,+``PlainTextResponse(p.read_text())``, ``HTMLResponse(...)``); a+same-module generator that itself opens and yields a file+(``WorkerCleanupStreamingResponse(generate())`` where ``generate``+reads the outputs directory) or that is handed a file object as an+argument (``W(passthru(open(p)))``); anything inside an allowlisted+file beyond rules 2, 3, 4 and 5 -- in particular, a new serving+*function* defined in an allowlisted file (``def download(p): return+FileResponse(p)`` in ``web/fastapi_app.py``) whose name is not in+``SERVING_HELPERS`` is not recognised, so calls to it anywhere are+unfenced; for rule 3, a rebinding of an outputs identifier, in the+same module or re-exported by another one (``root = OUTPUT_DIR`` then+``FileResponse(root / n)``; outside the allowlist rule 1 still flags+the primitive; the same gap applies to a ``SERVING_HELPERS`` call+handed such a rebinding); a serving helper defined in ``web/`` whose+name is not in ``SERVING_HELPERS``; a primitive, wrapper or helper+wrapped, renamed or re-exported by a module outside ``web/`` (which+this hook does not scan) and imported from there; ``Annotated`` reached+through an assignment alias (``A = Annotated``) with non-call metadata+in an allowlisted file; and dynamic lookups (``getattr``,+``importlib``, ``__import__``, ``module.__dict__[...]``, ``eval``).++The companion contract (tests/security/test_architecture_fences.py)+runs this same scanner over the same tree, pre-commit style (repo-root+cwd, repo-relative paths). Every path argument is made absolute+(relative ones against the cwd) and taken relative to the repository+root twice -- lexically (``..`` collapsed, symlinks not followed) and+resolved (symlinks followed) -- and the file is scanned if EITHER form+is in the fenced tree, so ``..`` segments, a non-root cwd, or a+symlink inside ``web/`` pointing elsewhere cannot move a file out of+scope. The allowlist is matched against the resolved path only (the+file whose content is scanned). Repo files outside the fenced tree+(both forms) are skipped; files outside the repository (mutation+fixtures) are always scanned, with no allowlist applied.+"""++import ast+import builtins+import sys+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parent.parent++#: The fenced tree (repo-relative; the trailing slash keeps+#: ``web_search_engines/`` out).+FENCED_PREFIX = "src/local_deep_research/web/"++#: Starlette/FastAPI primitives that serve files or arbitrary byte+#: streams over HTTP.+SERVING_PRIMITIVES = frozenset(+ {+ "FileResponse",+ "StaticFiles",+ "StreamingResponse",+ }+)++#: Name suffixes of LDR's own serving wrappers (subclasses of the+#: primitives, e.g. ``WorkerCleanupStreamingResponse``). Their content+#: argument must be a call to a generator defined in the same module.+WRAPPER_SUFFIXES = ("StreamingResponse", "FileResponse")++#: Function names of LDR's own file-serving helpers: functions (not+#: wrapper classes) that return a serving response, defined in an+#: allowlisted file, e.g. ``static_file_response(path)``. Rule 3+#: (outputs directory referenced inline) applies to their calls in any+#: argument position or keyword. That is defensive: the helper takes no+#: directory today, but the check stays correct if one is added.+SERVING_HELPERS = frozenset({"static_file_response"})++#: Repo-relative files exempt from the primitive-reference rule, and+#: why. The exemption covers the WHOLE file.+ALLOWED_FILES = {+ "src/local_deep_research/web/fastapi_app.py": (+ "only the favicon route uses FileResponse, for the fixed "+ "STATIC_DIR/favicon.ico; /static delegates to web/static_files.py "+ "(whole file exempt)"+ ),+ "src/local_deep_research/web/dependencies/threadpool.py": (+ "defines WorkerCleanupStreamingResponse (StreamingResponse "+ "subclass) for generated streaming bodies (whole file exempt)"+ ),+ "src/local_deep_research/web/static_files.py": (+ "shared /static and /redirect-static resolver; always serves from "+ "STATIC_DIR (no directory parameter) and only files whose resolved "+ "path is inside it (whole file exempt)"+ ),+}++#: Identifiers tying a path to the shared outputs directory.+OUTPUTS_IDENTIFIERS = (+ "get_research_outputs_directory",+ "OUTPUT_DIR",+ "outputs_dir",+)+++def _is_wrapper(name: str | None) -> bool:+ return (+ name is not None+ and name not in SERVING_PRIMITIVES+ and name.endswith(WRAPPER_SUFFIXES)+ )+++def _is_serving(name: str | None) -> bool:+ return name in SERVING_PRIMITIVES or _is_wrapper(name)+++def _is_helper(name: str | None) -> bool:+ # Leading underscores are ignored, so a private-looking alias such+ # as ``_static_file_response`` is still recognised as the helper.+ return name is not None and name.lstrip("_") in SERVING_HELPERS+++def _keeps_role(name: str, asname: str) -> bool:+ """True if importing ``name`` as ``asname`` keeps it recognisable.++ A primitive or wrapper must stay a serving name (a primitive or a+ ``...StreamingResponse`` / ``...FileResponse`` wrapper name), so+ every module that imports the alias applies the wrapper rules to+ it. A helper may become a helper name or any serving name (the+ wrapper rules are stricter than the helper rule).+ """+ if _is_serving(name):+ return _is_serving(asname)+ if _is_helper(name):+ return _is_serving(asname) or _is_helper(asname)+ return True+++def _import_aliases(tree: ast.AST) -> dict[str, set[str]]:+ """Local alias -> EVERY imported serving name it is bound to+ (``FR`` -> ``{"FileResponse"}``, ``sfr`` -> ``{"static_file_response"}``).++ The map is file-wide with no scope tracking, so one alias imported+ as different serving names in different scopes (two functions, or a+ ``TYPE_CHECKING`` block) maps to all of them, and every rule that+ applies to ANY of them is applied (fail closed): a helper alias can+ never mask a wrapper alias of the same local name.+ """+ aliases: dict[str, set[str]] = {}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ if alias.asname and (+ _is_serving(alias.name) or _is_helper(alias.name)+ ):+ aliases.setdefault(alias.asname, set()).add(alias.name)+ return aliases+++def _outputs_names(tree: ast.AST) -> set[str]:+ """OUTPUTS_IDENTIFIERS plus any local name one is imported as+ (``from x import OUTPUT_DIR as OD`` adds ``OD``)."""+ names = set(OUTPUTS_IDENTIFIERS)+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ if alias.asname and alias.name in OUTPUTS_IDENTIFIERS:+ names.add(alias.asname)+ return names+++def _resolved_names(node: ast.AST, aliases: dict[str, set[str]]) -> set[str]:+ """Every name ``node`` may refer to: the bare name itself (so a local+ name that is itself a serving name is never masked by an alias) plus+ every serving name it is imported as anywhere in the file."""+ if isinstance(node, ast.Name):+ return {node.id} | aliases.get(node.id, set())+ if isinstance(node, ast.Attribute):+ return {node.attr}+ return set()+++def _display(names: set[str]) -> str:+ return "/".join(sorted(names))+++def _references_outputs(node: ast.AST, outputs_names: set[str]) -> bool:+ # ast.walk also reaches the callee Name of+ # get_research_outputs_directory(), so call forms need no extra arm.+ for child in ast.walk(node):+ if isinstance(child, ast.Name) and child.id in outputs_names:+ return True+ if (+ isinstance(child, ast.Attribute)+ and child.attr in OUTPUTS_IDENTIFIERS+ ):+ return True+ return False+++def _content_argument(call: ast.Call) -> ast.AST | None:+ for kw in call.keywords:+ if kw.arg == "content":+ return kw.value+ if call.args and not isinstance(call.args[0], ast.Starred):+ return call.args[0]+ return None+++_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)+++def _own_body_yields(func: ast.AST) -> bool:+ """True if ``func``'s own body yields (nested scopes excluded)."""+ stack = list(ast.iter_child_nodes(func))+ while stack:+ node = stack.pop()+ if isinstance(node, (ast.Yield, ast.YieldFrom)):+ return True+ if isinstance(node, _SCOPES):+ continue+ stack.extend(ast.iter_child_nodes(node))+ return False+++_DEFS = (ast.FunctionDef, ast.AsyncFunctionDef)+++def _candidate_defs(tree: ast.AST) -> list[ast.AST]:+ """Module-level and function-nested defs. Everything inside a class+ body (methods, and defs nested in methods) is skipped: a method is+ never reached by a bare-name call, and a generator nested in a+ method is not accepted either (fail closed)."""+ found: list[ast.AST] = []+ stack = [tree]+ while stack:+ node = stack.pop()+ if isinstance(node, ast.ClassDef):+ continue+ if isinstance(node, _DEFS):+ found.append(node)+ stack.extend(ast.iter_child_nodes(node))+ return found+++def _is_generator_def(func: ast.AST) -> bool:+ # A decorator can replace the function with anything, so a+ # decorated def is never trusted as a generator.+ return not func.decorator_list and _own_body_yields(func)+++def _other_bindings(tree: ast.AST) -> set[str]:+ """Names bound by anything other than a function ``def``."""+ bound: set[str] = set()+ for node in ast.walk(tree):+ if isinstance(node, ast.Name) and not isinstance(node.ctx, ast.Load):+ bound.add(node.id)+ elif isinstance(node, ast.arg):+ bound.add(node.arg)+ elif isinstance(node, ast.alias):+ bound.add(node.asname or node.name.split(".")[0])+ elif isinstance(node, ast.ClassDef):+ bound.add(node.name)+ elif isinstance(node, ast.ExceptHandler) and node.name:+ bound.add(node.name)+ elif isinstance(node, (ast.Global, ast.Nonlocal)):+ bound.update(node.names)+ elif isinstance(node, (ast.MatchAs, ast.MatchStar)) and node.name:+ bound.add(node.name)+ elif isinstance(node, ast.MatchMapping) and node.rest:+ bound.add(node.rest)+ return bound+++def _has_star_import(tree: ast.AST) -> bool:+ """True if the module has a ``from x import *`` anywhere.++ A star import can rebind any name in the module -- including one+ that looks like an accepted same-module generator -- so its mere+ presence disqualifies every generator candidate, not just the+ names it happens to shadow (those aren't known statically).+ """+ return any(+ isinstance(node, ast.ImportFrom)+ and any(alias.name == "*" for alias in node.names)+ for node in ast.walk(tree)+ )+++def _local_generators(tree: ast.AST) -> set[str]:+ """Names that can only mean a same-module generator function."""+ if _has_star_import(tree):+ return set()+ generators = {d.name for d in _candidate_defs(tree) if _is_generator_def(d)}+ # Disqualify over EVERY def in the module, methods and defs nested in+ # methods included: a name counts only if all of its defs anywhere+ # are undecorated generators. Any other binding of it (assignment,+ # import, parameter...) or a builtin name (open, iter) disqualifies+ # it too.+ not_generators = {+ d.name+ for d in ast.walk(tree)+ if isinstance(d, _DEFS) and not _is_generator_def(d)+ }+ return (+ generators - not_generators - _other_bindings(tree) - set(dir(builtins))+ )+++def _is_local_generator_call(+ node: ast.AST | None, local_generators: set[str]+) -> bool:+ return (+ isinstance(node, ast.Call)+ and isinstance(node.func, ast.Name)+ and node.func.id in local_generators+ )+++def _primitive_references(tree: ast.AST) -> list[tuple[int, str]]:+ hits: list[tuple[int, str]] = []+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ for alias in node.names:+ if alias.name in SERVING_PRIMITIVES:+ hits.append((node.lineno, f"import of {alias.name}"))+ elif alias.name == "*":+ # A star import can bring a primitive (or a wrapper)+ # in without naming it.+ hits.append(+ (node.lineno, f"star import from {node.module}")+ )+ elif isinstance(node, ast.Attribute):+ if node.attr in SERVING_PRIMITIVES:+ hits.append((node.lineno, f"reference to .{node.attr}"))+ elif isinstance(node, ast.Name):+ if node.id in SERVING_PRIMITIVES:+ hits.append((node.lineno, f"reference to {node.id}"))+ return hits+++def _renaming_imports(tree: ast.AST) -> list[tuple[int, str]]:+ """``from x import <serving name> as <other>`` that loses the role.++ Every scanned file, allowlisted ones included. An alias that is not+ itself a serving or helper name would let ANOTHER module import the+ alias under a name no rule recognises (``from ..utils.streaming+ import CleanupStream``), so the rename is flagged where it happens.+ """+ hits: list[tuple[int, str]] = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.ImportFrom):+ continue+ for alias in node.names:+ if (+ alias.asname+ and alias.asname != alias.name+ and not _keeps_role(alias.name, alias.asname)+ ):+ hits.append(+ (+ node.lineno,+ f"import of {alias.name} renamed to {alias.asname} "+ "(a serving primitive, wrapper or helper must keep a "+ "name the fence recognises, e.g. a ...StreamingResponse "+ "suffix)",+ )+ )+ return hits+++#: Annotation content that is evaluated into something other than a+#: type (see ``_annotations``): a call (``Depends(static_file_response)``), a walrus (binds in+#: the enclosing scope, since annotations are evaluated eagerly) or a+#: lambda.+_EVALUATED = (ast.Call, ast.NamedExpr, ast.Lambda)+++def _annotated_names(tree: ast.AST) -> set[str]:+ """``Annotated`` plus every local name it is imported as."""+ names = {"Annotated"}+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom):+ names.update(+ alias.asname+ for alias in node.names+ if alias.name == "Annotated" and alias.asname+ )+ return names+++#: Nesting bound for quoted annotations (a string inside a string ...):+#: a string nested deeper than this counts as evaluated (fail closed)+#: and, in a type position, is reported as unchecked.+_MAX_QUOTE_DEPTH = 8++#: Offender text for a string in a type position the hook cannot check.+_UNCHECKED_STRING = (+ "annotation string that cannot be checked (it does not parse as an "+ "expression, or quotes nest deeper than "+ f"{_MAX_QUOTE_DEPTH}); write the annotation unquoted or as a valid "+ "forward reference"+)+++def _is_literal_head(node: ast.AST) -> bool:+ """True if ``node`` is ``Literal[...]`` (bare or qualified): its+ strings are values, never evaluated as types."""+ if not isinstance(node, ast.Subscript):+ return False+ head = node.value+ return (isinstance(head, ast.Name) and head.id == "Literal") or (+ isinstance(head, ast.Attribute) and head.attr == "Literal"+ )+++def _is_annotated_head(node: ast.AST, annotated: set[str]) -> bool:+ """True if ``node`` is a subscript of ``Annotated`` (under any import+ alias, or qualified as ``typing.Annotated``)."""+ if not isinstance(node, ast.Subscript):+ return False+ head = node.value+ return (isinstance(head, ast.Name) and head.id in annotated) or (+ isinstance(head, ast.Attribute) and head.attr == "Annotated"+ )+++def _annotation_nodes(+ root: ast.AST, annotated: set[str]+) -> tuple[list[tuple[ast.AST, int | None]], bool, list[int]]:+ """Every node of an annotation, quoted parts included.++ Returns ``(nodes, unparsable, unchecked)``. ``nodes`` holds+ ``(node, line)``+ pairs: ``line`` is None for a node of ``root`` itself and, for a node+ parsed out of a string, the line of the outermost string literal+ holding it. FastAPI (via ``typing.get_type_hints``) evaluates a+ quoted annotation, so every string in a type position is parsed as+ an expression, recursively (``"Annotated[NoteService, Depends()]"``,+ ``Optional["NoteService"]``), and the parsed tree is inspected+ exactly like an unquoted one. ``unparsable`` is True if any such+ string does not parse or nests deeper than ``_MAX_QUOTE_DEPTH`` (fail+ closed: the caller treats the annotation as evaluated).+ ``unchecked`` lists, by the line of its outermost string literal,+ each such string that sits in a type position, which the caller+ reports as an offender: a string that is a plain value -- anywhere+ inside ``Annotated`` metadata, a ``Literal[...]`` or the arguments+ of a call (``Query(description="...")``) -- is never evaluated as a+ type, so it is not reported. ``"*[NoteService]"`` is valid as a+ ``ForwardRef`` but not as an expression, so it is unchecked.++ Not parsed: the metadata strings of an ``Annotated[T, "doc"]``+ (elements after the first), which are kept as plain values and+ never evaluated.+ """+ nodes: list[tuple[ast.AST, int | None]] = []+ unparsable = False+ unchecked: list[int] = []+ values: set[int] = set()+ # ids of every node in a value (non-type) position.+ plain: set[int] = set()+ pending: list[tuple[ast.AST, int, int | None, bool]] = [+ (root, 0, None, False)+ ]+ while pending:+ current, depth, line, in_value = pending.pop()+ for node in ast.walk(current):+ nodes.append((node, line))+ if _is_annotated_head(node, annotated) and isinstance(+ node.slice, ast.Tuple+ ):+ values.update(id(meta) for meta in node.slice.elts[1:])+ for meta in node.slice.elts[1:]:+ plain.update(id(n) for n in ast.walk(meta))+ if _is_literal_head(node):+ plain.update(id(n) for n in ast.walk(node.slice))+ if isinstance(node, ast.Call):+ for arg in [*node.args, *node.keywords]:+ plain.update(id(n) for n in ast.walk(arg))+ if (+ not (+ isinstance(node, ast.Constant)+ and isinstance(node.value, str)+ )+ or id(node) in values+ ):+ continue+ here = node.lineno if line is None else line+ is_value = in_value or id(node) in plain+ if depth >= _MAX_QUOTE_DEPTH:+ unparsable = True+ if not is_value:+ unchecked.append(here)+ continue+ try:+ parsed = ast.parse(node.value.strip(), mode="eval")+ except (SyntaxError, ValueError, RecursionError, MemoryError):+ unparsable = True+ if not is_value:+ unchecked.append(here)+ continue+ pending.append((parsed.body, depth + 1, here, is_value))+ return nodes, unparsable, unchecked+++def _has_evaluated_metadata(+ nodes: list[tuple[ast.AST, int | None]], annotated: set[str]+) -> bool:+ """True if an ``Annotated[...]`` among ``nodes`` is anything but+ ``Annotated[T, constant, ...]``: a non-constant metadata element+ (``Annotated[T, dep]`` with ``dep = Depends()`` hands FastAPI a+ dependency without a call), a starred element (``Annotated[*(T,+ dep)]`` unpacks to the same thing) or a slice that is not a tuple+ (``Annotated[args]`` with ``args = (T, dep)``)."""+ for node, _line in nodes:+ if not _is_annotated_head(node, annotated):+ continue+ if not isinstance(node.slice, ast.Tuple):+ return True+ elements = node.slice.elts+ if any(isinstance(element, ast.Starred) for element in elements):+ return True+ if any(not isinstance(meta, ast.Constant) for meta in elements[1:]):+ return True+ return False+++#: Nodes that open their own scope: a store inside them never binds a+#: class attribute.+_NEW_SCOPES = (+ ast.FunctionDef,+ ast.AsyncFunctionDef,+ ast.ClassDef,+ ast.Lambda,+ ast.ListComp,+ ast.SetComp,+ ast.DictComp,+ ast.GeneratorExp,+)+_BLOCKS = (ast.stmt, ast.excepthandler, ast.match_case)+++def _class_body_blocks(cls: ast.ClassDef) -> list[ast.AST]:+ """Every statement (and ``except`` / ``case`` clause) executed in+ ``cls``'s own body, including those nested under ``if`` / ``try`` /+ ``with`` / ``for`` / ``while`` / ``match``, but not the bodies of a+ nested def or class (the def or class statement itself is+ included: it binds its name)."""+ blocks: list[ast.AST] = []+ pending: list[ast.AST] = list(cls.body)+ while pending:+ block = pending.pop()+ blocks.append(block)+ if not isinstance(block, _NEW_SCOPES):+ pending.extend(+ child+ for child in ast.iter_child_nodes(block)+ if isinstance(child, _BLOCKS)+ )+ return blocks+++def _own_expressions(block: ast.AST) -> list[ast.AST]:+ """The expression nodes of one statement or clause, not descending+ into nested statements or into a nested scope."""+ nodes: list[ast.AST] = []+ pending = [+ child+ for child in ast.iter_child_nodes(block)+ if not isinstance(child, _BLOCKS)+ ]+ while pending:+ node = pending.pop()+ nodes.append(node)+ if not isinstance(node, _NEW_SCOPES):+ pending.extend(ast.iter_child_nodes(node))+ return nodes+++#: Bases that never supply a class attribute (a field default).+_PLAIN_BASES = frozenset({"object", "Generic", "Protocol"})+++def _may_inherit_defaults(cls: ast.ClassDef) -> bool:+ """True if ``cls`` has a base other than ``object`` / ``Generic`` /+ ``Protocol`` (bare, qualified or subscripted), so a field it leaves+ without a default may inherit one from that base."""+ for base in cls.bases:+ head = base.value if isinstance(base, ast.Subscript) else base+ if isinstance(head, ast.Name):+ name = head.id+ elif isinstance(head, ast.Attribute):+ name = head.attr+ else:+ return True+ if name not in _PLAIN_BASES:+ return True+ return False+++def _class_field_defaults(cls: ast.ClassDef) -> dict[int, ast.AST]:+ """``id(field)`` -> its default, for every annotated assignment in+ ``cls``'s own body (see ``_class_body_blocks``).++ A dataclass (or FastAPI, via the generated ``__init__``) reads a+ field's default from the class attribute, so EVERY binding of the+ field's name in the class body counts, not just ``x: T = value``:+ ``svc: NoteService`` followed by ``svc = Depends()`` defaults the+ field to ``Depends()``. A plain ``name = value`` contributes+ ``value``; any other binding (augmented or unpacking assignment,+ loop / ``with`` / ``except`` / ``case`` target, import, def, class,+ walrus) contributes the binding statement itself, which is never a+ constant (fail closed). The default is the first non-constant+ contribution, else the field's own value. A field with no binding+ at all in the class body of a class with any base other than+ ``object`` / ``Generic`` / ``Protocol`` may inherit its default+ from that base, so its default is the class itself, which is never+ a constant (fail closed).+ """+ blocks = _class_body_blocks(cls)+ bound: dict[str, list[ast.AST]] = {}++ def bind(name: str | None, value: ast.AST) -> None:+ if name:+ bound.setdefault(name, []).append(value)++ fields: list[ast.AnnAssign] = []+ for block in blocks:+ if isinstance(block, ast.AnnAssign):+ fields.append(block)+ if block.value is not None and isinstance(block.target, ast.Name):+ bind(block.target.id, block.value)+ if block.value is not None:+ for node in ast.walk(block.value):+ if isinstance(node, ast.NamedExpr):+ bind(node.target.id, block)+ continue+ if (+ isinstance(block, ast.Assign)+ and len(block.targets) == 1+ and isinstance(block.targets[0], ast.Name)+ ):+ bind(block.targets[0].id, block.value)+ for node in ast.walk(block.value):+ if isinstance(node, ast.NamedExpr):+ bind(node.target.id, block)+ continue+ if isinstance(block, _NEW_SCOPES):+ bind(block.name, block)+ elif isinstance(block, (ast.Import, ast.ImportFrom)):+ for alias in block.names:+ bind(alias.asname or alias.name.split(".")[0], block)+ elif isinstance(block, ast.excepthandler):+ bind(block.name, block)+ for node in _own_expressions(block):+ if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):+ bind(node.id, block)+ elif isinstance(node, (ast.MatchAs, ast.MatchStar)):+ bind(node.name, block)+ elif isinstance(node, ast.MatchMapping):+ bind(node.rest, block)+ defaults: dict[int, ast.AST] = {}+ inherits = _may_inherit_defaults(cls)+ for field in fields:+ values = (+ bound.get(field.target.id, [])+ if isinstance(field.target, ast.Name)+ else []+ )+ chosen = next(+ (v for v in values if not isinstance(v, ast.Constant)),+ field.value,+ )+ if chosen is None and inherits:+ chosen = cls+ if chosen is not None:+ defaults[id(field)] = chosen+ return defaults+++def _annotations(tree: ast.AST) -> list[tuple[ast.AST, bool]]:+ """Every annotation as ``(annotation, type_only)``.++ An annotation is type-only -- never a rebinding -- unless:++ * it contains a call, walrus or lambda anywhere+ (``Annotated[T, Depends(static_file_response)]`` hands the callable to+ FastAPI; ``x: (s := static_file_response) = 1`` binds it in the enclosing+ scope, since annotations are evaluated eagerly before 3.14);+ * it is a parameter's or a class-body field's annotation (a+ dataclass field becomes an ``__init__`` parameter) whose default+ is not a constant: ``r: FileResponse = Depends()``,+ ``= Depends(None)`` or ``= dep`` with ``dep = Depends()`` makes+ FastAPI CALL the annotated class, filling its parameters from the+ request (FastAPI refuses some classes, ``FileResponse`` among them,+ at route registration; this check does not rely on that);+ * an ``Annotated[...]`` in it (under any import alias) carries a+ non-constant metadata element (``Annotated[class, dep]``), a+ starred element (``Annotated[*(class, dep)]``) or a slice that is+ not a tuple (``Annotated[args]``);+ * a string in it does not parse as an expression, or nests too+ deep (fail closed; one in a type position is also reported+ itself, see ``_string_annotation_hits``);+ * it is a class field with no binding in its own class body, on a+ class with a base other than ``object`` / ``Generic`` /+ ``Protocol``: the field may inherit a non-constant default.++ Every string in a type position is parsed and checked like unquoted+ code, recursively (see ``_annotation_nodes``), so a wholly quoted+ ``"Annotated[class, Depends()]"`` is not type-only either. A class+ field counts wherever it sits in the class body, also under ``if`` /+ ``try`` / ``with`` / loops, and its default is any binding of its+ name there (``svc: T`` then ``svc = Depends()``; see+ ``_class_field_defaults``).++ Callee names are not matched, so ``Depends`` imported under another+ name cannot hide a dependency (fail closed). Return annotations and+ module- or function-level variable annotations have no default.+ """+ annotated = _annotated_names(tree)+ defaults: dict[int, ast.AST] = {}+ for node in ast.walk(tree):+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):+ args = node.args+ positional = args.posonlyargs + args.args+ offset = len(positional) - len(args.defaults)+ for arg, default in zip(positional[offset:], args.defaults):+ defaults[id(arg)] = default+ for arg, default in zip(args.kwonlyargs, args.kw_defaults):+ if default is not None:+ defaults[id(arg)] = default+ elif isinstance(node, ast.ClassDef):+ defaults.update(_class_field_defaults(node))+ found: list[tuple[ast.AST, bool]] = []+ for node in ast.walk(tree):+ if (+ isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))+ and node.returns is not None+ ):+ root, default = node.returns, None+ elif isinstance(node, ast.arg) and node.annotation is not None:+ root, default = node.annotation, defaults.get(id(node))+ elif isinstance(node, ast.AnnAssign):+ root, default = node.annotation, defaults.get(id(node))+ else:+ continue+ nodes, unparsable, _unchecked = _annotation_nodes(root, annotated)+ type_only = (+ (default is None or isinstance(default, ast.Constant))+ and not unparsable+ and not any(isinstance(n, _EVALUATED) for n, _line in nodes)+ and not _has_evaluated_metadata(nodes, annotated)+ )+ found.append((root, type_only))+ return found+++def _annotation_ids(tree: ast.AST) -> set[int]:+ """ids of every node inside a type-only annotation (see+ ``_annotations``), which is never a rebinding."""+ return {+ id(child)+ for root, type_only in _annotations(tree)+ if type_only+ for child in ast.walk(root)+ }+++def _string_annotation_hits(+ tree: ast.AST, aliases: dict[str, set[str]]+) -> list[tuple[int, str]]:+ """Serving names quoted inside a STRING in a non-type-only+ annotation, in every scanned file.++ FastAPI resolves a forward reference (``r: "FileResponse" =+ Depends()``, or a wholly quoted ``"Annotated[FileResponse,+ Depends()]"``) in the module globals, so a quoted serving name is as+ live there as a bare one, and no other rule sees it. Strings are+ parsed recursively (see ``_annotation_nodes``); one in a type+ position that does not parse (or nests too deep) is reported+ itself, as an annotation string that cannot be checked."""+ annotated = _annotated_names(tree)+ hits: list[tuple[int, str]] = []+ for root, type_only in _annotations(tree):+ if type_only:+ continue+ nodes, _unparsable, unchecked = _annotation_nodes(root, annotated)+ hits.extend((line, _UNCHECKED_STRING) for line in unchecked)+ for inner, line in nodes:+ if line is None:+ continue+ names = {+ n+ for n in _resolved_names(inner, aliases)+ if _is_serving(n) or _is_helper(n)+ }+ if names:+ hits.append(+ (+ line,+ f"reference to {_display(names)} quoted in an "+ "evaluated annotation (FastAPI resolves it)",+ )+ )+ return hits+++def _allowlisted_rebindings(+ tree: ast.AST, aliases: dict[str, set[str]], callees: set[int]+) -> list[tuple[int, str]]:+ """Non-call references to serving names in an allowlisted file.++ An allowlisted file may reference primitives freely, but must not+ hand a primitive, wrapper or helper on under a name the fence does+ not recognise: ``Download = WorkerCleanupStreamingResponse``,+ ``return FileResponse``, ``partial(static_file_response, ...)``, or+ ``class Download(FileResponse)`` would each give importers an+ unfenced serving callable. Exempt: callees, type-only annotations+ (see ``_annotations``: ``= Depends()`` makes FastAPI call the+ annotated class with request-supplied arguments, so such an+ annotation is a reference), and the+ bases of a class whose own name is a serving name (a new+ ``...StreamingResponse`` / ``...FileResponse`` subclass is a+ wrapper, so the wrapper rules follow it into every importer).+ """+ exempt = _annotation_ids(tree) | callees+ hits: list[tuple[int, str]] = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.ClassDef):+ continue+ for base in node.bases:+ names = {+ n+ for n in _resolved_names(base, aliases)+ if _is_serving(n) or _is_helper(n)+ }+ if not names:+ continue+ exempt.add(id(base))+ if not _is_serving(node.name):+ hits.append(+ (+ node.lineno,+ f"class {node.name} subclasses {_display(names)} "+ "under a name that does not end in StreamingResponse "+ "/ FileResponse",+ )+ )+ for node in ast.walk(tree):+ if not isinstance(node, (ast.Name, ast.Attribute)):+ continue+ if not isinstance(node.ctx, ast.Load) or id(node) in exempt:+ continue+ names = {+ n+ for n in _resolved_names(node, aliases)+ if _is_serving(n) or _is_helper(n)+ }+ if names:+ hits.append(+ (+ node.lineno,+ f"non-call reference to {_display(names)} in an "+ "allowlisted file (serving callables must not be "+ "re-bound or handed on)",+ )+ )+ return hits+++def _parse(path: Path) -> tuple[ast.AST | None, str]:+ """Parse ``path``, or return ``(None, offender line)``.++ Fail closed: an unreadable or unparsable file is reported, never+ skipped, and a parser failure (too-deep nesting raises RecursionError+ or MemoryError) never crashes the run.+ """+ try:+ source = path.read_bytes()+ except OSError as exc:+ return None, f"{path}:1: could not read ({type(exc).__name__}: {exc})"+ try:+ # Bytes, not text: ast.parse then honours a UTF-8 BOM and a PEP+ # 263 coding cookie exactly as the interpreter does.+ return ast.parse(source, filename=str(path)), ""+ except (SyntaxError, ValueError, RecursionError, MemoryError) as exc:+ lineno = getattr(exc, "lineno", None) or 1+ return (+ None,+ f"{path}:{lineno}: could not parse ({type(exc).__name__}: {exc})",+ )+++def scan_file(path: Path, rel: str | None = None) -> list[str]:+ offenders: list[str] = []+ tree, error = _parse(path)+ if tree is None:+ return [error]+ allowlisted = rel in ALLOWED_FILES+ if not allowlisted:+ for lineno, what in _primitive_references(tree):+ offenders.append(+ f"{path}:{lineno}: {what} (file-serving primitive outside "+ "the ALLOWED_FILES allowlist)"+ )+ aliases = _import_aliases(tree)+ outputs_names = _outputs_names(tree)+ local_generators = _local_generators(tree)+ for lineno, what in _renaming_imports(tree):+ offenders.append(f"{path}:{lineno}: {what}")+ for lineno, what in _string_annotation_hits(tree, aliases):+ offenders.append(f"{path}:{lineno}: {what}")+ callees: set[int] = set()+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ callees.add(id(node.func))+ names = _resolved_names(node.func, aliases)+ serving = {n for n in names if _is_serving(n) or _is_helper(n)}+ if not serving:+ continue+ if _references_outputs(node, outputs_names):+ offenders.append(+ f"{path}:{node.lineno}: {_display(serving)}(...) serves from "+ "the shared research outputs directory"+ )+ wrappers = {n for n in names if _is_wrapper(n)}+ if wrappers and not _is_local_generator_call(+ _content_argument(node), local_generators+ ):+ offenders.append(+ f"{path}:{node.lineno}: {_display(wrappers)}(...) content is "+ "not a bare-name call to a yielding generator function "+ "defined in this module"+ )+ if not allowlisted:+ for node in ast.walk(tree):+ if not isinstance(node, (ast.Name, ast.Attribute)):+ continue+ wrappers = {+ n+ for n in _resolved_names(node, aliases)+ if _is_wrapper(n) or _is_helper(n)+ }+ if id(node) not in callees and wrappers:+ offenders.append(+ f"{path}:{node.lineno}: non-call reference to "+ f"{_display(wrappers)} (serving wrappers and helpers "+ "must be called directly)"+ )+ else:+ for lineno, what in _allowlisted_rebindings(tree, aliases, callees):+ offenders.append(f"{path}:{lineno}: {what}")+ return offenders+++def _repo_relative(path: Path) -> tuple[str | None, str | None]:+ """``(lexical, resolved)`` repo-relative posix paths of ``path``;+ each is None if that form of the path lies outside the repo.++ Both are absolute-ised against the cwd, so ``..`` segments and a cwd+ other than the repo root still yield the true repo-relative path.+ The lexical form only normalises ``..`` textually (symlinks are not+ followed); the resolved form follows symlinks. The caller scans a+ file if EITHER form is in scope, so a symlink inside the fenced+ tree whose target lies elsewhere is still scanned (fail closed).+ """++ def rel(candidate: Path) -> str | None:+ try:+ return candidate.relative_to(REPO_ROOT).as_posix()+ except ValueError:+ return None++ # Collapse ``..`` textually (pathlib keeps it; resolve() would+ # follow symlinks): ``a/link/../b`` -> ``a/b``.+ parts: list[str] = []+ for part in path.absolute().parts:+ if part == "..":+ if len(parts) > 1:+ parts.pop()+ elif part != ".":+ parts.append(part)+ lexical = rel(Path(*parts))+ return lexical, rel(path.resolve())+++def _safe_print(line: str) -> None:+ """Print ``line`` without crashing on undecodable path bytes.++ Argv path arguments are decoded with surrogateescape, so an+ offender line built from a non-UTF-8 filename can carry lone+ surrogates that a strict stdout encoder refuses to write+ (``UnicodeEncodeError``). Round-tripping through the+ ``backslashreplace`` error handler turns any such surrogate into a+ literal, printable escape instead of crashing the hook.+ """+ encoding = sys.stdout.encoding or "utf-8"+ print(+ line.encode(encoding, "backslashreplace").decode(+ encoding, "backslashreplace"+ )+ )+++def main(argv: list[str]) -> int:+ offenders: list[str] = []+ for arg in argv:+ path = Path(arg)+ if not path.suffix == ".py" or not path.is_file():+ continue+ lexical, resolved = _repo_relative(path)+ in_repo = [r for r in (lexical, resolved) if r is not None]+ if in_repo and not any(r.startswith(FENCED_PREFIX) for r in in_repo):+ continue+ # The allowlist goes by the file whose CONTENT is scanned (the+ # resolved path): a symlink named like an allowlisted file but+ # pointing elsewhere is not exempt.+ offenders.extend(scan_file(path, resolved))+ if offenders:+ _safe_print("Reports-dir serving fence: new HTTP file-serving site:")+ for offender in offenders:+ _safe_print(f" {offender}")+ _safe_print(+ "Report content is served from the per-user encrypted DB "+ "(research.py get_research_report); the shared artifacts "+ "directory must not gain an HTTP serving route. A new "+ "primitive reference needs an ALLOWED_FILES entry with a "+ "reason; a serving wrapper takes a direct call to a yielding "+ "generator function defined in the same module."+ )+ return 1+ return 0+++if __name__ == "__main__":+ sys.exit(main(sys.argv[1:]))diff --git a/changelog.d/6634.security.md b/changelog.d/6634.security.mdnew file mode 100644index 0000000000..d708b901fb--- /dev/null+++ b/changelog.d/6634.security.md@@ -0,0 +1 @@+Preventive hardening: the `_generate_report_path` helper (which has no production caller; saved reports are named by research ID) now appends a random segment, so the same query in the same second can no longer yield identical filenames in the install-wide reports directory. Two new pre-commit syntax checks, which fence accidental and idiomatic code; deliberate evasion by a contributor is out of scope and left to code review: `check-per-user-isolation` is a fast smoke check that constructions of user-data services/sessions (`NoteService`, `LibraryService`, `DownloadService`, `get_user_db_session`, the three library deletion services, `NoteAIService` and `FollowUpResearchService`) under `web/routers/`, `research_library/` and `web/services/` pass a username explicitly, as a username-named positional argument or a `*username*` keyword, with any such keyword bound to a literal such as `None` flagged (where that username comes from is enforced for router call sites by the cross-user isolation census tests), and `check-reports-dir-not-served` flags, under `web/`, any `FileResponse`, `StaticFiles` or `StreamingResponse` reference or star import outside a per-file allowlist (all of `web/fastapi_app.py`, `web/dependencies/threadpool.py` and `web/static_files.py`), any call to LDR's streaming-response wrapper whose body is not a direct call to an undecorated function defined in the same module (not inside a class) that itself yields, where a non-generator or decorated definition, any other binding, of that name anywhere in the module, or a `from x import *` anywhere in the module (which can rebind any name without the scanner being able to tell which) disqualifies it (so `open(path)`, a helper returning `open(path)`, `iter(...)`, a decorated generator or a path is flagged; the arguments of the generator call are not inspected, so `W(passthru(open(path)))` is accepted), and any serving call, including a call to the `static_file_response` helper, that references the outputs directory inline (also under an import alias), allowlisted files included. Within its scanned tree, neither check lets a fenced callable leave a module under a name it does not recognise: an import alias that drops the role (`WorkerCleanupStreamingResponse as CleanupStream`, `static_file_response as serve`, `get_user_db_session as open_session`; a leading underscore is fine) and any non-call reference (`Download = WorkerCleanupStreamingResponse`, also in an allowlisted file, where only type-only annotations and subclasses named `...StreamingResponse`/`...FileResponse` are exempt) are flagged, so a re-export cannot be imported and called unchecked elsewhere; an attribute read off a fenced callable (`NoteService.__call__`, `get_user_db_session.__wrapped__`, `WorkerCleanupStreamingResponse.__call__`) is such a non-call reference, whether bound or called, and the isolation check exempts only type-only annotations, ALL_CAPS constant reads (`NoteAIService.MAX_CLAIMS_PER_NOTE`) and one pinned staticmethod read (`NoteService._rollback_quietly`); an annotation is not type-only, so a fenced name in it (or quoted in a string in it) is flagged, when it is evaluated into more than a type: a parameter or class-field annotation with a non-constant default (`svc: NoteService = Depends()`, where FastAPI itself constructs the class with `username` taken from the request; a class field counts wherever it sits in the class body, including under `if`/`try`, and takes as its default any binding of its name there, such as `svc: NoteService` followed by `svc = Depends()`), an `Annotated[...]` with non-constant metadata (`Annotated[T, Depends(get_user_db_session)]`), a starred element (`Annotated[*(NoteService, dep)]`) or a non-tuple slice, a call, walrus or lambda inside it, a class field with no binding in its own class body on a class with a base other than `object`/`Generic`/`Protocol` (it may inherit a `Depends()` default), or a string that does not parse; a string in a type position that does not parse as an expression (such as `"*[NoteService]"`, a valid forward reference but not an expression) or nests too deep is itself reported as an annotation string that cannot be checked (call arguments, `Literal` members and `Annotated` metadata are plain values and are exempt); every string in a type position is parsed and checked like unquoted code, recursively, because FastAPI evaluates it, so a wholly quoted `"Annotated[NoteService, Depends()]"` is caught too (`Annotated` metadata strings, which are never evaluated, are not parsed); a symlink inside a scanned directory is scanned even if its target lies elsewhere. The cross-user isolation census additionally flags any router `Depends(...)`/`Security(...)` target (for a bare `Depends()`, the annotated class; qualified `fastapi.Depends`, `dependency=`, `__wrapped__`-style reads, wholly quoted annotations and starred `Annotated` elements included) that takes a username/user_id/owner and is not itself an auth dependency. Both checks report a file they cannot read or parse (including nesting too deep for the parser) instead of skipping it or crashing. It does not cover responses built from file content already read into memory (`Response(content=path.read_bytes())`, `PlainTextResponse(path.read_text())`), a same-module generator that itself reads a file or is handed an open file as an argument, serving helpers defined outside `web/`, renames, re-exports, wrappers or dependency factories in modules outside the scanned directories, `Annotated` reached through an assignment alias (`A = Annotated`) with non-call metadata, constant-valued non-literal `username=` expressions such as `username=str(None)`, dynamic lookups (`getattr`, `importlib`, `__import__`, `module.__dict__[...]`, `eval`), or deliberate evasion such as a default set after the class body or signature (`Cls.attr = Depends()`, `f.__defaults__ = ...`) or by a metaclass, decorator or `__init_subclass__`, walrus bindings in subscript targets or in other annotations, and module-level string or type aliases of a fenced name (`Svc = "NoteService"`); these examples are not exhaustive.diff --git a/src/local_deep_research/web/services/research_service.py b/src/local_deep_research/web/services/research_service.pyindex a4bba193ca..e9b9f1d99e 100644--- a/src/local_deep_research/web/services/research_service.py+++ b/src/local_deep_research/web/services/research_service.py@@ -4,6 +4,7 @@ import jsonimport reimport threadingimport time+import uuidfrom datetime import datetime, UTCfrom pathlib import Path@@ -546,8 +547,13 @@ def _generate_report_path(query: str) -> Path:query_hash = hashlib.md5( # DevSkim: ignore DS126858query.encode("utf-8"), usedforsecurity=False).hexdigest()[:10]+ # Preventive hardening (this helper has no production caller today):+ # the directory is shared install-wide, and the hash+timestamp prefix+ # alone is deterministic across users, so the trailing random segment+ # keeps same-query, same-second calls from colliding.return OUTPUT_DIR / (- f"research_report_{query_hash}_{int(datetime.now(UTC).timestamp())}.md"+ f"research_report_{query_hash}_"+ f"{int(datetime.now(UTC).timestamp())}_{uuid.uuid4().hex[:8]}.md")diff --git a/tests/security/test_architecture_fences.py b/tests/security/test_architecture_fences.pynew file mode 100644index 0000000000..c4bcebf711--- /dev/null+++ b/tests/security/test_architecture_fences.py@@ -0,0 +1,1936 @@+"""Architecture fences: the invariants cross-user safety rests on.++Two invariants argued during the OpenWebUI-advisory mapping were+assertions, not contracts. These tests pin them -- and run the *same*+scanner scripts the pre-commit hooks run, invoked the way pre-commit+invokes them (repo-root cwd, repo-relative paths), so the hook and the+contract cannot drift:++1. **Per-user isolation (smoke check)**: every construction of a+ user-data service/session under the routers, ``research_library/``+ and ``web/services/`` passes a username-named argument explicitly.+ Where that username came from (it must be the ``require_auth``-derived+ one) is enforced for router call sites by+ tests/security/test_cross_user_isolation_census.py, not here.+2. **Web-layer file-serving references are fenced**: report artifacts+ land in an install-shared directory whose cross-user safety rests on+ root confinement, no path disclosure, and no serving route. Any+ ``FileResponse`` / ``StaticFiles`` / ``StreamingResponse`` reference+ (or star import) under ``web/`` outside the hook's per-file+ ALLOWED_FILES is flagged; LDR's serving wrappers+ (``WorkerCleanupStreamingResponse``) must be handed a same-module+ generator call; and a serving call referencing the outputs directory+ inline is flagged everywhere, allowlisted files included.++Plus: ``_generate_report_path`` (currently without production callers)+yields collision-free names, as preventive hardening for the shared+directory.+"""++from __future__ import annotations++import ast+import os+import subprocess+import sys+from importlib import import_module+from pathlib import Path++import pytest++from local_deep_research.web.services import research_service++REPO_ROOT = Path(__file__).resolve().parents[2]+HOOKS = REPO_ROOT / ".pre-commit-hooks"+sys.path.insert(0, str(HOOKS))++# Hook filenames are hyphenated, so they must be imported by string via+# import_module (the same idiom tests/security/test_sensitive_logging_hook.py+# and tests/hooks/test_hook_common.py use).+_isolation_hook = import_module("check-per-user-isolation")+_reports_hook = import_module("check-reports-dir-not-served")++# Read the scopes from the hook modules themselves, so the contract+# scans exactly what the hooks fence.+ISOLATION_DIRS = list(_isolation_hook.ISOLATION_SCAN_DIRS)+WEB_DIR = _reports_hook.FENCED_PREFIX+ISOLATION_HOOK = "check-per-user-isolation.py"+REPORTS_HOOK = "check-reports-dir-not-served.py"++# Near-actual *.py counts per scanned dir (actual minus 3; minus 4 for+# web/, which has 71), so a rename, typo or wholesale move that shrinks+# a scan fails loudly.+MIN_PY_FILES = {+ "src/local_deep_research/web/routers/": 19,+ "src/local_deep_research/research_library/": 43,+ "src/local_deep_research/web/services/": 5,+ "src/local_deep_research/web/": 67,+}+++def _files_under(rel_dirs: list[str]) -> list[str]:+ """Repo-relative paths (pre-commit style) of the *.py files under."""+ files: list[str] = []+ for rel in rel_dirs:+ files.extend(+ p.relative_to(REPO_ROOT).as_posix()+ for p in (REPO_ROOT / rel).rglob("*.py")+ )+ return files+++def _run_hook(+ script: str,+ files: list[str],+ cwd: Path = REPO_ROOT,+ hooks_dir: Path = HOOKS,+ env: dict[str, str] | None = None,+) -> subprocess.CompletedProcess:+ return subprocess.run(+ [sys.executable, str(hooks_dir / script), *files],+ capture_output=True,+ text=True,+ timeout=120,+ cwd=cwd,+ env=env,+ )+++def _write(root: Path, rel: str, source: str) -> str:+ target = root / rel+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text(source, encoding="utf-8")+ return rel+++def _mirror_hooks(root: Path) -> Path:+ """Copy both hook scripts into ``root/.pre-commit-hooks``.++ The hooks derive REPO_ROOT from their own location, so the copies+ treat ``root`` as the repository: fixtures written under it get the+ real scope filter and allowlist, exactly as in-repo files would.+ """+ hooks = root / ".pre-commit-hooks"+ hooks.mkdir(parents=True, exist_ok=True)+ for script in (ISOLATION_HOOK, REPORTS_HOOK):+ (hooks / script).write_text(+ (HOOKS / script).read_text(encoding="utf-8"), encoding="utf-8"+ )+ return hooks+++class TestFenceCoverageFloors:+ def test_scanned_dirs_exist_and_feed_the_scanners(self):+ """Vacuous-pass guard for the tree scans below.++ If a fenced dir were renamed or its path typo'd, ``_files_under()``+ would yield nothing and the scans would pass vacuously over an+ empty list. Pinning on-disk existence and a non-trivial ``*.py``+ floor per scan makes that case fail loudly.+ """+ scanned = ISOLATION_DIRS + [WEB_DIR]+ missing = [rel for rel in scanned if not (REPO_ROOT / rel).is_dir()]+ assert not missing, (+ "fence scans list dirs absent from the tree: " + ", ".join(missing)+ )+ assert sorted(scanned) == sorted(MIN_PY_FILES), (+ "scanned dirs and MIN_PY_FILES floors diverged"+ )+ for rel, floor in MIN_PY_FILES.items():+ count = len(_files_under([rel]))+ assert count >= floor, (+ f"{rel} feeds its fence scan only {count} .py files "+ f"(floor {floor}); a rename or typo shrank the scanned set"+ )+ for allowed in _reports_hook.ALLOWED_FILES:+ assert (REPO_ROOT / allowed).is_file(), (+ f"stale ALLOWED_FILES entry: {allowed}"+ )++ def test_detector_sets_pinned(self):+ """Partial-loss guard: deleting ANY detector must fail loudly.++ If a set were narrowed (a constructor or serving primitive+ dropped) or the allowlist widened, every remaining scan would+ stay green while coverage silently shrank. Pin the exact+ membership so any change must consciously update this list too.+ """+ assert _isolation_hook.ISOLATION_SCAN_DIRS == (+ "src/local_deep_research/web/routers/",+ "src/local_deep_research/research_library/",+ "src/local_deep_research/web/services/",+ ), (+ "ISOLATION_SCAN_DIRS changed; if intentional, update the "+ "pinned scope and MIN_PY_FILES with it"+ )+ assert _reports_hook.WRAPPER_SUFFIXES == (+ "StreamingResponse",+ "FileResponse",+ ), "WRAPPER_SUFFIXES changed; update the pinned tuple with it"+ assert sorted(_reports_hook.SERVING_HELPERS) == [+ "static_file_response",+ ], "SERVING_HELPERS changed; update the pinned list with it"+ assert sorted(_isolation_hook.USER_DATA_CONSTRUCTORS) == [+ "BulkDeletionService",+ "CollectionDeletionService",+ "DocumentDeletionService",+ "DownloadService",+ "FollowUpResearchService",+ "LibraryService",+ "NoteAIService",+ "NoteService",+ "get_user_db_session",+ ], (+ "USER_DATA_CONSTRUCTORS membership changed; if intentional, "+ "update the pinned expected list with it"+ )+ assert sorted(_isolation_hook.ALLOWED_ATTRIBUTE_READS) == [+ ("NoteService", "_rollback_quietly"),+ ], (+ "ALLOWED_ATTRIBUTE_READS changed; an attribute read off a "+ "constructor can construct it without a username, so a new "+ "pair needs review and a conscious update of this list"+ )+ assert sorted(_reports_hook.SERVING_PRIMITIVES) == [+ "FileResponse",+ "StaticFiles",+ "StreamingResponse",+ ], (+ "SERVING_PRIMITIVES membership changed; if intentional, "+ "update the pinned expected list with it"+ )+ assert sorted(_reports_hook.ALLOWED_FILES) == [+ "src/local_deep_research/web/dependencies/threadpool.py",+ "src/local_deep_research/web/fastapi_app.py",+ "src/local_deep_research/web/static_files.py",+ ], (+ "ALLOWED_FILES changed; a new file-serving site needs review "+ "and a conscious update of this pinned list"+ )+++class TestPerUserIsolationFence:+ def test_every_user_data_construction_passes_a_username(self):+ result = _run_hook(ISOLATION_HOOK, _files_under(ISOLATION_DIRS))+ assert result.returncode == 0, (+ f"user-data access without username:\n{result.stdout}"+ )++ def test_the_scanner_catches_an_unbound_construction(self, tmp_path):+ """Mutation guard: the fence must actually fire."""+ hostile = tmp_path / "routes_violation.py"+ hostile.write_text(+ "from x import NoteService, get_user_db_session\n"+ "svc = NoteService()\n"+ "s = get_user_db_session(username=None)\n"+ "import x as ns\n"+ "t = ns.NoteService()\n"+ 'u = get_user_db_session(username=f"alice")\n'+ "from x import LibraryService as LS\n"+ "v = LS()\n"+ "w = NoteService(owner=username)\n"+ "y = get_user_db_session(username=None, owner_username=u)\n"+ "z = NoteService(username, username=None)\n",+ encoding="utf-8",+ )+ attr_ok = tmp_path / "attribute_binding_ok.py"+ attr_ok.write_text(+ "from x import NoteService\n"+ "class H:\n"+ " def __init__(self, username):\n"+ " self.username = username\n"+ " def go(self):\n"+ " return NoteService(self.username)\n"+ "def kw_value(username, auth):\n"+ " a = NoteService(username=username)\n"+ ' return get_user_db_session(username=auth["name"])\n',+ encoding="utf-8",+ )+ result = _run_hook(ISOLATION_HOOK, [str(hostile), str(attr_ok)])+ assert result.returncode == 1+ assert "routes_violation.py:2: NoteService" in result.stdout+ assert "routes_violation.py:3: get_user_db_session" in result.stdout, (+ "username=None (a literal constant) must be flagged"+ )+ assert "routes_violation.py:5: NoteService" in result.stdout, (+ "module-attribute construction (ns.NoteService()) must be flagged"+ )+ assert "routes_violation.py:6: get_user_db_session" in result.stdout, (+ 'username=f"alice" (a placeholder-free f-string) must be flagged'+ )+ assert "routes_violation.py:8: LibraryService" in result.stdout, (+ "an aliased constructor import (LS = LibraryService) must be "+ "flagged under its real name"+ )+ assert "routes_violation.py:9: NoteService" in result.stdout, (+ "a username-named value under a non-username keyword "+ "(owner=username) must be flagged"+ )+ for lineno in (10, 11):+ assert f"routes_violation.py:{lineno}: " in result.stdout, (+ f"line {lineno}: a literal username= must be flagged even "+ "when another argument names a username"+ )+ assert "attribute_binding_ok" not in result.stdout, (+ "a positional self.username attribute and a non-literal "+ "username= expression must not be flagged"+ )++ def test_every_fenced_service_is_flagged_without_a_username(self, tmp_path):+ """Each constructor beyond the original four is fenced too: the+ destructive deletion services, NoteAIService, and+ FollowUpResearchService, whose ``username`` defaults to None, so+ a bare ``FollowUpResearchService()`` is exactly the defaulted+ construction the fence exists to catch. Aliased and+ module-attribute forms are flagged under the real name, and the+ router call shapes used on main pass."""+ added = (+ "DocumentDeletionService",+ "CollectionDeletionService",+ "BulkDeletionService",+ "NoteAIService",+ "FollowUpResearchService",+ )+ hostile = tmp_path / "services_violation.py"+ hostile.write_text(+ "from x import "+ + ", ".join(added)+ + "\n"+ + "".join(f"s{i} = {name}()\n" for i, name in enumerate(added))+ + "f = FollowUpResearchService(username=None)\n"+ "from x import BulkDeletionService as BDS\n"+ "b = BDS()\n"+ "import x as svc\n"+ "n = svc.NoteAIService()\n",+ encoding="utf-8",+ )+ ok = tmp_path / "services_ok.py"+ ok.write_text(+ "from x import " + ", ".join(added) + "\n"+ "def route(username, dbpw):\n"+ " DocumentDeletionService(username)\n"+ " CollectionDeletionService(username)\n"+ " BulkDeletionService(\n"+ " username\n"+ " ).delete_documents([])\n"+ " NoteAIService(username, dbpw=dbpw)\n"+ " return FollowUpResearchService(username=username)\n",+ encoding="utf-8",+ )+ result = _run_hook(ISOLATION_HOOK, [str(hostile), str(ok)])+ assert result.returncode == 1+ for lineno, name in enumerate(added, start=2):+ assert f"services_violation.py:{lineno}: {name}" in result.stdout, (+ f"a bare {name}() must be flagged"+ )+ for expected, why in (+ (+ "services_violation.py:7: FollowUpResearchService",+ "username=None",+ ),+ ("services_violation.py:9: BulkDeletionService", "an import alias"),+ ("services_violation.py:11: NoteAIService", "a module attribute"),+ ):+ assert expected in result.stdout, f"{why} must be flagged"+ assert "services_ok" not in result.stdout, (+ "the username-passing call shapes used by the routers must pass"+ )++ def test_a_literal_under_any_username_named_keyword_is_flagged(+ self, tmp_path+ ):+ """The literal check must apply to EVERY keyword whose name+ contains 'username', not just the exact 'username' keyword: a+ literal owner_username, and a literal owner_username alongside+ a non-literal positional username, are both flagged. A+ non-literal owner_username= expression is accepted, as+ documented."""+ hostile = tmp_path / "owner_username.py"+ hostile.write_text(+ "from x import NoteService, get_user_db_session\n"+ "a = get_user_db_session(owner_username=None)\n"+ 'b = NoteService(username, owner_username="alice")\n',+ encoding="utf-8",+ )+ ok = tmp_path / "owner_username_ok.py"+ ok.write_text(+ "from x import NoteService\n"+ "def go(username, u):\n"+ " return NoteService(username, owner_username=u)\n",+ encoding="utf-8",+ )+ result = _run_hook(ISOLATION_HOOK, [str(hostile), str(ok)])+ assert result.returncode == 1+ assert "owner_username.py:2: get_user_db_session" in result.stdout, (+ "a literal owner_username=None must be flagged"+ )+ assert "owner_username.py:3: NoteService" in result.stdout, (+ "a literal owner_username= must be flagged even when a "+ "non-literal positional username argument is also present"+ )+ assert "owner_username_ok" not in result.stdout, (+ "owner_username=u (a non-literal expression) must be accepted"+ )++ def test_repo_relative_invocation_applies_the_scan_scope(self, tmp_path):+ """Pre-commit passes repo-relative paths: the scope filter must+ scan every ISOLATION_SCAN_DIRS file and skip the rest."""+ hooks = _mirror_hooks(tmp_path)+ bad = "svc = NoteService()\n"+ in_scope = [+ _write(tmp_path, rel + "bad.py", bad) for rel in ISOLATION_DIRS+ ]+ out_of_scope = _write(+ tmp_path, "src/local_deep_research/other/bad.py", bad+ )+ result = _run_hook(+ ISOLATION_HOOK,+ [*in_scope, out_of_scope],+ cwd=tmp_path,+ hooks_dir=hooks,+ )+ assert result.returncode == 1+ for rel in in_scope:+ assert rel in result.stdout, f"{rel} not scanned"+ assert out_of_scope not in result.stdout++ def test_paths_are_normalised_before_the_scope_filter(self, tmp_path):+ """``..`` segments, a non-root cwd and absolute in-repo paths+ all resolve to the true repo-relative path (fail closed)."""+ hooks = _mirror_hooks(tmp_path)+ bad = "svc = NoteService()\n"+ router = ISOLATION_DIRS[0]+ _write(tmp_path, router + "bad.py", bad)+ _write(tmp_path, "src/local_deep_research/other/bad.py", bad)+ dotted = "src/local_deep_research/other/../../../" + router + "bad.py"+ result = _run_hook(+ ISOLATION_HOOK, [dotted], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, "a '..' path escaped the scan scope"+ from_subdir = router.removeprefix("src/") + "bad.py"+ result = _run_hook(+ ISOLATION_HOOK,+ [from_subdir],+ cwd=tmp_path / "src",+ hooks_dir=hooks,+ )+ assert result.returncode == 1, "a non-root cwd escaped the scope"+ result = _run_hook(+ ISOLATION_HOOK,+ [str(tmp_path / "src/local_deep_research/other/bad.py")],+ cwd=tmp_path,+ hooks_dir=hooks,+ )+ assert result.returncode == 0, (+ "an absolute in-repo path outside the scope must be skipped"+ )++ def test_a_constructor_cannot_leave_a_module_under_another_name(+ self, tmp_path+ ):+ """Cross-module rename: no rule follows a name from one module+ into another, so ``sessions.py`` re-exporting+ ``get_user_db_session as open_session`` would let a router call+ ``open_session()`` unchecked. The rename (and any loaded+ non-call reference such as ``make = NoteService``) is flagged+ where it happens; an alias keeping the constructor name behind+ leading underscores is accepted and its calls are checked in+ every importer. Type-only annotations and ALL_CAPS constant reads+ off the class are not rebindings."""+ hooks = _mirror_hooks(tmp_path)+ sessions = _write(+ tmp_path,+ "src/local_deep_research/web/services/sessions.py",+ "from ...database.session_context import (\n"+ " get_user_db_session as open_session,\n"+ ")\n"+ "from ...database.session_context import (\n"+ " get_user_db_session as _get_user_db_session,\n"+ ")\n"+ "from .notes import NoteService, LibraryService\n"+ "make = NoteService\n"+ "class Mine(LibraryService):\n"+ " pass\n"+ "def ok(username, s: NoteService) -> LibraryService:\n"+ " cap = NoteService.MAX_LEN\n"+ " return _get_user_db_session(username)\n",+ )+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/notes_export.py",+ "from ..services.sessions import open_session, _get_user_db_session\n"+ "def a():\n"+ " with open_session() as s:\n"+ " return s\n"+ "def b():\n"+ " return _get_user_db_session()\n",+ )+ result = _run_hook(+ ISOLATION_HOOK, [sessions, router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected, why in (+ (+ f"{sessions}:1: get_user_db_session imported as open_session",+ "a rename to a non-constructor name",+ ),+ (f"{sessions}:8: non-call reference to NoteService", "make = ..."),+ (+ f"{sessions}:9: non-call reference to LibraryService",+ "a subclass",+ ),+ (+ f"{router}:6: get_user_db_session(...) without",+ "an underscore-prefixed alias imported into another module",+ ),+ ):+ assert expected in result.stdout, f"{why} not flagged"+ for lineno in (4, 11, 12, 13):+ assert f"{sessions}:{lineno}:" not in result.stdout, (+ f"line {lineno}: an underscore alias, an annotation or an "+ "attribute read must not be flagged"+ )++ def test_attribute_reads_off_a_constructor_are_references(self, tmp_path):+ """``NoteService.__call__`` / ``get_user_db_session.__wrapped__``+ is the constructor under another name: binding it, or calling+ it without a username, must be flagged exactly like ``make =+ NoteService``, whether the class is reached by bare name or as+ a module attribute. Only ALL_CAPS constants and the pinned+ ALLOWED_ATTRIBUTE_READS pairs may be read off a constructor."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/dunder.py",+ "from ..services.x import NoteService, get_user_db_session\n"+ "from ..services.x import FollowUpResearchService as _FURS\n"+ "from ..services import mod\n"+ "make = NoteService.__call__\n"+ "open_session = get_user_db_session.__wrapped__\n"+ "make2 = mod.NoteService.__call__\n"+ "def a():\n"+ " return NoteService.__call__()\n"+ "def b():\n"+ " return FollowUpResearchService.__call__()\n"+ "def c():\n"+ " with get_user_db_session.__call__() as s:\n"+ " return s\n"+ "def d():\n"+ " return _FURS.from_request()\n"+ "def ok(username, s):\n"+ " NoteService._rollback_quietly(s)\n"+ " cap = mod.NoteAIService.MAX_CLAIMS_PER_NOTE\n"+ " return NoteService(username), cap\n",+ )+ result = _run_hook(+ ISOLATION_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for lineno, name, attr in (+ (4, "NoteService", "__call__"),+ (5, "get_user_db_session", "__wrapped__"),+ (6, "NoteService", "__call__"),+ (8, "NoteService", "__call__"),+ (10, "FollowUpResearchService", "__call__"),+ (12, "get_user_db_session", "__call__"),+ (15, "FollowUpResearchService", "from_request"),+ ):+ expected = (+ f"{router}:{lineno}: non-call reference to {name} (via .{attr}:"+ )+ assert expected in result.stdout, f"{expected!r} not flagged"+ for lineno in (16, 17, 18, 19):+ assert f"{router}:{lineno}:" not in result.stdout, (+ f"line {lineno}: an allowlisted attribute read, an ALL_CAPS "+ "constant or a username-passing call must be accepted"+ )++ def test_evaluated_annotations_are_references(self, tmp_path):+ """An annotation is exempt only while it is just a type. FastAPI+ CALLS the annotated class of a ``Depends()`` parameter (and+ every ``Depends(f)`` target), filling ``username`` from the+ request (``?username=victim``); a walrus in an annotation binds+ the constructor in the enclosing scope (annotations are+ evaluated eagerly before 3.14). Each shape below is a reference;+ a plain type annotation, a non-constructor ``Depends()`` and an+ auth dependency in ``Annotated`` are not."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/injected.py",+ "from dataclasses import dataclass\n"+ "from typing import Annotated\n"+ "import fastapi\n"+ "from fastapi import Depends as D\n"+ "from ..services.x import NoteService, get_user_db_session\n"+ "def a(svc: NoteService = D()):\n"+ " return svc\n"+ "def b(svc: Annotated[NoteService, D()]):\n"+ " return svc\n"+ "def c(svc: Annotated[NoteService, D(NoteService)]):\n"+ " return svc\n"+ "def d(db: Annotated[object, D(get_user_db_session)]):\n"+ " return db\n"+ "def e(db: Annotated[object, D(get_user_db_session.__wrapped__)]):\n"+ " return db\n"+ "def f(*, svc: NoteService = fastapi.Security(scopes=['x'])):\n"+ " return svc\n"+ "def g(svc: 'NoteService' = D(None)):\n"+ " return svc\n"+ "x: (open_session := get_user_db_session) = 1\n"+ "def h(a: (make := NoteService) = None):\n"+ " return make()\n"+ "@dataclass\n"+ "class Deps:\n"+ " svc: NoteService = D()\n"+ "def ok(\n"+ " username,\n"+ " s: NoteService,\n"+ " csrf_protect: CsrfProtect = D(),\n"+ " user: Annotated[str, D(require_auth)] = None,\n"+ ") -> NoteService:\n"+ " svc: NoteService = NoteService(username)\n"+ " return svc\n"+ "dep = D()\n"+ "def i(svc: NoteService = dep):\n"+ " return svc\n"+ "from typing import Annotated as A\n"+ "def j(svc: A[NoteService, dep]):\n"+ " return svc\n"+ "def typed(\n"+ " s: NoteService = None,\n"+ " t: dict[str, NoteService] | None = None,\n"+ " u: A[NoteService, 'a constant'] = None,\n"+ ") -> NoteService:\n"+ " return s\n"+ "def l(a: register(NoteService)):\n"+ " return a\n",+ )+ result = _run_hook(+ ISOLATION_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for lineno, name, why in (+ (6, "NoteService", "a bare Depends() default"),+ (8, "NoteService", "Annotated[..., Depends()]"),+ (10, "NoteService", "Depends(NoteService) inside Annotated"),+ (12, "get_user_db_session", "Depends(f) inside Annotated"),+ (14, "get_user_db_session", "Depends(f.__wrapped__)"),+ (16, "NoteService", "a qualified Security(...) default"),+ (18, "NoteService", "a quoted forward reference + Depends(None)"),+ (20, "get_user_db_session", "a walrus in a variable annotation"),+ (21, "NoteService", "a walrus in a parameter annotation"),+ (25, "NoteService", "a Depends() dataclass field"),+ (35, "NoteService", "a Depends() bound to a name"),+ (38, "NoteService", "an aliased Annotated with a name"),+ (46, "NoteService", "a call inside a plain annotation"),+ ):+ expected = f"{router}:{lineno}: non-call reference to {name}"+ assert expected in result.stdout, f"{why} not flagged"+ for lineno in (*range(26, 35), *range(40, 46)):+ assert f"{router}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a type-only annotation, a non-constructor "+ "Depends() or an auth dependency must be accepted"+ )++ def test_quoted_starred_and_nested_annotations_are_references(+ self, tmp_path+ ):+ """FastAPI evaluates a wholly quoted annotation, unpacks a starred+ ``Annotated`` element and sees a class field declared under+ ``if`` / ``try`` in the class body or defaulted by a separate+ binding of its name (``svc: T`` then ``svc = Depends()``), so+ each of these builds ``NoteService`` with ``username`` from the+ request. A string in a type position that does not parse fails+ closed; plain quoted types, ``Annotated`` doc strings and+ constant class defaults stay type-only."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/quoted.py",+ "from dataclasses import dataclass\n"+ "from typing import Annotated, Optional\n"+ "from fastapi import Depends\n"+ "from ..services.x import NoteService, get_user_db_session\n"+ "dep = Depends()\n"+ 'def a(svc: "Annotated[NoteService, Depends()]"):\n'+ " return svc\n"+ 'def b(db: "Annotated[object, Depends(get_user_db_session)]"):\n'+ " return db\n"+ "def c(svc: Optional[\"'Annotated[NoteService, dep]'\"]):\n"+ " return svc\n"+ "def d(svc: Annotated[*(NoteService, dep)]):\n"+ " return svc\n"+ "def e(svc: Annotated[*(NoteService, Depends())]):\n"+ " return svc\n"+ "@dataclass\n"+ "class F:\n"+ " if True:\n"+ " svc: NoteService = Depends()\n"+ " try:\n"+ " db: get_user_db_session = dep\n"+ " except ImportError:\n"+ " pass\n"+ 'def g(svc: tuple[NoteService, "not an ) expression"]):\n'+ " return svc\n"+ 'def h(svc: Annotated[NoteService, "not an ) expression"]):\n'+ " return svc\n"+ "def ok(\n"+ ' s: "NoteService",\n'+ ' t: Optional["NoteService"] = None,\n'+ ' u: Annotated["NoteService", "a doc string"] = None,\n'+ ' v: "Annotated[NoteService, 0]" = None,\n'+ ") -> \"Optional['NoteService']\":\n"+ " return s\n"+ "class G:\n"+ " def m(self):\n"+ " svc: NoteService = dep\n"+ " return svc\n"+ " name: NoteService\n"+ " name = 'a constant'\n"+ "@dataclass\n"+ "class H:\n"+ " svc: NoteService\n"+ " svc = Depends()\n"+ " db: get_user_db_session\n"+ " for db in [dep]:\n"+ " pass\n",+ )+ result = _run_hook(+ ISOLATION_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for lineno, name, why in (+ (6, "NoteService", "a wholly quoted Annotated[..., Depends()]"),+ (8, "get_user_db_session", "a quoted Depends(f) in Annotated"),+ (10, "NoteService", "a doubly quoted Annotated with a name"),+ (12, "NoteService", "a starred Annotated with a name"),+ (14, "NoteService", "a starred Annotated with Depends()"),+ (19, "NoteService", "a Depends() field under if in a class"),+ (21, "get_user_db_session", "a field under try in a class"),+ (24, "NoteService", "an unparsable string in a type position"),+ (43, "NoteService", "a field defaulted by a later assignment"),+ (45, "get_user_db_session", "a field bound by a loop target"),+ ):+ expected = f"{router}:{lineno}: non-call reference to {name}"+ assert expected in result.stdout, f"{why} not flagged"+ for lineno in range(26, 42):+ assert f"{router}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a quoted type, an Annotated doc string, "+ "a constant class default or a function-local annotation "+ "must be accepted"+ )++ def test_unchecked_annotation_strings_and_inherited_defaults(+ self, tmp_path+ ):+ """A string in a type position that cannot be checked (does not+ parse as an expression, e.g. ``"*[NoteService]"``, which is a+ valid ForwardRef but not an expression, or nests deeper than+ ``_MAX_QUOTE_DEPTH``) is an offender in itself. A class field+ with no binding in its own body, on a class with a base other+ than ``object`` / ``Generic`` / ``Protocol``, may inherit a+ ``Depends()`` default, so it is a reference. Strings that are+ plain values (call arguments, ``Literal``, ``Annotated``+ metadata) and fields of base-less classes stay accepted."""+ hooks = _mirror_hooks(tmp_path)+ deep = "NoteService"+ for _ in range(_isolation_hook._MAX_QUOTE_DEPTH + 1):+ deep = repr(deep)+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/unchecked.py",+ "from typing import Annotated, Generic, Literal, Optional\n"+ "from typing import Protocol, TypeVar\n"+ "from fastapi import Query\n"+ "from pydantic import BaseModel\n"+ "from ..services.x import NoteService\n"+ 'T = TypeVar("T")\n'+ 'def a(x: "not an ) expression"):\n'+ " return x\n"+ 'def b(x: Optional["*[NoteService]"]):\n'+ " return x\n"+ "def c(x: " + deep + "):\n"+ " return x\n"+ "class Model(BaseModel):\n"+ " svc: NoteService\n"+ "class Sub(Model):\n"+ " db: NoteService\n"+ "def ok_d(\n"+ ' x: Annotated[str, Query(description="free ) text")] = None,\n'+ ' y: Literal["in progress", "a ) b"] = "a ) b",\n'+ ' z: Annotated[int, "a ) doc"] = 0,\n'+ "):\n"+ " return x\n"+ "class Plain:\n"+ " svc: NoteService\n"+ "class Obj(object):\n"+ " svc: NoteService\n"+ "class Gen(Generic[T]):\n"+ " svc: NoteService\n"+ "class Proto(Protocol):\n"+ " svc: NoteService\n"+ "class Defaulted(BaseModel):\n"+ " svc: NoteService = None\n",+ )+ result = _run_hook(+ ISOLATION_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for lineno, what, why in (+ (7, "annotation string that cannot be checked", "unparsable"),+ (9, "annotation string that cannot be checked", "ForwardRef-only"),+ (11, "annotation string that cannot be checked", "too deep"),+ (14, "non-call reference to NoteService", "inherited default"),+ (16, "non-call reference to NoteService", "inherited (subclass)"),+ ):+ assert f"{router}:{lineno}: {what}" in result.stdout, (+ f"{why} not flagged"+ )+ for lineno in range(17, 33):+ assert f"{router}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a plain-value string, a field of a "+ "base-less class or a constant default must be accepted"+ )++ def test_a_symlink_into_the_scope_is_scanned(self, tmp_path):+ """A symlink inside a scanned dir whose target lies outside it+ is still scanned: the scope accepts the lexical OR the resolved+ repo-relative path."""+ hooks = _mirror_hooks(tmp_path)+ target = _write(+ tmp_path,+ "src/local_deep_research/other/real.py",+ "svc = NoteService()\n",+ )+ link = ISOLATION_DIRS[0] + "linked.py"+ (tmp_path / link).parent.mkdir(parents=True, exist_ok=True)+ try:+ (tmp_path / link).symlink_to(tmp_path / target)+ except (OSError, NotImplementedError):+ pytest.skip("symlinks unsupported here")+ result = _run_hook(+ ISOLATION_HOOK, [link], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, "a symlink escaped the scan scope"+ result = _run_hook(+ ISOLATION_HOOK, [target], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 0, "the out-of-scope target is skipped"+++class TestReportsDirNotServedFence:+ def test_no_new_file_serving_site_in_the_web_layer(self):+ result = _run_hook(REPORTS_HOOK, _files_under([WEB_DIR]))+ assert result.returncode == 0, (+ f"new HTTP file-serving site:\n{result.stdout}"+ )++ def test_absolute_in_repo_path_to_an_allowlisted_file_passes(self):+ """Absolute paths go through the repo-relative resolution, so an+ allowlisted file (which does reference FileResponse) is exempt."""+ allowed = [str(REPO_ROOT / rel) for rel in _reports_hook.ALLOWED_FILES]+ result = _run_hook(REPORTS_HOOK, allowed)+ assert result.returncode == 0, result.stdout++ def test_the_scanner_catches_serving_routes(self, tmp_path):+ """Positive controls: the fence must fire on inline outputs+ references, aliased imports and module-attribute access."""+ inline = tmp_path / "serve_inline.py"+ inline.write_text(+ "from fastapi.responses import FileResponse\n"+ "from svc import OUTPUT_DIR\n"+ "def download(name):\n"+ " return FileResponse(OUTPUT_DIR / name)\n",+ encoding="utf-8",+ )+ bound = tmp_path / "serve_bound.py"+ bound.write_text(+ "from fastapi.responses import FileResponse as FR\n"+ "from svc import get_research_outputs_directory\n"+ "def download(name):\n"+ " root = get_research_outputs_directory().resolve()\n"+ " return FR(root / name)\n",+ encoding="utf-8",+ )+ attr = tmp_path / "serve_attr.py"+ attr.write_text(+ "import starlette.staticfiles as sf\n"+ "def mount(app, reports_dir):\n"+ " app.mount('/r', sf.StaticFiles(directory=reports_dir))\n",+ encoding="utf-8",+ )+ result = _run_hook(REPORTS_HOOK, [str(inline), str(bound), str(attr)])+ assert result.returncode == 1+ for name in ("serve_inline.py", "serve_bound.py", "serve_attr.py"):+ assert name in result.stdout, f"{name} not flagged"++ def test_star_imports_and_bare_names_are_flagged(self, tmp_path):+ """Positive controls: the fence must fire on star imports and on+ bare primitive names."""+ star_ldr = tmp_path / "star_ldr.py"+ star_ldr.write_text(+ "from ..dependencies.threadpool import *\n"+ "def f(g):\n"+ " return StreamingResponse(g())\n",+ encoding="utf-8",+ )+ star_fastapi = tmp_path / "star_fastapi.py"+ star_fastapi.write_text(+ "from fastapi.responses import *\n", encoding="utf-8"+ )+ bare = tmp_path / "bare_name.py"+ bare.write_text(+ "def f(p):\n return FileResponse(p)\n", encoding="utf-8"+ )+ result = _run_hook(+ REPORTS_HOOK, [str(star_ldr), str(star_fastapi), str(bare)]+ )+ assert result.returncode == 1+ for expected in (+ "star_ldr.py:1: star import",+ "star_ldr.py:3: reference to StreamingResponse",+ "star_fastapi.py:1: star import",+ "bare_name.py:2: reference to FileResponse",+ ):+ assert expected in result.stdout, f"{expected!r} not flagged"++ def test_serving_wrappers_must_take_a_local_generator(self, tmp_path):+ """WorkerCleanupStreamingResponse is defined in an allowlisted+ file, so importing it is fine -- but handing it a file object, a+ path or any non-generator content is flagged, under any alias."""+ # Every name but b_decorated and b_lambda is also defined as an+ # undecorated module-level generator (def <name>(): yield ...);+ # one other binding must disqualify it. b_decorated has only+ # ONE def, which yields but is decorated (the decorator alone+ # disqualifies it); b_lambda's own body never yields (only a+ # nested lambda does, which doesn't count), so it is never a+ # generator to begin with.+ disqualified = (+ "b_assign",+ "b_walrus",+ "b_for",+ "b_with",+ "b_del",+ "b_import",+ "b_class",+ "b_except",+ "b_global",+ "b_match",+ "b_star",+ "b_rest",+ "b_decorated",+ "b_lambda",+ "b_async",+ )+ hostile = tmp_path / "wrapper_hostile.py"+ hostile.write_text(+ "from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse,\n"+ " WorkerCleanupStreamingResponse as W,\n"+ ")\n"+ "from ..dependencies import threadpool as tp\n"+ "def a(reports_path):\n"+ " return WorkerCleanupStreamingResponse(open(reports_path, 'rb'))\n"+ "def b(p):\n"+ " return W(iter(open(p, 'rb')))\n"+ "def c(p):\n"+ " return tp.WorkerCleanupStreamingResponse(content=p)\n"+ "def d(self):\n"+ " return W(self.body)\n"+ "Alias = WorkerCleanupStreamingResponse\n"+ "from ..dependencies.threadpool import SafeFileResponse\n"+ "def e(p):\n"+ " return SafeFileResponse(p)\n"+ "def _load(p):\n"+ " return open(p, 'rb')\n"+ "def f(p):\n"+ " return W(_load(p))\n"+ "class Exporter:\n"+ " def open(self):\n"+ " yield b'x'\n"+ " def stream(self):\n"+ " yield b'x'\n"+ "def g(p):\n"+ " return W(open(p, 'rb'))\n"+ "def h(p):\n"+ " return W(iter(open(p, 'rb')))\n"+ "def gen_a():\n"+ " yield b'x'\n"+ "def i(gen_a):\n"+ " return W(gen_a())\n"+ "def gen_b():\n"+ " yield b'x'\n"+ "def j(p):\n"+ " def gen_b():\n"+ " return open(p, 'rb')\n"+ " return W(gen_b())\n"+ "def iter(x):\n"+ " yield x\n"+ "def k():\n"+ " return W(stream())\n"+ "def gen_c(p):\n"+ " def inner():\n"+ " yield b'x'\n"+ " return open(p, 'rb')\n"+ "def m(p):\n"+ " return W(gen_c(p))\n"+ # 51-57: a non-generator def inside a method disqualifies a+ # module-level generator of the same name.+ "def generate():\n"+ " yield b'x'\n"+ "class Svc:\n"+ " def dl(self, p):\n"+ " def generate():\n"+ " return open(p, 'rb')\n"+ " return W(generate())\n"+ # 58-: one line per disqualifying binding kind of a name+ # that is also defined as a module-level generator.+ "def b_assign():\n yield b''\n"+ "b_assign = lambda p: open(p, 'rb')\n"+ "def b_walrus():\n yield b''\n"+ "if (b_walrus := None):\n pass\n"+ "def b_for():\n yield b''\n"+ "for b_for in []:\n pass\n"+ "def b_with():\n yield b''\n"+ "with ctx() as b_with:\n pass\n"+ "def b_del():\n yield b''\n"+ "del b_del\n"+ "def b_import():\n yield b''\n"+ "from x import y as b_import\n"+ "def b_class():\n yield b''\n"+ "class b_class:\n pass\n"+ "def b_except():\n yield b''\n"+ "try:\n pass\nexcept Exception as b_except:\n pass\n"+ "def b_global():\n yield b''\n"+ "def rebind():\n global b_global\n"+ "def b_match():\n yield b''\n"+ "match 1:\n case b_match:\n pass\n"+ "def b_star():\n yield b''\n"+ "match 1:\n case [*b_star]:\n pass\n"+ "def b_rest():\n yield b''\n"+ "match 1:\n case {**b_rest}:\n pass\n"+ # R1: a decorator can replace the generator.+ "@reader\n"+ "def b_decorated(p):\n yield b''\n"+ # R7: a yield only inside a nested lambda does not make the+ # outer def a generator.+ "def b_lambda(p):\n"+ " f = lambda: (yield)\n"+ " return open(p, 'rb')\n"+ # An async non-generator def disqualifies the name too.+ "def b_async():\n yield b''\n"+ "def holder():\n"+ " async def b_async(p):\n"+ " return open(p, 'rb')\n"+ "def route_bindings(p):\n"+ " return [\n"+ + "".join(f" W({name}(p)),\n" for name in disqualified)+ + " ]\n",+ encoding="utf-8",+ )+ ok = tmp_path / "wrapper_ok.py"+ ok.write_text(+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse\n"+ "def route():\n"+ " def generate():\n"+ " yield b'x'\n"+ " return WorkerCleanupStreamingResponse(\n"+ " generate(), media_type='text/event-stream'\n"+ " )\n"+ "def route_kw():\n"+ " def stream():\n"+ " yield b'x'\n"+ " return WorkerCleanupStreamingResponse(content=stream())\n"+ "def module_gen(p):\n"+ " yield from [p]\n"+ "def route_module_gen(p):\n"+ " return WorkerCleanupStreamingResponse(module_gen(p))\n"+ "async def agen():\n"+ " yield b'x'\n"+ "def route_async():\n"+ " return WorkerCleanupStreamingResponse(agen())\n",+ encoding="utf-8",+ )+ result = _run_hook(REPORTS_HOOK, [str(hostile), str(ok)])+ assert result.returncode == 1+ # 21: a same-module helper that returns open() is not a+ # generator; 28/30: open/iter are builtins, never accepted even+ # though a method (open) or a module-level generator (iter) of+ # that name exists; 34/40: a generator name shadowed by a+ # parameter or by a non-generator def of the same name; 44: a+ # class-body method is not a bare-name callee; 50: a yield in a+ # nested function does not make the outer one a generator.+ # 57: a module-level generator whose name is also a+ # non-generator def nested in a method.+ for lineno in (7, 9, 11, 13, 17, 21, 28, 30, 34, 40, 44, 50, 57):+ assert f"wrapper_hostile.py:{lineno}: " in result.stdout, (+ f"wrapper call on line {lineno} not flagged"+ )+ lines = hostile.read_text(encoding="utf-8").splitlines()+ for name in disqualified:+ lineno = lines.index(f" W({name}(p)),") + 1+ assert f"wrapper_hostile.py:{lineno}: " in result.stdout, (+ f"W({name}(p)) on line {lineno} not flagged: {name} is "+ "disqualified by another binding or def shape"+ )+ assert "wrapper_hostile.py:14: non-call reference" in result.stdout+ assert "wrapper_ok.py" not in result.stdout, (+ "a same-module generator call must not be flagged"+ )++ def test_a_decorated_def_anywhere_disqualifies_the_name(self, tmp_path):+ """A decorator can replace the function, so a name is never a+ trusted generator if ANY def of it anywhere in the module is+ decorated -- even a def nested inside another function, and+ even though that nested def's own body does yield."""+ hostile = tmp_path / "decorated_anywhere.py"+ hostile.write_text(+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse as W\n"+ "def g():\n"+ " yield b''\n"+ "def route(p):\n"+ " @reader\n"+ " def g():\n"+ " yield b''\n"+ " return W(g())\n",+ encoding="utf-8",+ )+ result = _run_hook(REPORTS_HOOK, [str(hostile)])+ assert result.returncode == 1+ assert "decorated_anywhere.py:8: " in result.stdout, (+ "a decorated def nested in another function must disqualify "+ "the name everywhere, including a module-level generator call"+ )++ def test_an_unaliased_import_binding_disqualifies_the_name(self, tmp_path):+ """``_other_bindings`` must bind the import's natural name, not+ only an explicit ``as`` alias: a bare ``from evil import g`` and+ a dotted ``import g.sub`` (which binds the top-level name+ ``g``) each disqualify a same-named module-level generator."""+ from_import = tmp_path / "from_import.py"+ from_import.write_text(+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse as W\n"+ "def g():\n"+ " yield b''\n"+ "from evil import g\n"+ "def route(p):\n"+ " return W(g())\n",+ encoding="utf-8",+ )+ dotted_import = tmp_path / "dotted_import.py"+ dotted_import.write_text(+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse as W\n"+ "def g():\n"+ " yield b''\n"+ "import g.sub\n"+ "def route(p):\n"+ " return W(g())\n",+ encoding="utf-8",+ )+ result = _run_hook(REPORTS_HOOK, [str(from_import), str(dotted_import)])+ assert result.returncode == 1+ assert "from_import.py:6: " in result.stdout, (+ "an unaliased 'from evil import g' must bind g and "+ "disqualify the module-level generator of the same name"+ )+ assert "dotted_import.py:6: " in result.stdout, (+ "'import g.sub' binds the top-level name g too, and must "+ "disqualify the module-level generator of the same name"+ )++ def test_star_import_disqualifies_every_generator_candidate(self, tmp_path):+ """A ``from x import *`` can rebind any name in the module,+ including one that would otherwise pass as a same-module+ generator -- so its mere presence must disqualify every+ candidate, in every scanned file (allowlisted ones included:+ the wrapper-content rule applies there too)."""+ hooks = _mirror_hooks(tmp_path)+ allowed = _write(+ tmp_path,+ "src/local_deep_research/web/fastapi_app.py",+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse as W\n"+ "from evil import *\n"+ "def g():\n"+ " yield b''\n"+ "def route(p):\n"+ " return W(g())\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [allowed], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1+ assert f"{allowed}:6: " in result.stdout, (+ "a star import anywhere in the module must disqualify g as "+ "a trusted same-module generator, even in an allowlisted file"+ )++ def test_unparsable_files_fail_closed_and_bom_files_are_scanned(+ self, tmp_path+ ):+ """A UTF-8 BOM or a PEP 263 coding cookie must not hide a file+ from either scanner, and a file neither can parse (a syntax+ error, or nesting too deep for the parser) is reported, never+ silently skipped and never a crash."""+ serving = b"from starlette.responses import FileResponse\n"+ unbound = b"svc = NoteService()\n"+ bom = tmp_path / "bom.py"+ bom.write_bytes(b"\xef\xbb\xbf" + serving + unbound)+ latin1 = tmp_path / "latin1.py"+ latin1.write_bytes(+ b"# -*- coding: latin-1 -*-\n"+ b'label = "caf\xe9"\n' + serving + unbound+ )+ broken = tmp_path / "broken.py"+ broken.write_bytes(b"def f(:\n")+ # Nesting too deep for the parser raises RecursionError or+ # MemoryError (not SyntaxError): it must be reported, not crash+ # the run and hide the files after it.+ deep = tmp_path / "deep.py"+ deep.write_bytes(b"x = " + b"-" * 100000 + b"1\n")+ # A deep attribute chain (unlike the unary-minus chain above,+ # which raises MemoryError) raises RecursionError specifically:+ # both must be in the except tuple, not just one of them. A+ # generous C stack (seen with Python 3.12+, which bounds+ # recursion by actual C stack depth rather than+ # sys.getrecursionlimit() alone -- e.g. a 64 MB main-thread+ # stack) can let a shallower chain parse cleanly, making this+ # assertion fail spuriously and unable to exercise the+ # RecursionError arm of the hook's except tuple. Widen the+ # margin, and probe it in-process first: the hook subprocess is+ # launched with this same sys.executable (see _run_hook), so an+ # in-process ast.parse() is a faithful proxy for whether the+ # subprocess would raise too.+ recursion_depth = 2_000_000+ recursion_content = b"x = a" + b".b" * recursion_depth + b"\n"+ try:+ ast.parse(recursion_content)+ except RecursionError:+ pass+ else:+ pytest.skip(+ "ast.parse did not raise RecursionError for a "+ f"{recursion_depth}-deep attribute chain in this "+ "interpreter (unusually large C stack?); the hook "+ "subprocess shares sys.executable, so it would parse "+ "this fixture too and the RecursionError-catch "+ "assertion below cannot be exercised here"+ )+ recursion = tmp_path / "recursion.py"+ recursion.write_bytes(recursion_content)+ files = [str(deep), str(recursion), str(bom), str(latin1), str(broken)]++ result = _run_hook(REPORTS_HOOK, files)+ assert result.returncode == 1+ assert "Traceback" not in result.stderr, result.stderr+ for expected in (+ "deep.py:1: could not parse",+ "recursion.py:1: could not parse",+ "bom.py:1: import of FileResponse",+ "latin1.py:3: import of FileResponse",+ "broken.py:1: could not parse",+ ):+ assert expected in result.stdout, f"{expected!r} not reported"++ result = _run_hook(ISOLATION_HOOK, files)+ assert result.returncode == 1+ assert "Traceback" not in result.stderr, result.stderr+ for expected in (+ "deep.py:1: could not parse",+ "recursion.py:1: could not parse",+ "bom.py:2: NoteService",+ "latin1.py:4: NoteService",+ "broken.py:1: could not parse",+ ):+ assert expected in result.stdout, f"{expected!r} not reported"++ def test_non_utf8_filename_offender_is_printed_not_crashed(self, tmp_path):+ """An offender path whose filename bytes are not valid UTF-8+ must still be printable, even under a strict-UTF-8 stdout+ encoder (no locale/UTF-8-mode fallback to rescue it).++ Argv is decoded with surrogateescape, so such a filename+ reaches the hook as a Python str carrying lone surrogates.+ ``print()``-ing that str directly raises UnicodeEncodeError+ under a strict encoder; ``_safe_print`` must round-trip it+ through ``backslashreplace`` instead.+ """+ name_bytes = b"\xff\xfe.py"+ dir_bytes = os.fsencode(str(tmp_path))+ path_bytes = dir_bytes + os.sep.encode() + name_bytes+ violation = (+ b"from starlette.responses import FileResponse\n"+ b"svc = NoteService()\n"+ )+ try:+ fd = os.open(+ path_bytes, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644+ )+ except OSError:+ pytest.skip(+ "this filesystem rejects a non-UTF-8-encodable filename"+ )+ with os.fdopen(fd, "wb") as handle:+ handle.write(violation)+ # The same surrogateescape decoding argv gets, so the fixture+ # name below matches what the hook subprocess actually sees.+ path_str = os.fsdecode(path_bytes)+ env = {**os.environ, "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "0"}++ for hook in (REPORTS_HOOK, ISOLATION_HOOK):+ result = _run_hook(hook, [path_str], env=env)+ assert result.returncode == 1, (hook, result.stdout, result.stderr)+ assert "Traceback" not in result.stderr, (hook, result.stderr)+ assert "\\udcff\\udcfe.py" in result.stdout, (hook, result.stdout)++ def test_unreadable_files_are_reported_not_raised(self, tmp_path):+ """An OSError while reading a file is an offender line, not a+ crash (both scanners share the fail-closed contract)."""+ missing = tmp_path / "vanished.py"+ for hook in (_reports_hook, _isolation_hook):+ tree, error = hook._parse(missing)+ assert tree is None+ assert error.startswith(f"{missing}:1: could not read ("), error++ def test_permission_denied_file_is_reported_via_subprocess(self, tmp_path):+ """A PermissionError while reading a file (unreadable via+ chmod, not merely missing) is an offender line through the+ real hook subprocess, not a crash -- for both scanners."""+ if os.geteuid() == 0:+ pytest.skip("root bypasses file permission checks")+ locked = tmp_path / "locked.py"+ locked.write_text("svc = NoteService()\n", encoding="utf-8")+ locked.chmod(0o000)+ try:+ result = _run_hook(REPORTS_HOOK, [str(locked)])+ assert result.returncode == 1+ assert "Traceback" not in result.stderr, result.stderr+ assert "could not read (PermissionError" in result.stdout, (+ result.stdout+ )++ result = _run_hook(ISOLATION_HOOK, [str(locked)])+ assert result.returncode == 1+ assert "Traceback" not in result.stderr, result.stderr+ assert "could not read (PermissionError" in result.stdout, (+ result.stdout+ )+ finally:+ locked.chmod(0o644)++ def test_inline_outputs_are_flagged_even_in_allowlisted_files(+ self, tmp_path+ ):+ """The outputs-directory arm applies to every scanned file: an+ allowlisted file (exempt from the primitive rule) and a router+ using the wrapper are both flagged for serving OUTPUT_DIR."""+ hooks = _mirror_hooks(tmp_path)+ allowed = _write(+ tmp_path,+ "src/local_deep_research/web/fastapi_app.py",+ "from fastapi.responses import FileResponse\n"+ "from fastapi.responses import FileResponse as FR\n"+ "def dl(n):\n"+ " return FileResponse(OUTPUT_DIR / n)\n"+ "def dl2(self, n):\n"+ " return FR(self.outputs_dir / n)\n"+ "from svc import OUTPUT_DIR as OD\n"+ "def dl3(n):\n"+ " return FileResponse(OD / n)\n",+ )+ router = _write(+ tmp_path,+ WEB_DIR + "routers/downloads.py",+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse\n"+ "def dl(n):\n"+ " return WorkerCleanupStreamingResponse(\n"+ " open(get_research_outputs_directory() / n, 'rb')\n"+ " )\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [allowed, router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1+ outputs = "serves from the shared research outputs directory"+ for expected in (+ f"{allowed}:4: FileResponse(...) {outputs}",+ f"{allowed}:6: FileResponse(...) {outputs}",+ f"{allowed}:9: FileResponse(...) {outputs}",+ f"{router}:3: WorkerCleanupStreamingResponse(...) {outputs}",+ ):+ assert expected in result.stdout, f"{expected!r} not flagged"+ assert "file-serving primitive outside" not in result.stdout, (+ "the allowlisted file must stay exempt from the primitive rule"+ )++ def test_serving_helper_handed_the_outputs_dir_is_flagged(self, tmp_path):+ """Helper indirection: ``static_file_response`` lives in an+ allowlisted file, so a router calling it never references a+ primitive. Its current signature takes only ``path`` (the root is+ always STATIC_DIR), so the flagged calls below cannot run today;+ the rule is defensive, so that a future directory parameter+ cannot be handed the outputs directory (direct, aliased, as a+ module attribute, positionally or as a keyword) unflagged. A+ plain single-path call must not be flagged."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(+ tmp_path,+ WEB_DIR + "routers/report_files.py",+ "from ..static_files import static_file_response\n"+ "from ..static_files import static_file_response as sfr\n"+ "from .. import static_files\n"+ "def a(n):\n"+ " return static_file_response(n, get_research_outputs_directory())\n"+ "def b(n):\n"+ " return sfr(n, static_dir=OUTPUT_DIR)\n"+ "def c(self, n):\n"+ " return static_files.static_file_response(n, self.outputs_dir)\n"+ "def ok(n):\n"+ " return static_file_response(n)\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1+ outputs = "serves from the shared research outputs directory"+ for lineno in (5, 7, 9):+ assert (+ f"{router}:{lineno}: static_file_response(...) {outputs}"+ in result.stdout+ ), f"line {lineno}: helper handed the outputs dir not flagged"+ assert f"{router}:11:" not in result.stdout, (+ "a plain single-path helper call must not be flagged"+ )++ @pytest.mark.parametrize(+ ("source", "flagged"),+ [+ pytest.param(+ "def a(path):\n"+ " from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse as respond,\n"+ " )\n"+ " return respond(open(path, 'rb'))\n"+ "def b(n):\n"+ " from ..static_files import static_file_response as respond\n"+ " return respond(n)\n",+ {5: "content"},+ id="wrapper-alias-then-helper-alias",+ ),+ pytest.param(+ "def b(n):\n"+ " from ..static_files import static_file_response as respond\n"+ " return respond(n)\n"+ "def a(path):\n"+ " from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse as respond,\n"+ " )\n"+ " return respond(open(path, 'rb'))\n",+ {8: "content"},+ id="helper-alias-then-wrapper-alias",+ ),+ pytest.param(+ "from typing import TYPE_CHECKING\n"+ "from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse as respond,\n"+ ")\n"+ "if TYPE_CHECKING:\n"+ " from ..static_files import static_file_response as respond\n"+ "def a(path):\n"+ " return respond(open(path, 'rb'))\n"+ "handler = respond\n",+ {8: "content", 9: "non-call"},+ id="helper-alias-under-type-checking",+ ),+ pytest.param(+ "from ..static_files import (\n"+ " static_file_response as WorkerCleanupStreamingResponse,\n"+ ")\n"+ "def a(path):\n"+ " return WorkerCleanupStreamingResponse(open(path, 'rb'))\n",+ {5: "content"},+ id="helper-imported-under-a-wrapper-name",+ ),+ ],+ )+ def test_a_helper_alias_never_masks_a_wrapper_alias(+ self, tmp_path, source, flagged+ ):+ """Aliases are resolved file-wide, without scopes. A local name+ imported both as a serving wrapper and as a ``SERVING_HELPERS``+ function (in two functions, either order, or once under+ ``TYPE_CHECKING``) must still get the wrapper rules (content is a+ same-module generator call; no non-call reference), and a helper+ imported under a wrapper's own name stays a wrapper: fail closed,+ whichever import ``ast.walk`` happens to reach last."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(tmp_path, WEB_DIR + "routers/report_files.py", source)+ result = _run_hook(+ REPORTS_HOOK, [router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ messages = {+ "content": "WorkerCleanupStreamingResponse(...) content is not",+ "non-call": "non-call reference to WorkerCleanupStreamingResponse",+ }+ for lineno, kind in flagged.items():+ expected = f"{router}:{lineno}: {messages[kind]}"+ assert expected in result.stdout, f"{expected!r} not flagged"++ def test_repo_relative_invocation_applies_the_web_scope(self, tmp_path):+ """Pre-commit passes repo-relative paths: web/ files are scanned,+ web_search_engines/ (shared name prefix) is not, and the+ allowlist matches by repo-relative path -- also for absolute+ in-repo paths and paths with '..' segments."""+ hooks = _mirror_hooks(tmp_path)+ serving = (+ "from fastapi.responses import FileResponse\n"+ "def f(p):\n"+ " return FileResponse(p)\n"+ )+ in_scope = _write(tmp_path, WEB_DIR + "routers/bad.py", serving)+ sibling = _write(+ tmp_path, "src/local_deep_research/web_search_engines/x.py", serving+ )+ allowed = _write(+ tmp_path, next(iter(_reports_hook.ALLOWED_FILES)), serving+ )+ result = _run_hook(+ REPORTS_HOOK,+ [in_scope, sibling, allowed],+ cwd=tmp_path,+ hooks_dir=hooks,+ )+ assert result.returncode == 1+ assert in_scope in result.stdout+ assert sibling not in result.stdout+ assert allowed not in result.stdout++ result = _run_hook(+ REPORTS_HOOK,+ [str(tmp_path / allowed), str(tmp_path / sibling)],+ cwd=tmp_path,+ hooks_dir=hooks,+ )+ assert result.returncode == 0, (+ "absolute in-repo paths must get the allowlist and scope: "+ + result.stdout+ )++ dotted = (+ "src/local_deep_research/web_search_engines/../"+ + in_scope.removeprefix("src/local_deep_research/")+ )+ result = _run_hook(+ REPORTS_HOOK, [dotted], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, "a '..' path escaped the web scope"++ def test_a_serving_callable_cannot_leave_a_module_renamed(self, tmp_path):+ """Cross-module rename: a module re-exporting the wrapper as+ ``CleanupStream`` or the helper as ``serve`` lets a router call+ them with no rule applying (the router sees no serving name), so+ the renaming import is flagged where it happens, as is a helper+ rebound by assignment. An alias that keeps the role+ (``...StreamingResponse`` suffix, underscore-prefixed helper) is+ accepted and stays fenced in its importers."""+ hooks = _mirror_hooks(tmp_path)+ streaming = _write(+ tmp_path,+ WEB_DIR + "utils/streaming.py",+ "from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse as CleanupStream,\n"+ ")\n"+ "from ..static_files import static_file_response as serve\n"+ "from ..dependencies.threadpool import (\n"+ " WorkerCleanupStreamingResponse as CleanupStreamingResponse,\n"+ ")\n"+ "from ..static_files import static_file_response as _static_file_response\n"+ "from ..static_files import static_file_response\n"+ "serve2 = static_file_response\n",+ )+ router = _write(+ tmp_path,+ WEB_DIR + "routers/downloads.py",+ "from ..utils.streaming import CleanupStream, serve\n"+ "from ..utils.streaming import (\n"+ " CleanupStreamingResponse, _static_file_response,\n"+ ")\n"+ "def a(name):\n"+ " return CleanupStream(\n"+ " open(get_research_outputs_directory() / name, 'rb')\n"+ " )\n"+ "def b(name):\n"+ " return serve(name, OUTPUT_DIR)\n"+ "def c(p):\n"+ " return CleanupStreamingResponse(open(p, 'rb'))\n"+ "def d(name):\n"+ " return _static_file_response(name, OUTPUT_DIR)\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [streaming, router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected in (+ f"{streaming}:1: import of WorkerCleanupStreamingResponse "+ "renamed to CleanupStream",+ f"{streaming}:4: import of static_file_response renamed to serve",+ f"{streaming}:10: non-call reference to static_file_response",+ f"{router}:12: CleanupStreamingResponse(...) content is not",+ ):+ assert expected in result.stdout, f"{expected!r} not flagged"+ assert (+ f"{router}:14: _static_file_response(...) serves from the "+ "shared research outputs directory"+ ) in result.stdout, (+ "an underscore-prefixed helper alias must stay a helper"+ )+ for lineno in (5, 8, 9):+ assert f"{streaming}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a role-keeping alias must be accepted"+ )++ def test_attribute_reads_off_a_serving_callable_are_references(+ self, tmp_path+ ):+ """Same shapes as the isolation fence's dunder test:+ ``W.__call__`` / ``helper.__wrapped__`` is the callable under+ another name, so it is flagged as a non-call reference, both+ outside the allowlist and inside an allowlisted file."""+ hooks = _mirror_hooks(tmp_path)+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/dunder.py",+ "from ..dependencies.threadpool import "+ "WorkerCleanupStreamingResponse\n"+ "from ..static_files import static_file_response\n"+ "make = WorkerCleanupStreamingResponse.__call__\n"+ "serve = static_file_response.__wrapped__\n"+ "def a(p):\n"+ " return WorkerCleanupStreamingResponse.__call__(open(p))\n"+ "def b(p):\n"+ " return static_file_response.__call__(p)\n",+ )+ threadpool = _write(+ tmp_path,+ "src/local_deep_research/web/dependencies/threadpool.py",+ "from starlette.responses import StreamingResponse\n"+ "class WorkerCleanupStreamingResponse(StreamingResponse):\n"+ " pass\n"+ "D = WorkerCleanupStreamingResponse.__call__\n"+ "F = StreamingResponse.__wrapped__\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [router, threadpool], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected in (+ f"{router}:3: non-call reference to WorkerCleanupStreamingResponse",+ f"{router}:4: non-call reference to static_file_response",+ f"{router}:6: non-call reference to WorkerCleanupStreamingResponse",+ f"{router}:8: non-call reference to static_file_response",+ f"{threadpool}:4: non-call reference to "+ "WorkerCleanupStreamingResponse in an allowlisted file",+ f"{threadpool}:5: non-call reference to StreamingResponse in an "+ "allowlisted file",+ ):+ assert expected in result.stdout, f"{expected!r} not flagged"++ def test_allowlisted_files_cannot_hand_on_a_serving_callable(+ self, tmp_path+ ):+ """An allowlisted file may use primitives, but not re-bind or+ hand one on under a name the fence does not recognise: a plain+ assignment, a return of the class, a non-wrapper-named subclass+ and a role-dropping import alias are flagged. A wrapper-named+ subclass and type-only annotations are accepted."""+ hooks = _mirror_hooks(tmp_path)+ threadpool = _write(+ tmp_path,+ "src/local_deep_research/web/dependencies/threadpool.py",+ "from starlette.responses import StreamingResponse\n"+ "class WorkerCleanupStreamingResponse(StreamingResponse):\n"+ " pass\n"+ "Download = WorkerCleanupStreamingResponse\n"+ "class Exporter(StreamingResponse):\n"+ " pass\n"+ "def factory():\n"+ " return StreamingResponse\n"+ "def typed(x: StreamingResponse) -> StreamingResponse | None:\n"+ " return x\n"+ "from fastapi.responses import FileResponse as Download2\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [threadpool], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected in (+ f"{threadpool}:4: non-call reference to "+ "WorkerCleanupStreamingResponse in an allowlisted file",+ f"{threadpool}:5: class Exporter subclasses StreamingResponse",+ f"{threadpool}:8: non-call reference to StreamingResponse",+ f"{threadpool}:11: import of FileResponse renamed to Download2",+ ):+ assert expected in result.stdout, f"{expected!r} not flagged"+ for lineno in (1, 2, 9):+ assert f"{threadpool}:{lineno}:" not in result.stdout, (+ f"line {lineno}: an import, a wrapper-named subclass or an "+ "annotation must be accepted"+ )++ def test_evaluated_annotations_cannot_inject_a_serving_callable(+ self, tmp_path+ ):+ """``= Depends()`` makes FastAPI call the annotated class with+ request-filled arguments, and ``Annotated[T,+ Depends(static_file_response)]`` calls the helper with a+ request-supplied ``path`` (FastAPI refuses ``FileResponse``+ itself at route registration; the hook fails closed regardless),+ so even an allowlisted file may not name a serving callable in+ an annotation that is evaluated: one with a non-constant default,+ a call, walrus or lambda inside, or (in any scanned file) a+ quoted forward reference there."""+ hooks = _mirror_hooks(tmp_path)+ app = _write(+ tmp_path,+ "src/local_deep_research/web/fastapi_app.py",+ "from typing import Annotated\n"+ "from fastapi import Depends\n"+ "from starlette.responses import FileResponse\n"+ "from .static_files import static_file_response\n"+ "def a(f: FileResponse = Depends()):\n"+ " return f\n"+ "def b(f: Annotated[FileResponse, Depends()]):\n"+ " return f\n"+ "def c(f: Annotated[object, Depends(static_file_response)]):\n"+ " return f\n"+ "def d(f: 'FileResponse' = Depends()):\n"+ " return f\n"+ "x: (served := FileResponse) = 1\n"+ "def ok(f: FileResponse, c: CsrfProtect = Depends()) -> FileResponse:\n"+ " return f\n"+ "dep = Depends()\n"+ "def e(f: Annotated[FileResponse, dep]):\n"+ " return f\n",+ )+ router = _write(+ tmp_path,+ "src/local_deep_research/web/routers/quoted.py",+ "from fastapi import Depends\n"+ "from ..dependencies.threadpool import WorkerCleanupStreamingResponse\n"+ "def r(f: 'WorkerCleanupStreamingResponse' = Depends()):\n"+ " return f\n",+ )+ result = _run_hook(+ REPORTS_HOOK, [app, router], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected, why in (+ (f"{app}:5: non-call reference to FileResponse", "Depends()"),+ (f"{app}:7: non-call reference to FileResponse", "Annotated"),+ (+ f"{app}:9: non-call reference to static_file_response",+ "Depends(helper) inside Annotated",+ ),+ (f"{app}:11: reference to FileResponse quoted", "a quoted name"),+ (f"{app}:13: non-call reference to FileResponse", "a walrus"),+ (+ f"{app}:17: non-call reference to FileResponse",+ "Annotated metadata bound to a name",+ ),+ (+ f"{router}:3: reference to WorkerCleanupStreamingResponse "+ "quoted",+ "a quoted wrapper outside the allowlist",+ ),+ ):+ assert expected in result.stdout, f"{why} not flagged"+ assert f"{app}:14:" not in result.stdout, (+ "type-only annotations and a non-serving Depends() must be accepted"+ )++ def test_quoted_starred_and_nested_annotations_cannot_inject(+ self, tmp_path+ ):+ """The same evaluated shapes in an allowlisted file: a wholly+ quoted ``Annotated``, a starred ``Annotated`` element, a class+ field under ``if`` / ``try`` or defaulted by a later assignment,+ and an unparsable string in a type position each make the+ serving name a reference."""+ hooks = _mirror_hooks(tmp_path)+ app = _write(+ tmp_path,+ "src/local_deep_research/web/fastapi_app.py",+ "from dataclasses import dataclass\n"+ "from typing import Annotated\n"+ "from fastapi import Depends\n"+ "from starlette.responses import FileResponse\n"+ "from .static_files import static_file_response\n"+ "dep = Depends()\n"+ 'def a(f: "Annotated[object, Depends(static_file_response)]"):\n'+ " return f\n"+ "def b(f: Annotated[*(FileResponse, dep)]):\n"+ " return f\n"+ "@dataclass\n"+ "class C:\n"+ " if True:\n"+ " f: FileResponse = Depends()\n"+ " try:\n"+ " g: static_file_response = dep\n"+ " except ImportError:\n"+ " pass\n"+ 'def d(f: tuple[FileResponse, "1 +"]):\n'+ " return f\n"+ "def ok(\n"+ ' f: "FileResponse",\n'+ ' g: Annotated["FileResponse", "a doc string"] = None,\n'+ ') -> "FileResponse":\n'+ " return f\n"+ "@dataclass\n"+ "class E:\n"+ " f: FileResponse\n"+ " f = Depends()\n",+ )+ result = _run_hook(REPORTS_HOOK, [app], cwd=tmp_path, hooks_dir=hooks)+ assert result.returncode == 1, result.stdout+ for expected, why in (+ (+ f"{app}:7: reference to static_file_response quoted",+ "a wholly quoted Annotated",+ ),+ (f"{app}:9: non-call reference to FileResponse", "a starred one"),+ (+ f"{app}:14: non-call reference to FileResponse",+ "a Depends() field under if",+ ),+ (+ f"{app}:16: non-call reference to static_file_response",+ "a field under try",+ ),+ (+ f"{app}:19: non-call reference to FileResponse",+ "an unparsable string in a type position",+ ),+ (+ f"{app}:28: non-call reference to FileResponse",+ "a field defaulted by a later assignment",+ ),+ ):+ assert expected in result.stdout, f"{why} not flagged"+ for lineno in range(21, 26):+ assert f"{app}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a quoted type or an Annotated doc string "+ "must be accepted"+ )++ def test_unchecked_annotation_strings_and_inherited_defaults(+ self, tmp_path+ ):+ """In every scanned file a string in a type position that does+ not parse is an offender in itself; in an allowlisted file a+ class field with no binding in its own body, on a class with a+ real base, may inherit a ``Depends()`` default, so a serving+ name in its annotation is a reference."""+ hooks = _mirror_hooks(tmp_path)+ app = _write(+ tmp_path,+ "src/local_deep_research/web/fastapi_app.py",+ "from typing import Literal\n"+ "from starlette.responses import FileResponse\n"+ "class Base:\n"+ " pass\n"+ 'def a(f: "1 +"):\n'+ " return f\n"+ "class Sub(Base):\n"+ " f: FileResponse\n"+ 'def ok(f: Literal["a ) b"] = "a ) b") -> "FileResponse":\n'+ " return f\n"+ "class Plain:\n"+ " f: FileResponse\n",+ )+ other = _write(+ tmp_path,+ "src/local_deep_research/web/routers/other.py",+ 'def a(x: "*[int]"):\n return x\n',+ )+ result = _run_hook(+ REPORTS_HOOK, [app, other], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, result.stdout+ for expected, why in (+ (+ f"{app}:5: annotation string that cannot be checked",+ "unparsable",+ ),+ (f"{app}:8: non-call reference to FileResponse", "inherited"),+ (+ f"{other}:1: annotation string that cannot be checked",+ "unparsable outside the allowlist",+ ),+ ):+ assert expected in result.stdout, f"{why} not flagged"+ for lineno in range(9, 13):+ assert f"{app}:{lineno}:" not in result.stdout, (+ f"line {lineno}: a Literal string, a quoted type or a field "+ "of a base-less class must be accepted"+ )++ def test_a_symlink_into_the_web_scope_is_scanned(self, tmp_path):+ """A symlink inside web/ whose target lies outside it is still+ scanned (lexical OR resolved path in scope), and gets no+ allowlist exemption from its name."""+ hooks = _mirror_hooks(tmp_path)+ serving = "from fastapi.responses import FileResponse\n"+ target = _write(+ tmp_path, "src/local_deep_research/other/real.py", serving+ )+ link = WEB_DIR + "routers/linked.py"+ allowed_link = next(iter(_reports_hook.ALLOWED_FILES))+ for rel in (link, allowed_link):+ (tmp_path / rel).parent.mkdir(parents=True, exist_ok=True)+ try:+ (tmp_path / rel).symlink_to(tmp_path / target)+ except (OSError, NotImplementedError):+ pytest.skip("symlinks unsupported here")+ for rel in (link, allowed_link):+ result = _run_hook(+ REPORTS_HOOK, [rel], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 1, f"symlink {rel} escaped the fence"+ result = _run_hook(+ REPORTS_HOOK, [target], cwd=tmp_path, hooks_dir=hooks+ )+ assert result.returncode == 0, "the out-of-scope target is skipped"+++class TestReportFilenameCollisions:+ def test_same_query_same_second_yields_distinct_paths(+ self, tmp_path, monkeypatch+ ):+ """Same query, same second: the helper must still yield distinct+ names (preventive hardening; no production caller today)."""+ monkeypatch.setattr(research_service, "OUTPUT_DIR", tmp_path)+ import local_deep_research.web.services.research_service as rs++ real_datetime = rs.datetime++ class _FrozenDatetime(real_datetime):+ @classmethod+ def now(cls, tz=None):+ return real_datetime.fromtimestamp(1700000000, tz=tz)++ monkeypatch.setattr(rs, "datetime", _FrozenDatetime)++ first = research_service._generate_report_path("shared query")+ second = research_service._generate_report_path("shared query")++ assert first != second, (+ "deterministic filename: same query + same second collides "+ "in the shared directory"+ )diff --git a/tests/security/test_cross_user_isolation_census.py b/tests/security/test_cross_user_isolation_census.pyindex e30e809ae4..d1054a7849 100644--- a/tests/security/test_cross_user_isolation_census.py+++ b/tests/security/test_cross_user_isolation_census.py@@ -243,41 +243,126 @@ def _params(fn: ast.FunctionDef | ast.AsyncFunctionDef):yield p.arg, d, p.annotation-def _depends_target(default) -> str | None:- """Return the callable name inside ``Depends(...)``/``Security(...)``."""- if (- isinstance(default, ast.Call)- and isinstance(default.func, ast.Name)- and default.func.id in ("Depends", "Security")- ):- arg = default.args[0] if default.args else None- if isinstance(arg, ast.Name):- return arg.id- if isinstance(arg, ast.Attribute):- return arg.attr+def _dependency_name(node) -> str | None:+ """Name of the callable ``node`` denotes: ``f`` / ``mod.f`` -> ``f``;+ a dunder read off it (``get_user_db_session.__wrapped__``) is the+ callable itself; a quoted forward reference (``"NoteService"``) is+ resolved the way FastAPI resolves it, by name."""+ if isinstance(node, ast.Constant) and isinstance(node.value, str):+ try:+ node = ast.parse(node.value.strip(), mode="eval").body+ except SyntaxError:+ return None+ while isinstance(node, ast.Attribute) and node.attr.startswith("__"):+ node = node.value+ if isinstance(node, ast.Name):+ return node.id+ if isinstance(node, ast.Attribute):+ return node.attrreturn None+def _depends_target(default, annotation=None) -> str | None:+ """Return the callable name inside ``Depends(...)``/``Security(...)``.++ Both the bare and the qualified spelling (``fastapi.Depends``) and the+ ``dependency=`` keyword count. With no dependency (``Depends()`` /+ ``Depends(None)``) FastAPI calls the parameter's ANNOTATION itself, so+ the target is the annotated type's name (``svc: NoteService =+ Depends()`` -> ``NoteService``).+ """+ if not isinstance(default, ast.Call):+ return None+ func = default.func+ name = (+ func.id+ if isinstance(func, ast.Name)+ else func.attr+ if isinstance(func, ast.Attribute)+ else None+ )+ if name not in ("Depends", "Security"):+ return None+ arg = default.args[0] if default.args else None+ if arg is None:+ arg = next(+ (kw.value for kw in default.keywords if kw.arg == "dependency"),+ None,+ )+ if arg is None or (isinstance(arg, ast.Constant) and arg.value is None):+ arg = annotation+ return _dependency_name(arg)+++#: Nesting bound for a quoted annotation (a string inside a string ...).+_MAX_QUOTE_DEPTH = 8+++def _unquote(annotation):+ """A wholly quoted annotation parsed the way FastAPI evaluates it:+ ``"Annotated[NoteService, Depends()]"`` -> the ``Annotated`` subscript+ (recursively, up to ``_MAX_QUOTE_DEPTH``). Anything else, or a string+ that does not parse, is returned as is."""+ for _ in range(_MAX_QUOTE_DEPTH):+ if not (+ isinstance(annotation, ast.Constant)+ and isinstance(annotation.value, str)+ ):+ break+ try:+ annotation = ast.parse(annotation.value.strip(), mode="eval").body+ except (SyntaxError, ValueError, RecursionError, MemoryError):+ break+ return annotation+++def _annotated_elements(annotation) -> list:+ """The elements of ``Annotated[...]``'s subscript, with a starred+ tuple or list literal unpacked as Python unpacks it+ (``Annotated[*(T, Depends(f))]`` -> ``[T, Depends(f)]``)."""+ sl = annotation.slice+ elements = []+ for element in sl.elts if isinstance(sl, ast.Tuple) else [sl]:+ if isinstance(element, ast.Starred) and isinstance(+ element.value, (ast.Tuple, ast.List)+ ):+ elements.extend(element.value.elts)+ else:+ elements.append(element)+ return elements+++def _annotated_type(annotation):+ """The wrapped type of ``Annotated[T, ...]``, else ``annotation``."""+ if _is_annotated(annotation):+ elements = _annotated_elements(annotation)+ return elements[0] if elements else annotation+ return annotation+++def _is_annotated(annotation) -> bool:+ if not isinstance(annotation, ast.Subscript):+ return False+ head = annotation.value+ return (isinstance(head, ast.Name) and head.id == "Annotated") or (+ isinstance(head, ast.Attribute) and head.attr == "Annotated"+ )++def _annotated_metadata(annotation):"""Yield each metadata expression inside ``Annotated[T, meta, ...]``.Handles both the bare-name (``Annotated[...]``) and qualified(``typing.Annotated[...]``) spellings. ``ast.Subscript.slice`` is theexpression directly on the Python versions this project targets (3.9+),- so a multi-element subscript is an ``ast.Tuple``.+ so a multi-element subscript is an ``ast.Tuple``; a starred tuple or+ list literal in it is unpacked (see ``_annotated_elements``)."""- if not isinstance(annotation, ast.Subscript):+ if not _is_annotated(annotation):return- head = annotation.value- is_annotated = (isinstance(head, ast.Name) and head.id == "Annotated") or (- isinstance(head, ast.Attribute) and head.attr == "Annotated"- )- if not is_annotated:- return- sl = annotation.slice- elts = sl.elts if isinstance(sl, ast.Tuple) else [sl]- # elts[0] is the wrapped type; everything after it is metadata.- yield from elts[1:]+ # The first element is the wrapped type; everything after it is+ # metadata.+ yield from _annotated_elements(annotation)[1:]def _depends_targets(default, annotation) -> list:@@ -287,14 +372,18 @@ def _depends_targets(default, annotation) -> list:A handler may express its dependency either the legacy way(``x: T = Depends(f)``) or via ``Annotated``(``x: Annotated[T, Depends(f)]``) — both must be detected or the census- silently blinds itself to every ``Annotated``-spelled route.+ silently blinds itself to every ``Annotated``-spelled route. A wholly+ quoted annotation (``x: "Annotated[T, Depends(f)]"``) is evaluated by+ FastAPI, so it is parsed first (see ``_unquote``)."""targets = []- t = _depends_target(default)+ annotation = _unquote(annotation)+ wrapped = _annotated_type(annotation)+ t = _depends_target(default, wrapped)if t is not None:targets.append(t)for meta in _annotated_metadata(annotation):- t = _depends_target(meta)+ t = _depends_target(meta, wrapped)if t is not None:targets.append(t)return targets@@ -744,6 +833,42 @@ def db_chokepoint_calls(tree: ast.Module) -> list:return results+def injected_identity_callables(tree: ast.Module, current_module: str) -> list:+ """Dependencies FastAPI would call with a request-filled identity.++ FastAPI CALLS every ``Depends(f)`` / ``Security(f)`` target (for a bare+ ``Depends()``, the annotated class) and fills ITS parameters from the+ request. A target taking ``username`` / ``user_id`` / ``owner``+ (``NoteService``, ``get_user_db_session``) therefore gets that+ identity from ``?username=`` unless the target is itself an auth+ dependency (``require_auth``-derived, see ``_auth_dependency_names``).+ Covers handler and helper parameters (both spellings, via+ ``_depends_targets``) and ``Depends(...)`` anywhere else, such as a+ decorator's ``dependencies=[...]``. Returns ``(lineno, target)``.+ """+ imports = _resolve_imports(tree, current_module)+ auth_names = _auth_dependency_names(tree)+ found = []+ targets = []+ for node in ast.walk(tree):+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):+ for _, default, annotation in _params(node):+ targets.extend(+ (node.lineno, t)+ for t in _depends_targets(default, annotation)+ )+ elif isinstance(node, ast.Call):+ t = _depends_target(node)+ if t is not None:+ targets.append((node.lineno, t))+ for lineno, target in targets:+ if target in auth_names:+ continue+ if _identity_params_of(target, imports, current_module):+ found.append((lineno, target))+ return sorted(set(found))++def ungated_global_state_calls(route: Route) -> list:"""Global-registry calls made with an id but no prior owner lookup.@@ -1045,6 +1170,26 @@ def test_routers_open_no_database_outside_the_per_user_scope():)+def test_no_dependency_takes_a_user_identity_from_the_request():+ """``svc: NoteService = Depends()``, ``Annotated[T,+ Depends(get_user_db_session)]`` and ``Depends(NoteService)`` make+ FastAPI construct the user-data object itself, with ``username``+ filled from the request (``?username=victim``). No router may inject+ an identity-taking callable that is not an auth dependency."""+ violations = []+ for path in sorted(ROUTERS_DIR.glob("*.py")):+ tree = _parse(path)+ for lineno, target in injected_identity_callables(+ tree, _module_name(path)+ ):+ violations.append(f"{path.name}:{lineno} Depends({target})")+ assert not violations, _report(+ "CROSS-USER: a router injects a callable that takes a user "+ "identity, which FastAPI then fills from request input:",+ violations,+ )++def test_object_id_routes_reach_a_user_scoped_access():"""A route that takes an object id must resolve it against the caller.@@ -1286,6 +1431,73 @@ def leak_via_global()+_CONTROL_INJECTED_IDENTITY = """+from typing import Annotated+import fastapi+from fastapi import APIRouter, Depends, Request+from ...database.session_context import get_user_db_session+from ...research_library.notes.services.note_service import NoteService+from ..dependencies.auth import require_auth++router = APIRouter()++[email protected]("/a")+def bare(svc: NoteService = Depends()):+ return svc++[email protected]("/b")+def annotated_bare(svc: Annotated[NoteService, Depends()]):+ return svc++[email protected]("/c")+def annotated_session(db: Annotated[object, Depends(get_user_db_session)]):+ return db++[email protected]("/d")+def wrapped(db: object = fastapi.Depends(get_user_db_session.__wrapped__)):+ return db++[email protected]("/e", dependencies=[Depends(NoteService)])+def via_decorator(username: str = Depends(require_auth)):+ return username++[email protected]("/f")+def quoted(svc: "NoteService" = Depends(None)):+ return svc++[email protected]("/g")+def quoted_annotated(svc: "Annotated[NoteService, Depends()]"):+ return svc++[email protected]("/h")+def quoted_session(db: "Annotated[object, Depends(get_user_db_session)]"):+ return db++[email protected]("/i")+def starred(svc: Annotated[*(NoteService, Depends())]):+ return svc++[email protected]("/ok")+def ok(username: Annotated[str, Depends(require_auth)]):+ return NoteService(username)++[email protected]("/ok2")+def ok_quoted(username: "Annotated[str, Depends(require_auth)]"):+ return NoteService(username)+"""++def _control_routes(source, label="control.py"):tree = ast.parse(source)routes = _routes_in(tree, label)@@ -1370,6 +1582,42 @@ def test_census_flags_deliberately_unscoped_handlers():"discriminating and its clean result on the real tree is meaningless.")+ # 7. A dependency FastAPI would call with a request-filled username:+ # every injection shape is reported, the auth dependency is not.+ tree = ast.parse(_CONTROL_INJECTED_IDENTITY)+ injected = injected_identity_callables(+ tree, "local_deep_research.web.routers.control"+ )+ source_lines = _CONTROL_INJECTED_IDENTITY.splitlines()+ flagged_defs = {+ source_lines[lineno - 1].split("(")[0].removeprefix("def ")+ for lineno, _name in injected+ if source_lines[lineno - 1].startswith("def ")+ }+ assert flagged_defs == {+ "bare",+ "annotated_bare",+ "annotated_session",+ "wrapped",+ "quoted",+ "quoted_annotated",+ "quoted_session",+ "starred",+ }, (+ "Census did NOT flag every Depends() injection of an identity-taking "+ f"callable (got {sorted(flagged_defs)}) — "+ "test_no_dependency_takes_a_user_identity_from_the_request is blind."+ )+ assert any(+ name == "NoteService"+ and source_lines[lineno - 1].startswith('@router.get("/e"')+ for lineno, name in injected+ ), "Census did NOT flag dependencies=[Depends(NoteService)]."+ assert "require_auth" not in {name for _lineno, name in injected}, (+ "Census flagged the auth dependency itself; the check is not "+ "discriminating."+ )+def test_census_reports_the_route_table(record_property):"""Emit the census as a table so the result is inspectable in CI output.diff --git a/tests/security/test_research_service_isolation_fastapi.py b/tests/security/test_research_service_isolation_fastapi.pyindex 9f8f399543..b84c50c54a 100644--- a/tests/security/test_research_service_isolation_fastapi.py+++ b/tests/security/test_research_service_isolation_fastapi.py@@ -781,8 +781,12 @@ class TestNewsSnapshotOwnerScoping:# 5. _generate_report_path path containment (research_service.py:518)# ===========================================================================-# The only characters the generated basename may contain.-_REPORT_NAME_RE = re.compile(r"^research_report_[0-9a-f]{10}_\d+\.md$")+# The only characters the generated basename may contain. The trailing+# 8-hex random segment keeps same-query, same-second calls from colliding+# in the install-shared directory (preventive; the helper has no caller).+_REPORT_NAME_RE = re.compile(+ r"^research_report_[0-9a-f]{10}_\d+_[0-9a-f]{8}\.md$"+)HOSTILE_QUERIES = ["../../../etc/passwd",@@ -805,8 +809,9 @@ class TestGenerateReportPathContainment:"""``_generate_report_path(query)`` — the module's only path guard.The query is fully user-controlled. The function's containment property- is that the basename is derived ONLY from an md5 hex digest and a unix- timestamp, so no byte of the query can influence the path. These tests+ is that the basename is derived ONLY from an md5 hex digest, a unix+ timestamp, and a random uuid segment, so no byte of the query can+ influence the path. These testsre-anchor ``OUTPUT_DIR`` to a temp directory so the assertion proves theresult is anchored to that constant rather than merely being "some paththat happens to exist".diff --git a/tests/web/services/test_research_service_cleanup_and_cancel.py b/tests/web/services/test_research_service_cleanup_and_cancel.pyindex eb99470574..364b56650d 100644--- a/tests/web/services/test_research_service_cleanup_and_cancel.py+++ b/tests/web/services/test_research_service_cleanup_and_cancel.py@@ -619,9 +619,10 @@ class TestGenerateReportPath:first = _generate_report_path("stable query").namesecond = _generate_report_path("stable query").name- # The timestamp differs between the two calls; the hash segment that- # identifies the query must not.- assert first.split("_")[-1] == second.split("_")[-1]+ # The timestamp and random-uniqueness segments differ between the+ # two calls; the hash segment that identifies the query must not.+ # (Segments: research_report_<hash>_<ts>_<uniq>.md)+ assert first.split("_")[2] == second.split("_")[2]def test_the_path_stays_under_the_configured_output_directory(self):from local_deep_research.web.services import research_servicediff --git a/tests/web/services/test_research_service_main_port.py b/tests/web/services/test_research_service_main_port.pyindex fd98d4edc2..a339aa2940 100644--- a/tests/web/services/test_research_service_main_port.py+++ b/tests/web/services/test_research_service_main_port.py@@ -299,7 +299,7 @@ class TestGenerateReportPath:``TestGenerateReportPathContainment`` (tests/security/test_research_service_isolation_fastapi.py) pins the shape of the name- (``research_report_<10 hex>_<ts>.md``) and that the hash segment is a+ (``research_report_<10 hex>_<ts>_<8 hex>.md``) and that the hash segment is astable function of the query — but not WHICH digest. Swapping md5 forsha256 would keep all of those green while silently changing everypreviously generated report path. That is what this test pins.