@hummingbirdworks/proxy 0.2.1 → 0.3.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ps Hummingbird
+Copyright (c) 2026 Hummingbird
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,16 +2,13 @@
 
 A [mitmproxy](https://www.mitmproxy.org/)-based dev proxy that redirects
 Dataverse / Dynamics 365 **web resources** and **PCF control** assets to your
-local dev builds or a running dev server (e.g. Vite). This lets you iterate on
-web resources and PCF controls locally without deploying to the environment on
-every change.
+local dev builds or a running dev server (e.g. Vite), so you can iterate
+locally without deploying on every change.
 
 ## Prerequisites
 
-- **Node.js** >= 16 (to run the CLI).
-- **mitmproxy** installed and `mitmdump` available on your `PATH`
-  (Python 3.11+, for stdlib TOML support).
-  Install from <https://www.mitmproxy.org/> — e.g. `pipx install mitmproxy`.
+- **Node.js** >= 16.
+- **mitmproxy** — install from <https://www.mitmproxy.org/> — e.g. `pipx install mitmproxy`.
 
 ## Install and Configure
 
@@ -59,23 +56,30 @@ Optional keys on any rule:
 - `domain`: a host string, or an array of host strings. Omit for all hosts.
 - `disabled`: `true` to skip the rule.
 
-## Usage
-
-Run the proxy from the folder containing `proxy.config.toml`:
+### Combining several projects with `include`
 
-```sh
-npm run proxy
-```
+To proxy several projects against the same environment from one running proxy,
+`include` their configs instead of switching proxies as you navigate:
 
-Or point it at a specific config file:
+```toml
+[[rules]]
+type = "include"
+path = "../invoice-editor/proxy.config.toml"
 
-```sh
-npx hummingbird-proxy ./config/proxy.config.toml
+[[rules]]
+type = "include"
+# Use single quotes to support backslashes in absolute paths
+path = 'C:\Users\me\repos\myproject\proxy.config.toml'
 ```
 
-Any extra arguments are forwarded to `mitmdump` (e.g. change the port):
+## Usage
+
+Run the proxy from the folder containing `proxy.config.toml` (or pass a config
+path and any extra `mitmdump` args):
 
 ```sh
+npm run proxy
+# or a specific config, forwarding args to mitmdump (e.g. change the port)
 npx hummingbird-proxy ./proxy.config.toml -p 8888
 ```
 
@@ -89,42 +93,29 @@ chrome.exe --proxy-server="http://localhost:8080"
 
 ### First-time setup
 
-On first use, install the mitmproxy root certificate so HTTPS interception
-works: with the proxied browser open, visit <http://mitm.it/> and follow the
-instructions for your OS/browser.
+Install the mitmproxy root certificate so HTTPS interception works: with the
+proxied browser open, visit <http://mitm.it/> and follow the instructions.
 
 ### ⚠️ **Notes**
 
-- Chrome and Edge share a single background process across all windows. Either
-  close all Chrome/Edge windows before starting the proxy, or use a separate
-  profile for the proxied browser:
-
-  ```sh
-  msedge.exe --user-data-dir="%LOCALAPPDATA%\mitmproxy-browser-profile" --proxy-server="http://localhost:8080"
-  ```
-
-- Power Apps caches web resources and PCF controls in the browser. If changes
-  don't show up, force a full refresh (`Ctrl+Shift+R`). You may also need to
-  open DevTools → Application → Service Workers and check "Bypass for network"
-  to disable the service worker cache.
+- Chrome/Edge share one background process across windows. Close all
+  Chrome/Edge windows first, or use a separate profile:
+  `msedge.exe --user-data-dir="%LOCALAPPDATA%\mitmproxy-browser-profile" --proxy-server="http://localhost:8080"`
+- Power Apps caches assets in the browser. If changes don't show, hard refresh
+  (`Ctrl+Shift+R`); you may also need to bypass the service worker cache
+  (DevTools → Application → Service Workers → "Bypass for network").
 
 ## Using with Vite (HMR)
 
 A `devserver` rule routes a web resource's requests to a running Vite dev
-server, giving you hot module reload on the Dynamics-hosted page.
-
-The dev server can stay on plain HTTP — the browser only talks to the proxy, and
-the proxy relays requests (including the HMR websocket) to `localhost`. Because
-the Dynamics page is HTTPS, the browser would block an insecure `ws://` HMR
-socket as mixed content, so point the HMR client at `wss` and let the proxy
-forward it to the HTTP dev server. No dev-server cert (or `vite-plugin-mkcert`)
-is needed.
+server for hot module reload on the Dynamics-hosted page. The dev server stays
+on plain HTTP; the proxy relays everything (including the HMR websocket) to
+`localhost`, so no dev-server cert is needed.
 
 ### Vite config
 
-The package ships a Vite plugin that helps with the configuration of web resources. 
-It sets the base path, configures settings to support HMR with the proxy, and turns
-off cache busting since powerapps already has cache busting when you publish customizations.
+The package ships a Vite plugin that sets the base path, enables HMR through the
+proxy, and disables cache busting (Power Apps already busts caches on publish).
 
 ```ts
 import { defineConfig } from 'vite'
@@ -173,5 +164,4 @@ npm run proxy
 
 Open the Dynamics page hosting the web resource. Edit → save → the page updates
 without a manual refresh. If HMR doesn't trigger, confirm Vite's port matches
-the rule `url`, that the HMR socket connects over `wss`, and that the service
-worker cache is bypassed (see Notes above).
+the rule `url` and that the service worker cache is bypassed (see Notes above).

package/bin/hummingbird-proxy.js

@@ -95,15 +95,20 @@ function main() {
     return;
   }
 
-  // First non-flag argument is the config path; everything else is forwarded to mitmdump.
+  // Only the first token can be the config path, and only when it isn't a
+  // flag; everything else is forwarded to mitmdump so a flag's value (e.g. the
+  // `8888` in `-p 8888`) is never mistaken for the config path.
   let configArg;
-  const passthrough = [];
-  for (const arg of argv) {
-    if (configArg === undefined && !arg.startsWith("-")) {
-      configArg = arg;
-    } else {
-      passthrough.push(arg);
-    }
+  let passthrough;
+  if (argv.length > 0 && !argv[0].startsWith("-")) {
+    configArg = argv[0];
+    passthrough = argv.slice(1);
+  } else {
+    passthrough = argv.slice();
+  }
+  // Drop a leading `--` separator; the rest already goes to mitmdump.
+  if (passthrough[0] === "--") {
+    passthrough.shift();
   }
 
   const configPath = path.resolve(process.cwd(), configArg || DEFAULT_CONFIG);

package/hummingbird_proxy/__init__.py

@@ -0,0 +1,10 @@
+"""Dev proxy addon package for Dataverse / Dynamics 365 web resources and PCF controls.
+
+The mitmproxy entrypoint lives in ``powerapp_dev_proxy.py`` at the package root;
+it imports :class:`DataverseProxy` from here. See README.md for usage.
+"""
+
+from hummingbird_proxy.addon import DataverseProxy
+from hummingbird_proxy.config import config_path
+
+__all__ = ["DataverseProxy", "config_path"]

package/hummingbird_proxy/addon.py

@@ -0,0 +1,107 @@
+"""The mitmproxy addon: routes matching requests to local files or dev servers."""
+
+import asyncio
+import os
+
+from mitmproxy import ctx, http, tls
+
+from hummingbird_proxy import config, matching, serving
+from hummingbird_proxy.tls import start_dev_server_tls
+
+
+class DataverseProxy:
+    def __init__(self, config_path: str) -> None:
+        self.config_path = config_path
+        rules, self._config_paths = config.load_rules(config_path)
+        self.config = config.validate_config(rules)
+        self._config_mtimes = config.config_mtimes(self._config_paths)
+        self._watch_task: asyncio.Task | None = None
+
+    def running(self) -> None:
+        # Start watching the config files for changes once the event loop is up.
+        if self._watch_task is None:
+            self._watch_task = asyncio.ensure_future(self._watch_config())
+
+    def done(self) -> None:
+        if self._watch_task is not None:
+            self._watch_task.cancel()
+            self._watch_task = None
+
+    async def _watch_config(self) -> None:
+        while True:
+            await asyncio.sleep(config.CONFIG_POLL_INTERVAL)
+            mtimes = config.config_mtimes(self._config_paths)
+            if mtimes == self._config_mtimes:
+                continue
+            self._config_mtimes = mtimes
+            self._reload_config()
+
+    def _reload_config(self) -> None:
+        try:
+            rules, paths = config.load_rules(self.config_path)
+            new_config = config.validate_config(rules)
+        except (OSError, ValueError) as err:
+            ctx.log.warn(f"Config reload failed, keeping previous rules: {err}")
+            return
+        self.config = new_config
+        self._config_paths = paths
+        self._config_mtimes = config.config_mtimes(paths)
+        matching.clear_pcf_cache()
+        ctx.log.info(
+            f"Reloaded proxy config from {self.config_path} "
+            f"({len(new_config)} active rules across {len(paths)} files)"
+        )
+
+    def tls_start_server(self, data: tls.TlsData) -> None:
+        start_dev_server_tls(data)
+
+    def request(self, flow: http.HTTPFlow) -> None:
+        host = flow.request.pretty_host
+        web_resource = matching.web_resource_name(flow.request)
+
+        for item in self.config:
+            if not matching.domain_matches(item.get("domain"), host):
+                continue
+
+            item_type = item["type"]
+
+            if item_type == "devserver":
+                if web_resource is not None and web_resource.startswith(item["name"]):
+                    serving.proxy_to_dev_server(flow, item["url"], web_resource, item["name"])
+                    return
+
+            elif item_type == "single":
+                if web_resource == item["name"]:
+                    serving.serve_file(flow, item["file"], item_type, item["name"], item["_base_dir"])
+                    return
+
+            elif item_type == "folder":
+                if web_resource is not None and web_resource.startswith(item["name"]):
+                    relative = web_resource[len(item["name"]):]
+                    serving.serve_file(
+                        flow,
+                        os.path.join(item["folder"], *relative.split("/")),
+                        item_type,
+                        item["name"],
+                        item["_base_dir"],
+                        root=item["folder"],
+                    )
+                    return
+
+            elif item_type == "pcf":
+                hit = matching.pcf_match(flow.request.path, item["name"])
+                if hit is not None:
+                    relative, is_css = hit
+                    parts = [item["folder"]]
+                    if is_css:
+                        parts.append("css")
+                    parts.extend(segment for segment in relative.split("/") if segment)
+                    serving.serve_file(
+                        flow,
+                        os.path.join(*parts),
+                        item_type,
+                        item["name"],
+                        item["_base_dir"],
+                        root=item["folder"],
+                    )
+                    return

package/hummingbird_proxy/config.py

@@ -0,0 +1,147 @@
+"""Loading, validation and change-watching of the TOML proxy config."""
+
+import os
+import tomllib
+
+# type -> the set of keys an entry of that type must contain.
+_CONFIG_SCHEMA: dict[str, set[str]] = {
+    "single": {"name", "file"},
+    "folder": {"name", "folder"},
+    "devserver": {"name", "url"},
+    "pcf": {"name", "folder"},
+}
+_OPTIONAL_KEYS = {"type", "domain", "disabled"}
+
+# An "include" entry pulls in the rules from another config file. It is expanded
+# away at load time, so it never reaches validate_config / the request handler.
+_INCLUDE_KEYS = {"path"}
+_INCLUDE_OPTIONAL_KEYS = {"type", "disabled"}
+
+# Keys the loader attaches to each rule internally; not user-provided.
+_INTERNAL_KEYS = {"_base_dir"}
+
+# Safety net against pathological include nesting (cycles are caught separately).
+_MAX_INCLUDE_DEPTH = 20
+
+# How often (seconds) to poll the config files for changes.
+CONFIG_POLL_INTERVAL = 1.0
+
+
+def config_path() -> str:
+    """Absolute path of the TOML config file to load."""
+    override = os.environ.get("HUMMINGBIRD_PROXY_CONFIG")
+    if override:
+        return os.path.abspath(override)
+    return os.path.abspath(os.path.join(os.getcwd(), "proxy.config.toml"))
+
+
+def _load_config(path: str) -> list[dict]:
+    """Load and parse the TOML config file into a list of rule dicts."""
+    try:
+        with open(path, "rb") as handle:
+            data = tomllib.load(handle)
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"proxy config file not found: {path}. "
+            "Create a proxy.config.toml or set HUMMINGBIRD_PROXY_CONFIG."
+        )
+    except tomllib.TOMLDecodeError as err:
+        raise ValueError(f"invalid TOML in proxy config {path}: {err}")
+    rules = data.get("rules", [])
+    if not isinstance(rules, list):
+        raise ValueError("proxy config 'rules' must be an array of tables")
+    return rules
+
+
+def load_rules(path: str, _seen: frozenset[str] = frozenset(), _depth: int = 0) -> tuple[list[dict], set[str]]:
+    """Load rules from a config file, expanding any "include" entries.
+
+    Each returned rule carries a "_base_dir" key giving the directory its
+    relative paths resolve against, so rules pulled in from another config keep
+    resolving against that config's own location. Returns
+    (rules, config_paths) where config_paths is every config file touched, used
+    to watch them all for changes.
+    """
+    path = os.path.abspath(path)
+    if path in _seen:
+        raise ValueError(f"include cycle detected at config {path}")
+    if _depth > _MAX_INCLUDE_DEPTH:
+        raise ValueError(f"include nesting too deep (>{_MAX_INCLUDE_DEPTH}) at {path}")
+    _seen = _seen | {path}
+    base_dir = os.path.dirname(path)
+    rules: list[dict] = []
+    config_paths: set[str] = {path}
+
+    for index, item in enumerate(_load_config(path)):
+        if isinstance(item, dict) and item.get("type") == "include":
+            label = f"{path} include[{index}]"
+            missing = _INCLUDE_KEYS - item.keys()
+            if missing:
+                raise ValueError(f"{label}: missing keys {sorted(missing)}")
+            unknown = item.keys() - (_INCLUDE_KEYS | _INCLUDE_OPTIONAL_KEYS)
+            if unknown:
+                raise ValueError(f"{label}: unknown keys {sorted(unknown)}")
+            if item.get("disabled", False):
+                continue
+            target = item["path"]
+            if not os.path.isabs(target):
+                target = os.path.normpath(os.path.join(base_dir, target))
+            sub_rules, sub_paths = load_rules(target, _seen, _depth + 1)
+            rules.extend(sub_rules)
+            config_paths |= sub_paths
+        elif isinstance(item, dict):
+            rules.append({**item, "_base_dir": base_dir})
+        else:
+            rules.append(item)
+
+    return rules, config_paths
+
+
+def resolve_path(path: str, base_dir: str) -> str:
+    """Convert a path to absolute, relative to its config file's directory."""
+    if os.path.isabs(path):
+        return path
+    return os.path.normpath(os.path.join(base_dir, path))
+
+
+def validate_config(config: list[dict]) -> list[dict]:
+    """Validate CONFIG and return the entries that are not disabled."""
+    enabled: list[dict] = []
+    for index, item in enumerate(config):
+        label = f"CONFIG[{index}]"
+        if not isinstance(item, dict):
+            raise ValueError(f"{label}: expected a dict, got {type(item).__name__}")
+        item_type = item.get("type")
+        if item_type not in _CONFIG_SCHEMA:
+            raise ValueError(
+                f"{label}: unknown or missing 'type' {item_type!r}; "
+                f"expected one of {sorted(_CONFIG_SCHEMA)}"
+            )
+        required = _CONFIG_SCHEMA[item_type]
+        missing = required - item.keys()
+        if missing:
+            raise ValueError(f"{label} (type={item_type!r}): missing keys {sorted(missing)}")
+        unknown = item.keys() - (required | _OPTIONAL_KEYS | _INTERNAL_KEYS)
+        if unknown:
+            raise ValueError(f"{label} (type={item_type!r}): unknown keys {sorted(unknown)}")
+        # Prefix matching relies on a trailing slash to mark the name boundary,
+        # so normalize it rather than silently mismatching a sibling resource.
+        if item_type in ("folder", "devserver") and isinstance(item.get("name"), str):
+            if not item["name"].endswith("/"):
+                item["name"] += "/"
+        if not item.get("disabled", False):
+            enabled.append(item)
+    return enabled
+
+
+def _config_mtime(path: str) -> float | None:
+    """Modification time of the config file, or None if it is missing."""
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return None
+
+
+def config_mtimes(paths: set[str]) -> dict[str, float | None]:
+    """Modification times for every config file, keyed by path."""
+    return {path: _config_mtime(path) for path in paths}

package/hummingbird_proxy/matching.py

@@ -0,0 +1,55 @@
+"""URL matching helpers for web resource, PCF and domain rules."""
+
+import re
+
+from mitmproxy import http
+
+Domain = str | list[str] | None
+
+
+def domain_matches(domain: Domain, host: str) -> bool:
+    if domain is None:
+        return True
+    host = host.lower()
+    if isinstance(domain, str):
+        return host == domain.lower()
+    return any(host == d.lower() for d in domain)
+
+
+def web_resource_name(request: http.Request) -> str | None:
+    """Return the path following the ``webresources`` segment, or None."""
+    components = request.path_components
+    for i, component in enumerate(components):
+        if component.lower() == "webresources":
+            name = "/".join(components[i + 1:])
+            # path_components drops a trailing slash; keep it so dev-server root
+            # requests (e.g. the Vite HMR base URL) still match a rule prefix.
+            if name and request.path.split("?", 1)[0].endswith("/"):
+                name += "/"
+            return name
+    return None
+
+
+_pcf_patterns: dict[str, re.Pattern[str]] = {}
+
+
+def pcf_match(path: str, name: str) -> tuple[str, bool] | None:
+    """Match a PCF asset URL. Returns (relative asset path, is_css) or None."""
+    pattern = _pcf_patterns.get(name)
+    if pattern is None:
+        pattern = re.compile(
+            r"(?P<css>/css)?(?:/(?:cc_)?|cc_)"
+            + re.escape(name)
+            + r"(?:\.|/)(?P<rest>[^?]*)",
+            re.IGNORECASE,
+        )
+        _pcf_patterns[name] = pattern
+    match = pattern.search(path)
+    if match is None:
+        return None
+    return match.group("rest"), bool(match.group("css"))
+
+
+def clear_pcf_cache() -> None:
+    """Drop compiled PCF patterns; called when rules are reloaded."""
+    _pcf_patterns.clear()

package/hummingbird_proxy/serving.py

@@ -0,0 +1,89 @@
+"""Response builders: serve local files and relay to a dev server."""
+
+from urllib.parse import urlsplit
+
+import mimetypes
+import os
+
+from mitmproxy import ctx, http
+
+from hummingbird_proxy.config import resolve_path
+
+# Explicit types for common web assets; the OS mimetypes DB is unreliable here
+# (e.g. Windows maps .js to text/plain, which browsers refuse to execute).
+_CONTENT_TYPES = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".cjs": "text/javascript",
+    ".css": "text/css",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".json": "application/json",
+    ".map": "application/json",
+    ".svg": "image/svg+xml",
+    ".wasm": "application/wasm",
+}
+
+
+def _log_redirect(flow: http.HTTPFlow, rule_type: str, rule_name: str, destination: str) -> None:
+    ctx.log.info(
+        f"Redirected {flow.request.pretty_url} via {rule_type}:{rule_name} -> {destination}"
+    )
+
+
+def _is_within(root: str, path: str) -> bool:
+    """True if PATH is ROOT itself or nested under it (after normalization)."""
+    try:
+        return os.path.commonpath([root, path]) == root
+    except ValueError:
+        # Raised when the paths live on different drives (Windows).
+        return False
+
+
+def serve_file(
+    flow: http.HTTPFlow,
+    filepath: str,
+    rule_type: str,
+    rule_name: str,
+    base_dir: str,
+    root: str | None = None,
+) -> None:
+    absolute_path = resolve_path(filepath, base_dir)
+    if root is not None and not _is_within(resolve_path(root, base_dir), absolute_path):
+        ctx.log.warn(f"Blocked path traversal for {rule_type}:{rule_name} -> {absolute_path}")
+        flow.response = http.Response.make(
+            403,
+            b"dataverseproxy: path escapes the configured folder",
+            {"Content-Type": "text/plain"},
+        )
+        return
+    try:
+        with open(absolute_path, "rb") as handle:
+            content = handle.read()
+    except (FileNotFoundError, IsADirectoryError):
+        ctx.log.warn(f"Local file not found for {rule_type}:{rule_name} -> {absolute_path}")
+        flow.response = http.Response.make(
+            404,
+            f"dataverseproxy: local file not found: {absolute_path}".encode(),
+            {"Content-Type": "text/plain"},
+        )
+        return
+    ext = os.path.splitext(absolute_path)[1].lower()
+    content_type = (
+        _CONTENT_TYPES.get(ext) or mimetypes.guess_type(absolute_path)[0] or "application/octet-stream"
+    )
+    flow.response = http.Response.make(200, content, {"Content-Type": content_type})
+    _log_redirect(flow, rule_type, rule_name, absolute_path)
+
+
+def proxy_to_dev_server(flow: http.HTTPFlow, url: str, web_resource: str, rule_name: str) -> None:
+    target = urlsplit(url)
+    query = flow.request.path.split("?", 1)[1] if "?" in flow.request.path else ""
+    new_path = "/webresources/" + web_resource
+    if query:
+        new_path += "?" + query
+    flow.request.scheme = target.scheme
+    flow.request.host = target.hostname or "localhost"
+    flow.request.port = target.port or (443 if target.scheme == "https" else 80)
+    flow.request.path = new_path
+    _log_redirect(flow, "devserver", rule_name, f"{url}{new_path}")

package/hummingbird_proxy/tls.py

@@ -0,0 +1,52 @@
+"""TLS handling for upstream connections to local dev servers.
+
+Verification is skipped only for loopback dev servers (self-signed / mkcert
+certs); every real upstream keeps full certificate verification because the
+built-in TlsConfig addon handles any connection we leave untouched.
+"""
+
+import ipaddress
+
+from mitmproxy import connection, ctx, tls
+from mitmproxy.net import tls as net_tls
+from OpenSSL import SSL
+
+# Upstream hosts for which TLS verification is skipped.
+LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def start_dev_server_tls(data: tls.TlsData) -> None:
+    """Attach a no-verify TLS context when connecting to a loopback dev server.
+
+    Runs before the built-in TlsConfig addon; once ``data.ssl_conn`` is set,
+    TlsConfig skips the connection, so other upstreams keep full verification.
+    """
+    server = data.conn
+    if data.ssl_conn is not None or not isinstance(server, connection.Server):
+        return
+    if not server.address or server.address[0] not in LOOPBACK_HOSTS:
+        return
+
+    ssl_ctx = net_tls.create_proxy_server_context(
+        method=net_tls.Method.TLS_CLIENT_METHOD,
+        min_version=net_tls.Version[ctx.options.tls_version_server_min],
+        max_version=net_tls.Version[ctx.options.tls_version_server_max],
+        cipher_list=None,
+        ecdh_curve=None,
+        verify=net_tls.Verify.VERIFY_NONE,
+        ca_path=None,
+        ca_pemfile=None,
+        client_cert=None,
+        legacy_server_connect=False,
+    )
+    ssl_conn = SSL.Connection(ssl_ctx)
+    sni = server.sni or server.address[0]
+    try:
+        ipaddress.ip_address(sni)
+    except ValueError:
+        ssl_conn.set_tlsext_host_name(sni.encode("idna"))
+    alpn_offers = server.alpn_offers or data.context.client.alpn_offers
+    if alpn_offers:
+        ssl_conn.set_alpn_protos(list(alpn_offers))
+    ssl_conn.set_connect_state()
+    data.ssl_conn = ssl_conn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hummingbirdworks/proxy",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "mitmproxy-based dev proxy that redirects Dataverse / Dynamics 365 web resources and PCF control assets to local dev builds or a running dev server.",
   "bin": {
     "hummingbird-proxy": "bin/hummingbird-proxy.js"
@@ -12,9 +12,22 @@
     },
     "./package.json": "./package.json"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ps-Hummingbird/powerapps-mitm-proxy-addon.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ps-Hummingbird/powerapps-mitm-proxy-addon/issues"
+  },
+  "homepage": "https://github.com/ps-Hummingbird/powerapps-mitm-proxy-addon#readme",
+  "author": {
+    "name": "Hummingbird",
+    "url": "https://www.hummingbirdworks.ai/"
+  },
   "files": [
     "bin/",
     "vite/",
+    "hummingbird_proxy/",
     "powerapp_dev_proxy.py",
     "proxy.config.example.toml",
     "README.md"

package/powerapp_dev_proxy.py

@@ -1,457 +1,13 @@
 r"""
 mitmproxy addon that redirects Dataverse / Dynamics 365 web resources and PCF
-control assets to local dev builds or a running dev server.
+control assets to local dev builds or a running dev server. See README.md for
+setup and config usage.
 
-
---------------------------------------------------------------------------------
-First time setup:
-    1. Install mitmproxy: https://www.mitmproxy.org/  (e.g. `pipx install mitmproxy`)
-    2. Run `npx hummingbird-proxy` from the folder containing proxy.config.toml
-    3. Run `msedge.exe --proxy-server="http://localhost:8080"` or `chrome.exe --proxy-server="http://localhost:8080"`
-    4. Visit http://mitm.it/ in the new Chrome window and follow the instructions to install the mitmproxy root certificate.
---------------------------------------------------------------------------------
-Subsequent usage:
-    1. Run `npx hummingbird-proxy` from the folder containing proxy.config.toml
-    2. Run `msedge.exe --proxy-server="http://localhost:8080"` or `chrome.exe --proxy-server="http://localhost:8080"`
---------------------------------------------------------------------------------
-NOTE: Chrome and Edge run a single background process for all windows. 
-You need to either close all Chrome or Edge windows before starting the proxy, or use a separate user profile for the proxied browser.
-For example, run `msedge.exe --user-data-dir="%LOCALAPPDATA%\mitmproxy-browser-profile" --proxy-server="http://localhost:8080"` to use a separate profile.
---------------------------------------------------------------------------------
-NOTE: Power Apps will cache web resource and PCF controls in the browser. If you run into issues,
-try ctrl+shift+r to force a full refresh of the page and clear the cache. Sometimes you may need
-to open Chrome/Edge DevTools and open the Application tab, select "Service Workers" in the left menu, 
-and check "Bypass for network" to disable the service worker cache.
---------------------------------------------------------------------------------
-Config:
-
-Rules are loaded from a TOML config file. By default this is proxy.config.toml
-in the current working directory; the `hummingbird-proxy` CLI (or the
-HUMMINGBIRD_PROXY_CONFIG environment variable) can point at a different file.
-All relative file/folder paths in the config are resolved relative to the
-config file's own location, NOT this script.
-
-The config is a table with a "rules" array-of-tables. Each [[rules]] entry is
-one redirect. The config is validated at startup, so a malformed entry raises a
-clear error.
-
-Tip: use TOML single-quoted literal strings for Windows absolute paths so
-backslashes are not treated as escapes, e.g. folder = 'C:\Users\me\out'.
-
-Entry types:
-
-Redirect a folder of web resources to a local Vite dev server:
-    [[rules]]
-    type = "devserver"
-    name = "test_/bookings-editor/"
-    url = "https://localhost:5173"
-
-Redirect a single web resource file to a local file:
-    [[rules]]
-    type = "single"
-    name = "test_/ribbonscript/opportunity.js"
-    file = "./src/webresources/ribbonscript/opportunity.js"
-
-Redirect a folder of web resources to a local folder:
-    [[rules]]
-    type = "folder"
-    name = "test_/custom-app/"
-    folder = "./src/webresources/custom-app"
-
-Redirect a PCF control to its local build output folder:
-    [[rules]]
-    type = "pcf"
-    name = "test.BookingsEditor"
-    folder = "./bookings-editor/out/controls/BookingsEditor"
-
-Pull in the rules from another config file (so several projects can proxy the
-same Power Apps environment at once without switching proxies). Includes are
-resolved recursively; each included config's relative paths resolve against its
-own location, and every included file is watched for live reloads:
-    [[rules]]
-    type = "include"
-    path = "../bookings-editor/proxy.config.toml"
-
-Optional keys on any entry:
-"domain":   omit for all hosts, a host string, or an array of host strings
-"disabled": true to skip the entry
-
-Only redirect for a specific host:
-    [[rules]]
-    type = "single"
-    name = "test_/ribbonscript/opportunity-from-bom.js"
-    file = "./src/webresources/opportunity.js"
-    domain = "myorg.crm.dynamics.com"
---------------------------------------------------------------------------------
+mitmdump loads this file via ``-s``; its directory is placed on ``sys.path``
+during load, so the sibling ``hummingbird_proxy`` package resolves here. All
+implementation lives in that package; this module is just the entrypoint.
 """
 
-# ==============================================================================
-# Proxy engine. Redirect rules are loaded from the TOML config file described
-# in the docstring above; you generally shouldn't need to edit anything below.
-# ==============================================================================
-
-# Version 2026-08-20
-
-import asyncio
-import ipaddress
-import mimetypes
-import os
-import re
-import tomllib
-from urllib.parse import urlsplit
-
-from mitmproxy import connection, ctx, http, tls
-from mitmproxy.net import tls as net_tls
-from OpenSSL import SSL
-
-Domain = str | list[str] | None
-
-# TLS verification is skipped only for upstream connections to these loopback
-# hosts (local dev servers with self-signed / mkcert certs).
-LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
-
-# type -> the set of keys an entry of that type must contain.
-_CONFIG_SCHEMA: dict[str, set[str]] = {
-    "single": {"name", "file"},
-    "folder": {"name", "folder"},
-    "devserver": {"name", "url"},
-    "pcf": {"name", "folder"},
-}
-_OPTIONAL_KEYS = {"type", "domain", "disabled"}
-
-# An "include" entry pulls in the rules from another config file. It is expanded
-# away at load time, so it never reaches _validate_config / the request handler.
-_INCLUDE_KEYS = {"path"}
-_INCLUDE_OPTIONAL_KEYS = {"type", "disabled"}
-
-# Keys the loader attaches to each rule internally; not user-provided.
-_INTERNAL_KEYS = {"_base_dir"}
-
-# Safety net against pathological include nesting (cycles are caught separately).
-_MAX_INCLUDE_DEPTH = 20
-
-
-def _config_path() -> str:
-    """Absolute path of the TOML config file to load."""
-    override = os.environ.get("HUMMINGBIRD_PROXY_CONFIG")
-    if override:
-        return os.path.abspath(override)
-    return os.path.abspath(os.path.join(os.getcwd(), "proxy.config.toml"))
-
-
-def _load_config(path: str) -> list[dict]:
-    """Load and parse the TOML config file into a list of rule dicts."""
-    try:
-        with open(path, "rb") as handle:
-            data = tomllib.load(handle)
-    except FileNotFoundError:
-        raise FileNotFoundError(
-            f"proxy config file not found: {path}. "
-            "Create a proxy.config.toml or set HUMMINGBIRD_PROXY_CONFIG."
-        )
-    except tomllib.TOMLDecodeError as err:
-        raise ValueError(f"invalid TOML in proxy config {path}: {err}")
-    rules = data.get("rules", [])
-    if not isinstance(rules, list):
-        raise ValueError("proxy config 'rules' must be an array of tables")
-    return rules
-
-
-def _load_rules(path: str, _seen: frozenset[str] = frozenset(), _depth: int = 0) -> tuple[list[dict], set[str]]:
-    """Load rules from a config file, expanding any "include" entries.
-
-    Each returned rule carries a "_base_dir" key giving the directory its
-    relative paths resolve against, so rules pulled in from another config keep
-    resolving against that config's own location. Returns
-    (rules, config_paths) where config_paths is every config file touched, used
-    to watch them all for changes.
-    """
-    path = os.path.abspath(path)
-    if path in _seen:
-        raise ValueError(f"include cycle detected at config {path}")
-    if _depth > _MAX_INCLUDE_DEPTH:
-        raise ValueError(f"include nesting too deep (>{_MAX_INCLUDE_DEPTH}) at {path}")
-    _seen = _seen | {path}
-    base_dir = os.path.dirname(path)
-    rules: list[dict] = []
-    config_paths: set[str] = {path}
-
-    for index, item in enumerate(_load_config(path)):
-        if isinstance(item, dict) and item.get("type") == "include":
-            label = f"{path} include[{index}]"
-            missing = _INCLUDE_KEYS - item.keys()
-            if missing:
-                raise ValueError(f"{label}: missing keys {sorted(missing)}")
-            unknown = item.keys() - (_INCLUDE_KEYS | _INCLUDE_OPTIONAL_KEYS)
-            if unknown:
-                raise ValueError(f"{label}: unknown keys {sorted(unknown)}")
-            if item.get("disabled", False):
-                continue
-            target = item["path"]
-            if not os.path.isabs(target):
-                target = os.path.normpath(os.path.join(base_dir, target))
-            sub_rules, sub_paths = _load_rules(target, _seen, _depth + 1)
-            rules.extend(sub_rules)
-            config_paths |= sub_paths
-        elif isinstance(item, dict):
-            rules.append({**item, "_base_dir": base_dir})
-        else:
-            rules.append(item)
-
-    return rules, config_paths
-
-
-def _resolve_path(path: str, base_dir: str) -> str:
-    """Convert a path to absolute, relative to its config file's directory."""
-    if os.path.isabs(path):
-        return path
-    return os.path.normpath(os.path.join(base_dir, path))
-
-
-def _validate_config(config: list[dict]) -> list[dict]:
-    """Validate CONFIG and return the entries that are not disabled."""
-    enabled: list[dict] = []
-    for index, item in enumerate(config):
-        label = f"CONFIG[{index}]"
-        if not isinstance(item, dict):
-            raise ValueError(f"{label}: expected a dict, got {type(item).__name__}")
-        item_type = item.get("type")
-        if item_type not in _CONFIG_SCHEMA:
-            raise ValueError(
-                f"{label}: unknown or missing 'type' {item_type!r}; "
-                f"expected one of {sorted(_CONFIG_SCHEMA)}"
-            )
-        required = _CONFIG_SCHEMA[item_type]
-        missing = required - item.keys()
-        if missing:
-            raise ValueError(f"{label} (type={item_type!r}): missing keys {sorted(missing)}")
-        unknown = item.keys() - (required | _OPTIONAL_KEYS | _INTERNAL_KEYS)
-        if unknown:
-            raise ValueError(f"{label} (type={item_type!r}): unknown keys {sorted(unknown)}")
-        if not item.get("disabled", False):
-            enabled.append(item)
-    return enabled
-
-
-def _domain_matches(domain: Domain, host: str) -> bool:
-    if domain is None:
-        return True
-    host = host.lower()
-    if isinstance(domain, str):
-        return host == domain.lower()
-    return any(host == d.lower() for d in domain)
-
-
-def _web_resource_name(request: http.Request) -> str | None:
-    """Return the path following the ``webresources`` segment, or None."""
-    components = request.path_components
-    for i, component in enumerate(components):
-        if component.lower() == "webresources":
-            name = "/".join(components[i + 1:])
-            # path_components drops a trailing slash; keep it so dev-server root
-            # requests (e.g. the Vite HMR base URL) still match a rule prefix.
-            if name and request.path.split("?", 1)[0].endswith("/"):
-                name += "/"
-            return name
-    return None
-
-
-_pcf_patterns: dict[str, re.Pattern[str]] = {}
-
-
-def _pcf_match(path: str, name: str) -> tuple[str, bool] | None:
-    """Match a PCF asset URL. Returns (relative asset path, is_css) or None."""
-    pattern = _pcf_patterns.get(name)
-    if pattern is None:
-        pattern = re.compile(
-            r"(?P<css>/css)?(?:/(?:cc_)?|cc_)"
-            + re.escape(name)
-            + r"(?:\.|/)(?P<rest>[^?]*)",
-            re.IGNORECASE,
-        )
-        _pcf_patterns[name] = pattern
-    match = pattern.search(path)
-    if match is None:
-        return None
-    return match.group("rest"), bool(match.group("css"))
-
-
-def _log_redirect(flow: http.HTTPFlow, rule_type: str, rule_name: str, destination: str) -> None:
-    ctx.log.info(
-        f"Redirected {flow.request.pretty_url} via {rule_type}:{rule_name} -> {destination}"
-    )
-
-
-def _serve_file(flow: http.HTTPFlow, filepath: str, rule_type: str, rule_name: str, base_dir: str) -> None:
-    absolute_path = _resolve_path(filepath, base_dir)
-    try:
-        with open(absolute_path, "rb") as handle:
-            content = handle.read()
-    except (FileNotFoundError, IsADirectoryError):
-        ctx.log.warn(f"Local file not found for {rule_type}:{rule_name} -> {absolute_path}")
-        flow.response = http.Response.make(
-            404,
-            f"dataverseproxy: local file not found: {absolute_path}".encode(),
-            {"Content-Type": "text/plain"},
-        )
-        return
-    content_type = mimetypes.guess_type(absolute_path)[0] or "application/octet-stream"
-    flow.response = http.Response.make(200, content, {"Content-Type": content_type})
-    _log_redirect(flow, rule_type, rule_name, absolute_path)
-
-
-def _proxy_to_dev_server(flow: http.HTTPFlow, url: str, web_resource: str, rule_name: str) -> None:
-    target = urlsplit(url)
-    query = flow.request.path.split("?", 1)[1] if "?" in flow.request.path else ""
-    new_path = "/webresources/" + web_resource
-    if query:
-        new_path += "?" + query
-    flow.request.scheme = target.scheme
-    flow.request.host = target.hostname or "localhost"
-    flow.request.port = target.port or (443 if target.scheme == "https" else 80)
-    flow.request.path = new_path
-    _log_redirect(flow, "devserver", rule_name, f"{url}{new_path}")
-
-
-# How often (seconds) to poll the config file for changes.
-_CONFIG_POLL_INTERVAL = 1.0
-
-
-def _config_mtime(path: str) -> float | None:
-    """Modification time of the config file, or None if it is missing."""
-    try:
-        return os.path.getmtime(path)
-    except OSError:
-        return None
-
-
-def _config_mtimes(paths: set[str]) -> dict[str, float | None]:
-    """Modification times for every config file, keyed by path."""
-    return {path: _config_mtime(path) for path in paths}
-
-
-class DataverseProxy:
-    def __init__(self, config_path: str) -> None:
-        self.config_path = config_path
-        rules, self._config_paths = _load_rules(config_path)
-        self.config = _validate_config(rules)
-        self._config_mtimes = _config_mtimes(self._config_paths)
-        self._watch_task: asyncio.Task | None = None
-
-    def running(self) -> None:
-        # Start watching the config files for changes once the event loop is up.
-        if self._watch_task is None:
-            self._watch_task = asyncio.ensure_future(self._watch_config())
-
-    def done(self) -> None:
-        if self._watch_task is not None:
-            self._watch_task.cancel()
-            self._watch_task = None
-
-    async def _watch_config(self) -> None:
-        while True:
-            await asyncio.sleep(_CONFIG_POLL_INTERVAL)
-            mtimes = _config_mtimes(self._config_paths)
-            if mtimes == self._config_mtimes:
-                continue
-            self._config_mtimes = mtimes
-            self._reload_config()
-
-    def _reload_config(self) -> None:
-        try:
-            rules, paths = _load_rules(self.config_path)
-            config = _validate_config(rules)
-        except (OSError, ValueError) as err:
-            ctx.log.warn(f"Config reload failed, keeping previous rules: {err}")
-            return
-        self.config = config
-        self._config_paths = paths
-        self._config_mtimes = _config_mtimes(paths)
-        _pcf_patterns.clear()
-        ctx.log.info(
-            f"Reloaded proxy config from {self.config_path} "
-            f"({len(config)} active rules across {len(paths)} files)"
-        )
-
-    def tls_start_server(self, data: tls.TlsData) -> None:
-        # Provide a no-verify TLS context for localhost dev servers only. This runs
-        # before the built-in TlsConfig addon; once data.ssl_conn is set, TlsConfig
-        # skips the connection, so every other (real) upstream keeps full
-        # certificate verification.
-        server = data.conn
-        if data.ssl_conn is not None or not isinstance(server, connection.Server):
-            return
-        if not server.address or server.address[0] not in LOOPBACK_HOSTS:
-            return
-
-        ssl_ctx = net_tls.create_proxy_server_context(
-            method=net_tls.Method.TLS_CLIENT_METHOD,
-            min_version=net_tls.Version[ctx.options.tls_version_server_min],
-            max_version=net_tls.Version[ctx.options.tls_version_server_max],
-            cipher_list=None,
-            ecdh_curve=None,
-            verify=net_tls.Verify.VERIFY_NONE,
-            ca_path=None,
-            ca_pemfile=None,
-            client_cert=None,
-            legacy_server_connect=False,
-        )
-        ssl_conn = SSL.Connection(ssl_ctx)
-        sni = server.sni or server.address[0]
-        try:
-            ipaddress.ip_address(sni)
-        except ValueError:
-            ssl_conn.set_tlsext_host_name(sni.encode("idna"))
-        alpn_offers = server.alpn_offers or data.context.client.alpn_offers
-        if alpn_offers:
-            ssl_conn.set_alpn_protos(list(alpn_offers))
-        ssl_conn.set_connect_state()
-        data.ssl_conn = ssl_conn
-
-    def request(self, flow: http.HTTPFlow) -> None:
-        host = flow.request.pretty_host
-        web_resource = _web_resource_name(flow.request)
-
-        for item in self.config:
-            if not _domain_matches(item.get("domain"), host):
-                continue
-
-            item_type = item["type"]
-
-            if item_type == "devserver":
-                if web_resource is not None and web_resource.startswith(item["name"]):
-                    _proxy_to_dev_server(flow, item["url"], web_resource, item["name"])
-                    return
-
-            elif item_type == "single":
-                if web_resource == item["name"]:
-                    _serve_file(flow, item["file"], item_type, item["name"], item["_base_dir"])
-                    return
-
-            elif item_type == "folder":
-                if web_resource is not None and web_resource.startswith(item["name"]):
-                    relative = web_resource[len(item["name"]):]
-                    _serve_file(
-                        flow,
-                        os.path.join(item["folder"], *relative.split("/")),
-                        item_type,
-                        item["name"],
-                        item["_base_dir"],
-                    )
-                    return
-
-            elif item_type == "pcf":
-                hit = _pcf_match(flow.request.path, item["name"])
-                if hit is not None:
-                    relative, is_css = hit
-                    parts = [item["folder"]]
-                    if is_css:
-                        parts.append("css")
-                    parts.extend(segment for segment in relative.split("/") if segment)
-                    _serve_file(flow, os.path.join(*parts), item_type, item["name"], item["_base_dir"])
-                    return
-
-
-CONFIG_PATH = _config_path()
+from hummingbird_proxy import DataverseProxy, config_path
 
-addons = [DataverseProxy(CONFIG_PATH)]
+addons = [DataverseProxy(config_path())]

package/proxy.config.example.toml

@@ -25,3 +25,10 @@ domain = "myorg.crm.dynamics.com"
 type = "pcf"
 name = "test.BookingsEditor"
 folder = "./bookings-editor/out/controls/BookingsEditor"
+
+# Pull in the rules from another project's config so several projects can proxy
+# the same Power Apps environment at once. The included config's relative paths
+# resolve against its own location, and it is watched for live reloads too.
+[[rules]]
+type = "include"
+path = "../bookings-editor/proxy.config.toml"