azure-dev-proxy 0.1.0__py3-none-any.whl

azure_dev_proxy/routers/management.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import asdict
+from importlib.resources import files
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+from aiohttp import web
+
+from ..auth import HANDOFF_KEY, LOGIN_PATH, SESSION_PATH
+from ..config import Config, TokenRule
+from ._base import Router
+from .utils import GRAPHQL_PREFIX
+
+if TYPE_CHECKING:
+    from ..proxy import Proxy
+
+
+API_PATH = "/:config"
+PERSISTED_PATH = API_PATH + "/persisted"
+SCRIPT_PATH = "/:app.js"
+RESPONSE_HEADERS = {
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "strict-origin",
+    "Content-Security-Policy": (
+        "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; "
+        "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"
+    ),
+}
+
+
+class Management(Router):
+    """Persisted routing configuration and process-lifetime temporary overrides."""
+
+    def __init__(self, proxy: Proxy) -> None:
+        super().__init__(proxy)
+        self._overrides: dict[str, TokenRule] = {}
+        self._csrf = secrets.token_hex(32)
+        assets = files("azure_dev_proxy").joinpath("static")
+        self._html = assets.joinpath("index.html").read_text(encoding="utf-8")
+        self._script = assets.joinpath("app.js").read_text(encoding="utf-8")
+
+    def register(self, app: web.Application) -> None:
+        """Register local UI, config and auth paths, with a local special-path fallback."""
+        app[MANAGEMENT_KEY] = self
+        for path in (
+            "/",
+            API_PATH,
+            PERSISTED_PATH,
+            SCRIPT_PATH,
+            LOGIN_PATH,
+            SESSION_PATH,
+        ):
+            app.router.add_route("*", path, self.handle)
+        app.router.add_route("*", "/:{endpoint:.*}", self.handle)
+
+    @staticmethod
+    def is_local_path(path: str) -> bool:
+        """Return whether a path belongs to the local UI or management API."""
+        return (
+            path == "/" or path.startswith("/:") and not path.startswith(GRAPHQL_PREFIX)
+        )
+
+    @staticmethod
+    def is_edit_host(host: str) -> bool:
+        """Return whether an already validated Host names the editing origin."""
+        return urlsplit("http://" + host).hostname == "localhost"
+
+    def effective_rules(
+        self, base_rules: tuple[TokenRule, ...]
+    ) -> tuple[TokenRule, ...]:
+        """Return overrides before base rules, each ordered by host specificity."""
+        return (
+            *sorted(self._overrides.values(), key=lambda rule: rule.priority),
+            *sorted(base_rules, key=lambda rule: rule.priority),
+        )
+
+    def resource_for(self, origin: str, config: Config) -> str | None:
+        """Return the token audience selected by the effective rules."""
+        override = Config(tuple(self._overrides.values())).resource_for(origin)
+        return config.resource_for(origin) if override is None else override
+
+    def _snapshot(
+        self,
+        configuration: Config,
+        *,
+        editable: bool,
+        persistence_available: bool,
+    ) -> web.Response:
+        effective = self.effective_rules(configuration.token_rules)
+        return web.json_response(
+            {
+                "base_rules": [asdict(rule) for rule in configuration.token_rules],
+                "overrides": [
+                    asdict(rule) for rule in effective[: len(self._overrides)]
+                ],
+                "effective_rules": [asdict(rule) for rule in effective],
+                "trusted_origins": list(configuration.trusted_origins),
+                "override_lifetime": "Until process exit, including automatic idle shutdown.",
+                "editable": editable,
+                "persistence_available": persistence_available,
+            },
+            headers=RESPONSE_HEADERS,
+        )
+
+    @staticmethod
+    def validate_browser(request: web.Request) -> None:
+        """Require same-origin management requests, except deliberate UI navigation."""
+        if request.get(HANDOFF_KEY, False):
+            return
+        host = request.headers["Host"]
+        origin = request.headers.get("Origin")
+        navigation = (
+            request.method in {"GET", "HEAD"}
+            and request.path in {"/", SESSION_PATH}
+            and request.headers.get("Sec-Fetch-Mode") == "navigate"
+            and request.headers.get("Sec-Fetch-Dest") == "document"
+            and (
+                request.path == SESSION_PATH
+                or request.headers.get("Sec-Fetch-User") == "?1"
+            )
+        )
+        if (
+            origin is not None
+            and origin != "http://" + host
+            or request.headers.get("Sec-Fetch-Site") == "cross-site"
+            and not navigation
+        ):
+            raise web.HTTPForbidden(text="Local same-origin access required\n")
+
+    async def handle(self, request: web.Request) -> web.Response:
+        """Serve local configuration without exposing tokens or forwarding CORS."""
+        proxy = self.proxy
+        self.validate_browser(request)
+        host = request.headers["Host"]
+        origin = request.headers.get("Origin")
+        editable = self.is_edit_host(host)
+        configuration = proxy.config
+        persistence_available = proxy.config_path is not None
+        if request.method in {"GET", "HEAD"} and request.path == "/":
+            port = urlsplit("http://" + host).port or 80
+            page = self._html
+            for marker, value in {
+                "__CSRF__": self._csrf if editable else "",
+                "__EDITABLE__": "true" if editable else "false",
+                "__EDIT_URL__": f"http://localhost:{port}/",
+                "__FORWARD_ORIGIN__": f"http://127.0.0.1:{port}",
+                "__EDITOR_HIDDEN__": "" if editable else "hidden",
+                "__AUTH_WARNING_HIDDEN__": (
+                    "hidden" if proxy.authentication.enabled else ""
+                ),
+            }.items():
+                page = page.replace(marker, value)
+            return web.Response(
+                text=page, content_type="text/html", headers=RESPONSE_HEADERS
+            )
+        if request.method in {"GET", "HEAD"} and request.path == SCRIPT_PATH:
+            return web.Response(
+                text=self._script,
+                content_type="text/javascript",
+                headers=RESPONSE_HEADERS,
+            )
+        if request.path not in {API_PATH, PERSISTED_PATH}:
+            if request.path in {"/", SCRIPT_PATH}:
+                raise web.HTTPMethodNotAllowed(request.method, ["GET", "HEAD"])
+            raise web.HTTPNotFound(text="Unknown management endpoint\n")
+        persisted = request.path == PERSISTED_PATH
+        if request.method in {"GET", "HEAD"} and not persisted:
+            return self._snapshot(
+                configuration,
+                editable=editable,
+                persistence_available=persistence_available,
+            )
+        if request.method not in {"POST", "DELETE"}:
+            allowed = (
+                ["POST", "DELETE"] if persisted else ["GET", "HEAD", "POST", "DELETE"]
+            )
+            raise web.HTTPMethodNotAllowed(request.method, allowed)
+        csrf = request.headers.getall("X-Azure-Proxy-CSRF", [])
+        if (
+            not editable
+            or origin is None
+            or len(csrf) != 1
+            or not secrets.compare_digest(csrf[0], self._csrf)
+            or request.content_type != "application/json"
+        ):
+            raise web.HTTPForbidden(text="Same-origin JSON and CSRF token required\n")
+        try:
+            body = await request.read()
+            value = json.loads(body)
+            if persisted and (not isinstance(value, dict) or set(value) != {"host"}):
+                raise ValueError("A persisted-rule operation requires a hostname")
+            parsed = Config.parse({"token_rules": [value]})
+        except (ValueError, UnicodeError, web.HTTPRequestEntityTooLarge):
+            raise web.HTTPBadRequest(
+                text="Invalid or oversized hostname/resource override\n"
+            ) from None
+        rule = parsed.token_rules[0]
+        if persisted:
+            if proxy.config_path is None:
+                raise web.HTTPConflict(
+                    text="No configuration file is available for persisted changes\n"
+                )
+            if request.method == "POST":
+                promoted = self._overrides.get(rule.host)
+                if promoted is None:
+                    raise web.HTTPNotFound(
+                        text="Temporary rule no longer exists; refresh and retry\n"
+                    )
+                rule = promoted
+            try:
+                updated = Config.update_rule(
+                    proxy.config_path,
+                    rule,
+                    delete=request.method == "DELETE",
+                )
+            except PermissionError:
+                raise web.HTTPForbidden(
+                    text="The configuration file is read-only or not writable\n"
+                ) from None
+            except ValueError:
+                raise web.HTTPConflict(
+                    text="The configuration file contains invalid JSON or rules\n"
+                ) from None
+            except OSError:
+                raise web.HTTPInternalServerError(
+                    text="Could not update the configuration file\n"
+                ) from None
+            proxy.config = Config(updated.token_rules, proxy.config.trusted_origins)
+            if request.method == "POST":
+                self._overrides.pop(rule.host, None)
+            configuration = proxy.config
+        elif request.method == "DELETE":
+            self._overrides.pop(rule.host, None)
+        else:
+            self._overrides[rule.host] = rule
+        return self._snapshot(
+            configuration,
+            editable=editable,
+            persistence_available=persistence_available,
+        )
+
+
+MANAGEMENT_KEY = web.AppKey("management", Management)

