snulbug 0.2.4__tar.gz → 0.2.6__tar.gz

{snulbug-0.2.4 → snulbug-0.2.6}/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on Keep a Changelog, and this project follows semantic versi
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-24
+
+Trusted internal lease selection and gateway credential-boundary hardening.
+
+- Add trusted, request-local Python/ASGI lease-ID selection for embedding gateways, reusing identity bindings, expiry/revocation checks, policy previews, and atomic call budgets. Reject conflicting selections without recovering or injecting lease credentials.
+- Consume lease credential headers at the upstream boundary, including custom header names, facade transport plugins, and streamed HTTP requests. Include configured custom lease-header names in replay/audit redaction.
+- Validate supplied selections on facade discovery without consuming calls, and reject lease denials on bodyless HTTP stream opens before forwarding.
+- Require certifi 2026.10.19 or later and update the lockfile to remove compromised emSign CA trust roots ([GHSA-6q48-6c7w-9gw2](https://github.com/advisories/GHSA-6q48-6c7w-9gw2)).
+
+Upgrade note: public clients continue to send their existing lease headers, but
+upstream applications no longer receive them. Keep lease enforcement at the
+gateway; embedding hosts must independently authorize any internally selected
+lease reference. No change to renewal/expiry configuration or MCP protocol defaults.
+See the [trusted selection integration guide](docs/mcp-proxy.md#trusted-internal-lease-selection).
+
+## [0.2.5] - 2026-10-23
+
+Public-origin preservation for shared MCP and HTTP gateways.
+Read the [0.2.5 upgrade notes](docs/upgrading-to-0.2.5.md) before deploying an
+existing ngrok share or a share with required signed HTTP mount contracts.
+
+- Forward canonical public host, scheme, and port from the configured share URL across internal hops. HTTP mounts can opt into `preserve_host = true`; backend Host remains the default and upstream TLS verification is unchanged.
+- Generate ngrok policies that capture and validate the original public authority/scheme before forwarding and replace caller-supplied origin/audit headers. Reject invalid capture pairs at the gateway and unsafe public URLs at config load; keep observed ingress headers for audit provenance, not forwarding authority.
+- Include effective origin and Host mode in mount health checks, doctor, status, reports, the web console, readiness reviews, and signed mount contracts. Existing ngrok policies need manual review and reattachment; no cloud changes or share regeneration are applied automatically.
+- Add regression coverage for spoofed/duplicate headers, redirects, prefixes, ports, IPv6, MCP forwarding, health/cache invalidation, and contract drift, including installed-wheel packaging checks.
+
+No change to the default MCP protocol or preview limitations. Application auth,
+proxy trust, base paths, and CSRF defenses remain the mounted app's responsibility;
+this release does not rewrite HTML, redirect locations, or cookie paths.
+
 ## [0.2.4] - 2026-10-19
 
 Operational hardening for always-on shares and shared HTTP/MCP gateways.

{snulbug-0.2.4 → snulbug-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snulbug
-Version: 0.2.4
+Version: 0.2.6
 Summary: A local-dev MCP policy proxy with Lua policies, replay logs, and learned least-privilege bundles
 Project-URL: Homepage, https://github.com/nahuaque/snulbug
 Project-URL: Repository, https://github.com/nahuaque/snulbug
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: certifi>=2026.10.19
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: jsonschema<5,>=4.23
 Requires-Dist: lupa>=2.5

{snulbug-0.2.4 → snulbug-0.2.6}/docs/devcontainers.md

@@ -10,8 +10,8 @@ servers with a shared control plane.
 ```json
 {
   "features": {
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.4": {
-      "version": "0.2.4",
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.6": {
+      "version": "0.2.6",
       "mode": "member-agent",
       "policy_profile": "tunnel-safe",
       "registry": "redis://redis:6379/0",

{snulbug-0.2.4 → snulbug-0.2.6}/docs/mcp-proxy.md

@@ -123,6 +123,7 @@ auth = "upstream"
 methods = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
 forward_authorization = true
 forward_cookies = true
+preserve_host = false
 timeout = 30.0
 health_path = "/healthz"
 health_status = 200
@@ -214,6 +215,69 @@ the forwarded host, protocol, and prefix headers. Snulbug does not rewrite HTML,
 redirect locations, or cookie paths. Use `strip_prefix = false` for an app that
 already serves its prefix. WebSocket upgrades are not supported by these HTTP mounts.
 
+### Public origin and Host preservation
+
+The share's existing `mcp.proxy.tunnel_public_url` is the single source of truth
+for the external scheme, authority, and port. Its MCP path is not part of the
+origin: `https://share.example.com/mcp` yields `https://share.example.com`, and
+the `/app` mount separately supplies `X-Forwarded-Prefix: /app`.
+
+```toml
+[mcp.proxy]
+tunnel_public_url = "https://share.example.com/mcp"
+
+[[mcp.proxy.http_routes]]
+prefix = "/app"
+upstream = "http://127.0.0.1:3000"
+auth = "upstream"
+preserve_host = true
+```
+
+Merge these values into existing tables rather than adding duplicate mounts.
+The app receives `Host: share.example.com`, `X-Forwarded-Host: share.example.com`,
+`X-Forwarded-Proto: https`, `X-Forwarded-Port: 443`, and
+`X-Forwarded-Prefix: /app`. Explicit non-default public ports are retained.
+The connection destination, HTTPS SNI, and certificate verification still use
+the configured upstream URL. Client Origin/Referer headers are not rewritten.
+
+`preserve_host` defaults to `false`: Host remains the backend authority for apps
+that use internal virtual hosts, while the canonical forwarding headers still
+advertise the public URL. MCP upstreams also retain their backend Host and
+receive canonical host/protocol/port forwarding metadata. This does not change
+OAuth resource/audience or DPoP checks, or pass client OAuth credentials upstream.
+
+Caller-supplied forwarding/original-origin headers do not select the public
+origin. Generated ngrok Cloud Endpoint policies capture and check the original
+public authority/scheme before forwarding, replacing caller-supplied capture
+and audit headers. Snulbug rejects duplicate, incomplete, malformed, or
+mismatched capture pairs with HTTP 400, then removes them before dispatch.
+Those headers are consistency checks, not proof that a request came from ngrok.
+Direct local requests without capture headers are supported and intentionally
+advertise the same configured public origin. No extra trusted-header opt-in is
+needed. Only one canonical origin is supported; aliases/wildcards are not
+automatically trusted.
+
+Without `tunnel_public_url`, HTTP mounts retain local-request forwarding
+behavior and doctor warns that the external origin is unknown. `preserve_host =
+true` requires an explicit public URL. Invalid public URLs, including credentials,
+query strings, fragments, malformed authorities, and control characters, fail
+configuration validation.
+
+Configure the app/framework to trust forwarding headers only from snulbug's
+immediate backend connection, with its public host in any allowed-host list.
+Prefix stripping does not automatically configure an application's root path;
+set the app's `/app` base path or use its supported forwarded-prefix integration.
+Host preservation alone does not implement CSRF protection or application auth.
+
+Doctor/status/report and the console's HTTP mount contracts show the effective
+public origin and Host mode. Backend health checks use the same origin/Host
+contract without client credentials. Changing the public origin or Host mode
+invalidates cached health and readiness review and changes signed mount bindings.
+After upgrading an existing ngrok share, review the desired policy in share
+doctor, update the generated Cloud Endpoint policy file, and reattach it in ngrok.
+Restart the gateway after config changes. This feature does not rewrite a live
+Cloud Endpoint or regenerate existing shares automatically.
+
 Restart `share run` after editing mounts. The router works with proxy and facade
 MCP modes and any tunnel that forwards the gateway origin. For generated ngrok
 setup, register routes at share creation so the Cloud Endpoint policy permits
@@ -932,6 +996,13 @@ Send the returned `x-snulbug-lease` header with MCP requests. The proxy hot-load
 the JSON file on each call, so new leases and revocations do not require a proxy
 restart.
 
+The lease credential terminates at snulbug. The default and configured lease
+headers are stripped before upstream HTTP forwarding, including streaming and
+facade transports; upstream applications do not receive the client's lease token.
+An embedding gateway can instead select an exact lease reference through the
+[trusted Python/ASGI selection API](#trusted-internal-lease-selection), without
+recovering a credential or injecting a synthetic header.
+
 Create an invite when you want snulbug to package the share URL, bearer header,
 lease header, and downstream client snippets together:
 
@@ -1580,3 +1651,66 @@ application = create_proxy_application(
 
 You can run that ASGI app with Uvicorn, Hypercorn, Daphne, or another ASGI
 server.
+
+### Trusted Internal Lease Selection
+
+A hosting gateway that already authenticates a caller and authorizes a task can
+pass its exact lease ID in request-local ASGI context. Configure the existing
+lease store and policy normally:
+
+```python
+from snulbug import create_proxy_application, select_mcp_lease
+
+proxy = create_proxy_application(
+    "http://127.0.0.1:9000",
+    "policy.snulbug/policy.lua",
+    lease_file="leases.json",
+    lease_required=True,
+)
+
+
+def with_task_selection(proxy, resolve_authorized_lease):
+    async def application(scope, receive, send):
+        if scope["type"] == "http":
+            # The host authenticates the caller and authorizes this exact task.
+            lease_id = await resolve_authorized_lease(scope)
+            if lease_id is not None:
+                scope = select_mcp_lease(scope, lease_id=lease_id)
+        await proxy(scope, receive, send)
+
+    return application
+```
+
+`resolve_authorized_lease` belongs to the hosting application. It must return only
+an authorized reference, not an arbitrary caller-selected ID. Public headers,
+query parameters, request bodies, Lua context, and replay logs never populate
+trusted selection automatically. Do not copy any of them into this context
+without independent authentication and authorization. This is an in-process
+integration boundary, not protection against malicious Python code in the host.
+
+`select_mcp_lease(scope, lease_id=...)` returns a shallow scope copy containing a
+frozen `TrustedLeaseSelection` at `TRUSTED_LEASE_SCOPE_KEY`. A trusted ASGI
+integration can also set that typed value directly; strings and JSON mappings at
+the key fail closed. Selecting a different ID on an already selected scope raises
+`ValueError`. No global or session selection is retained.
+
+Selection is **not approval**. Snulbug resolves the exact ID from its configured
+store and runs the same identity bindings, expiry, revocation, tool/argument
+restrictions, and call-budget checks as header-based requests. Existing OAuth and
+Lua checks remain in force. Discovery and Lua/catalog previews do not consume
+calls; final `tools/call` admission consumes once under the existing store lock.
+No new lease, credential recovery, renewal, or TTL extension is performed.
+
+If a lease header is also supplied, it must validate to the selected lease.
+Different or invalid credentials and duplicate headers are rejected, even when
+leases are optional. An unknown ID never falls back to another available lease.
+Denials use `lease.selection_conflict`, `lease.selection_invalid`, or the existing
+lease reason codes. Lease audit metadata identifies `selection = "trusted"` or
+`"header"` and retains the lease/task/invite references without a plaintext token.
+
+The original scope headers remain available inside snulbug for preview and audit
+redaction, including configured custom lease-header names, but are filtered at
+the outbound boundary. Facade transport plugins
+receive a scope without the lease credential headers or trusted selection object.
+Business task selection and grant/revision permissions remain the host's concern;
+snulbug continues to own lease enforcement and accounting.

{snulbug-0.2.4 → snulbug-0.2.6}/docs/ngrok-end-to-end.md

@@ -106,6 +106,33 @@ and preserving prefixes. Existing shares need both a TOML route and an updated
 Cloud Endpoint Traffic Policy; changing TOML alone leaves ngrok's old deny rule
 in effect.
 
+### Public Links and Redirects
+
+The generated share sets `mcp.proxy.tunnel_public_url` to the exact public MCP
+URL. Snulbug derives the public origin from that URL, not from the internal
+Agent Endpoint or caller-supplied forwarding headers. Mounted apps receive the
+public host, scheme, and port through `X-Forwarded-*`, plus their mount prefix.
+This also applies to local requests through snulbug while the public URL is set.
+
+For apps that need the literal public Host header, add `preserve_host = true`
+to that existing `[[mcp.proxy.http_routes]]` table. Leave it false (the default)
+when the backend expects its own internal host. Configure the app to trust
+snulbug as its immediate proxy and serve its public base path, such as `/app`.
+See [public-origin forwarding](mcp-proxy.md#public-origin-and-host-preservation).
+
+The generated Cloud Endpoint policy captures the original host/scheme before
+forwarding, rejects authorities/schemes different from the configured public
+origin with HTTP 421, and replaces caller-supplied origin/audit headers.
+Snulbug validates captured pairs and rejects invalid or mismatched values with
+HTTP 400. These checks do not authenticate the forwarding agent or replace
+application/MCP authentication.
+
+Changing the public URL requires updating TOML and the generated Cloud Endpoint
+policy and reattaching that policy in ngrok. Existing policies from older
+versions do not gain capture rules automatically; use share doctor's desired
+baseline and drift checks to review and update them. Do not recreate the share
+just to update its tunnel policy or discard its invites and evidence.
+
 ## 3. Export the generated client headers
 
 The generated share requires both bearer auth and an `x-snulbug-lease` header

{snulbug-0.2.4 → snulbug-0.2.6}/docs/release.md

@@ -59,7 +59,7 @@ python -m zipfile -l dist/snulbug-*.whl
 8. Install from TestPyPI in a clean environment and smoke test:
 
 ```bash
-uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ snulbug==0.2.4 --help
+uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ snulbug==0.2.6 --help
 ```
 
 9. Run the manual `Publish` workflow with `repository = pypi` when the TestPyPI
@@ -67,4 +67,4 @@ uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org
 10. Create the GitHub release and tag after the PyPI package is available.
 
 The `Publish` workflow uses `workflow_dispatch`, not a tag trigger. Creating or
-pushing `v0.2.4` does not publish a package or automatically create a GitHub release.
+pushing `v0.2.6` does not publish a package or automatically create a GitHub release.

snulbug-0.2.6/docs/upgrading-to-0.2.5.md

@@ -0,0 +1,97 @@
+# Upgrading to 0.2.5
+
+Snulbug 0.2.5 preserves the configured public origin across internal tunnel hops
+and downstream MCP/HTTP forwarding. Back up the complete share directory before
+upgrading and treat it as secret-bearing material. Do not recreate an existing
+share with `share create --force` to update its tunnel policy.
+
+For upgrades from before 0.2.4, also review the
+[always-on runtime and HTTP mount upgrade notes](upgrading-to-0.2.4.md).
+
+## Check the canonical public URL
+
+The existing `mcp.proxy.tunnel_public_url` now determines downstream
+`X-Forwarded-Host`, `X-Forwarded-Proto`, and `X-Forwarded-Port`. The MCP path is
+excluded from the origin; HTTP mounts independently provide their public prefix.
+Local requests through the gateway intentionally advertise the same configured
+public origin, not the local/internal hostname.
+
+Use the exact intended HTTP(S) share URL without credentials, query strings, or
+fragments. Malformed authorities and control characters now fail configuration
+validation. Without a public URL, HTTP mounts retain local-request forwarding
+and doctor warns that the external origin is unknown. Aliases and wildcard hosts
+are not automatically trusted.
+
+## Decide whether the app needs the public Host
+
+By default, the literal Host remains the backend authority. The canonical
+forwarding headers are sufficient for apps that support trusted proxy headers.
+For an app that needs the public Host for virtual hosting or URL generation,
+merge this option into its existing mount:
+
+```toml
+[mcp.proxy]
+tunnel_public_url = "https://share.example.com/mcp"
+
+[[mcp.proxy.http_routes]]
+prefix = "/app"
+upstream = "http://127.0.0.1:3000"
+auth = "upstream"
+preserve_host = true
+```
+
+Do not add duplicate tables for an existing prefix. `preserve_host = true`
+requires an explicit public URL. The connection target, HTTPS SNI, and
+certificate verification remain tied to the upstream URL. MCP upstreams retain
+their own backend Host while receiving canonical forwarding metadata.
+
+Configure the app to trust snulbug's immediate backend connection, accept its
+public hostname, and generate URLs for `/app`. Prefix stripping does not set an
+application's root path automatically. Snulbug does not rewrite HTML, Location
+headers, cookie paths, Origin, or Referer. Application login, permissions, and
+CSRF protection remain the app's responsibility; MCP leases do not guard it.
+
+## Review and reattach the ngrok policy
+
+Newly generated ngrok Cloud Endpoint policies capture the public host/scheme
+before internal forwarding, reject unexpected origins with HTTP 421, and replace
+caller-supplied forwarding/capture/audit headers. Snulbug rejects malformed,
+duplicate, incomplete, or mismatched captured pairs with HTTP 400. These headers
+are consistency checks, not authentication of the tunnel agent.
+
+Existing policy files and live Cloud Endpoints are not changed automatically:
+
+1. Confirm the intended public URL in the existing share configuration.
+2. Run `snulbug mcp share doctor DIRECTORY` and review the desired ngrok baseline
+   and drift result. Add `--compact` for JSON, which includes `ngrok.desired_policy` when
+   inspection is available; the discovery extra supplies YAML inspection.
+3. Review and update `tunnel/ngrok-traffic-policy.yml`, retaining any deliberately
+   customized rules, and reattach the reviewed policy to the public Cloud Endpoint.
+4. Restart the gateway after config changes and rerun doctor. A running agent or
+   valid local YAML does not prove that the public endpoint has the new policy.
+
+Direct requests without captured headers remain supported. Older policies do not
+gain capture checks by upgrading Python alone, and doctor can flag them as drifted.
+Passive console refreshes do not apply cloud changes or probe upstreams repeatedly.
+
+## Renew reviews and contracts deliberately
+
+Effective public origins and Host modes now participate in HTTP mount bindings.
+Existing mount health results and readiness reviews can become stale, and a
+required signed contract created before these fields existed can prevent startup.
+Inspect the intended exposure, run health/doctor checks, then renew the review
+and regenerate/sign the contract through the existing `share contract` workflow.
+Do not bypass a required contract just to suppress drift.
+
+## Verify before handoff
+
+```bash
+snulbug mcp share doctor /path/to/share
+snulbug mcp share status /path/to/share
+snulbug mcp share report /path/to/share
+```
+
+Check a safe MCP operation and an app link/redirect through the public URL.
+The default MCP protocol and experimental profile limitations are unchanged.
+Local release QA and ngrok config validation do not certify live provider/client
+interoperability. See [public-origin forwarding](mcp-proxy.md#public-origin-and-host-preservation).

{snulbug-0.2.4 → snulbug-0.2.6}/examples/codespace_local_gateway/.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
   "name": "snulbug Codespace MCP member",
   "features": {
     "ghcr.io/devcontainers/features/python:1": {},
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.4": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.6": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

{snulbug-0.2.4 → snulbug-0.2.6}/features/snulbug/README.md

@@ -6,7 +6,7 @@ workspace helpers for Codespaces/devcontainers.
 ```json
 {
   "features": {
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.4": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.6": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

{snulbug-0.2.4 → snulbug-0.2.6}/features/snulbug/devcontainer-feature.json

@@ -1,6 +1,6 @@
 {
   "id": "snulbug",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "name": "snulbug",
   "description": "Install snulbug and optional helpers for MCP policy gateways and remote fabric members in devcontainers.",
   "documentationURL": "https://github.com/nahuaque/snulbug/blob/main/docs/devcontainers.md",

{snulbug-0.2.4 → snulbug-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "snulbug"
-version = "0.2.4"
+version = "0.2.6"
 description = "A local-dev MCP policy proxy with Lua policies, replay logs, and learned least-privilege bundles"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,6 +35,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
+    "certifi>=2026.10.19",
     "httpx>=0.28,<1",
     "jsonschema>=4.23,<5",
     "lupa>=2.5",

{snulbug-0.2.4 → snulbug-0.2.6}/snulbug/__init__.py

@@ -1,6 +1,6 @@
 """Local-dev MCP policy proxy and programmable Lua ASGI policy layer."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 
 from .auth_providers import (
     AuthProvider,
@@ -201,13 +201,16 @@ from .inspection import format_mcp_inspection_report, inspect_mcp_log
 from .lab import format_mcp_auth_lab_report, run_mcp_auth_lab, run_mcp_lab
 from .learn import amend_mcp_policy, learn_mcp_policy
 from .leases import (
+    TRUSTED_LEASE_SCOPE_KEY,
     LeasePolicyConfig,
+    TrustedLeaseSelection,
     cleanup_inactive_leases,
     create_lease,
     list_leases,
     reactivate_lease,
     renew_lease,
     revoke_lease,
+    select_mcp_lease,
 )
 from .manifests import load_manifest, manifest_digest, sign_upstream_manifest, verify_upstream_manifest, write_manifest
 from .mcp_auth import (
@@ -500,6 +503,8 @@ __all__ = [
     "LuaMiddleware",
     "LuaRuntimeError",
     "LeasePolicyConfig",
+    "TrustedLeaseSelection",
+    "TRUSTED_LEASE_SCOPE_KEY",
     "LIFECYCLE_STATES",
     "MemoryFabricRuntimeStateStore",
     "MemoryStateStore",
@@ -764,6 +769,7 @@ __all__ = [
     "render_gateway_toml",
     "replay_record_log",
     "revoke_lease",
+    "select_mcp_lease",
     "revoke_mcp_share_invite",
     "revoke_mcp_share_lease",
     "run_mcp_auth_lab",

{snulbug-0.2.4 → snulbug-0.2.6}/snulbug/cli/rich_share.py

@@ -161,7 +161,11 @@ def http_mounts_table(mounts: Mapping[str, Any]) -> Table:
             Text(f"{mount.get('prefix')}\n{mount.get('upstream')}"),
             _value(mount.get("auth")),
             Text(", ".join(mount.get("methods", []))),
-            Text(f"Authorization: {mount.get('forward_authorization')}; cookies: {mount.get('forward_cookies')}"),
+            Text(
+                f"Authorization: {mount.get('forward_authorization')}; cookies: {mount.get('forward_cookies')}\n"
+                f"Origin: {mount.get('public_origin') or 'local request'}\n"
+                f"Host: {'public' if mount.get('preserve_host') else 'upstream'}"
+            ),
             Text(("pass" if health.get("ok") else "fail") if health.get("checked") else "not checked"),
         )
     if not mounts.get("items"):

{snulbug-0.2.4 → snulbug-0.2.6}/snulbug/config.py

@@ -15,6 +15,7 @@ from .policy_backoff import (
     DEFAULT_POLICY_BACKOFF_KEY_FIELDS,
     DEFAULT_POLICY_BACKOFF_REASON_CODES,
 )
+from .public_origin import public_origin
 from .tool_catalog import CATALOG_PROJECTION_MODES
 from .upstream_transports import get_upstream_transport
 
@@ -249,6 +250,8 @@ lease_file = "leases.json"
 lease_required = true
 lease_header = "x-snulbug-lease"
 tunnel_provider = "auto"
+# Canonical public origin for forwarded host/protocol/port; MCP path is excluded.
+# HTTP mounts can opt into preserve_host = true to send the public Host as well.
 tunnel_public_url = ""
 cloudflare_access_profile = ""
 tailscale_profile = ""
@@ -598,6 +601,7 @@ def normalize_mcp_proxy_config(config: Mapping[str, Any], *, base_dir: str | Pat
         raise ValueError("mcp.proxy.tunnel_public_url must be a string")
     if normalized.get("tunnel_public_url") == "":
         normalized["tunnel_public_url"] = None
+    origin = public_origin(normalized.get("tunnel_public_url"))
     for field in ("policy", "record_out", "lease_file"):
         value = normalized.get(field)
         if value is not None and not isinstance(value, str | Path):
@@ -676,6 +680,8 @@ def normalize_mcp_proxy_config(config: Mapping[str, Any], *, base_dir: str | Pat
     normalized["http_routes"] = normalize_http_routes(
         normalized.get("http_routes", []), mcp_path=normalized["streamable_http_endpoint_path"]
     )
+    if origin is None and any(route.get("preserve_host") for route in normalized["http_routes"]):
+        raise ValueError("HTTP route preserve_host requires mcp.proxy.tunnel_public_url")
     normalized["streamable_http_allowed_origins"] = _normalize_string_list(
         normalized.get("streamable_http_allowed_origins", []),
         field="streamable_http_allowed_origins",

{snulbug-0.2.4 → snulbug-0.2.6}/snulbug/http_mounts.py

@@ -12,6 +12,7 @@ from typing import Any
 import httpx
 
 from .http_routes import http_route_contract
+from .public_origin import public_origin
 from .share_doctor import ShareDoctorCheck, ShareDoctorCheckResult, ShareDoctorContext
 
 
@@ -31,7 +32,9 @@ class ShareHttpMountsDoctorCheck(ShareDoctorCheck):
 def http_mount_contracts(proxy: Mapping[str, Any]) -> list[dict[str, Any]]:
     return sorted(
         [
-            http_route_contract(route, timeout=float(proxy.get("timeout", 30.0)))
+            http_route_contract(
+                route, timeout=float(proxy.get("timeout", 30.0)), public_url=proxy.get("tunnel_public_url")
+            )
             for route in proxy.get("http_routes", [])
         ],
         key=lambda route: route["prefix"],
@@ -60,6 +63,13 @@ def inspect_http_mounts(proxy: Mapping[str, Any], *, live_checks: bool = False,
             )
 
         declared = contract["auth"] != "undeclared"
+        origin_message = (
+            f"{prefix}: public origin is {contract['public_origin']}; Host uses "
+            + ("the public authority" if contract["preserve_host"] else "the upstream authority")
+            if contract["public_origin"]
+            else f"{prefix}: public origin is not configured; forwarded URLs use the local request origin"
+        )
+        check("origin", "pass" if contract["public_origin"] else "warn", origin_message)
         check(
             "auth",
             "pass" if declared else "fail",
@@ -130,7 +140,14 @@ def _probe_health(contract: Mapping[str, Any], *, timeout: float) -> dict[str, A
     }
     try:
         with httpx.Client(timeout=min(timeout, contract["timeout"]), trust_env=False, follow_redirects=False) as client:
-            with client.stream("GET", target, headers={"accept": "*/*"}) as response:
+            origin = public_origin(contract["public_origin"])
+            headers = {"accept": "*/*"}
+            if origin:
+                headers.update({name.decode(): value.decode() for name, value in origin.headers()})
+                headers["x-forwarded-prefix"] = contract["prefix"]
+                if contract["preserve_host"]:
+                    headers["host"] = origin.authority
+            with client.stream("GET", target, headers=headers) as response:
                 result["status"] = response.status_code
                 result["ok"] = response.status_code == contract["health_status"]
                 result["message"] = (

{snulbug-0.2.4 → snulbug-0.2.6}/snulbug/http_routes.py

@@ -10,6 +10,8 @@ from urllib.parse import quote, urlsplit
 
 import httpx
 
+from .public_origin import public_origin
+
 if TYPE_CHECKING:
     from .middleware import ASGIApp, Receive, Scope, Send
 
@@ -33,6 +35,7 @@ HTTP_ROUTE_FIELDS = {
     "methods",
     "forward_authorization",
     "forward_cookies",
+    "preserve_host",
     "timeout",
     "health_path",
     "health_status",
@@ -109,7 +112,7 @@ def _normalize_contract(route: Mapping[str, Any]) -> dict[str, Any]:
     contract = {key: value for key, value in route.items() if key not in {"prefix", "upstream", "strip_prefix"}}
     if "auth" in contract and (not isinstance(contract["auth"], str) or contract["auth"] not in {"public", "upstream"}):
         raise ValueError("HTTP route auth must be 'public' or 'upstream'; MCP auth does not protect HTTP mounts")
-    for key in ("forward_authorization", "forward_cookies"):
+    for key in ("forward_authorization", "forward_cookies", "preserve_host"):
         if key in contract and not isinstance(contract[key], bool):
             raise ValueError(f"HTTP route {key} must be a boolean")
     if "methods" in contract:
@@ -156,9 +159,14 @@ def _normalize_contract(route: Mapping[str, Any]) -> dict[str, Any]:
     return contract
 
 
-def http_route_contract(route: Mapping[str, Any], *, timeout: float = 30.0) -> dict[str, Any]:
+def http_route_contract(
+    route: Mapping[str, Any], *, timeout: float = 30.0, public_url: str | None = None
+) -> dict[str, Any]:
     """One effective contract for routing, inspection, and signed share bindings."""
 
+    origin = public_origin(public_url)
+    if route.get("preserve_host") and origin is None:
+        raise ValueError("HTTP route preserve_host requires mcp.proxy.tunnel_public_url")
     return {
         "prefix": route["prefix"],
         "upstream": route["upstream"],
@@ -167,6 +175,8 @@ def http_route_contract(route: Mapping[str, Any], *, timeout: float = 30.0) -> d
         "methods": sorted(route.get("methods", DEFAULT_HTTP_METHODS)),
         "forward_authorization": route.get("forward_authorization", route.get("auth") != "public"),
         "forward_cookies": route.get("forward_cookies", route.get("auth") != "public"),
+        "preserve_host": route.get("preserve_host", False),
+        "public_origin": origin.url if origin else None,
         "timeout": route.get("timeout", timeout),
         "health_path": route.get("health_path"),
         "health_status": route.get("health_status", 200),
@@ -196,12 +206,16 @@ class HttpRoutesMiddleware:
         mcp_path: str = "/mcp",
         timeout: float = 30.0,
         lease_header: str = "x-snulbug-lease",
+        public_url: str | None = None,
     ) -> None:
         self.app = app
         if not math.isfinite(timeout) or timeout <= 0:
             raise ValueError("HTTP route timeout must be positive and finite")
         self.routes = sorted(
-            [http_route_contract(route, timeout=timeout) for route in normalize_http_routes(routes, mcp_path=mcp_path)],
+            [
+                http_route_contract(route, timeout=timeout, public_url=public_url)
+                for route in normalize_http_routes(routes, mcp_path=mcp_path)
+            ],
             key=lambda r: -len(r["prefix"]),
         )
         self.timeout = timeout
@@ -312,9 +326,15 @@ class HttpRoutesMiddleware:
                 or (name == b"cookie" and not route["forward_cookies"])
             ):
                 headers.append((name, value))
-        if original_host:
+        origin = public_origin(route["public_origin"])
+        if origin:
+            headers.extend(origin.headers())
+            if route["preserve_host"]:
+                headers.append((b"host", origin.authority.encode("ascii")))
+        elif original_host:
             headers.append((b"x-forwarded-host", original_host))
-        headers.append((b"x-forwarded-proto", scope.get("scheme", "http").encode("ascii")))
+        if not origin:
+            headers.append((b"x-forwarded-proto", scope.get("scheme", "http").encode("ascii")))
         headers.append((b"x-forwarded-prefix", route["prefix"].encode("ascii")))
         if scope.get("client"):
             headers.append((b"x-forwarded-for", scope["client"][0].encode("ascii")))