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

apisec_code_bolt/frameworks/dotnet/wcf_plugin.py

@@ -0,0 +1,1239 @@
+"""
+WCF (Windows Communication Foundation) framework plugin.
+
+Detects service contracts and emits one route per operation:
+
+    [ServiceContract(Name = "Orders")]
+    public interface IOrderService {
+        [OperationContract]
+        Order GetOrder(string id);
+
+        [OperationContract(IsOneWay = true)]
+        void CancelOrder(string id);
+
+        [OperationContract]
+        [WebGet(UriTemplate = "/orders/{id}")]
+        Order GetOrderRest(string id);
+
+        [OperationContract]
+        [WebInvoke(Method = "POST", UriTemplate = "/orders")]
+        Order CreateOrderRest(CreateOrderRequest req);
+    }
+
+Per-operation route emission:
+
+| Decorator(s)                    | method     | path                              | kind        |
+|---------------------------------|------------|-----------------------------------|-------------|
+| `[OperationContract]` only      | `POST`     | `/{ServiceName}/{Operation}`      | `wcf_soap`  |
+| `[OperationContract(IsOneWay)]` | `POST`     | `/{ServiceName}/{Operation}`      | `wcf_oneway`|
+| `[WebGet]`                      | `GET`      | `UriTemplate` arg, or `/Operation`| `http`      |
+| `[WebInvoke]`                   | `Method`*  | `UriTemplate` arg, or `/Operation`| `http`      |
+
+* `[WebInvoke]` defaults to POST when its `Method` argument is omitted.
+
+The plugin walks **interfaces** (where `[ServiceContract]` lives) rather than
+implementation classes.  The interface IS the contract — every operation
+defined on it is callable surface, whether or not we can also see the
+implementing class in the same parse.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+from ...core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+    QualifiedName,
+)
+from ...parsing.base import ParsedClass, ParsedFile, ParsedFunction
+from ...parsing.csharp.literals import parse_csharp_string_literal
+from ...parsing.services import AnalysisContext
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+_WCF_IMPORTS: frozenset[str] = frozenset(
+    {
+        "System.ServiceModel",
+        "System.ServiceModel.Web",
+        "System.ServiceModel.Channels",
+        "System.ServiceModel.Description",
+        "CoreWCF",
+    }
+)
+
+_SERVICE_CONTRACT_ATTR = "ServiceContract"
+_OPERATION_CONTRACT_ATTR = "OperationContract"
+
+# REST-style WCF attributes (WebHttpBinding).
+_WEB_GET_ATTR = "WebGet"
+_WEB_INVOKE_ATTR = "WebInvoke"
+
+# Security + fault attributes.
+_PRINCIPAL_PERMISSION_ATTR = "PrincipalPermission"
+_FAULT_CONTRACT_ATTR = "FaultContract"
+
+# `typeof(X)` argument syntax from C# attribute args — used by [FaultContract].
+# The C# parser typically surfaces the expression as the string `"typeof(X)"`.
+_TYPEOF_RE = re.compile(r"typeof\s*\(\s*([A-Za-z_][\w\.]*)\s*\)")
+
+# Method-string arg on [WebInvoke(Method = "POST", ...)] → HttpMethod.
+# [WebInvoke] defaults to POST when Method is omitted (per WCF docs).
+_WEB_INVOKE_METHOD_MAP: dict[str, HttpMethod] = {
+    "GET": HttpMethod.GET,
+    "POST": HttpMethod.POST,
+    "PUT": HttpMethod.PUT,
+    "DELETE": HttpMethod.DELETE,
+    "PATCH": HttpMethod.PATCH,
+    "HEAD": HttpMethod.HEAD,
+    "OPTIONS": HttpMethod.OPTIONS,
+}
+
+# UriTemplate path placeholders: `{name}` for segments, `{*name}` for catch-all.
+# WCF UriTemplate doesn't support route constraints like ASP.NET — simpler regex.
+_URI_TEMPLATE_PARAM_RE = re.compile(r"\{\*?([A-Za-z_][\w]*)\}")
+
+
+# =============================================================================
+# Config-derived endpoint metadata
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class _WcfEndpoint:
+    """A single endpoint resolved from Web.config / App.config or a
+    CoreWCF `Startup.cs` / `Program.cs` registration.
+
+    `project_root` is the directory of the enclosing `.csproj` (or None
+    when no enclosing project is found — e.g. unit-test setups without
+    project files).  Endpoints are matched only against contracts in
+    the same project, which prevents simple-name collisions across
+    unrelated `IFoo` interfaces in different projects."""
+
+    address: str
+    binding: str
+    base_address: str | None = None
+    project_root: str | None = None
+
+
+# Methods inherited from System.Object — never WCF operations.
+_OBJECT_METHOD_NAMES: frozenset[str] = frozenset(
+    {
+        "Equals",
+        "GetHashCode",
+        "ToString",
+        "Finalize",
+    }
+)
+
+# Parameter types that are part of the WCF plumbing layer, not the request body.
+_PLUMBING_PARAM_TYPES: frozenset[str] = frozenset(
+    {
+        "Message",  # System.ServiceModel.Channels.Message
+        "MessageHeaders",
+        "OperationContext",
+        "AsyncCallback",  # Begin/End pattern callback
+        "Object",  # AsyncState in Begin pattern
+        "IAsyncResult",  # End* parameter
+        "CancellationToken",
+    }
+)
+
+
+# =============================================================================
+# WcfPlugin
+# =============================================================================
+
+
+class WcfPlugin(BaseFrameworkPlugin):
+    """Framework plugin for WCF service contracts (SOAP)."""
+
+    FRAMEWORK: ClassVar[Framework] = Framework.WCF
+    LANGUAGE: ClassVar[Language] = Language.CSHARP
+    DETECTION_IMPORTS: ClassVar[frozenset[str]] = _WCF_IMPORTS
+
+    def __init__(self) -> None:
+        # {id(AnalysisContext): {contract_fqn: [_WcfEndpoint, ...]}}.  Built
+        # lazily on the first extract_routes call per project so the cross-
+        # file config scan runs once per analysis run.
+        # Keyed by the resolved project_root path string — stable across
+        # `AnalysisContext` instances pointing at the same project, and
+        # immune to Python memory-address recycling (which `id(context)`
+        # is not).  Same project root → same scan result → same cache.
+        self._endpoint_cache: dict[str, dict[str, list[_WcfEndpoint]]] = {}
+
+    # -------------------------------------------------------------------------
+    # Detection
+    # -------------------------------------------------------------------------
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        # Primary signal: System.ServiceModel / CoreWCF imports.
+        for imp in parsed_file.imports:
+            module = imp.module or ""
+            if module.startswith("System.ServiceModel") or module.startswith("CoreWCF"):
+                return True
+        # Fallback: a class carries [ServiceContract] even without the import
+        # (rare — usually means global usings or fully-qualified attribute).
+        return any(self._is_service_contract(cls) for cls in parsed_file.classes)
+
+    # -------------------------------------------------------------------------
+    # Route extraction
+    # -------------------------------------------------------------------------
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        routes: list[ExtractedRoute] = []
+        endpoint_map = self._load_endpoint_map(context)
+        # The project that owns this file scopes which programmatic
+        # endpoints apply — distinct projects can declare same-name
+        # interfaces (e.g. multiple `IEchoService`s across scenario
+        # projects in corewcf-samples).
+        file_project_root = _find_enclosing_csproj(
+            Path(parsed_file.path) if parsed_file.path else None
+        )
+
+        for cls in parsed_file.classes:
+            if not self._is_service_contract(cls):
+                continue
+
+            service_name = self._extract_service_name(cls)
+            # When config defines endpoints for this contract, emit one route
+            # per (operation, endpoint) pair — the same contract can be
+            # exposed via multiple bindings with different addresses /
+            # security models.
+            scoped = self._endpoints_for_contract(cls, endpoint_map, file_project_root)
+            if scoped:
+                endpoints = scoped
+            elif self._contract_is_registered_elsewhere(cls, endpoint_map):
+                # This contract IS registered — but not in this file's
+                # project.  That's the client-side declaration pattern
+                # (e.g. `*_client/IEchoService.cs`): the interface mirrors
+                # the server contract for proxy generation, not for hosting.
+                # Skip — no routes from a client-side contract file.
+                continue
+            else:
+                # Standalone contract — no Web.config / Startup.cs
+                # registration anywhere.  Emit a single placeholder route
+                # per operation (PR A/B behaviour).
+                endpoints = [None]
+
+            for method in cls.methods:
+                if not self._is_operation_contract(method):
+                    continue
+                if method.name in _OBJECT_METHOD_NAMES:
+                    continue
+                if self._is_end_async_helper(method, cls):
+                    continue
+                for endpoint in endpoints:
+                    route = self._extract_operation_route(
+                        method,
+                        cls,
+                        service_name,
+                        endpoint=endpoint,
+                    )
+                    if route is not None:
+                        routes.append(route)
+
+        return routes
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """
+        Detect WCF auth schemes from:
+        1. [PrincipalPermission] on operation methods → declarative role auth
+        2. wsHttpBinding call sites → CUSTOM (Windows/Kerberos/Message security)
+        3. basicHttpBinding → CUSTOM (defaults to no auth; explicit transport
+           security config is needed for actual HTTP Basic — emit CUSTOM only)
+        4. TransportSecurity / MessageSecurity call sites → CUSTOM
+        """
+        schemes: list[ExtractedAuthScheme] = []
+        seen: set[str] = set()
+
+        def _add(name: str, scheme_type: AuthSchemeType, line: int = 1) -> None:
+            if name not in seen:
+                seen.add(name)
+                schemes.append(
+                    ExtractedAuthScheme(
+                        scheme_type=scheme_type,
+                        name=name,
+                        location=CodeLocation(file=parsed_file.path, line=line),
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        # [PrincipalPermission] decorator on any operation method → role auth active.
+        # Check decorators directly rather than import names to avoid false positives
+        # from System.Security.Claims or Microsoft.IdentityModel.Tokens imports.
+        for cls in parsed_file.classes:
+            for method in cls.methods:
+                for mdec in method.decorators:
+                    if mdec.name == "PrincipalPermission":
+                        _add(
+                            "WcfRoleAuth",
+                            AuthSchemeType.CUSTOM,
+                            method.location.line if method.location else 1,
+                        )
+
+        # Binding-based auth from call sites (programmatic host/channel configuration)
+        for call in parsed_file.call_sites:
+            name_lower = call.callee_name.lower()
+            line = call.location.line if call.location else 1
+            if "wshttpbinding" in name_lower:
+                _add("WsHttpBinding", AuthSchemeType.CUSTOM, line)
+            elif "basichttpbinding" in name_lower:
+                # basicHttpBinding defaults to SecurityMode.None; emit CUSTOM since
+                # actual transport security requires additional configuration.
+                _add("BasicHttpBinding", AuthSchemeType.CUSTOM, line)
+            elif "transportsecurity" in name_lower or "messagesecurity" in name_lower:
+                _add("WcfSecurity", AuthSchemeType.CUSTOM, line)
+
+        return schemes
+
+    def extract_auth_dependencies(
+        self, parsed_file: ParsedFile, known_scheme_names: set[str] | None = None, **kwargs
+    ) -> list[ExtractedAuthDependency]:
+        """
+        Extract `[PrincipalPermission(SecurityAction.Demand, Role = "...")]`
+        attributes — WCF's declarative role-based authorisation.
+
+        Multiple `[PrincipalPermission]` attributes on the same operation
+        are an OR (the caller must be in *any* of the listed roles); we
+        collapse them into a single dependency whose `requires_roles` is
+        the union.
+        """
+        auth_deps: list[ExtractedAuthDependency] = []
+        for cls in parsed_file.classes:
+            if not self._is_service_contract(cls):
+                continue
+            for method in cls.methods:
+                if not self._is_operation_contract(method):
+                    continue
+                roles = self._extract_principal_permission_roles(method)
+                if not roles:
+                    continue
+                handler_qname = method.qualified_name or QualifiedName(
+                    module=cls.qualified_name.module if cls.qualified_name else "",
+                    name=f"{cls.name}.{method.name}",
+                )
+                auth_deps.append(
+                    ExtractedAuthDependency(
+                        name=handler_qname.full,
+                        qualified_name=handler_qname,
+                        location=method.location,
+                        dependency_type=AuthDependencyType.ANNOTATION,
+                        requires_roles=roles,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+        return auth_deps
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+    # -------------------------------------------------------------------------
+    # Service-contract detection
+    # -------------------------------------------------------------------------
+
+    def _is_service_contract(self, cls: ParsedClass) -> bool:
+        """Whether the class/interface carries [ServiceContract]."""
+        return any(d.name == _SERVICE_CONTRACT_ATTR for d in cls.decorators)
+
+    def _is_operation_contract(self, method: ParsedFunction) -> bool:
+        return any(d.name == _OPERATION_CONTRACT_ATTR for d in method.decorators)
+
+    def _is_end_async_helper(self, method: ParsedFunction, cls: ParsedClass) -> bool:
+        """A `EndFoo` method paired with a `BeginFoo` operation is plumbing.
+
+        Begin/End is the legacy WCF async pattern.  Only the `BeginFoo` half
+        carries [OperationContract(AsyncPattern = true)]; the `EndFoo` half
+        usually doesn't, but defensively detect either spelling so we don't
+        double-emit.
+        """
+        if not method.name.startswith("End"):
+            return False
+        peer = "Begin" + method.name[len("End") :]
+        return any(m.name == peer for m in cls.methods)
+
+    # -------------------------------------------------------------------------
+    # Name extraction
+    # -------------------------------------------------------------------------
+
+    def _extract_service_name(self, cls: ParsedClass) -> str:
+        """
+        Service name from `[ServiceContract(Name = "...")]`, falling back to
+        the interface/class name minus the leading `I` (the established
+        .NET convention for service interfaces).
+        """
+        for dec in cls.decorators:
+            if dec.name != _SERVICE_CONTRACT_ATTR:
+                continue
+            name_arg = dec.arguments.get("Name") if dec.arguments else None
+            if isinstance(name_arg, str) and name_arg:
+                return name_arg
+        # `IOrderService` → `OrderService`; `OrderService` (unprefixed) stays.
+        name = cls.name
+        if name.startswith("I") and len(name) > 1 and name[1].isupper():
+            return name[1:]
+        return name
+
+    def _extract_operation_name(self, method: ParsedFunction) -> str:
+        """Operation name from `[OperationContract(Name = "...")]` or method name."""
+        for dec in method.decorators:
+            if dec.name != _OPERATION_CONTRACT_ATTR:
+                continue
+            name_arg = dec.arguments.get("Name") if dec.arguments else None
+            if isinstance(name_arg, str) and name_arg:
+                return name_arg
+        # Strip `Begin` prefix on async-pattern operations: `BeginGetOrder`
+        # → `GetOrder` (the SOAP wire operation name).
+        if method.name.startswith("Begin") and self._is_async_pattern(method):
+            return method.name[len("Begin") :]
+        return method.name
+
+    # -------------------------------------------------------------------------
+    # OperationContract flag accessors
+    # -------------------------------------------------------------------------
+
+    def _is_one_way(self, method: ParsedFunction) -> bool:
+        for dec in method.decorators:
+            if dec.name != _OPERATION_CONTRACT_ATTR:
+                continue
+            val = dec.arguments.get("IsOneWay") if dec.arguments else None
+            if _is_truthy(val):
+                return True
+        return False
+
+    def _is_async_pattern(self, method: ParsedFunction) -> bool:
+        """[OperationContract(AsyncPattern = true)] — the Begin/End style."""
+        for dec in method.decorators:
+            if dec.name != _OPERATION_CONTRACT_ATTR:
+                continue
+            val = dec.arguments.get("AsyncPattern") if dec.arguments else None
+            if _is_truthy(val):
+                return True
+        return False
+
+    def _extract_principal_permission_roles(
+        self,
+        method: ParsedFunction,
+    ) -> list[str]:
+        """
+        Collect `Role` arguments from every `[PrincipalPermission]` on the
+        method.  WCF semantics: multiple attributes form an OR — the caller
+        must be in *any* of the listed roles.  We return the union, in
+        deterministic order (preserves the order the developer wrote them).
+        """
+        roles: list[str] = []
+        seen: set[str] = set()
+        for dec in method.decorators:
+            if dec.name != _PRINCIPAL_PERMISSION_ATTR:
+                continue
+            role_arg = dec.arguments.get("Role") if dec.arguments else None
+            if isinstance(role_arg, str) and role_arg and role_arg not in seen:
+                roles.append(role_arg)
+                seen.add(role_arg)
+        return roles
+
+    def _extract_fault_types(self, method: ParsedFunction) -> list[str]:
+        """
+        Collect referenced types from every `[FaultContract(typeof(X))]`.
+
+        The C# parser surfaces the `typeof(X)` expression as a string-typed
+        positional argument.  Extract the inner type name; preserve order
+        across multiple [FaultContract] attributes.
+        """
+        faults: list[str] = []
+        seen: set[str] = set()
+        for dec in method.decorators:
+            if dec.name != _FAULT_CONTRACT_ATTR:
+                continue
+            candidate: object | None = None
+            if dec.positional_args:
+                candidate = dec.positional_args[0]
+            elif dec.arguments:
+                candidate = dec.arguments.get("detailType") or dec.arguments.get("DetailType")
+            if not isinstance(candidate, str):
+                continue
+            match = _TYPEOF_RE.search(candidate)
+            type_name = match.group(1) if match else candidate.strip()
+            if type_name and type_name not in seen:
+                faults.append(type_name)
+                seen.add(type_name)
+        return faults
+
+    # -------------------------------------------------------------------------
+    # Per-operation emission
+    # -------------------------------------------------------------------------
+
+    def _extract_operation_route(
+        self,
+        method: ParsedFunction,
+        cls: ParsedClass,
+        service_name: str,
+        endpoint: _WcfEndpoint | None = None,
+    ) -> ExtractedRoute | None:
+        operation_name = self._extract_operation_name(method)
+        is_one_way = self._is_one_way(method)
+
+        # REST-style WCF (WebHttpBinding) overrides SOAP defaults:
+        # `[WebGet]` / `[WebInvoke]` provide an HTTP verb and URI template
+        # that replace the conventional `/{ServiceName}/{Operation}` path.
+        web_route = self._extract_web_route_info(method, operation_name)
+        if web_route is not None:
+            http_method, template = web_route
+            path = self._apply_endpoint_to_rest(template, endpoint)
+            kind = "http"
+            tags = self._compose_tags("wcf", "rest", endpoint=endpoint)
+        else:
+            http_method = HttpMethod.POST
+            path = self._apply_endpoint_to_soap(service_name, operation_name, endpoint)
+            kind = "wcf_oneway" if is_one_way else "wcf_soap"
+            tags = self._compose_tags("wcf", "soap", endpoint=endpoint)
+
+        # [FaultContract(typeof(X))] → `fault:X` tag.  Multiple are common.
+        for fault_type in self._extract_fault_types(method):
+            tags.append(f"fault:{fault_type}")
+
+        # [PrincipalPermission(..., Role="X")] → dependency_refs pointing
+        # at the auth dependency emitted by extract_auth_dependencies.  The
+        # dep name is the method's fully-qualified name (same convention
+        # as MVC's [Authorize] handling).
+        dependency_refs: list[str] = []
+        if self._extract_principal_permission_roles(method):
+            handler_qname = method.qualified_name or QualifiedName(
+                module=cls.qualified_name.module if cls.qualified_name else "",
+                name=f"{cls.name}.{method.name}",
+            )
+            dependency_refs.append(handler_qname.full)
+
+        path_params, query_params, body = self._extract_params(
+            method,
+            path,
+            is_rest=web_route is not None,
+        )
+        if body is None and web_route is None:
+            # SOAP body fallback (REST handles its own body inference above).
+            body = self._extract_body(method)
+
+        response = (
+            None
+            if is_one_way and web_route is None
+            else ExtractedResponse(
+                status_code=200,
+                model_name=self._extract_response_model(method),
+            )
+        )
+
+        handler_qname = method.qualified_name or QualifiedName(
+            module=cls.qualified_name.module if cls.qualified_name else "",
+            name=f"{cls.name}.{method.name}",
+        )
+
+        return ExtractedRoute(
+            method=http_method,
+            path=path,
+            handler_function=handler_qname,
+            handler_location=method.location,
+            path_params=path_params,
+            query_params=query_params,
+            header_params=[],
+            cookie_params=[],
+            body=body,
+            response=response
+            if response is not None
+            # one-way still needs *some* response shape for the dataclass;
+            # 202 Accepted is the closest SOAP equivalent ("acknowledged,
+            # no reply").
+            else ExtractedResponse(status_code=202, model_name=None),
+            tags=tags,
+            dependency_refs=dependency_refs,
+            confidence=Confidence.HIGH,
+            kind=kind,
+        )
+
+    # -------------------------------------------------------------------------
+    # REST (WebHttpBinding) extraction
+    # -------------------------------------------------------------------------
+
+    def _extract_web_route_info(
+        self,
+        method: ParsedFunction,
+        operation_name: str,
+    ) -> tuple[HttpMethod, str] | None:
+        """
+        If `method` carries `[WebGet]` or `[WebInvoke]`, return the
+        resolved (HttpMethod, normalised path).  Otherwise None.
+        """
+        for dec in method.decorators:
+            if dec.name == _WEB_GET_ATTR:
+                uri = dec.arguments.get("UriTemplate") if dec.arguments else None
+                return HttpMethod.GET, self._normalize_uri_template(uri, operation_name)
+
+            if dec.name == _WEB_INVOKE_ATTR:
+                args = dec.arguments or {}
+                method_arg = args.get("Method")
+                verb_name = (
+                    method_arg.upper() if isinstance(method_arg, str) and method_arg else "POST"
+                )
+                http_method = _WEB_INVOKE_METHOD_MAP.get(verb_name, HttpMethod.POST)
+                uri = args.get("UriTemplate")
+                return http_method, self._normalize_uri_template(uri, operation_name)
+        return None
+
+    def _normalize_uri_template(
+        self,
+        uri: object,
+        operation_name: str,
+    ) -> str:
+        """
+        WCF default when UriTemplate is absent: the operation name.  When
+        present, ensure a leading slash and preserve the rest verbatim
+        (`{param}` and `?key={value}` portions are handled downstream).
+        """
+        if isinstance(uri, str) and uri:
+            return uri if uri.startswith("/") else "/" + uri
+        return "/" + operation_name
+
+    def _extract_params(
+        self,
+        method: ParsedFunction,
+        path: str,
+        is_rest: bool,
+    ) -> tuple[list[ExtractedParameter], list[ExtractedParameter], ExtractedBody | None]:
+        """
+        For REST routes, classify method parameters by where they appear in
+        the URI template.  For SOAP, return empty lists — the body is the
+        whole request and is handled by `_extract_body`.
+        """
+        if not is_rest:
+            return [], [], None
+
+        path_part, _, query_part = path.partition("?")
+        path_names = set(_URI_TEMPLATE_PARAM_RE.findall(path_part))
+        query_names = set(_URI_TEMPLATE_PARAM_RE.findall(query_part))
+
+        path_params: list[ExtractedParameter] = []
+        query_params: list[ExtractedParameter] = []
+        body: ExtractedBody | None = None
+
+        for param in method.parameters:
+            type_name = (param.type_annotation or "").strip()
+            simple = type_name.split("<")[0].strip().rstrip("?").rsplit(".", 1)[-1]
+            if simple in _PLUMBING_PARAM_TYPES:
+                continue
+
+            if param.name in path_names:
+                path_params.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=ParameterLocation.PATH,
+                        type_annotation=param.type_annotation,
+                        required=True,
+                        code_location=param.location,
+                    )
+                )
+            elif param.name in query_names:
+                query_params.append(
+                    ExtractedParameter(
+                        name=param.name,
+                        location=ParameterLocation.QUERY,
+                        type_annotation=param.type_annotation,
+                        required=(param.default_value is None),
+                        default_value=param.default_value,
+                        code_location=param.location,
+                    )
+                )
+            elif body is None:
+                # Any remaining non-plumbing parameter is the request body —
+                # which only makes sense for POST/PUT/PATCH in REST.
+                body = ExtractedBody(
+                    content_type="application/xml",
+                    model_name=type_name or None,
+                    required=True,
+                )
+
+        return path_params, query_params, body
+
+    def _extract_body(self, method: ParsedFunction) -> ExtractedBody | None:
+        """
+        First parameter whose type isn't WCF plumbing becomes the SOAP body.
+
+        WCF can also use `[MessageContract]` types or accept `Message` directly,
+        but for first-pass extraction the "first user-defined parameter" rule
+        catches the canonical pattern.
+        """
+        for param in method.parameters:
+            type_name = (param.type_annotation or "").strip()
+            if not type_name:
+                continue
+            simple = type_name.split("<")[0].strip().rstrip("?").rsplit(".", 1)[-1]
+            if simple in _PLUMBING_PARAM_TYPES:
+                continue
+            return ExtractedBody(
+                content_type="application/soap+xml",
+                model_name=type_name,
+                required=True,
+            )
+        return None
+
+    def _extract_response_model(self, method: ParsedFunction) -> str | None:
+        """Unwrap `Task<T>` / `IAsyncResult` / `void` to the actual response type."""
+        ret = (method.return_type or "").strip()
+        if not ret or ret in ("void", "Task", "ValueTask", "IAsyncResult"):
+            return None
+        for wrapper in ("Task<", "ValueTask<"):
+            if ret.startswith(wrapper) and ret.endswith(">"):
+                inner = ret[len(wrapper) : -1].strip()
+                return inner or None
+        return ret
+
+    # -------------------------------------------------------------------------
+    # Config-derived endpoint resolution
+    # -------------------------------------------------------------------------
+
+    def _load_endpoint_map(
+        self,
+        context: AnalysisContext | None,
+    ) -> dict[str, list[_WcfEndpoint]]:
+        """
+        Build `{contract_FQN: [_WcfEndpoint, ...]}` from every Web.config /
+        App.config and CoreWCF Startup.cs / Program.cs under the project
+        root.  Cached per AnalysisContext.
+
+        XML config is authoritative: when a contract has endpoints declared
+        in both XML and programmatic CoreWCF registration, the XML entries
+        are used (legacy WCF deployments use XML as the deployment-time
+        config; CoreWCF hosts use programmatic, but rarely both at once).
+
+        Returns {} when no context is provided (unit-test invocation) — the
+        plugin then emits placeholder paths from PR A/B behaviour.
+        """
+        if context is None or context.project_root is None:
+            return {}
+        # Cache key: resolved absolute path of the project root.  Stable
+        # across `AnalysisContext` instances; avoids the `id(context)`
+        # memory-recycling hazard.
+        try:
+            key = str(Path(context.project_root).resolve())
+        except OSError:
+            key = str(context.project_root)
+        if key not in self._endpoint_cache:
+            xml_map = _scan_config_files(context.project_root)
+            startup_map = _scan_startup_files(context.project_root)
+            merged = dict(xml_map)
+            for contract, eps in startup_map.items():
+                merged.setdefault(contract, eps)
+            # Dedupe within each contract by full _WcfEndpoint equality
+            # (address + binding + base_address).  CoreWCF samples commonly
+            # have multiple Startup.cs files each registering the same
+            # contract at the same address — those collapse to one route
+            # here, not one route per registration call.
+            self._endpoint_cache[key] = {
+                contract: _dedupe_preserve_order(eps) for contract, eps in merged.items()
+            }
+        return self._endpoint_cache[key]
+
+    def _contract_is_registered_elsewhere(
+        self,
+        cls: ParsedClass,
+        endpoint_map: dict[str, list[_WcfEndpoint]],
+    ) -> bool:
+        """Return True iff some endpoint anywhere in the map registers this
+        contract — used to distinguish client-side interface declarations
+        (no registrations in their own project, but the contract IS
+        registered in the server project) from genuinely standalone
+        contracts (no registrations anywhere).  Independent of
+        project_root scoping."""
+        if not endpoint_map:
+            return False
+        if cls.qualified_name and cls.qualified_name.full in endpoint_map:
+            return True
+        if cls.name in endpoint_map:
+            return True
+        return any(fqn.rsplit(".", 1)[-1] == cls.name for fqn in endpoint_map)
+
+    def _endpoints_for_contract(
+        self,
+        cls: ParsedClass,
+        endpoint_map: dict[str, list[_WcfEndpoint]],
+        file_project_root: str | None = None,
+    ) -> list[_WcfEndpoint]:
+        """
+        Match a parsed `[ServiceContract]` class to its config endpoints,
+        restricted to endpoints registered in the same project.
+
+        Lookup order (each step filtered by project_root):
+          1. Fully-qualified name (Web.config typically uses FQN)
+          2. Unqualified class name (Startup.cs uses C# typeof short form)
+          3. Suffix match — any map key whose simple-name segment matches
+
+        `file_project_root` is the contract file's enclosing `.csproj`
+        directory.  An endpoint with `project_root=None` is treated as
+        globally applicable (no .csproj in unit-test setups; legacy
+        deployments where Web.config sits outside any project).  This
+        prevents same-simple-name interfaces in different projects from
+        sharing each other's registrations.
+        """
+        if not endpoint_map:
+            return []
+
+        def _scope(eps: list[_WcfEndpoint]) -> list[_WcfEndpoint]:
+            return [
+                ep
+                for ep in eps
+                if ep.project_root is None
+                or file_project_root is None
+                or ep.project_root == file_project_root
+            ]
+
+        if cls.qualified_name:
+            fqn = cls.qualified_name.full
+            if fqn in endpoint_map:
+                scoped = _scope(endpoint_map[fqn])
+                if scoped:
+                    return scoped
+        if cls.name in endpoint_map:
+            scoped = _scope(endpoint_map[cls.name])
+            if scoped:
+                return scoped
+        # Suffix match across map keys.
+        for fqn, eps in endpoint_map.items():
+            if fqn.rsplit(".", 1)[-1] == cls.name:
+                scoped = _scope(eps)
+                if scoped:
+                    return scoped
+        return []
+
+    def _apply_endpoint_to_soap(
+        self,
+        service_name: str,
+        operation_name: str,
+        endpoint: _WcfEndpoint | None,
+    ) -> str:
+        """SOAP path: replace `/{ServiceName}/{Operation}` with `<address>/{Operation}`."""
+        if endpoint is None:
+            return f"/{service_name}/{operation_name}"
+        if _is_full_url(endpoint.address):
+            return endpoint.address.rstrip("/") + "/" + operation_name
+        address = endpoint.address.strip("/")
+        if not address:
+            return f"/{operation_name}"
+        return f"/{address}/{operation_name}"
+
+    def _apply_endpoint_to_rest(
+        self,
+        uri_template: str,
+        endpoint: _WcfEndpoint | None,
+    ) -> str:
+        """REST path: prepend the endpoint address to the UriTemplate."""
+        if endpoint is None:
+            return uri_template
+        if _is_full_url(endpoint.address):
+            base = endpoint.address.rstrip("/")
+            return base + (uri_template if uri_template.startswith("/") else "/" + uri_template)
+        address = endpoint.address.strip("/")
+        if not address:
+            return uri_template
+        template = uri_template if uri_template.startswith("/") else "/" + uri_template
+        return f"/{address}{template}"
+
+    def _compose_tags(
+        self,
+        *base_tags: str,
+        endpoint: _WcfEndpoint | None = None,
+    ) -> list[str]:
+        """Build the route tag list, tagging the binding when known."""
+        tags = list(base_tags)
+        if endpoint and endpoint.binding:
+            tags.append(f"binding:{endpoint.binding}")
+        return tags
+
+
+# =============================================================================
+# Config file scanner
+# =============================================================================
+
+
+def _scan_config_files(root: Path) -> dict[str, list[_WcfEndpoint]]:
+    """
+    Walk `root` for `Web.config` / `App.config` files and extract
+    `<system.serviceModel>` endpoint registrations.
+
+    Returns `{contract_full_name: [_WcfEndpoint, ...]}`.  Multiple
+    endpoints per contract are common (one binding for SOAP, another for
+    REST/JSON, etc.) — preserve all of them in registration order.
+    """
+    mapping: dict[str, list[_WcfEndpoint]] = {}
+    try:
+        config_paths = sorted(
+            {
+                *root.rglob("Web.config"),
+                *root.rglob("App.config"),
+            }
+        )
+    except (OSError, ValueError):
+        return mapping
+
+    for path in config_paths:
+        try:
+            tree = ET.parse(path)
+        except (ET.ParseError, OSError):
+            continue
+        # XML config endpoints are deployment-time configuration that
+        # applies cross-project: traditional .NET Framework WCF puts
+        # the contract interface in one assembly (`*.Contracts.csproj`)
+        # and hosts it from a separate project's App.config (e.g. a
+        # ConsoleHost / WindowsService).  Leaving `project_root=None`
+        # lets `_endpoints_for_contract` apply these endpoints to
+        # contracts in any project.  Programmatic endpoints stay
+        # project-scoped (see `_scan_startup_files`).
+        for service in tree.getroot().iter("service"):
+            base_addresses = [
+                add.get("baseAddress", "")
+                for add in service.findall("./host/baseAddresses/add")
+                if add.get("baseAddress")
+            ]
+            base_addr = base_addresses[0] if base_addresses else None
+            for endpoint in service.findall("./endpoint"):
+                contract = endpoint.get("contract")
+                if not contract:
+                    continue
+                ep = _WcfEndpoint(
+                    address=endpoint.get("address", "") or "",
+                    binding=endpoint.get("binding", "") or "",
+                    base_address=base_addr,
+                    project_root=None,
+                )
+                mapping.setdefault(contract, []).append(ep)
+    return mapping
+
+
+def _is_full_url(s: str) -> bool:
+    return s.startswith("http://") or s.startswith("https://") or s.startswith("net.tcp://")
+
+
+def _find_enclosing_csproj(path: Path | None) -> str | None:
+    """Walk up `path`'s ancestors looking for a sibling `*.csproj` file.
+    Returns the containing directory as a string, or None when no
+    project file is found (unit-test setups, files outside any
+    project)."""
+    if path is None:
+        return None
+    try:
+        current = path.parent if path.is_file() else path
+    except OSError:
+        return None
+    with contextlib.suppress(OSError):
+        current = current.resolve()
+    while True:
+        try:
+            if any(current.glob("*.csproj")):
+                return str(current)
+        except OSError:
+            return None
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def _dedupe_preserve_order(items: list[_WcfEndpoint]) -> list[_WcfEndpoint]:
+    """Remove duplicate `_WcfEndpoint` entries while preserving the
+    first-seen order — keeps deterministic output across runs.
+
+    Dedup key:
+      - address (lower-cased — CoreWCF / IIS route case-insensitively)
+      - binding (lower-cased)
+      - project_root (so programmatic endpoints from different projects
+        with same address don't collapse before scope-filtering)
+
+    `base_address` is intentionally NOT part of the key.  Two endpoints
+    sharing (address, binding) but declared in different host projects'
+    `<host><baseAddresses>` blocks at different ports/hostnames produce
+    the same route URL (`_apply_endpoint_to_soap` uses `address`, not
+    `base_address`) — they're the same logical route surface, just hosted
+    on different ports/URLs.  Real exposure: QIQO ships both a
+    `ConsoleHost/App.config` (port 7473) and a `WindowsServiceHost/App.config`
+    (port 7476) declaring the same endpoints.
+    """
+    seen: set[tuple[str, str, str | None]] = set()
+    out: list[_WcfEndpoint] = []
+    for ep in items:
+        key = (
+            ep.address.lower(),
+            ep.binding.lower(),
+            ep.project_root,
+        )
+        if key not in seen:
+            seen.add(key)
+            out.append(ep)
+    return out
+
+
+# =============================================================================
+# CoreWCF programmatic-endpoint scanner
+# =============================================================================
+#
+# CoreWCF hosts register endpoints in Startup.cs / Program.cs, not in
+# Web.config.  Both REST (AddServiceWebEndpoint) and SOAP (AddServiceEndpoint)
+# share the same shape:
+#
+#     builder.AddServiceWebEndpoint<TService, TContract>(
+#         new WebHttpBinding { ... }, "api", behavior => { ... });
+#
+# We extract the contract type (2nd type parameter) and the address (2nd
+# positional argument, when a string literal).  Non-literal addresses
+# (variables, configuration lookups) are out of scope for v1.
+
+
+_ADD_ENDPOINT_RE = re.compile(
+    r"\.(AddServiceWebEndpoint|AddServiceEndpoint)\s*"
+    r"<\s*[\w.]+\s*,\s*([\w.]+)\s*>\s*\("
+)
+
+# Non-generic SOAP form used by `System.ServiceModel.ServiceHost`:
+#     host.AddServiceEndpoint(contract, binding, "address");
+# where `contract` is either `typeof(X)` inline or a variable previously
+# assigned from `typeof(X)`.  CoreWCF generic form covers most newer code;
+# this branch picks up legacy / `ServiceHost`-based hosting in
+# `NetFrameworkServer`-style samples.
+_NONGENERIC_ADD_ENDPOINT_RE = re.compile(
+    r"\.AddServiceEndpoint\s*\(\s*"
+    r"(typeof\s*\(\s*([\w.]+)\s*\)|[A-Za-z_]\w*)\s*,"
+)
+
+# `Type contract = typeof(Foo.IBar);` or `var contract = typeof(Foo.IBar);`
+# — used to resolve the contract type when AddServiceEndpoint is called
+# with a variable rather than an inline typeof.
+_TYPEOF_ASSIGN_RE = re.compile(r"\b(?:Type|var)\s+([A-Za-z_]\w*)\s*=\s*typeof\s*\(\s*([\w.]+)\s*\)")
+
+
+def _scan_startup_files(root: Path) -> dict[str, list[_WcfEndpoint]]:
+    """
+    Walk `root` for `.cs` files and extract `AddServiceWebEndpoint<T, C>(...)`
+    and `AddServiceEndpoint<T, C>(...)` calls into the same shape used by
+    XML config.
+
+    Returns `{contract_simple_name: [_WcfEndpoint, ...]}`.  We key by the
+    simple contract name because programmatic registration uses the
+    `typeof(IFoo)` short form rather than the FQN — `_endpoints_for_contract`
+    already handles both forms.
+    """
+    mapping: dict[str, list[_WcfEndpoint]] = {}
+    try:
+        cs_paths = sorted(root.rglob("*.cs"))
+    except (OSError, ValueError):
+        return mapping
+    for path in cs_paths:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        # Cheap pre-filter: skip files that don't mention either method.
+        if "AddServiceEndpoint" not in text and "AddServiceWebEndpoint" not in text:
+            continue
+        project_root = _find_enclosing_csproj(path)
+        for method, contract, address in _iter_addservice_calls(text):
+            binding = "webHttpBinding" if method == "AddServiceWebEndpoint" else ""
+            ep = _WcfEndpoint(
+                address=address,
+                binding=binding,
+                base_address=None,
+                project_root=project_root,
+            )
+            mapping.setdefault(contract, []).append(ep)
+    return mapping
+
+
+def _iter_addservice_calls(source: str):
+    """
+    Yield `(method_name, contract_simple_name, address_literal)` for each
+    `AddService(Web)Endpoint(...)` call in `source`.  Two shapes covered:
+
+    1. Generic form (CoreWCF):
+           builder.AddServiceWebEndpoint<TService, TContract>(binding, "addr", ...)
+           builder.AddServiceEndpoint<TService, TContract>(binding, "addr")
+
+    2. Non-generic form (`System.ServiceModel.ServiceHost`):
+           host.AddServiceEndpoint(contract, binding, "addr")
+       — where `contract` is `typeof(X)` inline or a local variable
+       previously assigned from `typeof(X)`.
+
+    Skips calls where the address is not a plain string literal —
+    interpolated strings and variable references need richer analysis.
+    """
+    for match in _ADD_ENDPOINT_RE.finditer(source):
+        contract = match.group(2)
+        address = _second_positional_string(source, match.end())
+        if address is None:
+            continue
+        yield match.group(1), contract, address
+
+    # Non-generic form — resolve typeof variables one pass per file.
+    var_to_type: dict[str, str] = {}
+    for m in _TYPEOF_ASSIGN_RE.finditer(source):
+        var_to_type[m.group(1)] = m.group(2).rsplit(".", 1)[-1]
+
+    for match in _NONGENERIC_ADD_ENDPOINT_RE.finditer(source):
+        # Skip when this is actually a generic call — `AddServiceEndpoint<T,C>(`
+        # would also match the bare `(` portion otherwise.
+        head = source[match.start() : match.end()]
+        if "<" in head:
+            continue
+        inline_typeof = match.group(2)
+        var_name = match.group(1)
+        if inline_typeof:
+            contract = inline_typeof.rsplit(".", 1)[-1]
+        else:
+            contract = var_to_type.get(var_name)
+            if contract is None:
+                continue
+        # The regex already consumed `(<contract>,` — cursor is at the start
+        # of the binding arg.  `_second_positional_string` skips one arg and
+        # returns the next string literal — which here is the address.
+        address = _second_positional_string(source, match.end())
+        if address is None:
+            continue
+        yield "AddServiceEndpoint", contract, address
+
+
+def _second_positional_string(source: str, start: int) -> str | None:
+    """
+    Given `source` positioned just past the opening `(` of a method call,
+    return the contents of the second positional argument iff it is a plain
+    `"..."` string literal.  Returns None for any other case
+    (verbatim strings, interpolated strings, non-literals, only one arg).
+    """
+    depth = 1
+    i = start
+    in_str = False
+    in_chr = False
+    in_line_comment = False
+    in_block_comment = False
+    # Phase 1: scan past the first argument to the first top-level comma.
+    while i < len(source):
+        c = source[i]
+        nxt = source[i + 1] if i + 1 < len(source) else ""
+        if in_line_comment:
+            if c == "\n":
+                in_line_comment = False
+            i += 1
+            continue
+        if in_block_comment:
+            if c == "*" and nxt == "/":
+                in_block_comment = False
+                i += 2
+                continue
+            i += 1
+            continue
+        if in_str:
+            if c == "\\":
+                i += 2
+                continue
+            if c == '"':
+                in_str = False
+            i += 1
+            continue
+        if in_chr:
+            if c == "\\":
+                i += 2
+                continue
+            if c == "'":
+                in_chr = False
+            i += 1
+            continue
+        if c == "/" and nxt == "/":
+            in_line_comment = True
+            i += 2
+            continue
+        if c == "/" and nxt == "*":
+            in_block_comment = True
+            i += 2
+            continue
+        if c == '"':
+            in_str = True
+            i += 1
+            continue
+        if c == "'":
+            in_chr = True
+            i += 1
+            continue
+        if c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+            if depth == 0:
+                return None  # call ended before a second argument
+        elif c == "," and depth == 1:
+            i += 1
+            break
+        i += 1
+    else:
+        return None
+    # Phase 2: parse the second positional as a C# string literal —
+    # plain `"..."` or verbatim `@"..."` (where `""` is an embedded
+    # quote, decoded back to a single `"` in the returned content).
+    #
+    # Interpolated `$"..."` (and the verbatim-interpolated `$@"..."` /
+    # `@$"..."`) are intentionally deferred: emitting interpolated
+    # templates with `{placeholder}` segments would create routes whose
+    # paths can't match a resolved-value GT.  Closing that gap is v7
+    # charter work: needs a constant-resolution pass over `const string`
+    # / `static readonly string` fields in scope, plus paired GT
+    # updates for any newly-emitted resolved URLs.
+    parsed = parse_csharp_string_literal(source, i)
+    if parsed is None:
+        return None
+    content, _open, _after = parsed
+    return content
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def _is_truthy(val: object) -> bool:
+    """Accept Python True or the C# attribute-arg string `"true"` (case-insensitive)."""
+    if val is True:
+        return True
+    if isinstance(val, str) and val.strip().lower() == "true":
+        return True
+    return False
+
+
+# =============================================================================
+# Self-registration
+# =============================================================================
+
+_wcf_plugin = WcfPlugin()
+FrameworkPluginRegistry.register(_wcf_plugin)