azure-dev-proxy 0.1.0__tar.gz

azure_dev_proxy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish tagged releases to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    uses: ./.github/workflows/tests.yml
+
+  build:
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Check release version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected:
+              raise SystemExit(f"Release tag must be {expected}")
+          PY
+      - name: Install Hatch
+        run: python -m pip install hatch
+      - name: Build distributions
+        run: hatch build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v6
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/azure-dev-proxy
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v6
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

azure_dev_proxy-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Run tests
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Hatch
+        run: python -m pip install hatch
+      - name: Run tests and lint
+        run: hatch run tests

azure_dev_proxy-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml

azure_dev_proxy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Wardrop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

azure_dev_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: azure-dev-proxy
+Version: 0.1.0
+Summary: Loopback HTTP(S) proxy with HTTPS-only Azure CLI authentication
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.14
+Requires-Dist: idna<4,>=3.7

azure_dev_proxy-0.1.0/README.md

@@ -0,0 +1,258 @@
+# Azure Dev Proxy
+
+A reverse proxy that allows you to open APIs or webpages using your existing
+Azure CLI sign-in. It forwards requests through a local loopback endpoint and
+injects `Authorization: Bearer` tokens for configured HTTPS destinations.
+
+The browser UI provides URL navigation, host-to-token-audience mappings, and
+GraphiQL. Command-line clients use the same forwarding routes. HTTP destinations
+are supported, but never receive an Azure token.
+
+## Get started
+
+You need Python 3.11 or newer and Azure CLI available as `az` on your path.
+Install from PyPI, sign in, and start the proxy as a non-root user:
+
+```sh
+python -m pip install azure-dev-proxy
+az login
+azure-dev-proxy
+```
+
+The proxy listens on loopback interfaces at port 8080, not on the local network.
+Shared-key authentication protects access to the proxy separately from upstream
+Azure authentication. On first use, it creates an `auth-token` file beside its
+configuration and reuses the key across restarts.
+
+### Browser
+
+1. Open a ready-to-use URL from the startup logs, or visit
+   `http://localhost:8080/` and enter the key.
+2. Add a [host mapping](#configure-host-mappings) if your service is not covered
+   by the defaults.
+3. Paste the destination URL and select **Open URL**.
+
+### curl
+
+With the proxy running, open another terminal. In a POSIX shell, replace
+`/path/to/auth-token` with the key-file path printed at startup and send a GET
+request:
+
+```sh
+PROXY_KEY=$(cat /path/to/auth-token)
+
+curl --fail-with-body \
+  -H "X-Azure-Dev-Proxy-Token: $PROXY_KEY" \
+  "http://127.0.0.1:8080/https://api.example.com/path"
+```
+
+To POST JSON:
+
+```sh
+curl --fail-with-body \
+  -H "X-Azure-Dev-Proxy-Token: $PROXY_KEY" \
+  -H "Content-Type: application/json" \
+  --data '{"name":"example"}' \
+  "http://127.0.0.1:8080/https://api.example.com/items"
+```
+
+Replace the example URLs with your API and configure a matching host mapping
+if it needs an Azure token. If you use `--config` or `--token-file`, read the
+key file shown at startup instead.
+
+The header authenticates to the local proxy; the host mapping selects the
+upstream bearer token. Embed the destination URL in the request path rather
+than using `curl --proxy`. Use `127.0.0.1` to avoid the `localhost` redirect.
+
+> [!WARNING]
+> **Keep the proxy key and startup logs private.** Startup URLs intentionally
+> include the key for convenient sign-in. Anyone with the key and access to the
+> local listener can use your Azure identity through the proxy. Keys can also
+> appear in browser history, command traces, or process listings. The proxy does
+> not isolate malicious applications running as your own user.
+
+## Configure host mappings
+
+A host mapping allowlists an HTTPS destination for token injection and selects
+the token resource, or audience, requested through Azure CLI. Use the audience
+required by the API; it may differ from the API's URL.
+
+On `localhost`, expand **Host mappings and temporary overrides**, enter a
+hostname and resource, and select **Save temporary override**. A blank resource
+uses the destination's HTTPS origin.
+
+Temporary rules apply immediately and disappear on process exit. **Save to
+persisted** writes a rule to the configuration file; **Delete persisted**
+removes a saved rule. Persisted edits require a writable file and apply without
+a restart. Failed writes leave the active rules unchanged.
+
+Alternatively, supply JSON:
+
+```json
+{
+  "token_rules": [
+    {"host": "api.example.com", "resource": "https://identity.example.com"},
+    {"host": "*.example.org"}
+  ],
+  "trusted_origins": []
+}
+```
+
+```sh
+azure-dev-proxy --config ./config.json
+azure-dev-proxy --config ./config.json --check-config
+```
+
+Replace the placeholder domains with your service settings. Exact hosts take
+priority over wildcards; the longest wildcard suffix wins. Wildcards match
+subdomains, not the bare domain. A missing or `null` resource uses the
+destination's HTTPS origin. Unmatched hosts are forwarded without an Azure
+token. Temporary overrides take priority over persisted rules.
+
+Configuration uses the native per-user directory:
+
+| Platform | Default configuration file |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/azure-dev-proxy/config.json`, or `~/.config/azure-dev-proxy/config.json` when unset. |
+| Windows | `%APPDATA%\azure-dev-proxy\config.json`, or `~\AppData\Roaming\azure-dev-proxy\config.json` when unset. |
+| macOS | `~/Library/Application Support/azure-dev-proxy/config.json` |
+
+The generated `auth-token` lives beside the configuration unless `--token-file`
+is supplied. `XDG_CONFIG_HOME` applies only on Linux and other non-Windows,
+non-macOS platforms. Missing files receive bundled defaults; existing files
+define the complete rule list and are never merged with updated defaults.
+
+On Windows and macOS, existing files under `~/.config` are not moved
+automatically. Use `--config` with the old path to retain those settings and
+the adjacent key, or move both files to the native directory.
+
+### Bundled mappings
+
+The [default configuration](azure_dev_proxy/default-config.json) includes
+public-cloud mappings for management, storage, secrets, messaging, analytics,
+AI, monitoring, and productivity APIs. It is a curated allowlist, not a
+wildcard for every Azure-hosted service. Your signed-in user still needs the
+service's permissions and consent; supply any additional API-required headers.
+
+Event Hubs and Service Bus share `*.servicebus.windows.net` but require
+different audiences. The default selects Service Bus. For Event Hubs, add an
+exact hostname override with resource `https://eventhubs.azure.net`.
+
+## Forwarding and GraphQL
+
+Forwarding routes embed the upstream URL in the local path:
+
+```text
+http://127.0.0.1:8080/https://api.example.com/path
+http://127.0.0.1:8080/http://localhost:4000/path
+```
+
+The URL-entry page defaults to HTTPS when the scheme is omitted. Forwarding
+routes on `localhost` redirect to `127.0.0.1`, separating upstream pages from
+the configuration editor. Only `localhost` permits configuration edits;
+IP-loopback origins expose read-only mappings.
+
+For GraphiQL, open:
+
+```text
+http://localhost:8080/:graphiql/https://api.example.com/graphql
+```
+
+### Browser applications
+
+To permit cross-origin forwarding from a local application, add its exact
+origin to `trusted_origins`, for example `["http://localhost:3000"]`. Include
+nondefault ports; paths, wildcards, and opaque (`null`) origins are rejected.
+Only trusted origins receive forwarding CORS headers.
+
+The application must also authenticate with `X-Azure-Dev-Proxy-Token`; origin
+trust does not replace authentication or enable cross-site session cookies.
+By default, only the proxy's own loopback origins are trusted.
+
+**Trust only applications and forwarded pages that may use your Azure
+identity.** Forwarded pages share the IP-loopback origin; host mappings do not
+isolate those pages from one another.
+
+## Security and sessions
+
+Azure tokens are injected only for mapped HTTPS destinations. Redirects are
+evaluated independently, and HTTP forwarding is always anonymous. Caller
+`Authorization` headers, cookies, and proxy credentials are stripped upstream.
+Request and response bodies are streamed without automatic decompression.
+
+Browser-origin checks run before forwarding or token acquisition. Configuration
+mutations additionally require same-origin access and an anti-CSRF token.
+Browsers must support Fetch Metadata. Clients without browser provenance
+headers are treated as CLI clients but still require proxy authentication.
+
+The reserved `azure-dev-proxy-token=KEY` query parameter also authenticates
+requests and establishes a session. It is stripped before forwarding.
+Browser navigations redirect to a key-free URL; API requests receive their
+response directly. Other query parameters retain their encoding and order.
+
+Sessions use HttpOnly, SameSite=Lax, host-only cookies. A short-lived, single-use
+handoff pairs sessions across `localhost` and `127.0.0.1`. Sessions can survive
+restarts with the same key and port; rotate the key and restart to invalidate
+them.
+
+On POSIX, the key must be a regular file owned by the current user with no
+group or other permissions. Symlinks are rejected, and validation and reading
+use the same file descriptor to prevent pathname-replacement races. On Windows,
+protect the containing directory's inherited permissions. Request logs omit
+the reserved key parameter; startup logs intentionally include it.
+
+## Runtime options
+
+| Option | Purpose |
+|---|---|
+| `--port 8080` | Set the loopback port. |
+| `--az-path /path/to/az` | Select the Azure CLI executable; defaults to `az` on `PATH`. |
+| `--config FILE` | Select a JSON configuration file. |
+| `--check-config` | Validate configuration without listening; creates defaults if missing. |
+| `--idle-timeout 300` | Exit after five idle minutes; default `0` disables idle shutdown. |
+| `--token-file FILE` | Select a protected key file. |
+| `--token KEY` | Supply the proxy key directly. |
+| `--no-auth` | Disable proxy authentication and key-file creation. |
+
+`AZURE_DEV_PROXY_TOKEN` also supplies a key; explicit `--token` or
+`--token-file` options take precedence. **With `--no-auth`, other local users
+and applications can use the proxy without a key.**
+
+Active requests and streams prevent idle shutdown; open pages and unused
+keep-alive connections do not. Temporary rules and acquired tokens are
+memory-only.
+
+Systemd socket activation accepts one or two loopback TCP listeners through
+`LISTEN_PID` and `LISTEN_FDS`; their ports must match `--port`. Otherwise, the
+proxy binds IPv4 and available IPv6 loopback interfaces.
+
+## Development
+
+From a local checkout:
+
+```sh
+python -m pip install -e .
+```
+
+Install [Hatch](https://hatch.pypa.io/latest/install/), then run:
+
+```sh
+hatch run tests
+hatch run format
+hatch build
+```
+
+`tests` runs pytest with a 100% Python line-and-branch coverage gate, including
+CLI subprocesses, followed by Ruff lint and format checks and ty type checking.
+`format` applies Ruff fixes and formatting. For a focused run, use
+`hatch run unit-test -k token -v`.
+
+Use `hatch run coverage` for the coverage report alone. While adding tests,
+`hatch run coverage --cov-fail-under=0` reports remaining gaps without enforcing
+the gate. Add `--cov-report=html` for a browsable report in `htmlcov/`.
+
+The import namespace is `azure_dev_proxy`. Configuration, authentication, token
+acquisition, and listeners are separate modules. `Proxy` loads configuration,
+initializes the token provider and local authentication, and owns the aiohttp
+application and lifecycle, with routes in `azure_dev_proxy.routers`. Callers
+can also supply configuration, a token provider, or authentication explicitly.

azure_dev_proxy-0.1.0/azure_dev_proxy/__init__.py

@@ -0,0 +1 @@
+"""Local Azure-authenticated HTTPS reverse proxy."""

azure_dev_proxy-0.1.0/azure_dev_proxy/__main__.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from pathlib import Path
+
+from .config import Config
+from .proxy import Proxy
+
+
+def port_number(value: str) -> int:
+    try:
+        port = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("Port must be an integer") from error
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("Port must be between 1 and 65535")
+    return port
+
+
+def main() -> None:
+    """
+    Run the loopback proxy or validate its configuration without listening.
+
+    POSIX supports inherited systemd listeners; otherwise the service binds its
+    own loopback sockets. Windows uses direct listeners and native signal handling.
+    """
+    parser = argparse.ArgumentParser(
+        prog="azure-dev-proxy",
+        description="Local HTTP(S) proxy with HTTPS-only Azure CLI tokens",
+    )
+    parser.add_argument("--version", action="version", version="azure-dev-proxy 0.1.0")
+    parser.add_argument(
+        "--port", type=port_number, default=8080, help="Loopback port (default: 8080)"
+    )
+    parser.add_argument(
+        "--az-path",
+        default="az",
+        help="Azure CLI executable path (default: az on PATH)",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        help="JSON configuration (default: the user's azure-dev-proxy/config.json)",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=idle_seconds,
+        default=0,
+        help="Opt-in idle shutdown seconds (default: 0, disabled)",
+    )
+    auth = parser.add_mutually_exclusive_group()
+    auth.add_argument(
+        "--token", help="Proxy authentication key (or AZURE_DEV_PROXY_TOKEN)"
+    )
+    auth.add_argument(
+        "--token-file",
+        type=Path,
+        help="Saved key file (default: auth-token beside the configuration)",
+    )
+    auth.add_argument(
+        "--no-auth", action="store_true", help="Disable proxy authentication"
+    )
+    parser.add_argument(
+        "--check-config",
+        action="store_true",
+        help="Validate configuration and exit without listening",
+    )
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    try:
+        if not args.check_config and hasattr(os, "geteuid") and os.geteuid() == 0:
+            raise ValueError("Run azure-dev-proxy as a non-root user")
+        if args.check_config:
+            Config.load(
+                args.config if args.config is not None else Config.default_path()
+            )
+            return
+        proxy = Proxy(
+            config_path=args.config,
+            az_path=args.az_path,
+            token=args.token,
+            token_file=args.token_file,
+            no_auth=args.no_auth,
+        )
+        proxy.serve(args.port, idle_timeout=args.idle_timeout)
+    except (OSError, ValueError, RuntimeError) as error:
+        parser.exit(1, f"Could not start azure-dev-proxy: {error}\n")
+
+
+def idle_seconds(value: str) -> int:
+    """Parse nonnegative idle seconds; zero disables automatic shutdown."""
+    try:
+        seconds = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError("Idle timeout must be an integer") from None
+    if seconds < 0:
+        raise argparse.ArgumentTypeError("Idle timeout must be nonnegative")
+    return seconds
+
+
+if __name__ == "__main__":
+    main()