azure_dev_proxy/routers/reverse_proxy.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+
+from aiohttp import ClientError, web
+from multidict import CIMultiDict
+from yarl import URL
+
+from ..auth import ROUTE_KEY, TOKEN_HEADER, ProxyAuthentication
+from ._base import Router
+from .management import MANAGEMENT_KEY
+from .utils import (
+    ProxyCall,
+    parse_target,
+    rewrite_refresh,
+    rewrite_url,
+    validate_destination,
+)
+
+LOG = logging.getLogger("azure_dev_proxy.proxy")
+HOP_HEADERS = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
+
+
+class ReverseProxy(Router):
+    """Streaming HTTP(S) forwarding through the proxy's owned upstream session."""
+
+    def register(self, app: web.Application) -> None:
+        """Register ordinary forwarding after all local endpoints."""
+        app[REVERSE_PROXY_KEY] = self
+        app.router.add_route("*", "/{destination:.*}", self.handle)
+
+    async def handle(self, request: web.Request) -> web.StreamResponse:
+        """Parse and forward an ordinary destination using its raw route bytes."""
+        try:
+            target = parse_target(request[ROUTE_KEY])
+        except ValueError:
+            raise web.HTTPBadRequest(text="Invalid destination route\n") from None
+        call = validate_destination(request, target, port=self.proxy.port)
+        return await self.forward(request, target, call)
+
+    async def forward(
+        self,
+        request: web.Request,
+        target: URL,
+        call: ProxyCall,
+        *,
+        explicit_scheme: bool = False,
+    ) -> web.StreamResponse:
+        """
+        Stream a validated HTTP(S) destination through the upstream session.
+
+        Args:
+            request: Authenticated request approved by the browser policy.
+            target: Parsed destination, already checked for self-loops.
+            call: Request log context updated with the acquisition result.
+            explicit_scheme: Force explicit HTTPS in rewritten navigation,
+                as GraphiQL POSTs require. Otherwise preserve the ordinary
+                route's scheme style. HTTP always retains its scheme.
+        """
+        proxy = self.proxy
+        origin = str(target.origin())
+        headers = filtered_headers(CIMultiDict(request.headers), request=True)
+        if "Referer" in headers:
+            referer, _ = ProxyAuthentication.strip_query_token(headers["Referer"])
+            headers["Referer"] = referer
+        headers["Host"] = target.raw_authority
+        resource = request.app[MANAGEMENT_KEY].resource_for(origin, proxy.config)
+        call.source = "non-https" if target.scheme != "https" else "not-allowlisted"
+        if resource is not None:
+            call.source = "acquisition-interrupted"
+            result = await proxy.tokens.get_with_status(origin, resource)
+            call.source = result.source
+            call.token = result.token is not None
+            if result.token is not None:
+                headers["Authorization"] = f"Bearer {result.token}"
+        call.emit(request.method)
+        if proxy.session is None:
+            raise RuntimeError("Proxy session has not started")
+        response: web.StreamResponse | None = None
+        explicit_scheme = explicit_scheme or request[ROUTE_KEY][1:].lower().startswith(
+            ("http://", "https://")
+        )
+        try:
+            async with proxy.session.request(
+                request.method,
+                target,
+                headers=headers,
+                data=_body_chunks(request) if request.can_read_body else None,
+                allow_redirects=False,
+                ssl=proxy.tls,
+            ) as upstream:
+                response_headers = filtered_headers(
+                    CIMultiDict(upstream.headers), request=False
+                )
+                try:
+                    for name in ("Location", "Refresh"):
+                        values = response_headers.getall(name, [])
+                        if values:
+                            del response_headers[name]
+                            for value in values:
+                                rewritten = (
+                                    rewrite_url(
+                                        value,
+                                        target,
+                                        proxy.local_origin,
+                                        explicit_scheme=explicit_scheme,
+                                    )
+                                    if name == "Location"
+                                    else rewrite_refresh(
+                                        value,
+                                        target,
+                                        proxy.local_origin,
+                                        explicit_scheme=explicit_scheme,
+                                    )
+                                )
+                                response_headers.add(name, rewritten)
+                except ValueError:
+                    LOG.warning(
+                        "Unsupported or invalid navigation header from %s", origin
+                    )
+                    raise web.HTTPBadGateway(
+                        text="Unsupported or invalid upstream navigation target\n"
+                    ) from None
+                if upstream.status == 101:
+                    raise web.HTTPBadGateway(
+                        text="Upstream protocol upgrades are not supported\n"
+                    )
+                response = web.StreamResponse(
+                    status=upstream.status, headers=response_headers
+                )
+                await response.prepare(request)
+                async for chunk in upstream.content.iter_chunked(65536):
+                    await response.write(chunk)
+                await response.write_eof()
+                return response
+        except (ClientError, OSError, TimeoutError) as error:
+            LOG.warning("Upstream failure for %s (%s)", origin, type(error).__name__)
+            if response is not None and response.prepared:
+                if request.transport is not None:
+                    request.transport.close()
+                return response
+            if isinstance(error, TimeoutError):
+                raise web.HTTPGatewayTimeout(text="Upstream timed out\n") from None
+            raise web.HTTPBadGateway(text="Upstream connection failed\n") from None
+
+
+def filtered_headers(headers: CIMultiDict[str], *, request: bool) -> CIMultiDict[str]:
+    """Strip hop-by-hop headers and credentials while retaining duplicate fields."""
+    blocked = HOP_HEADERS | {"cookie", "set-cookie"}
+    if request:
+        blocked |= {"host", "authorization", TOKEN_HEADER.lower()}
+    for connection in headers.getall("Connection", []):
+        blocked.update(part.strip().lower() for part in connection.split(","))
+    return CIMultiDict(
+        (key, value) for key, value in headers.items() if key.lower() not in blocked
+    )
+
+
+async def _body_chunks(request: web.Request) -> AsyncIterator[bytes]:
+    async for chunk in request.content.iter_chunked(65536):
+        yield chunk
+
+
+REVERSE_PROXY_KEY = web.AppKey("reverse_proxy", ReverseProxy)

