apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/frameworks/python/fastapi/plugin.py

@@ -0,0 +1,1390 @@
+"""
+FastAPI framework plugin with clean abstractions.
+
+This is the refactored FastAPI plugin that uses the abstract service protocols
+from parsing.services instead of directly depending on Python-specific modules.
+
+DESIGN PRINCIPLES:
+1. Uses AnalysisContext for all service access (DRY)
+2. Framework-specific logic is here, language-specific parsing is elsewhere
+3. Depends only on abstract protocols, not concrete implementations
+4. Can be tested with mock services
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from ....core.types import (
+    AnalysisNote,
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+    QualifiedName,
+)
+from ....parsing.base import ParsedClass, ParsedDecorator, ParsedFile, ParsedFunction
+from ....parsing.services import AnalysisContext
+from ...base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedJwtConfig,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+if TYPE_CHECKING:
+    from ....parsing.python.parameter_analyzer import AnalyzedParameter, ParameterAnalyzer
+
+
+# =============================================================================
+# FastAPI Constants
+# =============================================================================
+
+
+FASTAPI_ROUTE_DECORATORS = frozenset(
+    {
+        "get",
+        "post",
+        "put",
+        "patch",
+        "delete",
+        "head",
+        "options",
+        "trace",
+        "api_route",
+        "websocket",
+    }
+)
+
+FASTAPI_IMPORTS = frozenset(
+    {
+        "fastapi",
+        "fastapi.FastAPI",
+        "fastapi.APIRouter",
+        "fastapi.Depends",
+        "fastapi.Query",
+        "fastapi.Path",
+        "fastapi.Body",
+        "fastapi.Header",
+        "fastapi.Cookie",
+        "fastapi.Form",
+        "fastapi.File",
+        "fastapi.security",
+        "starlette",
+        "starlette.middleware",
+    }
+)
+
+HTTP_METHOD_MAP = {
+    "get": HttpMethod.GET,
+    "post": HttpMethod.POST,
+    "put": HttpMethod.PUT,
+    "patch": HttpMethod.PATCH,
+    "delete": HttpMethod.DELETE,
+    "head": HttpMethod.HEAD,
+    "options": HttpMethod.OPTIONS,
+    "trace": HttpMethod.TRACE,
+    "websocket": HttpMethod.WEBSOCKET,
+}
+
+AUTH_SCHEME_PATTERNS = {
+    "OAuth2PasswordBearer": AuthSchemeType.OAUTH2_PASSWORD,
+    "OAuth2AuthorizationCodeBearer": AuthSchemeType.OAUTH2_AUTHORIZATION_CODE,
+    "HTTPBasic": AuthSchemeType.HTTP_BASIC,
+    "HTTPBearer": AuthSchemeType.JWT_BEARER,
+    "APIKeyHeader": AuthSchemeType.API_KEY_HEADER,
+    "APIKeyQuery": AuthSchemeType.API_KEY_QUERY,
+    "APIKeyCookie": AuthSchemeType.API_KEY_COOKIE,
+}
+
+PARAM_LOCATION_MAP = {
+    "path": ParameterLocation.PATH,
+    "query": ParameterLocation.QUERY,
+    "header": ParameterLocation.HEADER,
+    "cookie": ParameterLocation.COOKIE,
+    "body": ParameterLocation.BODY,
+    "form": ParameterLocation.FORM,
+}
+
+KNOWN_FORM_TYPES: dict[str, tuple[str, list[str]]] = {
+    "OAuth2PasswordRequestForm": (
+        "application/x-www-form-urlencoded",
+        ["username", "password", "scope", "client_id", "client_secret"],
+    ),
+    "OAuth2PasswordRequestFormStrict": (
+        "application/x-www-form-urlencoded",
+        ["username", "password", "scope"],
+    ),
+}
+
+
+# =============================================================================
+# FastAPI Plugin
+# =============================================================================
+
+
+class FastAPIPlugin(BaseFrameworkPlugin):
+    """
+    FastAPI framework plugin using clean abstractions.
+
+    This plugin extracts:
+    - Routes from decorators, dynamic registration, and CBVs
+    - Dependencies (Depends)
+    - Authentication schemes and dependencies
+    - Middleware
+
+    It receives an AnalysisContext and uses abstract service protocols
+    instead of Python-specific implementations directly.
+    """
+
+    FRAMEWORK: ClassVar[Framework] = Framework.FASTAPI
+    LANGUAGE: ClassVar[Language] = Language.PYTHON
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = FASTAPI_IMPORTS
+
+    def __init__(self) -> None:
+        """Initialize the plugin."""
+        # Per-file tracking
+        self._app_vars: dict[Path, set[str]] = {}
+        self._router_vars: dict[Path, set[str]] = {}
+        self._import_aliases: dict[Path, dict[str, str]] = {}
+        self._known_models: dict[Path, set[str]] = {}
+        self._type_aliases: dict[Path, dict[str, str]] = {}
+
+        # Analysis notes for the current file
+        self._notes: list[AnalysisNote] = []
+
+        # Current analysis context (set per extraction call)
+        self._context: AnalysisContext | None = None
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        """Detect if FastAPI is used in this file."""
+        for imp in parsed_file.imports:
+            if imp.module in {"fastapi", "starlette"}:
+                return True
+            if imp.module and imp.module.startswith(("fastapi.", "starlette.")):
+                return True
+            for name in imp.names:
+                if name in {"FastAPI", "APIRouter", "Depends"}:
+                    return True
+        return False
+
+    # =========================================================================
+    # Main Extraction Entry Points
+    # =========================================================================
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        """
+        Extract HTTP routes from FastAPI decorators and dynamic registrations.
+
+        Args:
+            parsed_file: The parsed source file
+            context: Analysis context with services (type resolver, path resolver, etc.)
+
+        Returns:
+            List of extracted routes
+        """
+        self._context = context
+        self._notes = []
+        routes: list[ExtractedRoute] = []
+        file_path = parsed_file.path
+
+        # Initialize per-file tracking
+        self._app_vars[file_path] = set()
+        self._router_vars[file_path] = set()
+        self._import_aliases[file_path] = {}
+        self._known_models[file_path] = set()
+        self._type_aliases[file_path] = {}
+
+        # Step 1: Build context from file
+        self._build_import_aliases(parsed_file)
+        self._identify_app_routers(parsed_file)
+        self._register_models(parsed_file)
+        self._collect_type_aliases(parsed_file)
+
+        # Step 2: Create parameter analyzer
+        param_analyzer = self._create_parameter_analyzer(file_path)
+
+        # Step 3: Extract decorator-based routes
+        for func in parsed_file.functions:
+            route = self._extract_route_from_function(func, parsed_file, param_analyzer)
+            if route:
+                route = self._apply_router_prefix(route, file_path)
+                route = self._apply_router_dependencies(route, file_path)
+                route = self._reconcile_path_params(route)
+                routes.append(route)
+
+        # Step 4: Extract routes from class methods
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                route = self._extract_route_from_function(method, parsed_file, param_analyzer)
+                if route:
+                    route = self._apply_router_prefix(route, file_path)
+                    route = self._apply_router_dependencies(route, file_path)
+                    route = self._reconcile_path_params(route)
+                    routes.append(route)
+
+        # Step 5: Extract dynamic routes (add_api_route, route tables)
+        dynamic_routes = self._extract_dynamic_routes(parsed_file, param_analyzer)
+        routes.extend(dynamic_routes)
+
+        # Step 6: Extract CBV routes
+        cbv_routes = self._extract_cbv_routes(parsed_file, param_analyzer)
+        routes.extend(cbv_routes)
+
+        return routes
+
+    def extract_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedDependency]:
+        """Extract dependency definitions."""
+        self._context = context
+        dependencies: list[ExtractedDependency] = []
+
+        for func in parsed_file.functions:
+            if self._is_dependency_function(func, parsed_file):
+                dep = self._create_dependency(func, parsed_file.path)
+                dependencies.append(dep)
+
+        return dependencies
+
+    def extract_auth_schemes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedAuthScheme]:
+        """Extract OAuth2/JWT/API key authentication schemes."""
+        self._context = context
+        schemes: list[ExtractedAuthScheme] = []
+
+        for assign in parsed_file.assignments:
+            scheme = self._extract_auth_scheme_from_assignment(assign, parsed_file.path)
+            if scheme:
+                schemes.append(scheme)
+
+        schemes.extend(self._extract_auth_schemes_from_classes(parsed_file, parsed_file.path))
+
+        seen_names: set[str] = set()
+        deduped: list[ExtractedAuthScheme] = []
+        for s in schemes:
+            if s.name not in seen_names:
+                seen_names.add(s.name)
+                deduped.append(s)
+        return deduped
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+        known_scheme_names: set[str] | None = None,
+        all_project_depends_names: set[str] | None = None,
+    ) -> list[ExtractedAuthDependency]:
+        """Extract authentication dependency functions.
+
+        ``all_project_depends_names`` is the set of all function names that
+        appear as arguments to ``Depends()`` *anywhere* in the project (built
+        in a pre-pass by ``ProjectAnalyzer._extract_auth_data``).  When
+        provided it allows detecting auth deps whose definition lives in a
+        separate file from where they are used (the standard FastAPI pattern
+        of ``deps.py`` + ``routers/*.py``).
+        """
+        self._context = context
+        auth_deps: list[ExtractedAuthDependency] = []
+
+        for func in parsed_file.functions:
+            auth_dep = self._extract_auth_dependency(
+                func,
+                parsed_file,
+                known_scheme_names or set(),
+                all_project_depends_names or set(),
+            )
+            if auth_dep:
+                auth_deps.append(auth_dep)
+
+        return auth_deps
+
+    def extract_jwt_config(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> ExtractedJwtConfig | None:
+        """Extract JWT configuration.
+
+        Detects library, algorithms, validation flags (signature, expiry,
+        issuer, audience), and secret source (env / config / hardcoded).
+
+        pyjwt / python-jose defaults: validates signature + expiry unless
+        explicitly disabled via options={"verify_signature": False, ...}.
+        """
+        import ast
+
+        self._context = context
+        jwt_config = ExtractedJwtConfig(library="", detected=False)
+
+        jwt_libraries = {"jose", "python-jose", "pyjwt", "jwt", "authlib"}
+        for imp in parsed_file.imports:
+            if imp.module in jwt_libraries or any(
+                imp.module.startswith(f"{lib}.") for lib in jwt_libraries
+            ):
+                jwt_config.detected = True
+                jwt_config.library = imp.module.split(".")[0]
+                break
+
+        if not jwt_config.detected:
+            return None
+
+        # pyjwt / python-jose: validates signature + expiry by default
+        # unless options= explicitly disables them.
+        jwt_config.validates_signature = True
+        jwt_config.validates_expiry = True
+
+        # Build a map of module-level string literals so we can detect
+        # SECRET = "hardcoded-key" followed by jwt.decode(token, SECRET, ...).
+        _module_literals: dict[str, str] = {}
+        for assign in parsed_file.assignments:
+            if assign.in_function is not None:
+                continue
+            val = (assign.source_value or "").strip()
+            if (val.startswith('"') and val.endswith('"')) or (
+                val.startswith("'") and val.endswith("'")
+            ):
+                with contextlib.suppress(ValueError, SyntaxError):
+                    _module_literals[assign.target] = ast.literal_eval(val)
+
+        for call in parsed_file.call_sites:
+            callee_lower = call.callee_name.lower()
+            if "decode" not in callee_lower:
+                continue
+
+            jwt_config.locations.append(call.location)
+
+            for arg in call.arguments:
+                # algorithms= → algorithm list.
+                # The Python parser stores list literals as their source-code
+                # string (e.g. '["HS256"]') with literal_type="list", so we
+                # must parse them with ast.literal_eval rather than
+                # isinstance(val, list).
+                if arg.name == "algorithms" and arg.literal_value is not None:
+                    self._collect_py_algorithms(arg.literal_value, jwt_config)
+
+                # key / secret argument (position 1 in jwt.decode(token, key, ...))
+                if arg.position == 1 and jwt_config.secret_source is None:
+                    if arg.is_literal and isinstance(arg.literal_value, str):
+                        jwt_config.secret_source = "hardcoded"
+                    elif arg.is_variable and arg.variable_name:
+                        name_lc = arg.variable_name.lower()
+                        if any(kw in name_lc for kw in ("getenv", "environ", "env_")):
+                            jwt_config.secret_source = "env"
+                            jwt_config.secret_name = arg.variable_name
+                        elif any(kw in name_lc for kw in ("settings", "config", "cfg", "conf")):
+                            jwt_config.secret_source = "config"
+                            jwt_config.secret_name = arg.variable_name
+                        elif arg.variable_name in _module_literals:
+                            # Module-level string constant → treat as hardcoded
+                            jwt_config.secret_source = "hardcoded"
+
+                # options= dict → explicit verification overrides.
+                # Stored as source-code string '{"verify_signature": False}';
+                # parse with ast.literal_eval.
+                if arg.name == "options" and arg.literal_value is not None:
+                    opts = self._parse_dict_arg(arg.literal_value)
+                    if opts is not None:
+                        if opts.get("verify_signature") is False:
+                            jwt_config.validates_signature = False
+                        if opts.get("verify_exp") is False:
+                            jwt_config.validates_expiry = False
+                        if opts.get("verify_iss") is False:
+                            jwt_config.validates_issuer = False
+                        if opts.get("verify_aud") is False:
+                            jwt_config.validates_audience = False
+
+                # issuer= / audience= kwargs in jose / authlib
+                if arg.name in ("issuer", "iss") and arg.literal_value:
+                    jwt_config.validates_issuer = True
+                if arg.name in ("audience", "aud") and arg.literal_value:
+                    jwt_config.validates_audience = True
+
+        return jwt_config
+
+    @staticmethod
+    def _collect_py_algorithms(val: Any, jwt_config: ExtractedJwtConfig) -> None:
+        """Append algorithm names from an ``algorithms=`` call argument.
+
+        The Python parser stores list literals as their source-code string
+        (``'["HS256"]'``) with ``literal_type="list"``, so we attempt
+        ``ast.literal_eval`` before falling back to a regex scan.
+        """
+        import ast
+
+        if isinstance(val, list):
+            jwt_config.algorithms.extend(v for v in val if isinstance(v, str))
+            return
+        if not isinstance(val, str):
+            return
+        stripped = val.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            with contextlib.suppress(ValueError, SyntaxError):
+                items = ast.literal_eval(stripped)
+                if isinstance(items, list):
+                    jwt_config.algorithms.extend(v for v in items if isinstance(v, str))
+                    return
+            # Regex fallback: grab any quoted token inside the brackets
+            for name in re.findall(r'"([A-Za-z0-9_-]+)"', stripped):
+                jwt_config.algorithms.append(name)
+        else:
+            jwt_config.algorithms.append(stripped)
+
+    @staticmethod
+    def _parse_dict_arg(val: Any) -> dict | None:
+        """Parse a dict from a ``literal_value`` that may be a string or dict.
+
+        The Python parser stores dict literals as source-code strings
+        (e.g. ``'{"verify_signature": False}'``).  ``ast.literal_eval``
+        handles this transparently.
+        """
+        import ast
+
+        if isinstance(val, dict):
+            return val
+        if isinstance(val, str):
+            with contextlib.suppress(ValueError, SyntaxError):
+                result = ast.literal_eval(val.strip())
+                if isinstance(result, dict):
+                    return result
+        return None
+
+    def extract_middleware(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedMiddleware]:
+        """Extract middleware definitions."""
+        self._context = context
+        middleware: list[ExtractedMiddleware] = []
+
+        for call in parsed_file.call_sites:
+            if call.callee_name.endswith("add_middleware"):
+                mw = self._extract_middleware_from_call(call, parsed_file.path)
+                if mw:
+                    middleware.append(mw)
+
+        for func in parsed_file.functions:
+            mw = self._extract_middleware_from_decorator(func, parsed_file.path)
+            if mw:
+                middleware.append(mw)
+
+        return middleware
+
+    # =========================================================================
+    # Initialization Helpers
+    # =========================================================================
+
+    def _build_import_aliases(self, parsed_file: ParsedFile) -> None:
+        """Build import alias mapping."""
+        file_path = parsed_file.path
+        aliases = {}
+
+        for imp in parsed_file.imports:
+            if imp.is_from_import:
+                for name in imp.names:
+                    if imp.alias and len(imp.names) == 1:
+                        aliases[imp.alias] = name
+            else:
+                if imp.alias:
+                    aliases[imp.alias] = imp.module.split(".")[-1]
+
+        self._import_aliases[file_path] = aliases
+
+    def _identify_app_routers(self, parsed_file: ParsedFile) -> None:
+        """Identify FastAPI and APIRouter variables."""
+        file_path = parsed_file.path
+
+        for assign in parsed_file.assignments:
+            if assign.source_type == "call":
+                called = assign.source_call or ""
+                resolved = self._resolve_call_name(called, file_path)
+
+                if resolved in {"FastAPI", "fastapi.FastAPI"}:
+                    self._app_vars[file_path].add(assign.target)
+                elif resolved in {"APIRouter", "fastapi.APIRouter"}:
+                    self._router_vars[file_path].add(assign.target)
+
+    def _resolve_call_name(self, name: str, file_path: Path) -> str:
+        """Resolve a call name using import aliases."""
+        aliases = self._import_aliases.get(file_path, {})
+        parts = name.split(".")
+        if parts[0] in aliases:
+            parts[0] = aliases[parts[0]]
+            return ".".join(parts)
+        return name
+
+    def _register_models(self, parsed_file: ParsedFile) -> None:
+        """Register known model types for the file."""
+        file_path = parsed_file.path
+        models = set()
+
+        # Get models from file
+        for cls in parsed_file.classes:
+            if cls.is_pydantic_model or self._is_pydantic_class(cls):
+                models.add(cls.name)
+                models.add(cls.qualified_name.full)
+
+        # Get models from type resolver via context
+        if self._context and self._context.type_resolver:
+            all_models = self._context.type_resolver.get_all_models()
+
+            # Build a set of simple names from qualified names for fast suffix lookup
+            simple_name_index: dict[str, list[str]] = {}
+            for qname in all_models:
+                simple = qname.rsplit(".", 1)[-1]
+                simple_name_index.setdefault(simple, []).append(qname)
+
+            for qname in all_models:
+                models.add(qname)
+
+            # Resolve simple names through this file's imports so that
+            # `from schemas import GetTestSchema` makes "GetTestSchema"
+            # recognisable as a known model in this file's scope.
+            for imp in parsed_file.imports:
+                if imp.is_from_import:
+                    for imported_name in imp.names:
+                        if imported_name in simple_name_index:
+                            models.add(imported_name)
+                else:
+                    # `import schemas` — the module name itself could match
+                    module_name = imp.alias or imp.module
+                    if module_name in simple_name_index:
+                        models.add(module_name)
+
+        self._known_models[file_path] = models
+
+    def _is_pydantic_class(self, cls: ParsedClass) -> bool:
+        """Check if a class is a Pydantic model."""
+        pydantic_bases = {"BaseModel", "BaseSettings", "pydantic.BaseModel"}
+        return any(base in pydantic_bases for base in cls.base_classes)
+
+    def _collect_type_aliases(self, parsed_file: ParsedFile) -> None:
+        """Collect type aliases whose RHS is ``Annotated[T, Depends(...)]`` or similar.
+
+        These are common in FastAPI projects::
+
+            SessionDep = Annotated[Session, Depends(get_db)]
+            CurrentUser: TypeAlias = Annotated[User, Depends(get_current_user)]
+
+        We store ``alias_name -> rhs_text`` so that
+        :class:`TypeAnnotationAnalyzer` can expand them before parsing.
+        """
+        file_path = parsed_file.path
+        aliases: dict[str, str] = {}
+        dependency_keywords = ("Depends(", "Security(")
+
+        for assign in parsed_file.assignments:
+            if assign.in_function is not None:
+                continue
+            rhs = assign.source_value or ""
+            if "Annotated[" in rhs and any(kw in rhs for kw in dependency_keywords):
+                aliases[assign.target] = rhs
+
+        if self._context and self._context.all_parsed_files:
+            for other_file in self._context.all_parsed_files:
+                if other_file.path == file_path:
+                    continue
+                for assign in other_file.assignments:
+                    if assign.in_function is not None:
+                        continue
+                    rhs = assign.source_value or ""
+                    if "Annotated[" not in rhs:
+                        continue
+                    if not any(kw in rhs for kw in dependency_keywords):
+                        continue
+                    exported_name = assign.target
+                    for imp in parsed_file.imports:
+                        if imp.is_from_import and exported_name in imp.names:
+                            aliases[exported_name] = rhs
+                            break
+
+        self._type_aliases[file_path] = aliases
+
+    def _create_parameter_analyzer(self, file_path: Path) -> ParameterAnalyzer:
+        """Create a parameter analyzer with current context."""
+        from ....parsing.python.parameter_analyzer import ParameterAnalyzer
+
+        return ParameterAnalyzer(
+            import_aliases=self._import_aliases.get(file_path, {}),
+            known_models=self._known_models.get(file_path, set()),
+            type_aliases=self._type_aliases.get(file_path, {}),
+        )
+
+    # =========================================================================
+    # Route Extraction
+    # =========================================================================
+
+    def _extract_route_from_function(
+        self,
+        func: ParsedFunction,
+        parsed_file: ParsedFile,
+        param_analyzer: ParameterAnalyzer,
+    ) -> ExtractedRoute | None:
+        """Extract route from a function's decorators."""
+        for dec in func.decorators:
+            route = self._parse_route_decorator(dec, func, parsed_file, param_analyzer)
+            if route:
+                return route
+        return None
+
+    def _parse_route_decorator(
+        self,
+        decorator: ParsedDecorator,
+        func: ParsedFunction,
+        parsed_file: ParsedFile,
+        param_analyzer: ParameterAnalyzer,
+    ) -> ExtractedRoute | None:
+        """Parse a route decorator into ExtractedRoute."""
+        file_path = parsed_file.path
+        dec_name = decorator.name.lower()
+        full_name = decorator.qualified_name.full if decorator.qualified_name else decorator.name
+
+        http_method = None
+        router_name = None
+
+        # Direct decorator
+        if dec_name in FASTAPI_ROUTE_DECORATORS:
+            http_method = HTTP_METHOD_MAP.get(dec_name)
+
+        # App/router method
+        parts = full_name.split(".")
+        if len(parts) >= 2:
+            var_name = parts[-2]
+            method_name = parts[-1].lower()
+
+            if method_name in FASTAPI_ROUTE_DECORATORS:
+                app_vars = self._app_vars.get(file_path, set())
+                router_vars = self._router_vars.get(file_path, set())
+
+                if var_name in app_vars or var_name in router_vars:
+                    http_method = HTTP_METHOD_MAP.get(method_name)
+                    router_name = var_name
+
+        if not http_method:
+            return None
+
+        # Extract path
+        path = self._extract_route_path(decorator)
+
+        # Resolve computed path
+        path = self._resolve_computed_path(path, file_path)
+
+        # Analyze parameters
+        analyzed_params = param_analyzer.analyze_function_params(func.parameters, route_path=path)
+
+        # Convert to extracted parameters
+        path_params, query_params, header_params, cookie_params, body, deps = (
+            self._convert_analyzed_params(analyzed_params, parsed_file)
+        )
+
+        # Synthesize path params from the URL template that aren't in the handler
+        # signature (e.g. {organization} defined at the router prefix level).
+        template_param_names = set(re.findall(r"\{([^}:]+)(?::[^}]+)?\}", path))
+        signature_param_names = {p.name for p in path_params}
+        for tpl_name in sorted(template_param_names - signature_param_names):
+            path_params.insert(
+                0,
+                ExtractedParameter(
+                    name=tpl_name,
+                    location=ParameterLocation.PATH,
+                    type_annotation="str",
+                    required=True,
+                    constraints={"source": "router_prefix"},
+                ),
+            )
+
+        # Extract decorator-level dependencies (e.g. dependencies=[Depends(fn)])
+        decorator_deps_raw = decorator.arguments.get("dependencies")
+        if decorator_deps_raw:
+            deps.extend(self._extract_decorator_dependencies(decorator_deps_raw))
+
+        # Get metadata
+        tags = decorator.arguments.get("tags", [])
+        if isinstance(tags, str):
+            tags = [tags]
+
+        # Calculate confidence
+        confidence = Confidence.HIGH
+        if any(p.location_confidence < 0.5 for p in analyzed_params):
+            confidence = Confidence.MEDIUM
+
+        return ExtractedRoute(
+            method=http_method,
+            path=path,
+            handler_function=func.qualified_name,
+            handler_location=func.location,
+            path_params=path_params,
+            query_params=query_params,
+            header_params=header_params,
+            cookie_params=cookie_params,
+            body=body,
+            response=self._extract_response_info(func, decorator),
+            router_name=router_name,
+            tags=tags,
+            operation_id=decorator.arguments.get("operation_id"),
+            summary=decorator.arguments.get("summary"),
+            description=func.docstring,
+            deprecated=decorator.arguments.get("deprecated", False),
+            dependency_refs=deps,
+            confidence=confidence,
+        )
+
+    def _extract_route_path(self, decorator: ParsedDecorator) -> str:
+        """Extract route path from decorator."""
+        if decorator.positional_args:
+            first = decorator.positional_args[0]
+            if isinstance(first, str):
+                return first
+
+        if "path" in decorator.arguments:
+            return str(decorator.arguments["path"])
+
+        if decorator.arguments:
+            first_value = next(iter(decorator.arguments.values()), None)
+            if isinstance(first_value, str) and first_value.startswith("/"):
+                return first_value
+
+        return "/"
+
+    _DECORATOR_DEP_RE = re.compile(r"(?:Depends|Security)\s*\(\s*([^),]+)")
+
+    def _extract_decorator_dependencies(self, raw: Any) -> list[str]:
+        """Extract dependency function names from a decorator ``dependencies`` kwarg.
+
+        Handles both source-text strings (from ``_extract_literal_or_code``)
+        and pre-parsed lists.  Works for any ``Depends(fn)`` / ``Security(fn)``
+        reference regardless of framework.
+        """
+        refs: list[str] = []
+        if isinstance(raw, str):
+            for m in self._DECORATOR_DEP_RE.finditer(raw):
+                dep_name = m.group(1).strip()
+                if dep_name:
+                    refs.append(dep_name)
+        elif isinstance(raw, (list, tuple)):
+            for item in raw:
+                if isinstance(item, str):
+                    for m in self._DECORATOR_DEP_RE.finditer(item):
+                        dep_name = m.group(1).strip()
+                        if dep_name:
+                            refs.append(dep_name)
+        return refs
+
+    def _resolve_computed_path(self, path: str, file_path: Path) -> str:
+        """Resolve computed path using path resolver from context."""
+        # Skip if already simple
+        if path.startswith("/") and "{" not in path and "f'" not in path and 'f"' not in path:
+            return path
+
+        if self._context and self._context.path_resolver:
+            resolved = self._context.path_resolver.resolve(path, file_path)
+
+            if resolved.confidence < 1.0:
+                self._notes.append(
+                    AnalysisNote(
+                        level="warning",
+                        message=f"Partial path resolution: {path} -> {resolved.path}",
+                    )
+                )
+
+            return resolved.path
+
+        return path
+
+    def _apply_router_prefix(self, route: ExtractedRoute, file_path: Path) -> ExtractedRoute:
+        """Apply router prefix resolution."""
+        if not self._context or not self._context.router_registry:
+            return route
+
+        router_name = route.router_name
+        if not router_name:
+            return route
+
+        full_path = self._context.router_registry.resolve_path(router_name, route.path, file_path)
+
+        if full_path != route.path:
+            self._notes.append(
+                AnalysisNote(
+                    level="info",
+                    message=f"Router prefix applied: {route.path} -> {full_path}",
+                )
+            )
+            route.path = full_path
+
+        return route
+
+    def _apply_router_dependencies(self, route: ExtractedRoute, file_path: Path) -> ExtractedRoute:
+        """Merge router-level dependencies into the route's dependency_refs.
+
+        Router-level dependencies declared via
+        ``app.include_router(router, dependencies=[Depends(get_current_user)])``
+        apply to every route under that router.  This method propagates them
+        so downstream auth analysis can see them.
+        """
+        if not self._context or not self._context.router_registry:
+            return route
+
+        router_name = route.router_name
+        if not router_name:
+            return route
+
+        inherited = self._context.router_registry.get_router_dependencies(router_name, file_path)
+
+        if inherited:
+            existing = set(route.dependency_refs)
+            for dep_name in inherited:
+                if dep_name not in existing:
+                    route.dependency_refs.append(dep_name)
+
+        return route
+
+    def _reconcile_path_params(self, route: ExtractedRoute) -> ExtractedRoute:
+        """Ensure all {placeholder} names in the final composed path appear in path_params.
+
+        After router prefix application the composed path may contain template
+        variables (e.g. ``/{organization}/cases``) whose names were never seen by
+        the decorator-level parameter analyser.  This post-hoc pass:
+
+        1. Synthesises missing path params from the URL template.
+        2. Moves any matching names out of query_params (where they land by
+           default when the handler has an unannotated ``name: str`` arg).
+        """
+        template_names = set(re.findall(r"\{([^}:]+)(?::[^}]+)?\}", route.path))
+        existing_path = {p.name for p in route.path_params}
+
+        for name in sorted(template_names - existing_path):
+            route.path_params.insert(
+                0,
+                ExtractedParameter(
+                    name=name,
+                    location=ParameterLocation.PATH,
+                    type_annotation="str",
+                    required=True,
+                    constraints={"source": "router_prefix"},
+                ),
+            )
+
+        path_names = {p.name for p in route.path_params}
+        route.query_params = [q for q in route.query_params if q.name not in path_names]
+        return route
+
+    def _convert_analyzed_params(
+        self,
+        analyzed_params: list[AnalyzedParameter],
+        parsed_file: ParsedFile,
+    ) -> tuple[
+        list[ExtractedParameter],
+        list[ExtractedParameter],
+        list[ExtractedParameter],
+        list[ExtractedParameter],
+        ExtractedBody | None,
+        list[str],
+    ]:
+        """Convert analyzed parameters to extracted parameters."""
+        path_params: list[ExtractedParameter] = []
+        query_params: list[ExtractedParameter] = []
+        header_params: list[ExtractedParameter] = []
+        cookie_params: list[ExtractedParameter] = []
+        body: ExtractedBody | None = None
+        deps: list[str] = []
+
+        for param in analyzed_params:
+            if param.default_is_dependency:
+                if param.dependency_function:
+                    deps.append(param.dependency_function)
+                elif param.base_type in KNOWN_FORM_TYPES:
+                    content_type, fields = KNOWN_FORM_TYPES[param.base_type]
+                    body = ExtractedBody(
+                        content_type=content_type,
+                        model_name=param.base_type,
+                        model_fields=fields,
+                    )
+                continue
+
+            extracted = ExtractedParameter(
+                name=param.name,
+                location=PARAM_LOCATION_MAP.get(param.location, ParameterLocation.QUERY),
+                type_annotation=param.type_annotation,
+                required=not param.has_default and not param.is_optional,
+                default_value=param.default_value if param.has_default else None,
+                constraints=param.constraints,
+            )
+
+            if param.location == "path":
+                path_params.append(extracted)
+            elif param.location == "query":
+                query_params.append(extracted)
+            elif param.location == "header":
+                header_params.append(extracted)
+            elif param.location == "cookie":
+                cookie_params.append(extracted)
+            elif param.location == "body":
+                body = self._create_body(param, parsed_file)
+            elif param.location == "form" and not body:
+                body = ExtractedBody(content_type="application/x-www-form-urlencoded")
+
+        return path_params, query_params, header_params, cookie_params, body, deps
+
+    _FILE_UPLOAD_TYPES = frozenset({"UploadFile", "bytes", "BinaryIO"})
+
+    def _create_body(self, param: AnalyzedParameter, parsed_file: ParsedFile) -> ExtractedBody:
+        """Create body from analyzed parameter."""
+        model_name = param.base_type
+        model_fields: list[str] = []
+        model_qn: QualifiedName | None = None
+
+        # Determine content type: multipart for file uploads, JSON otherwise
+        content_type = "application/json"
+        if param.marker_type == "File" or (model_name and model_name in self._FILE_UPLOAD_TYPES):
+            content_type = "multipart/form-data"
+
+        # Use type resolver from context to get model fields
+        if model_name and self._context and self._context.type_resolver:
+            fields = self._context.type_resolver.get_model_fields(model_name, parsed_file.path)
+            model_fields = [f.name for f in fields]
+
+            resolved = self._context.type_resolver.resolve_type(model_name, parsed_file.path)
+            if resolved:
+                model_qn = QualifiedName(module="", name=resolved.qualified_name)
+
+        return ExtractedBody(
+            content_type=content_type,
+            model_name=model_name,
+            model_qualified_name=model_qn,
+            model_fields=model_fields,
+            required=not param.is_optional,
+        )
+
+    def _extract_response_info(
+        self,
+        func: ParsedFunction,
+        decorator: ParsedDecorator,
+    ) -> ExtractedResponse:
+        """Extract response information."""
+        response = ExtractedResponse()
+
+        if "response_model" in decorator.arguments:
+            response.model_name = str(decorator.arguments["response_model"])
+        if "status_code" in decorator.arguments:
+            with contextlib.suppress(ValueError, TypeError):
+                response.status_code = int(decorator.arguments["status_code"])
+
+        if func.return_type and not response.model_name:
+            response.model_name = self._extract_base_type(func.return_type)
+
+        return response
+
+    def _extract_base_type(self, annotation: str) -> str:
+        """Extract base type from annotation."""
+        if annotation.startswith("Optional["):
+            annotation = annotation[9:-1]
+        if annotation.startswith("list[") or annotation.startswith("List["):
+            annotation = annotation[5:-1]
+        return annotation
+
+    # =========================================================================
+    # Dynamic & CBV Routes
+    # =========================================================================
+
+    def _extract_dynamic_routes(
+        self,
+        parsed_file: ParsedFile,
+        param_analyzer: ParameterAnalyzer,
+    ) -> list[ExtractedRoute]:
+        """Extract routes from add_api_route() and route tables."""
+        routes: list[ExtractedRoute] = []
+        file_path = parsed_file.path
+
+        # Get dynamic detector from context
+        detector = self._context.get_service("dynamic_route_detector") if self._context else None
+        if not detector:
+            return routes
+
+        dynamic_routes = detector.get_routes_for_file(file_path)
+
+        for dyn_route in dynamic_routes:
+            resolved_path = self._resolve_computed_path(dyn_route.path, file_path)
+
+            for method in dyn_route.methods:
+                http_method = HTTP_METHOD_MAP.get(method.lower())
+                if not http_method:
+                    continue
+
+                route = ExtractedRoute(
+                    method=http_method,
+                    path=resolved_path,
+                    handler_function=QualifiedName(module="", name=dyn_route.handler_name),
+                    handler_location=CodeLocation(file=file_path, line=dyn_route.line),
+                    confidence=Confidence.MEDIUM if dyn_route.is_fully_resolved else Confidence.LOW,
+                )
+
+                route = self._apply_router_prefix(route, file_path)
+                route = self._apply_router_dependencies(route, file_path)
+                route = self._reconcile_path_params(route)
+                routes.append(route)
+
+        return routes
+
+    def _extract_cbv_routes(
+        self,
+        parsed_file: ParsedFile,
+        param_analyzer: ParameterAnalyzer,
+    ) -> list[ExtractedRoute]:
+        """Extract routes from class-based views."""
+        routes: list[ExtractedRoute] = []
+        file_path = parsed_file.path
+
+        # Get CBV extractor from context
+        extractor = self._context.get_service("cbv_extractor") if self._context else None
+        if not extractor:
+            return routes
+
+        cbv_classes = extractor.get_classes_for_file(file_path)
+
+        for cbv in cbv_classes:
+            for cbv_route in cbv.routes:
+                http_method = HTTP_METHOD_MAP.get(cbv_route.method.lower())
+                if not http_method:
+                    continue
+
+                path = self._resolve_computed_path(cbv_route.path, file_path)
+
+                route = ExtractedRoute(
+                    method=http_method,
+                    path=path,
+                    handler_function=QualifiedName(
+                        module=cbv.qualified_name, name=cbv_route.handler_method
+                    ),
+                    handler_location=CodeLocation(file=file_path, line=cbv_route.line),
+                    confidence=Confidence.HIGH if cbv_route.confidence > 0.8 else Confidence.MEDIUM,
+                    tags=cbv_route.tags,
+                    dependency_refs=cbv_route.dependencies,
+                )
+
+                route = self._apply_router_prefix(route, file_path)
+                route = self._apply_router_dependencies(route, file_path)
+                route = self._reconcile_path_params(route)
+                routes.append(route)
+
+        return routes
+
+    # =========================================================================
+    # Dependency Extraction
+    # =========================================================================
+
+    def _is_dependency_function(
+        self,
+        func: ParsedFunction,
+        parsed_file: ParsedFile,
+        all_project_depends_names: set[str] | None = None,
+    ) -> bool:
+        """Check if a function is ever used as a FastAPI ``Depends()`` argument.
+
+        Checks the same file first (fast path).  Falls back to
+        ``all_project_depends_names``, a cross-file pre-pass set built by
+        ``ProjectAnalyzer._extract_auth_data``, to handle the standard FastAPI
+        pattern where auth deps are defined in ``deps.py`` and used in
+        ``routers/*.py``.
+        """
+        func_name = func.name
+
+        # Same-file check (original logic).
+        for call in parsed_file.call_sites:
+            if call.callee_name == "Depends":
+                for arg in call.arguments:
+                    if arg.is_variable and arg.variable_name == func_name:
+                        return True
+                    if arg.literal_value == func_name:
+                        return True
+
+        for other_func in parsed_file.functions:
+            for param in other_func.parameters:
+                if param.default_value and f"Depends({func_name})" in param.default_value:
+                    return True
+
+        # Cross-file fallback: was this function name used in Depends() elsewhere?
+        return bool(all_project_depends_names and func_name in all_project_depends_names)
+
+    def _create_dependency(self, func: ParsedFunction, file_path: Path) -> ExtractedDependency:
+        """Create dependency from function."""
+        depends_on: list[QualifiedName] = []
+
+        for param in func.parameters:
+            if param.default_value and "Depends(" in param.default_value:
+                match = re.search(r"Depends\s*\(\s*(\w+)\s*\)", param.default_value)
+                if match:
+                    depends_on.append(QualifiedName(module="", name=match.group(1)))
+
+        return ExtractedDependency(
+            name=func.name,
+            qualified_name=func.qualified_name,
+            location=func.location,
+            dependency_type="function",
+            provides_type=func.return_type,
+            depends_on=depends_on,
+            is_auth_related=self._is_auth_related(func),
+            confidence=Confidence.HIGH,
+        )
+
+    _AUTH_KEYWORDS = frozenset(
+        {
+            "auth",
+            "authenticate",
+            "login",
+            "user",
+            "token",
+            "verify",
+            "permission",
+            "principal",
+            "credential",
+            "identity",
+            "session",
+            "bearer",
+            "api_key",
+            "apikey",
+            "security",
+            "authorize",
+            "authenticated",
+            "current_user",
+        }
+    )
+
+    _JWT_CALL_PATTERNS = frozenset(
+        {
+            "encode",
+            "decode",
+            "jwt_encode",
+            "jwt_decode",
+            "create_access_token",
+            "create_token",
+            "verify_token",
+        }
+    )
+
+    def _is_auth_related(self, func: ParsedFunction) -> bool:
+        """Check if function is auth-related via name heuristics or call-graph signals."""
+        name_lower = func.name.lower()
+        if any(kw in name_lower for kw in self._AUTH_KEYWORDS):
+            return True
+
+        for call in getattr(func, "call_sites", []):
+            callee_lower = call.callee_name.lower() if hasattr(call, "callee_name") else ""
+            if any(pat in callee_lower for pat in self._JWT_CALL_PATTERNS):
+                return True
+
+        return False
+
+    # =========================================================================
+    # Auth Extraction
+    # =========================================================================
+
+    def _extract_auth_schemes_from_classes(
+        self,
+        parsed_file: ParsedFile,
+        file_path: Path,
+    ) -> list[ExtractedAuthScheme]:
+        """Detect auth schemes defined via class inheritance.
+
+        Catches patterns like ``class RWAPIKeyHeader(APIKeyHeader): ...`` where
+        no module-level assignment instantiates the class.
+        """
+        schemes: list[ExtractedAuthScheme] = []
+        for cls in parsed_file.classes:
+            for base in cls.base_classes:
+                base_simple = base.rsplit(".", 1)[-1]
+                if base_simple in AUTH_SCHEME_PATTERNS:
+                    schemes.append(
+                        ExtractedAuthScheme(
+                            scheme_type=AUTH_SCHEME_PATTERNS[base_simple],
+                            name=cls.name,
+                            location=CodeLocation(file=file_path, line=cls.location.line),
+                            config={"class": cls.name, "base_class": base},
+                            confidence=Confidence.MEDIUM,
+                        )
+                    )
+                    break
+        return schemes
+
+    def _extract_auth_scheme_from_assignment(
+        self, assign, file_path: Path
+    ) -> ExtractedAuthScheme | None:
+        """Extract auth scheme from assignment."""
+        if assign.source_type != "call":
+            return None
+
+        called = assign.source_call or ""
+        resolved = self._resolve_call_name(called, file_path)
+
+        for pattern, scheme_type in AUTH_SCHEME_PATTERNS.items():
+            if pattern in resolved or pattern in called:
+                return ExtractedAuthScheme(
+                    scheme_type=scheme_type,
+                    name=assign.target,
+                    location=CodeLocation(file=file_path, line=assign.location.line),
+                    config={"class": called},
+                    confidence=Confidence.HIGH,
+                )
+
+        # Fallback: resolve through class inheritance (e.g. class JWTBearer(APIKeyHeader))
+        if self._context and self._context.type_resolver:
+            call_base = called.split("(")[0].strip().rsplit(".", 1)[-1]
+            resolved_type = self._context.type_resolver.resolve_type(call_base, file_path)
+            if resolved_type and getattr(resolved_type, "base_classes", None):
+                for base in resolved_type.base_classes:
+                    base_simple = base.rsplit(".", 1)[-1] if "." in base else base
+                    if base_simple in AUTH_SCHEME_PATTERNS:
+                        return ExtractedAuthScheme(
+                            scheme_type=AUTH_SCHEME_PATTERNS[base_simple],
+                            name=assign.target,
+                            location=CodeLocation(file=file_path, line=assign.location.line),
+                            config={"class": called, "base_class": base_simple},
+                            confidence=Confidence.MEDIUM,
+                        )
+
+        return None
+
+    def _extract_auth_dependency(
+        self,
+        func: ParsedFunction,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        all_project_depends_names: set[str] | None = None,
+    ) -> ExtractedAuthDependency | None:
+        """Extract auth dependency from function."""
+        if not self._is_auth_related(func):
+            return None
+
+        if not self._is_dependency_function(func, parsed_file, all_project_depends_names):
+            return None
+
+        # Correlate with known auth scheme variables: scan the function's
+        # call sites and parameter defaults for references to scheme names.
+        matched_schemes: list[str] = []
+        if known_scheme_names:
+            for call in getattr(func, "call_sites", []):
+                callee_base = (
+                    call.callee_name.rsplit(".", 1)[-1] if hasattr(call, "callee_name") else ""
+                )
+                if callee_base in known_scheme_names:
+                    matched_schemes.append(callee_base)
+            for param in func.parameters:
+                if param.default_value:
+                    for scheme_name in known_scheme_names:
+                        if scheme_name in param.default_value:
+                            matched_schemes.append(scheme_name)
+
+        return ExtractedAuthDependency(
+            name=func.name,
+            qualified_name=func.qualified_name,
+            location=func.location,
+            dependency_type=AuthDependencyType.FUNCTION,
+            uses_schemes=list(dict.fromkeys(matched_schemes)),
+            confidence=Confidence.MEDIUM,
+        )
+
+    # =========================================================================
+    # Middleware Extraction
+    # =========================================================================
+
+    # Known class-name substrings that indicate the middleware performs
+    # authentication. Used to flag `add_middleware(AuthMiddleware, ...)` style
+    # registrations so the engine's missing_auth rule can treat all routes in
+    # that app as auth-protected (see Fix 2 / Fix 7).
+    _AUTH_MIDDLEWARE_PATTERNS: ClassVar[tuple[str, ...]] = (
+        "authmiddleware",
+        "authenticationmiddleware",
+        "authbackend",
+        "securitymiddleware",
+        "jwtmiddleware",
+        "sessionmiddleware",
+        "httpbasicauth",
+        "basicauthmiddleware",
+        "bearerauthmiddleware",
+        "oauth2middleware",
+        "tokenauthmiddleware",
+        "apikeymiddleware",
+        "loginrequiredmiddleware",
+    )
+
+    def _extract_middleware_from_call(self, call, file_path: Path) -> ExtractedMiddleware | None:
+        """Extract middleware from add_middleware call."""
+        middleware_class = None
+        for arg in call.arguments:
+            if arg.position == 0 or arg.keyword is None:
+                middleware_class = arg.variable_name or arg.literal_value or arg.expression_text
+                break
+
+        if not middleware_class:
+            return None
+
+        operations: list[str] = []
+        class_lower = str(middleware_class).lower()
+
+        if "cors" in class_lower:
+            operations.append("cors")
+        if (
+            any(pat in class_lower for pat in self._AUTH_MIDDLEWARE_PATTERNS)
+            or "auth" in class_lower
+        ):
+            operations.append("auth")
+        if "gzip" in class_lower:
+            operations.append("compression")
+
+        return ExtractedMiddleware(
+            name=str(middleware_class),
+            location=call.location,
+            middleware_type="middleware",
+            applies_to_all=True,
+            operations=operations,
+            confidence=Confidence.HIGH,
+        )
+
+    def _extract_middleware_from_decorator(
+        self, func: ParsedFunction, file_path: Path
+    ) -> ExtractedMiddleware | None:
+        """Extract middleware from @app.middleware decorator."""
+        for dec in func.decorators:
+            if dec.name == "middleware":
+                return ExtractedMiddleware(
+                    name=func.name,
+                    qualified_name=func.qualified_name,
+                    location=func.location,
+                    middleware_type="http",
+                    applies_to_all=True,
+                    operations=["custom"],
+                    confidence=Confidence.HIGH,
+                )
+        return None
+
+
+# =============================================================================
+# Registration
+# =============================================================================
+
+
+_fastapi_plugin = FastAPIPlugin()
+FrameworkPluginRegistry.register(_fastapi_plugin)