azure_dev_proxy/routers/utils.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import ipaddress
+import logging
+import re
+from dataclasses import dataclass
+from urllib.parse import unquote_plus, urljoin, urlsplit
+
+from aiohttp import web
+from yarl import URL
+
+from ..config import Config
+
+LOG = logging.getLogger("azure_dev_proxy.proxy")
+GRAPHQL_PREFIX = "/:graphiql/"
+
+
+@dataclass
+class ProxyCall:
+    """
+    Sanitized destination and token status for one request's log entry.
+
+    Attributes:
+        url: Destination URL with sensitive fields redacted.
+        token: Whether an Azure token was attached to the upstream request.
+        source: Token acquisition or local-response category.
+        logged: Whether the request's single log entry has already been emitted.
+    """
+
+    url: str
+    token: bool = False
+    source: str = "not-attempted"
+    logged: bool = False
+
+    def emit(self, method: str) -> None:
+        if not self.logged:
+            LOG.info(
+                "Proxy call url=%s method=%s token=%s source=%s",
+                self.url,
+                method,
+                "yes" if self.token else "no",
+                self.source,
+            )
+            self.logged = True
+
+
+CALL_KEY = web.RequestKey("proxy_call", ProxyCall)
+
+
+def validate_destination(request: web.Request, target: URL, *, port: int) -> ProxyCall:
+    """
+    Record a parsed destination and reject loops into the local proxy.
+
+    Args:
+        request: Request with its log context installed by the middleware.
+        target: Parsed HTTP(S) destination.
+        port: Local proxy listener port used to detect self-loops.
+
+    Returns:
+        The request's log context, updated with the sanitized destination.
+
+    Raises:
+        web.HTTPBadRequest: The destination loops back into the proxy.
+    """
+    call = request[CALL_KEY]
+    call.url = log_url(str(target))
+    host = target.host or ""
+    try:
+        loopback = ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        loopback = host == "localhost"
+    if loopback and target.port == port:
+        raise web.HTTPBadRequest(text="Destination loops back into this proxy\n")
+    return call
+
+
+def log_url(value: str) -> str:
+    base, separator, raw_query = value.partition("?")
+    query = []
+    for parameter in raw_query.split("&"):
+        key, equals, content = parameter.partition("=")
+        normalized = re.sub(r"[^a-z0-9]", "", unquote_plus(key).lower())
+        sensitive = any(
+            word in normalized for word in ("token", "secret", "password", "signature")
+        )
+        sensitive = sensitive or normalized in {
+            "key",
+            "apikey",
+            "sig",
+            "code",
+            "authorization",
+            "credential",
+        }
+        query.append(key + equals + ("REDACTED" if sensitive and equals else content))
+    value = base + separator + "&".join(query)
+    value = re.sub(r"(?<=/)[^/?]*@", "REDACTED@", value)
+    return "".join(
+        character
+        if ord(character) >= 32 and ord(character) != 127
+        else f"\\x{ord(character):02x}"
+        for character in value
+    )
+
+
+def parse_target(raw_path: str) -> URL:
+    """
+    Parse a proxy destination without re-encoding its path or query.
+
+    Args:
+        raw_path: Root-relative proxy path containing a bare hostname or an
+            explicit HTTP(S) URL. Bare destinations default to HTTPS.
+
+    Raises:
+        ValueError: The route contains an invalid authority, fragment or path.
+    """
+    route, separator, query = raw_path.partition("?")
+    if not route.startswith("/") or any(ord(c) < 32 or ord(c) == 127 for c in raw_path):
+        raise ValueError("Invalid proxy route")
+    route = route[1:]
+    scheme = "https"
+    if route[:8].lower() == "https://":
+        route = route[8:]
+    elif route[:7].lower() == "http://":
+        scheme = "http"
+        route = route[7:]
+    authority, _, path = route.partition("/")
+    authority = Config.normalize_authority(
+        authority, default_port=80 if scheme == "http" else 443
+    )
+    if "#" in raw_path or "\\" in path:
+        raise ValueError("Invalid upstream path")
+    return URL(
+        scheme
+        + "://"
+        + authority
+        + "/"
+        + path
+        + (separator + query if separator else ""),
+        encoded=True,
+    )
+
+
+def rewrite_url(
+    value: str,
+    upstream: URL,
+    local_origin: str,
+    *,
+    explicit_scheme: bool = False,
+) -> str:
+    """
+    Resolve upstream navigation through the proxy, retaining encoded URL fields.
+
+    Args:
+        value: Absolute or relative navigation URL from the upstream.
+        upstream: Destination URL against which relative references resolve.
+        local_origin: Proxy origin used for the rewritten navigation.
+        explicit_scheme: Include HTTPS explicitly rather than using a bare-host
+            proxy path. HTTP targets always include their scheme.
+
+    Raises:
+        ValueError: The navigation target is invalid or does not use HTTP(S).
+    """
+    if any(ord(c) < 32 or ord(c) == 127 for c in value) or "\\" in value:
+        raise ValueError("Invalid navigation URL")
+    target = urlsplit(urljoin(str(upstream), value))
+    if target.scheme not in {"http", "https"}:
+        raise ValueError("Only HTTP(S) navigation targets are supported")
+    authority = Config.normalize_authority(
+        target.netloc, default_port=80 if target.scheme == "http" else 443
+    )
+    scheme = target.scheme + "://" if explicit_scheme or target.scheme == "http" else ""
+    return (
+        local_origin
+        + "/"
+        + scheme
+        + authority
+        + (target.path or "/")
+        + ("?" + target.query if target.query else "")
+        + ("#" + target.fragment if target.fragment else "")
+    )
+
+
+def rewrite_refresh(
+    value: str,
+    upstream: URL,
+    local_origin: str,
+    *,
+    explicit_scheme: bool = False,
+) -> str:
+    """
+    Rewrite a Refresh header's optional navigation target through the proxy.
+
+    Args:
+        value: Upstream Refresh header with a delay and optional URL.
+        upstream: Destination URL against which relative references resolve.
+        local_origin: Proxy origin used for the rewritten navigation.
+        explicit_scheme: Include HTTPS explicitly, as in rewrite_url.
+
+    Raises:
+        ValueError: The header or its navigation target is invalid.
+    """
+    match = re.fullmatch(
+        r"\s*(\d+(?:\.\d+)?)\s*(?:;\s*url\s*=\s*(.*?)\s*)?", value, re.IGNORECASE
+    )
+    if not match:
+        raise ValueError("Invalid Refresh header")
+    delay, target = match.groups()
+    if target is None:
+        return delay
+    if target.startswith(("'", '"')):
+        if len(target) < 2 or target[-1] != target[0]:
+            raise ValueError("Invalid quoted Refresh target")
+        target = target[1:-1]
+    rewritten = rewrite_url(
+        target,
+        upstream,
+        local_origin,
+        explicit_scheme=explicit_scheme,
+    )
+    return f"{delay}; url={rewritten}"