Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

92.8 KB
Raw Blame
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# OpenSandbox egress system addon.
#
# Always loaded by the egress mitmproxy launcher. Stays transparent on the
# wire (does not add or alter headers that would reveal the proxy to peers).
#
# Behavior:
#   1. Forces streaming for SSE / chunked responses so each chunk is forwarded
#      immediately, bypassing the stream_large_bodies=1m buffer set in config.yaml
#      (which otherwise stalls LLM-style small-chunk streams).
#   2. Acts as Credential Proxy when the egress sidecar has an active
#      Credential Vault revision, read from the Go sidecar over a private Unix
#      socket. Every new flow conditionally checks the cached snapshot tag;
#      only a changed tag transfers a full snapshot. Lookup or protocol failures
#      fail closed for all intercepted requests, including hosts outside any
#      binding scope. Credential values are never logged; response header values
#      containing them are redacted. Response bodies are not rewritten.
#      Exchange bindings (OSEP-0025) carry only a marker in the snapshot:
#      the async `requestheaders` hook resolves them per request on the
#      active socket `_resolve` endpoint and fails closed (407/kill) on any
#      failure; static bindings stay inline and never suspend the hook.
#      Processing is split across hooks because stream_large_bodies=1m streams
#      bodies above 1 MiB upstream before the `request` hook fires: binding
#      match, path/query/header rewrites and header injection run in
#      `requestheaders` (before the upstream connection is made); only body
#      substitutions, which need the full body, run in `request` and are
#      skipped for streamed requests.
#   3. Implements SNI-aware ignore_hosts for transparent mode. mitmproxy's
#      built-in ignore_hosts check in transparent mode matches against the
#      destination IP first; the SNI hostname is only available inside the TLS
#      ClientHello, which arrives after the initial check. This addon re-checks
#      the same ignore_hosts patterns against the SNI hostname at the
#      tls_clienthello layer and sets ignore_connection=True when a match is
#      found, ensuring domain-based TLS pass-through works reliably.
#   4. Passes through TLS connections that carry no SNI. Without a hostname,
#      upstream hostname verification falls back to the destination IP, which
#      fails for any public certificate lacking an IP SAN (hostname mismatch),
#      so every no-SNI connection would otherwise become a broken MITM attempt.
#      Pass-through is skipped when ssl_insecure is enabled, keeping the
#      explicit insecure-MITM escape hatch working for no-SNI clients.
#      TCP-layer enforcement (deny/allow rules) still applies to these flows.
#   5. Owns the authenticated revision receiver only when the Go launcher hands
#      off a complete per-process internal session. The default remains disabled.
#      When that session also carries the live admission bundle, TLS decisions
#      and request admission run against the installed immutable decision
#      snapshot (credential_bound.py): unbound HTTPS passes through opaquely,
#      bound hosts are decrypted only with a registry admission, and requests
#      are authorized per revision with bounded drain on removal.
#
# User-defined addons can be loaded alongside this script via
# OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT (comma-separated for multiple scripts).
from __future__ import annotations

import asyncio
import http.client as http_client
import ipaddress
import json
import os
import re
import socket
import time
from contextlib import suppress
from typing import TYPE_CHECKING, Any, Awaitable, NoReturn
from urllib.parse import quote, quote_plus, unquote

from mitmproxy import ctx, http
from mitmproxy.tls import ClientHelloData

if TYPE_CHECKING:
    from revision_receiver import Revision

CREDENTIAL_PROXY_SOCKET_ENV = "OPENSANDBOX_CREDENTIAL_PROXY_SOCKET"
DEFAULT_CREDENTIAL_PROXY_SOCKET = "/run/opensandbox/credential-proxy/active.sock"
ACTIVE_VAULT_PATH = "/credential-vault/_active"
CREDENTIAL_RESOLVE_PATH = "/credential-vault/_resolve"
# Mirrors the Go resolver timeout env (seconds, 1..120, default 2); the fixed
# margin lets the egress deliver its own timeout classification first.
CREDENTIAL_RESOLVER_TIMEOUT_ENV = "OPENSANDBOX_EGRESS_CREDENTIAL_RESOLVER_TIMEOUT"
CREDENTIAL_RESOLVER_MAX_CONCURRENCY_ENV = (
    "OPENSANDBOX_EGRESS_CREDENTIAL_RESOLVER_MAX_CONCURRENCY"
)
CREDENTIAL_RESOLVE_TIMEOUT_MARGIN_SECONDS = 0.25
DEFAULT_CREDENTIAL_RESOLVER_TIMEOUT_SECONDS = 2
CREDENTIAL_RESOLVER_TIMEOUT_BOUNDS = (1, 120)
DEFAULT_CREDENTIAL_RESOLVER_CONCURRENCY = 32
CREDENTIAL_RESOLVER_CONCURRENCY_BOUNDS = (1, 1024)
MAX_RESOLVE_RESPONSE_BYTES = 256 * 1024
FLOW_REDACTIONS_KEY = "opensandbox_credential_redactions"
FLOW_BINDING_KEY = "opensandbox_credential_binding"
FLOW_VAULT_REDACTIONS_KEY = "opensandbox_credential_vault_redactions"
FLOW_VAULT_SUPPRESS_KEY = "opensandbox_credential_vault_suppress"
FLOW_REJECTION_KEY = "opensandbox_credential_rejected"
FLOW_REQUEST_HANDLE_KEY = "opensandbox_credential_request_handle"
FLOW_H2_AUTHORITY_KEY = "opensandbox_credential_h2_authority"
HEADER_SUBSTITUTION_DENYLIST = {
    "host",
    "content-length",
    "transfer-encoding",
    "connection",
    "upgrade",
    "te",
    "trailer",
    "proxy-authorization",
    "proxy-authenticate",
    "forwarded",
    "x-forwarded-for",
    "x-forwarded-host",
    "x-forwarded-proto",
}
ACTIVE_VAULT_HEADER_RESERVED_NAMES = {
    "host",
    "content-length",
    "content-type",
    "transfer-encoding",
    "connection",
    "upgrade",
    "te",
    "trailer",
    "proxy-authorization",
    "proxy-authenticate",
    "forwarded",
    "x-forwarded-for",
    "x-forwarded-host",
    "x-forwarded-proto",
}
_ACTIVE_VAULT_HEADER_NAME_RE = re.compile(r"^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$")
_ACTIVE_VAULT_HOST_LABEL_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
_PERCENT_ESCAPE_RE = re.compile(r"%([0-9A-Fa-f]{2})")
# Strict snapshot key sets: unknown fields reject the whole snapshot
# (OSEP-0025 version-skew gate) instead of silently degrading bindings.
_ACTIVE_VAULT_TOP_LEVEL_FIELDS = {"revision", "bindings", "redactions"}
_ACTIVE_VAULT_BINDING_FIELDS = {
    "name",
    "match",
    "headers",
    "substitutions",
    "exchange",
}
# `ports` is deprecated upstream but still rendered by the Go snapshot for
# legacy vaults; allowed and ignored here.
_ACTIVE_VAULT_MATCH_FIELDS = {"schemes", "ports", "hosts", "methods", "paths"}
_ACTIVE_VAULT_HEADER_FIELDS = {"name", "value"}
_ACTIVE_VAULT_SUBSTITUTION_FIELDS = {"placeholder", "value", "in"}
_RESOLVE_RESPONSE_FIELDS = {"revision", "binding", "headers", "redactions", "suppressHeaders"}
_RESOLVE_HEADER_FIELDS = {"name", "value"}
_ENV_INT_RE = re.compile(r"[+-]?[0-9]+")
_REVISION_RUNTIME_ERROR = "credential proxy: invalid revision runtime configuration"
_REVISION_ENV = {
    "socket": "OPENSANDBOX_EGRESS_REVISION_IPC_SOCKET",
    "token": "OPENSANDBOX_EGRESS_REVISION_IPC_TOKEN",
    "control": "OPENSANDBOX_EGRESS_REVISION_CONTROL_GENERATION",
    "subject": "OPENSANDBOX_EGRESS_REVISION_SUBJECT_GENERATION",
    "limit": "OPENSANDBOX_EGRESS_REVISION_MAX_SNAPSHOT_BYTES",
}


class ActiveVault:
    def __init__(
        self,
        revision: int,
        bindings: list[dict[str, Any]],
        redactions: list[str],
        etag: str = "",
    ) -> None:
        self.revision = revision
        self.bindings = bindings
        self.redactions = redactions
        self.etag = etag


class ActiveVaultLookupError(Exception):
    """The active vault could not be validated for this flow."""


_vault_cache: ActiveVault | None = None
_revision_receiver: Any | None = None
_revision_server: Any | None = None
_live_runtime: Any | None = None
# Read-only binding views keyed by the complete, already-verified Revision.
# Keep only one entry, until the next cache miss or done(); this does not promise
# immediate wiping of retired credentials or mutate views held by older flows.
_live_vault_cache: tuple[Revision, ActiveVault | None] | None = None

# Operator-only diagnostics; no public interception mode is enabled here.
_tls_shadow_enabled = os.environ.get(
    "OPENSANDBOX_EGRESS_MITMPROXY_SHADOW", ""
).strip().lower() in {"1", "true", "on"}

# Fast Sandbox profile: one shared mitmdump serving N sandboxes; the active vault is
# selected by the client's source IP (preserved by the interception DNAT), so
# the immutable snapshot cache is keyed per client IP. Every flow performs a
# conditional snapshot-tag check; the full secret-bearing snapshot is transferred
# only when its opaque tag changes. The sidecar profile keeps one shared cache.
# The per-IP cache is bounded because spoofed source IPs could otherwise grow
# it without limit.
_fast_sandbox_mode_enabled = False
_vault_cache_by_ip: dict[str, ActiveVault] = {}
_VAULT_CACHE_MAX_IPS = 4096


def _set_fast_sandbox_mode(enabled: bool) -> None:
    global _fast_sandbox_mode_enabled
    _fast_sandbox_mode_enabled = enabled


def _set_fast_sandbox_mode_from_env() -> None:
    _set_fast_sandbox_mode(
        os.environ.get("OPENSANDBOX_EGRESS_PROFILE", "").strip().lower() == "fast-sandbox"
    )


_set_fast_sandbox_mode_from_env()


def _fatal_revision_runtime() -> NoReturn:
    # mitmproxy 11 loads -s scripts in a reload watcher. Generic exceptions are
    # swallowed and OptionsError only stops that watcher, so SystemExit is the
    # process-level fence that prevents a listener without the system addon.
    raise SystemExit(_REVISION_RUNTIME_ERROR) from None


def _revision_configuration() -> tuple[str, str, str, str, int] | None:
    present = {key for key, name in _REVISION_ENV.items() if name in os.environ}
    if not present:
        return None
    if present != set(_REVISION_ENV):
        _fatal_revision_runtime()
    values = {key: os.environ[name] for key, name in _REVISION_ENV.items()}
    limit_text = values["limit"]
    if (
        any(not value for value in values.values())
        or not limit_text.isascii()
        or not limit_text.isdecimal()
    ):
        _fatal_revision_runtime()
    try:
        limit = int(limit_text)
    except ValueError:
        _fatal_revision_runtime()
    if limit <= 0 or limit >= 2**63 or str(limit) != limit_text:
        _fatal_revision_runtime()
    return (
        values["socket"],
        values["token"],
        values["control"],
        values["subject"],
        limit,
    )


def load(_loader: Any) -> None:
    """Start the revision receiver the launcher selected for this process."""
    global _revision_receiver, _revision_server, _live_runtime
    if _revision_receiver is not None or _revision_server is not None or _live_runtime is not None:
        _fatal_revision_runtime()
    configuration = _revision_configuration()
    if configuration is None:
        return
    socket_path, token, control, subject, limit = configuration
    # The live credential-bound mode never runs with insecure upstream
    # verification: check the effective option before the receiver starts.
    # The installation-only receiver keeps the legacy escape hatch.
    if _live_admission_requested():
        _validate_live_options()
    receiver = server = runtime = None
    try:
        from revision_ipc import Server

        if _live_admission_requested():
            import credential_bound

            runtime, server = credential_bound.configure(
                socket_path, token, control, subject, limit
            )
            receiver = runtime.registry
        else:
            from revision_publication import InstallationReceiver

            receiver = InstallationReceiver(
                control,
                subject,
                max_snapshot_bytes=limit,
            )
            server = Server(
                receiver,
                socket_path,
                token,
                max_snapshot_bytes=limit,
                request_timeout=1,
            )
            server.start()
    except Exception:  # noqa: BLE001 - configuration may contain credentials
        if runtime is not None:
            with suppress(Exception):
                runtime.close()
        if server is not None:
            with suppress(Exception):
                server.close()
        elif receiver is not None:
            with suppress(Exception):
                receiver.close()
        _fatal_revision_runtime()
    _revision_receiver = receiver
    _revision_server = server
    _live_runtime = runtime


def _live_admission_requested() -> bool:
    """True when the launcher supplied any live admission budget variable."""
    try:
        import credential_bound

        return credential_bound.live_admission_requested()
    except Exception:  # noqa: BLE001 - only the launcher bundle matters here
        return False


def configure(updated: set) -> None:
    """Fence insecure TLS and native pre-TLS bypasses in the live runtime."""
    if not {"ssl_insecure", "ignore_hosts", "allow_hosts"}.intersection(updated):
        return
    if _live_runtime is None and not _live_admission_requested():
        return
    _validate_live_options()


def _validate_live_options() -> None:
    from credential_bound import validate_live_options

    validate_live_options(ctx.options)


def done() -> None:
    """Fence the receiver and remove only its owned socket during addon exit."""
    global _revision_receiver, _revision_server, _live_runtime, _live_vault_cache
    server = _revision_server
    runtime = _live_runtime
    _revision_receiver = None
    _revision_server = None
    _live_runtime = None
    _live_vault_cache = None
    if runtime is not None:
        try:
            runtime.close()
        except Exception:  # noqa: BLE001 - never expose session-bearing details
            ctx.log.warn("credential proxy: revision runtime cleanup failed")
    if server is not None:
        try:
            server.close()
        except Exception:  # noqa: BLE001 - never expose session-bearing details
            ctx.log.warn("credential proxy: revision runtime cleanup failed")


class UnixSocketHTTPConnection(http_client.HTTPConnection):
    def __init__(self, socket_path: str, timeout: float) -> None:
        super().__init__("credential-proxy", timeout=timeout)
        self.socket_path = socket_path

    def connect(self) -> None:
        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        try:
            sock.settimeout(self.timeout)
            sock.connect(self.socket_path)
        except Exception:
            # A failed connect must not leak the freshly created socket.
            sock.close()
            raise
        self.sock = sock


def tls_clienthello(data: ClientHelloData) -> None:
    """Decide TLS interception for this ClientHello.

    Live credential-bound mode (OSEP-0023 experimental sidecar): classify
    against the installed immutable decision snapshot. Unbound SNI, ECH-hidden
    or no-SNI traffic passes through opaquely; a bound host is decrypted only
    with a registry admission; any deny outcome terminates the connection
    instead of decrypting or tunneling an unknown state.

    Legacy mode: re-check ignore_hosts patterns against the SNI hostname.

    In transparent mode, mitmproxy checks ignore_hosts against the
    destination IP:port before the TLS handshake.  If the check fails at
    that stage (SNI not yet available), we get a second chance here with
    the actual hostname from the ClientHello SNI extension.

    Connections without SNI cannot be matched against hostname patterns and
    cannot be safely MITM'd: with no hostname available, upstream hostname
    verification falls back to the destination IP, which fails for any public
    certificate without an IP SAN (hostname mismatch), turning every no-SNI
    connection into a broken MITM attempt. Such connections are passed through
    untouched, unless the operator explicitly opted into insecure upstream
    verification (OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE), in which case
    MITM remains possible and the escape hatch keeps working. TCP-layer
    enforcement (deny/allow rules) still applies.
    """
    live = _live_runtime
    if live is not None:
        _tls_clienthello_live(live, data)
        return

    sni = data.client_hello.sni
    if not sni:
        if not ctx.options.ssl_insecure:
            data.ignore_connection = True
        return

    patterns = ctx.options.ignore_hosts
    if not patterns:
        return

    for pattern in patterns:
        try:
            if re.search(pattern, sni):
                data.ignore_connection = True
                return
        except re.error:
            pass


def next_layer(data: Any) -> None:
    """Install a fixed-version H2 instance before the selected HttpLayer starts."""
    live = _live_runtime
    client = data.context.client
    if live is None or getattr(client, "alpn", None) != b"h2":
        return
    token = live.token_for(client)
    if token is None:
        return
    try:
        from credential_bound_h2 import BoundH2Server, dependency_versions_supported
        from mitmproxy.proxy.layers.http import HttpLayer

        if (
            not dependency_versions_supported()
            or getattr(data.context.options, "connection_strategy", None) != "lazy"
            or getattr(data.context.server, "via", None) is not None
        ):
            # A chained proxy has a different physical-transport owner. It is
            # outside this direct/lazy proof; reject before request admission.
            raise ValueError("unsupported H2 transport")
        if data.layer is None:
            selector = ctx.master.addons.get("nextlayer")
            if selector is None:
                raise ValueError("missing layer selector")
            selector.next_layer(data)
        selected = data.layer
        # TLS and other outer layers still get their normal selector behavior.
        if not isinstance(selected, HttpLayer):
            return
        existing = live.h2_for(client)
        if existing is not None:
            if selected.connections.get(client) is existing:
                return
            raise ValueError("duplicate H2 owner")
        if client in selected.connections:
            raise ValueError("HTTP layer already started")
        adapter = BoundH2Server(selected.context.fork(), live, selected, token)
        selected.connections[client] = adapter
        if not live.attach_h2(client, adapter):
            raise ValueError("H2 attachment rejected")
    except Exception:  # noqa: BLE001 - only fixed diagnostics cross this boundary
        live._close_established(client)
        ctx.log.warn("credential proxy: H2 adapter unavailable; connection denied")


def server_connect(data: Any) -> None:
    live = _live_runtime
    if live is not None:
        live.server_connect(data)


def server_connect_error(data: Any) -> None:
    live = _live_runtime
    if live is not None:
        live.server_connect_error(data)


def server_connected(data: Any) -> None:
    live = _live_runtime
    if live is not None:
        live.server_connected(data)


def server_disconnected(data: Any) -> None:
    live = _live_runtime
    if live is not None:
        live.server_disconnected(data)


def _clienthello_ech_hidden(client_hello: Any) -> bool | None:
    """Inspect the actual ClientHello extension list for ECH (0xfe0d).

    mitmproxy 11 exposes ``ClientHello.extensions`` as ``list[(int, bytes)]``;
    GREASE ECH values are treated as ECH-bearing because the inner name stays
    hidden either way. Returns True when the extension is present, False when
    the extension list is valid and empty of it, and None when the extension
    data is absent or malformed — uninspectable input must deny, never be
    silently treated as ECH-free.
    """
    try:
        extensions = client_hello.extensions
    except Exception:  # noqa: BLE001 - never trust uninspectable hello data
        return None
    if not isinstance(extensions, (list, tuple)):
        return None
    for extension in extensions:
        if not (
            isinstance(extension, tuple)
            and len(extension) == 2
            and type(extension[0]) is int
            and isinstance(extension[1], (bytes, bytearray))
        ):
            return None
        if extension[0] == 0xFE0D:
            return True
    return False


# Closed admission outcomes only; never include SNI, credentials or raw errors.
_TLS_ADMISSION_REASONS = {
    "decrypt": ("binding_host",),
    "passthrough": ("ech", "no_sni", "static_ignore", "no_binding_host"),
    "deny": ("unknown_identity", "invalid_sni", "snapshot_missing",
             "generation_mismatch", "invalid_input", "registry_exhausted",
             "admission_disabled", "ssl_insecure", "malformed_extensions"),
}


def _record_tls_admission(decision: str, reason: str) -> None:
    """Best-effort admission event, not handshake success or request count."""
    with suppress(Exception):
        if reason in _TLS_ADMISSION_REASONS.get(decision, ()):
            ctx.log.warn(f"credential proxy: tls-admission-v1 {decision} {reason}")


def _tls_clienthello_live(live: Any, data: ClientHelloData) -> None:
    # The live credential-bound mode must never run with insecure upstream
    # verification; deny the handshake outright instead of trusting an
    # unverified origin identity with a credential.
    if ctx.options.ssl_insecure:
        _record_tls_admission("deny", "ssl_insecure")
        with suppress(Exception):
            ctx.log.warn("credential proxy: tls decision deny reason=ssl_insecure")
        import credential_bound

        credential_bound.terminate_handshake(data.context.client)
        return
    # ECH hides the inner name: inspect the real extension list before any
    # outer-SNI matching so hidden names can never select a credential.
    ech_hidden = _clienthello_ech_hidden(data.client_hello)
    if ech_hidden is None:
        _record_tls_admission("deny", "malformed_extensions")
        with suppress(Exception):
            ctx.log.warn("credential proxy: tls decision deny reason=malformed_extensions")
        import credential_bound

        credential_bound.terminate_handshake(data.context.client)
        return
    sni = data.client_hello.sni
    from static_passthrough import destination_port

    port = destination_port(getattr(getattr(data.context, "server", None), "address", None))
    result = live.admit_tls(sni, ech_hidden=ech_hidden, destination_port=port)
    _record_tls_admission(result.action, result.reason)
    if result.action == "passthrough":
        data.ignore_connection = True
        return
    if result.action == "deny":
        # Fail closed: bootstrapping, generation mismatch, invalid or
        # unadmittable SNI, or an exhausted registry terminate the connection.
        # A deny never degrades into opaque tunneling or decrypt-all.
        with suppress(Exception):
            ctx.log.warn(f"credential proxy: tls decision deny reason={result.reason}")
        import credential_bound

        credential_bound.terminate_handshake(data.context.client)
        return
    live.track(result.token, data.context.client)


def _load_active_vault(client_ip: str | None = None) -> ActiveVault | None:
    if _fast_sandbox_mode_enabled:
        return _load_active_vault_for_ip(client_ip)
    return _load_active_vault_shared()


def _load_active_vault_shared() -> ActiveVault | None:
    global _vault_cache
    try:
        vault = _fetch_active_vault(None, _vault_cache)
    except ActiveVaultLookupError:
        # Never retain a potentially revoked plaintext snapshot after the
        # proxy can no longer confirm its opaque tag.
        _vault_cache = None
        raise
    _vault_cache = vault
    return vault


def _load_active_vault_for_ip(client_ip: str | None) -> ActiveVault | None:
    if not client_ip:
        raise ActiveVaultLookupError("fast-sandbox vault lookup requires a client IP")
    if client_ip not in _vault_cache_by_ip and len(_vault_cache_by_ip) >= _VAULT_CACHE_MAX_IPS:
        _vault_cache_by_ip.clear()
    cached = _vault_cache_by_ip.get(client_ip)
    try:
        vault = _fetch_active_vault(client_ip, cached)
    except ActiveVaultLookupError:
        _vault_cache_by_ip.pop(client_ip, None)
        raise
    if vault is None:
        _vault_cache_by_ip.pop(client_ip, None)
    else:
        _vault_cache_by_ip[client_ip] = vault
    return vault


def _fetch_active_vault(
    client_ip: str | None = None,
    cached: ActiveVault | None = None,
) -> ActiveVault | None:
    socket_path = (
        os.environ.get(CREDENTIAL_PROXY_SOCKET_ENV, "").strip()
        or DEFAULT_CREDENTIAL_PROXY_SOCKET
    )
    path = ACTIVE_VAULT_PATH
    if client_ip:
        # fast-sandbox profile: one shared socket, dispatch inside — the handler
        # resolves clientIp -> subject -> that subject's vault snapshot
        path = f"{ACTIVE_VAULT_PATH}?clientIp={quote(client_ip)}"
    connection = UnixSocketHTTPConnection(socket_path, timeout=0.25)
    try:
        headers = {}
        if cached is not None:
            if not cached.etag:
                raise ActiveVaultLookupError("cached active vault has no ETag")
            headers["If-None-Match"] = cached.etag
        connection.request("GET", path, headers=headers)
        response = connection.getresponse()
        body = response.read()
        if response.status == 304:
            if cached is None:
                raise ActiveVaultLookupError(
                    "active vault returned 304 without a cached snapshot"
                )
            if response.getheader("ETag") != cached.etag:
                raise ActiveVaultLookupError("active vault 304 response has an invalid ETag")
            return cached
        if response.status == 404:
            return None
        if response.status != 200:
            raise ActiveVaultLookupError(
                f"active vault lookup returned HTTP {response.status}"
            )
        payload = json.loads(body.decode("utf-8"))
        vault = _parse_active_vault(payload)
        etag = _validate_active_vault_etag(response.getheader("ETag"))
        if cached is not None and etag == cached.etag:
            raise ActiveVaultLookupError(
                "active vault tag did not advance after a conditional lookup"
            )
        vault.etag = etag
        return vault
    except ActiveVaultLookupError:
        raise
    except Exception as exc:
        raise ActiveVaultLookupError(f"active vault lookup failed: {exc}") from exc
    finally:
        with suppress(Exception):
            connection.close()


def _parse_active_vault(payload: Any) -> ActiveVault:
    if not isinstance(payload, dict):
        raise ActiveVaultLookupError("active vault payload must be an object")
    unexpected_fields = set(payload) - _ACTIVE_VAULT_TOP_LEVEL_FIELDS
    if unexpected_fields:
        raise ActiveVaultLookupError(
            "active vault payload contains unsupported fields: "
            + ",".join(sorted(unexpected_fields))
        )
    revision = payload.get("revision")
    if isinstance(revision, bool) or not isinstance(revision, int) or revision <= 0:
        raise ActiveVaultLookupError("active vault revision must be a positive integer")
    bindings = payload.get("bindings")
    if not isinstance(bindings, list) or any(not isinstance(item, dict) for item in bindings):
        raise ActiveVaultLookupError("active vault bindings must be a list of objects")
    redactions = payload.get("redactions", [])
    if not isinstance(redactions, list) or any(
        not isinstance(value, str) or not value for value in redactions
    ):
        raise ActiveVaultLookupError("active vault redactions must be non-empty strings")

    redaction_set = set(redactions)
    normalized_bindings: list[dict[str, Any]] = []
    for index, binding in enumerate(bindings):
        unexpected_fields = set(binding) - _ACTIVE_VAULT_BINDING_FIELDS
        if unexpected_fields:
            raise ActiveVaultLookupError(
                f"active vault binding {index} contains unsupported fields: "
                + ",".join(sorted(unexpected_fields))
            )
        name = binding.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ActiveVaultLookupError(
                f"active vault binding {index} name must be a non-empty string"
            )

        exchange = _parse_active_vault_exchange(binding, index)

        match = binding.get("match")
        if not isinstance(match, dict):
            raise ActiveVaultLookupError(
                f"active vault binding {index} match must be an object"
            )
        unexpected_fields = set(match) - _ACTIVE_VAULT_MATCH_FIELDS
        if unexpected_fields:
            raise ActiveVaultLookupError(
                f"active vault binding {index} match contains unsupported fields: "
                + ",".join(sorted(unexpected_fields))
            )
        host_field = f"binding {index} match.hosts"
        hosts = [
            _normalize_active_vault_host(host, host_field)
            for host in _normalize_active_vault_strings(match.get("hosts"), host_field)
        ]
        schemes = _normalize_active_vault_strings(
            match.get("schemes"), f"binding {index} match.schemes", str.lower
        )
        if any(scheme not in {"http", "https"} for scheme in schemes):
            raise ActiveVaultLookupError(
                f"active vault binding {index} match.schemes contains an unsupported scheme"
            )
        methods = _normalize_active_vault_strings(
            match.get("methods"), f"binding {index} match.methods", str.upper
        )
        paths = _normalize_active_vault_strings(
            match.get("paths"), f"binding {index} match.paths"
        )
        if any(not path.startswith("/") for path in paths):
            raise ActiveVaultLookupError(
                f"active vault binding {index} match.paths must start with /"
            )

        raw_headers = binding.get("headers")
        if raw_headers is None:
            raw_headers = []
        if not isinstance(raw_headers, list) or any(
            not isinstance(header, dict) for header in raw_headers
        ):
            raise ActiveVaultLookupError(
                f"active vault binding {index} headers must be a list of objects"
            )
        normalized_headers: list[dict[str, str]] = []
        for header_index, header in enumerate(raw_headers):
            unexpected_fields = set(header) - _ACTIVE_VAULT_HEADER_FIELDS
            if unexpected_fields:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} "
                    "contains unsupported fields: "
                    + ",".join(sorted(unexpected_fields))
                )
            header_name = header.get("name")
            header_value = header.get("value")
            if not isinstance(header_name, str) or not header_name.strip():
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} name "
                    "must be a non-empty string"
                )
            header_name = header_name.strip()
            if _ACTIVE_VAULT_HEADER_NAME_RE.fullmatch(header_name) is None:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} name "
                    "is not a valid HTTP field name"
                )
            if header_name.lower() in ACTIVE_VAULT_HEADER_RESERVED_NAMES:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} name "
                    "is reserved"
                )
            if not isinstance(header_value, str):
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} value "
                    "must be a string"
                )
            if header_value and header_value not in redaction_set:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} header {header_index} value "
                    "is missing from redactions"
                )
            normalized_headers.append({"name": header_name, "value": header_value})

        raw_substitutions = binding.get("substitutions")
        if raw_substitutions is None:
            raw_substitutions = []
        if not isinstance(raw_substitutions, list) or any(
            not isinstance(substitution, dict) for substitution in raw_substitutions
        ):
            raise ActiveVaultLookupError(
                f"active vault binding {index} substitutions must be a list of objects"
            )
        normalized_substitutions: list[dict[str, Any]] = []
        for substitution_index, substitution in enumerate(raw_substitutions):
            unexpected_fields = set(substitution) - _ACTIVE_VAULT_SUBSTITUTION_FIELDS
            if unexpected_fields:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "contains unsupported fields: "
                    + ",".join(sorted(unexpected_fields))
                )
            placeholder = substitution.get("placeholder")
            value = substitution.get("value")
            if not isinstance(placeholder, str) or not placeholder.strip():
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "placeholder must be a non-empty string"
                )
            if not isinstance(value, str):
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "value must be a string"
                )
            surfaces = _normalize_active_vault_strings(
                substitution.get("in"),
                f"binding {index} substitution {substitution_index} in",
                str.lower,
            )
            if any(
                surface not in {"path", "query", "header", "body"}
                for surface in surfaces
            ):
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "contains an unsupported surface"
                )
            missing_redactions = (
                _active_snapshot_substitution_redaction_variants(value) - redaction_set
            )
            if missing_redactions:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "value representations are missing from redactions"
                )
            if placeholder not in redaction_set:
                raise ActiveVaultLookupError(
                    f"active vault binding {index} substitution {substitution_index} "
                    "placeholder is missing from redactions"
                )
            normalized_substitutions.append(
                {"placeholder": placeholder, "value": value, "in": surfaces}
            )

        normalized_binding: dict[str, Any] = {
            "name": name.strip(),
            "match": {
                "schemes": schemes,
                "hosts": hosts,
                "methods": methods,
                "paths": paths,
            },
            "headers": normalized_headers,
            "substitutions": normalized_substitutions,
        }
        if exchange is not None:
            normalized_binding["exchange"] = exchange
        normalized_bindings.append(normalized_binding)
    return ActiveVault(
        revision=revision,
        bindings=normalized_bindings,
        redactions=list(redactions),
    )


def _parse_active_vault_exchange(binding: dict[str, Any], index: int) -> dict[str, str] | None:
    """Validate the optional exchange marker: exactly ``{"credential": name}``
    with explicitly empty ``headers``/``substitutions``; any present value
    (including ``null``) other than that shape fails the snapshot closed.
    """
    if "exchange" not in binding:
        return None
    raw_exchange = binding["exchange"]
    if not isinstance(raw_exchange, dict) or set(raw_exchange) != {"credential"}:
        raise ActiveVaultLookupError(
            f"active vault binding {index} exchange must contain only credential"
        )
    credential = raw_exchange["credential"]
    if not isinstance(credential, str) or not credential.strip():
        raise ActiveVaultLookupError(
            f"active vault binding {index} exchange credential must be a non-empty string"
        )
    for field in ("headers", "substitutions"):
        if binding.get(field) != []:
            raise ActiveVaultLookupError(
                f"active vault binding {index} with exchange must carry an "
                f"empty {field} list"
            )
    return {"credential": credential}


def _normalize_active_vault_strings(
    value: Any,
    field: str,
    normalize: Any | None = None,
) -> list[str]:
    if not isinstance(value, list) or not value:
        raise ActiveVaultLookupError(f"active vault {field} must be a non-empty list")
    normalized: list[str] = []
    for item in value:
        if not isinstance(item, str) or not item.strip():
            raise ActiveVaultLookupError(
                f"active vault {field} must contain non-empty strings"
            )
        item = item.strip()
        normalized.append(normalize(item) if normalize is not None else item)
    return normalized


def _normalize_active_vault_host(value: str, field: str) -> str:
    host = value.strip().lower()
    host = host.removesuffix(".")
    if not host or "://" in host or "/" in host:
        raise ActiveVaultLookupError(f"active vault {field} contains an invalid host")

    if host.startswith("*."):
        suffix = host[2:]
        if not suffix or "*" in suffix or _active_vault_host_is_ip(suffix):
            raise ActiveVaultLookupError(
                f"active vault {field} contains an invalid wildcard host"
            )
        if not _active_vault_host_is_fqdn(suffix):
            raise ActiveVaultLookupError(
                f"active vault {field} contains an invalid wildcard host"
            )
        return f"*.{suffix}"

    if "*" in host or _active_vault_host_is_ip(host):
        raise ActiveVaultLookupError(f"active vault {field} contains an invalid host")
    if not _active_vault_host_is_fqdn(host):
        raise ActiveVaultLookupError(f"active vault {field} contains an invalid host")
    return host


def _active_vault_host_is_ip(host: str) -> bool:
    try:
        ipaddress.ip_address(host)
    except ValueError:
        return False
    return True


def _active_vault_host_is_fqdn(host: str) -> bool:
    return (
        len(host) <= 253
        and "." in host
        and all(_ACTIVE_VAULT_HOST_LABEL_RE.fullmatch(label) for label in host.split("."))
    )


def _active_snapshot_substitution_redaction_variants(value: str) -> set[str]:
    url_encoded = quote(value, safe="")
    form_encoded = quote_plus(value, safe="")
    variants = {
        value,
        url_encoded,
        _lowercase_percent_escapes(url_encoded),
        form_encoded,
        _lowercase_percent_escapes(form_encoded),
        _go_json_encoded_string_content(value),
        json.dumps(value)[1:-1],
    }
    variants.discard("")
    return variants


def _lowercase_percent_escapes(value: str) -> str:
    return _PERCENT_ESCAPE_RE.sub(lambda match: f"%{match.group(1).lower()}", value)


def _go_json_encoded_string_content(value: str) -> str:
    encoded = json.dumps(value, ensure_ascii=False)[1:-1]
    return (
        encoded.replace("<", r"\u003c")
        .replace(">", r"\u003e")
        .replace("&", r"\u0026")
        .replace("\u2028", r"\u2028")
        .replace("\u2029", r"\u2029")
    )


def _validate_active_vault_etag(value: str | None) -> str:
    if value is None or re.fullmatch(r'"[A-Za-z0-9._~-]{1,128}"', value) is None:
        raise ActiveVaultLookupError("active vault response has an invalid ETag")
    return value


class CredentialResolveError(Exception):
    """Resolve failure with a log-safe reason: transport | invalid_response
    | deadline | http_<status>. Resolve content never reaches logs."""


def _env_int_range(name: str, default: int, bounds: tuple[int, int]) -> int:
    # Mirrors Go EnvIntRange: unparsable or out-of-bounds keeps the default.
    raw = os.environ.get(name, "").strip()
    if not raw or _ENV_INT_RE.fullmatch(raw) is None:
        return default
    value = int(raw)
    if not bounds[0] <= value <= bounds[1]:
        return default
    return value


def _resolve_budget_seconds() -> float:
    return (
        _env_int_range(
            CREDENTIAL_RESOLVER_TIMEOUT_ENV,
            DEFAULT_CREDENTIAL_RESOLVER_TIMEOUT_SECONDS,
            CREDENTIAL_RESOLVER_TIMEOUT_BOUNDS,
        )
        + CREDENTIAL_RESOLVE_TIMEOUT_MARGIN_SECONDS
    )


# Concurrency aligned with the Go endpoint's semaphore; keyed by loop
# because tests and script reloads swap event loops.
_resolve_limiter_state: tuple[asyncio.AbstractEventLoop, asyncio.Semaphore] | None = None


def _resolve_limiter() -> asyncio.Semaphore:
    global _resolve_limiter_state
    loop = asyncio.get_running_loop()
    state = _resolve_limiter_state
    if state is None or state[0] is not loop:
        state = (
            loop,
            asyncio.Semaphore(
                _env_int_range(
                    CREDENTIAL_RESOLVER_MAX_CONCURRENCY_ENV,
                    DEFAULT_CREDENTIAL_RESOLVER_CONCURRENCY,
                    CREDENTIAL_RESOLVER_CONCURRENCY_BOUNDS,
                )
            ),
        )
        _resolve_limiter_state = state
    return state[1]


def _parse_resolve_response(raw: bytes, binding_name: str) -> dict[str, Any]:
    """Strictly validate one 200 resolve body against the frozen contract."""
    if len(raw) > MAX_RESOLVE_RESPONSE_BYTES:
        raise CredentialResolveError("invalid_response")
    try:
        document = json.loads(raw.decode("utf-8"))
    except Exception:
        raise CredentialResolveError("invalid_response") from None
    if not isinstance(document, dict) or set(document) != _RESOLVE_RESPONSE_FIELDS:
        raise CredentialResolveError("invalid_response")
    revision = document["revision"]
    if isinstance(revision, bool) or not isinstance(revision, int) or revision <= 0:
        raise CredentialResolveError("invalid_response")
    if document["binding"] != binding_name:
        raise CredentialResolveError("invalid_response")
    raw_headers = document["headers"]
    if not isinstance(raw_headers, list):
        raise CredentialResolveError("invalid_response")
    headers: list[dict[str, str]] = []
    for header in raw_headers:
        if not isinstance(header, dict) or set(header) != _RESOLVE_HEADER_FIELDS:
            raise CredentialResolveError("invalid_response")
        name = header["name"]
        value = header["value"]
        if (
            not isinstance(name, str)
            or not name.strip()
            or _ACTIVE_VAULT_HEADER_NAME_RE.fullmatch(name) is None
            or name.lower() in ACTIVE_VAULT_HEADER_RESERVED_NAMES
            or not isinstance(value, str)
            or not value
        ):
            raise CredentialResolveError("invalid_response")
        headers.append({"name": name, "value": value})
    redactions = document["redactions"]
    if not isinstance(redactions, list) or any(
        not isinstance(item, str) or not item for item in redactions
    ):
        raise CredentialResolveError("invalid_response")
    raw_suppress = document["suppressHeaders"]
    if not isinstance(raw_suppress, list):
        raise CredentialResolveError("invalid_response")
    suppress: set[str] = set()
    for name in raw_suppress:
        if (
            not isinstance(name, str)
            or not name.strip()
            or _ACTIVE_VAULT_HEADER_NAME_RE.fullmatch(name) is None
            or name.lower() in ACTIVE_VAULT_HEADER_RESERVED_NAMES
        ):
            raise CredentialResolveError("invalid_response")
        suppress.add(name.lower())
    return {
        "revision": revision,
        "headers": headers,
        "redactions": redactions,
        "suppressHeaders": suppress,
    }


def _resolve_exchange_http(
    socket_path: str, timeout: float, path: str, payload: dict[str, Any]
) -> dict[str, Any]:
    """One resolve RPC; failures normalize to CredentialResolveError."""
    connection = UnixSocketHTTPConnection(socket_path, timeout=timeout)
    try:
        body = json.dumps(payload).encode("utf-8")
        connection.request(
            "POST", path, body=body, headers={"Content-Type": "application/json"}
        )
        response = connection.getresponse()
        # Bound the read itself; the size check must not follow an unbounded
        # buffer, multiplied by concurrent per-request resolves.
        raw = response.read(MAX_RESOLVE_RESPONSE_BYTES + 1)
        if response.status != 200:
            raise CredentialResolveError(f"http_{response.status}")
        return _parse_resolve_response(raw, payload["binding"])
    except CredentialResolveError:
        raise
    except Exception:
        raise CredentialResolveError("transport") from None
    finally:
        with suppress(Exception):
            connection.close()


def _request_host(flow: http.HTTPFlow) -> str:
    # H2 Request.authority/pretty_host decodes IDNA. Bindings use ASCII names;
    # use the already validated raw authority without rewriting the target.
    verified = flow.metadata.get(FLOW_H2_AUTHORITY_KEY)
    if verified is not None:
        return verified
    host = flow.request.pretty_host or flow.request.host or ""
    return host.rstrip(".").lower()


def _request_port(flow: http.HTTPFlow) -> int:
    if flow.request.port:
        return int(flow.request.port)
    return 443 if flow.request.scheme == "https" else 80


def _request_path(flow: http.HTTPFlow) -> str:
    path = flow.request.path or "/"
    return path.split("?", 1)[0] or "/"


_DOT_SEGMENT_RE = re.compile(r"/\.\.(/|$)")


def _path_is_ambiguous(raw_path: str, *, allow_encoded_slash: bool = False) -> bool:
    """Return True if the raw request path could decode to a different path
    than the one used for binding match (dot-segments, backslashes, or a
    percent-decode that never converges). Legitimate clients resolve dot
    segments before sending, so ``..`` on the wire is an attempt to confuse
    path-based authorization.

    ``allow_encoded_slash`` tolerates ``%2f`` at any percent-decoding depth
    on the client-supplied path (legit for npm scoped package registry paths
    like ``/@scope%2fname`` and artifact-store coordinate paths like
    ``pkg%252F1.0``). Whether an encoded slash is safe is decided by the
    complementary :func:`_path_decoding_changes_binding` check, which rejects
    a path whose decoding crosses an authorization boundary. Backslashes and
    dot-segments are always rejected at every decoding depth.
    """
    path = raw_path.split("?", 1)[0]

    # Only match ``..`` as a complete path segment (/../ or trailing /..).
    if _DOT_SEGMENT_RE.search(path):
        return True

    # Iteratively decode to catch nested encodings like %252e%252e. Decoding
    # only turns ``%xx`` escapes into literal characters, so anything that
    # appears at an intermediate depth survives to the fixpoint; checking the
    # fixpoint covers every depth.
    decoded = path
    for _ in range(10):
        lower = decoded.lower()
        if not allow_encoded_slash and "%2f" in lower:
            return True
        if "%5c" in lower:
            return True
        if "\\" in decoded:
            return True
        next_decoded = unquote(decoded)
        if next_decoded == decoded:
            break
        decoded = next_decoded
    else:
        # No fixpoint within the iteration bound: absurdly nested escapes on
        # a client path mean we cannot establish a canonical view; fail closed.
        return True
    if _DOT_SEGMENT_RE.search(decoded):
        return True

    return False


def _path_decoding_changes_binding(
    flow: http.HTTPFlow, vault: ActiveVault
) -> bool:
    """Return True if percent-decoding the raw path to any depth would change
    which credential binding matches (i.e. decoding crosses an authorization
    boundary).

    This is the credential-injection invariant: the binding selected on the
    raw wire path must be identical for every decode depth, so the injection
    decision does not depend on how many times any downstream processor
    decodes the path. Legit encoded uses — npm scoped package registry paths
    like ``/@scope%2fname`` or artifact-store coordinate paths like
    ``pkg%252F1.0`` — decode to a path matching the same binding, so they
    pass; crafted paths like ``/api/v8/projects/123%2f..%2f456/variables``
    are rejected before credential injection.
    """
    raw_path = _request_path(flow)

    # Collect every intermediate view from the raw path down to the decode
    # fixpoint, so the invariant holds no matter how many times an encoded
    # slash is nested (%2f, %252f, %25252f, ...).
    views = [raw_path]
    decoded = raw_path
    for _ in range(10):
        next_decoded = unquote(decoded)
        if next_decoded == decoded:
            break
        decoded = next_decoded
        views.append(decoded)

    if len(views) == 1:
        return False

    # If any decoded form contains dot-segments, treat it as ambiguous.
    for view in views[1:]:
        if _DOT_SEGMENT_RE.search(view):
            return True

    scheme = (flow.request.scheme or "").lower()
    host = _request_host(flow)
    port = _request_port(flow)
    method = (flow.request.method or "").upper()

    def _non_path_matches(binding: dict[str, Any]) -> bool:
        match = binding.get("match") or {}
        schemes = match.get("schemes") or ["https"]
        if scheme not in schemes:
            return False
        canonical_port = 443 if scheme == "https" else 80
        if port != canonical_port:
            return False
        methods = [m.upper() for m in (match.get("methods") or ["GET", "POST", "PUT", "PATCH", "DELETE"])]
        if method not in methods:
            return False
        for pattern in match.get("hosts") or []:
            ok, _ = _host_matches(host, pattern)
            if ok:
                return True
        return False

    def _matches_with_path(path: str) -> set[int]:
        matched: set[int] = set()
        for idx, binding in enumerate(vault.bindings):
            if not _non_path_matches(binding):
                continue
            paths = (binding.get("match") or {}).get("paths") or ["/*"]
            if any(_path_matches(path, p) for p in paths):
                matched.add(idx)
        return matched

    raw_matches = _matches_with_path(raw_path)
    return any(_matches_with_path(view) != raw_matches for view in views[1:])


def _host_matches(host: str, pattern: str) -> tuple[bool, int]:
    pattern = pattern.rstrip(".").lower()
    if pattern.startswith("*."):
        suffix = pattern[1:]
        apex = pattern[2:]
        return host.endswith(suffix) and host != apex, 1
    return host == pattern, 2


def _path_matches(path: str, pattern: str) -> bool:
    if pattern.endswith("*"):
        return path.startswith(pattern[:-1])
    return path == pattern


def _binding_matches(flow: http.HTTPFlow, binding: dict[str, Any]) -> tuple[bool, int]:
    match = binding.get("match") or {}
    scheme = (flow.request.scheme or "").lower()
    host = _request_host(flow)
    port = _request_port(flow)
    method = (flow.request.method or "").upper()
    path = _request_path(flow)

    schemes = match.get("schemes") or ["https"]
    if scheme not in schemes:
        return False, 0
    canonical_port = 443 if scheme == "https" else 80
    if port != canonical_port:
        return False, 0
    if method not in [m.upper() for m in (match.get("methods") or ["GET", "POST", "PUT", "PATCH", "DELETE"])]:
        return False, 0
    if not any(_path_matches(path, p) for p in (match.get("paths") or ["/*"])):
        return False, 0

    best_precedence = 0
    for pattern in match.get("hosts") or []:
        ok, precedence = _host_matches(host, pattern)
        if ok and precedence > best_precedence:
            best_precedence = precedence
    return best_precedence > 0, best_precedence


def _request_may_be_streamed(flow: http.HTTPFlow) -> bool:
    """True if mitmproxy may enable request-body streaming for this flow.

    Streaming is enabled whenever the body is expected to exceed
    ``stream_large_bodies`` (1 MiB), either up front (known Content-Length)
    or mid-upload once buffered bytes cross the threshold (chunked or
    HTTP/2 bodies without Content-Length). A local response cannot be served
    for such flows (mitmproxy 11.0.2 raises ``NotImplementedError``), so
    they must be killed instead.
    """
    if getattr(flow.request, "stream", False):
        return True
    if "content-length" in flow.request.headers:
        return False
    if (flow.request.http_version or "").upper().startswith("HTTP/2"):
        return True
    return "transfer-encoding" in flow.request.headers


def _reject_request(
    flow: http.HTTPFlow,
    body: bytes,
    status_code: int = 403,
) -> None:
    """Terminate a request before it is forwarded upstream.

    mitmproxy 11.0.2 refuses to serve a locally-set response while a request
    body is being streamed: ``start_request_stream`` raises
    ``NotImplementedError`` once ``flow.response`` is set, and streaming is
    enabled as soon as a body is known to exceed ``stream_large_bodies``
    (1 MiB) — either up front via Content-Length or mid-upload for chunked
    bodies. A local response is therefore only safe when the body size is
    fully known; otherwise the flow is killed, which closes the client
    connection without forwarding anything.
    """
    flow.metadata[FLOW_REJECTION_KEY] = True
    if _request_may_be_streamed(flow):
        if flow.killable:
            flow.kill()
        return
    flow.response = http.Response.make(status_code, body, {"content-type": "text/plain"})


def _flow_rejected(flow: http.HTTPFlow) -> bool:
    """True if the flow was terminated by :func:`_reject_request`."""
    return bool(flow.metadata.get(FLOW_REJECTION_KEY))


def _select_binding(flow: http.HTTPFlow, vault: ActiveVault) -> dict[str, Any] | None:
    matches: list[tuple[int, dict[str, Any]]] = []
    for binding in vault.bindings:
        ok, precedence = _binding_matches(flow, binding)
        if ok:
            matches.append((precedence, binding))
    if not matches:
        return None

    highest = max(precedence for precedence, _ in matches)
    selected = [binding for precedence, binding in matches if precedence == highest]
    if len(selected) != 1:
        _reject_request(flow, b"credential binding ambiguous\n")
        ctx.log.warn(
            "credential proxy: ambiguous binding match for "
            f"{flow.request.method} {_request_host(flow)}{_request_path(flow)}"
        )
        return None
    return selected[0]


def _split_path_query(raw_path: str) -> tuple[str, str | None]:
    if "?" not in raw_path:
        return raw_path or "/", None
    path, query = raw_path.split("?", 1)
    return path or "/", query


def _request_body_bytes(flow: http.HTTPFlow) -> bytes | None:
    body = getattr(flow.request, "raw_content", None)
    if body is None:
        body = getattr(flow.request, "content", None)
    if body is None:
        return None
    if isinstance(body, str):
        return body.encode("utf-8")
    return body


def _set_request_body_bytes(flow: http.HTTPFlow, body: bytes) -> None:
    flow.request.content = body
    if "transfer-encoding" in flow.request.headers:
        del flow.request.headers["transfer-encoding"]
    flow.request.headers["content-length"] = str(len(body))


def _encoded_substitution_value(value: str, surface: str, content_type: str = "") -> str:
    if surface in {"path", "query"}:
        return quote(value, safe="")
    if surface == "body":
        normalized_type = content_type.split(";", 1)[0].strip().lower()
        if normalized_type == "application/json" or normalized_type.endswith("+json"):
            return json.dumps(value)[1:-1]
        if normalized_type == "application/x-www-form-urlencoded":
            return quote_plus(value, safe="")
    return value


def _replace_literals_once(text: str, replacements: list[tuple[str, str]]) -> tuple[str, list[int]]:
    # Apply replacements against the original text so inserted credential values
    # are never scanned again for later placeholders.
    if not replacements:
        return text, []

    parts: list[str] = []
    applied: list[int] = []
    applied_set: set[int] = set()
    i = 0
    while i < len(text):
        selected_index = -1
        selected_placeholder = ""
        selected_replacement = ""
        for index, (placeholder, replacement) in enumerate(replacements):
            if len(placeholder) <= len(selected_placeholder):
                continue
            if text.startswith(placeholder, i):
                selected_index = index
                selected_placeholder = placeholder
                selected_replacement = replacement
        if selected_index >= 0:
            parts.append(selected_replacement)
            if selected_index not in applied_set:
                applied.append(selected_index)
                applied_set.add(selected_index)
            i += len(selected_placeholder)
            continue
        parts.append(text[i])
        i += 1

    if not applied:
        return text, []
    return "".join(parts), applied


def _substitution_replacements(
    substitutions: list[dict[str, Any]], surface: str, content_type: str = ""
) -> list[tuple[str, str]]:
    replacements: list[tuple[str, str]] = []
    for substitution in substitutions:
        placeholder = substitution.get("placeholder")
        value = substitution.get("value")
        surfaces = substitution.get("in") or []
        if not placeholder or value is None or surface not in surfaces:
            continue
        replacements.append(
            (
                str(placeholder),
                _encoded_substitution_value(str(value), surface, content_type),
            )
        )
    return replacements


def _apply_path_query_substitutions(
    flow: http.HTTPFlow,
    substitutions: list[dict[str, Any]],
) -> list[str]:
    raw_path = flow.request.path or "/"
    path_part, query_part = _split_path_query(raw_path)
    path_changed = False
    query_changed = False
    applied: list[str] = []

    path_part, path_applied = _replace_literals_once(
        path_part, _substitution_replacements(substitutions, "path")
    )
    if path_applied:
        path_changed = True
        applied.extend("path" for _ in path_applied)
    if query_part is not None:
        query_part, query_applied = _replace_literals_once(
            query_part, _substitution_replacements(substitutions, "query")
        )
        if query_applied:
            query_changed = True
            applied.extend("query" for _ in query_applied)

    if path_changed:
        candidate_path = path_part
        if query_part is not None:
            candidate_path = f"{candidate_path}?{query_part}"
        if _path_is_ambiguous(candidate_path):
            _reject_request(
                flow, b"request path contains ambiguous substituted segments\n"
            )
            ctx.log.warn(
                "credential proxy: rejected request after path substitution: "
                f"{flow.request.method} {_request_host(flow)} path=[REDACTED]"
            )
            return applied

    if path_changed or query_changed:
        flow.request.path = path_part if query_part is None else f"{path_part}?{query_part}"
    return applied


def _apply_header_substitutions(
    flow: http.HTTPFlow,
    substitutions: list[dict[str, Any]],
) -> list[str]:
    applied: list[str] = []
    replacements = _substitution_replacements(substitutions, "header")
    if not replacements:
        return applied
    for name, header_value in list(flow.request.headers.items()):
        if name.lower() in HEADER_SUBSTITUTION_DENYLIST:
            continue
        updated, header_applied = _replace_literals_once(str(header_value), replacements)
        if header_applied:
            flow.request.headers[name] = updated
            applied.extend("header" for _ in header_applied)
    return applied


def _apply_body_substitutions(
    flow: http.HTTPFlow,
    substitutions: list[dict[str, Any]],
) -> list[str]:
    body = _request_body_bytes(flow)
    if body is None:
        return []

    content_encoding = flow.request.headers.get("content-encoding", "").strip().lower()
    if content_encoding and content_encoding != "identity":
        return []

    content_type = flow.request.headers.get("content-type", "")
    if content_type.split(";", 1)[0].strip().lower().startswith("multipart/"):
        return []

    try:
        text = body.decode("utf-8")
    except UnicodeDecodeError:
        return []

    applied: list[str] = []
    replacements = _substitution_replacements(substitutions, "body", content_type)
    text, body_applied = _replace_literals_once(text, replacements)
    applied.extend("body" for _ in body_applied)

    if applied:
        _set_request_body_bytes(flow, text.encode("utf-8"))
    return applied


def _apply_requestheaders_substitutions(flow: http.HTTPFlow, binding: dict[str, Any]) -> list[str]:
    """Path/query/header substitutions (body not read yet at this stage)."""
    substitutions = binding.get("substitutions") or []
    if not substitutions:
        return []

    applied = []
    applied.extend(_apply_path_query_substitutions(flow, substitutions))
    if _flow_rejected(flow):
        return applied
    applied.extend(_apply_header_substitutions(flow, substitutions))
    return applied


def _has_substitutions_on(binding: dict[str, Any], surfaces: set[str]) -> bool:
    return any(
        surface in surfaces
        for substitution in (binding.get("substitutions") or [])
        for surface in (substitution.get("in") or [])
    )


def _flow_client_ip(flow: http.HTTPFlow) -> str | None:
    try:
        client_conn = getattr(flow, "client_conn", None)
        if client_conn is None:
            return None
        return client_conn.peername[0]
    except Exception:  # noqa: BLE001 - defensive; missing peername means no dispatch key
        return None


def _connection_sni(flow: http.HTTPFlow) -> str | None:
    """Normalized SNI of the transport that carried this request, if any."""
    sni = getattr(getattr(flow, "client_conn", None), "sni", None)
    if not isinstance(sni, str) or not sni:
        return None
    return sni.lower().removesuffix(".")


_H1_AUTHORITY_FORBIDDEN_RE = re.compile(r"[\x00-\x20\x7f,@/\\?#%]")


def _parse_h1_authority(value: Any) -> tuple[str, int] | None:
    """Parse one Host/absolute-target authority into (normalized host, port).

    Strict HTTP/1 identity semantics for the live credential-bound mode: no
    whitespace, controls, comma, userinfo, slash, backslash, query, fragment
    or percent-encoded authority; at most one optional numeric port. DNS
    names normalize like vault hosts (ASCII lowercase with one optional
    trailing root dot). Returns None on any violation.
    """
    if type(value) is not str or not value or not value.isascii():
        return None
    if _H1_AUTHORITY_FORBIDDEN_RE.search(value):
        return None
    if value.count(":") > 1:
        return None
    host, separator, port_text = value.partition(":")
    port = 443
    if separator:
        if (
            not port_text
            or not port_text.isdecimal()
            or (port_text[0] == "0" and len(port_text) > 1)
            or len(port_text) > 5
        ):
            return None
        port = int(port_text)
        if not 1 <= port <= 65535:
            return None
    host = host.lower().removesuffix(".")
    if (
        not host
        or _active_vault_host_is_ip(host)
        or not _active_vault_host_is_fqdn(host)
    ):
        return None
    return host, port


def _live_h1_authority(flow: http.HTTPFlow) -> str | None:
    """Validate the HTTP/1 identity of one decrypted live request.

    Returns the normalized authority host, or None when the request must be
    denied: a non-HTTP/1 version (H2 has a separate raw-identity gate),
    CONNECT authority-form inside a decrypted stream, a non-443 target,
    missing/duplicate/malformed Host, or an absolute-target authority that
    disagrees with Host. Transparent-mode ``data.host`` may be an IP, so the
    transport destination is never compared here — only HTTP identity.
    """
    request = flow.request
    version = (request.http_version or "").upper()
    if version not in ("HTTP/1.0", "HTTP/1.1"):
        return None
    if (request.method or "").upper() == "CONNECT":
        return None
    if int(request.port or 0) != 443:
        return None
    try:
        hosts = request.headers.get_all("host")
    except Exception:  # noqa: BLE001 - a headers object without get_all denies
        return None
    if not isinstance(hosts, (list, tuple)) or len(hosts) != 1:
        return None
    parsed = _parse_h1_authority(hosts[0])
    if parsed is None:
        return None
    host, port = parsed
    if port != 443:
        return None
    # Prefer the raw wire authority bytes: request.authority applies IDNA
    # decoding, which would turn valid ASCII punycode into Unicode before
    # the strict ASCII parse. Fake requests without .data fall back to the
    # property value.
    authority: Any = None
    data = getattr(request, "data", None)
    raw_authority = getattr(data, "authority", None) if data is not None else None
    if isinstance(raw_authority, (bytes, bytearray, memoryview)):
        try:
            authority = bytes(raw_authority).decode("ascii")
        except UnicodeDecodeError:
            return None
    elif raw_authority is not None:
        authority = raw_authority
    elif data is None:
        authority = getattr(request, "authority", None)
    if authority:
        try:
            absolute = _parse_h1_authority(authority)
        except Exception:  # noqa: BLE001 - an unparseable authority denies
            return None
        if absolute is None or absolute != (host, port):
            return None
    return host


def _live_h2_authority(flow: http.HTTPFlow, identity: Any, adapter: Any) -> str | None:
    """Validate raw inbound identity, never transparent-mode rewritten identity."""
    request = flow.request
    if (request.http_version or "").upper() not in ("HTTP/2", "HTTP/2.0"):
        return None
    raw = identity.headers
    if type(raw) is not tuple or any(
        type(item) is not tuple or len(item) != 2
        or type(item[0]) is not bytes or type(item[1]) is not bytes
        for item in raw
    ):
        return None
    schemes = [value for name, value in raw if name == b":scheme"]
    authorities = [value for name, value in raw if name == b":authority"]
    methods = [value for name, value in raw if name == b":method"]
    hosts = [value for name, value in raw if name == b"host"]
    if (
        schemes != [b"https"] or len(authorities) != 1 or len(methods) != 1
        or methods[0].upper() == b"CONNECT" or not methods[0]
        or any(name == b":protocol" for name, _ in raw) or len(hosts) > 1
    ):
        return None
    target = adapter.http_layer.context.server
    address = target.address
    if (
        not address or type(address[1]) is not int or address[1] != 443
        or not target.tls or int(request.port or 0) != 443
    ):
        return None
    try:
        authority = _parse_h1_authority(authorities[0].decode("ascii"))
        host = _parse_h1_authority(hosts[0].decode("ascii")) if hosts else authority
    except UnicodeDecodeError:
        return None
    if authority is None or authority[1] != 443 or host != authority:
        return None
    return authority[0]


def _abort_live_h2(live: Any, flow: http.HTTPFlow, adapter: Any = None) -> None:
    """An invariant failure is never advertised as retryable refusal."""
    flow.metadata[FLOW_REJECTION_KEY] = True
    if adapter is not None:
        adapter.fail_closed()
    else:
        live._close_established(getattr(flow, "client_conn", None))
    if flow.killable:
        flow.kill()


def _requestheaders_live_h2(live: Any, flow: http.HTTPFlow) -> None:
    client = getattr(flow, "client_conn", None)
    adapter = live.h2_for(client)
    token = live.token_for(client)
    if (
        adapter is None or token is None or adapter.token is not token
        or getattr(ctx.options, "ssl_insecure", False)
        or getattr(getattr(flow, "server_conn", None), "via", None) is not None
        or getattr(adapter.http_layer.context.server, "via", None) is not None
    ):
        _abort_live_h2(live, flow, adapter)
        return
    try:
        identity = adapter.consume_identity(flow.request)
        if identity is None:
            if adapter.request_is_closed(flow.request):
                if flow.killable:
                    flow.kill()
                return
            _abort_live_h2(live, flow, adapter)
            return
        admission = live.acquire_request(token, client_stream_id=identity.stream_id)
    except Exception:  # noqa: BLE001 - do not expose identity or snapshot errors
        _abort_live_h2(live, flow, adapter)
        return
    if admission.action != "allow" or admission.handle is None:
        if admission.reason in ("connection_fenced", "request_registry_exhausted"):
            adapter.refuse(identity, flow)
        else:
            _abort_live_h2(live, flow, adapter)
        return
    handle = admission.handle
    flow.metadata[FLOW_REQUEST_HANDLE_KEY] = handle
    try:
        adapter.bind_request(identity, flow, handle)
        authority = _live_h2_authority(flow, identity, adapter)
    except Exception:  # noqa: BLE001 - retain admitted handle until abnormal teardown
        _abort_live_h2(live, flow, adapter)
        return
    if authority is None or authority != _connection_sni(flow) or authority != token.sni:
        _abort_live_h2(live, flow, adapter)
        ctx.log.warn("credential proxy: rejected invalid H2 request authority")
        return
    flow.metadata[FLOW_H2_AUTHORITY_KEY] = authority
    try:
        vault = _live_snapshot_vault(admission.snapshot)
    except ActiveVaultLookupError:
        # This handle still protects downstream/upstream output obligations.
        _abort_live_h2(live, flow, adapter)
        ctx.log.warn("credential proxy: admitted snapshot failed validation; request denied")
        return
    _observe_tls_shadow(flow, vault)
    if vault is not None:
        _apply_vault_binding(flow, vault, live=live)


def _finish_live_request(flow: http.HTTPFlow) -> None:
    """H1 hooks finish immediately; H2 retains transport output obligations."""
    handle = flow.metadata.get(FLOW_REQUEST_HANDLE_KEY)
    live = _live_runtime
    if handle is not None and live is not None:
        if getattr(handle, "client_stream_id", None) is not None:
            adapter = live.h2_for(getattr(flow, "client_conn", None))
            if adapter is not None:
                adapter.application_done(flow)
            else:
                _abort_live_h2(live, flow)
            return
        flow.metadata.pop(FLOW_REQUEST_HANDLE_KEY, None)
        live.finish_request(handle)


def _observe_tls_shadow(
    flow: http.HTTPFlow, vault: ActiveVault | None, *, lookup_failed: bool = False
) -> None:
    if not _tls_shadow_enabled:
        return
    try:
        if flow.request.scheme != "https" or flow.request.port != 443:
            return
        from tls_shadow import project

        sni = getattr(getattr(flow, "client_conn", None), "sni", None)
        outcome = project(
            sni, None if vault is None else vault.bindings, lookup_failed=lookup_failed
        )
        if _fast_sandbox_mode_enabled and vault is None and not lookup_failed:
            # Fast Sandbox 404 also means unknown source identity, not just no vault.
            outcome = "unknown_subject_or_vault"
        # Fixed vocabulary only: no hostname, revision, subject, path, or secret.
        ctx.log.warn("credential proxy: tls-shadow " + outcome)
    except Exception:  # noqa: BLE001 - diagnostics must never change traffic
        with suppress(Exception):
            ctx.log.warn("credential proxy: tls-shadow observer_error")


def _requestheaders_pull(flow: http.HTTPFlow) -> Awaitable[None] | None:
    """Pull-mode processing; returns an awaitable only when an exchange
    binding defers its resolve I/O to the caller."""
    try:
        vault = _load_active_vault(_flow_client_ip(flow))
    except ActiveVaultLookupError as exc:
        _observe_tls_shadow(flow, None, lookup_failed=True)
        ctx.log.warn(f"credential proxy: {exc}; request denied")
        _reject_request(
            flow,
            b"credential proxy unavailable\n",
            status_code=503,
        )
        return None
    _observe_tls_shadow(flow, vault)
    if vault is None:
        return None
    return _apply_vault_binding(flow, vault)


async def requestheaders(flow: http.HTTPFlow) -> None:
    """Credential proxy phase 1: binding match and request metadata rewrite.

    Header injection must happen here, before the upstream connection is
    made: with ``stream_large_bodies=1m`` the ``request`` hook fires only
    after a body above 1 MiB has been streamed upstream.

    In live credential-bound mode the vault comes from the admitted decision
    snapshot (see :func:`_requestheaders_live`) instead of the pull cache.

    The hook is async because mitmproxy awaits it before the request
    continues: exchange bindings defer resolve I/O to the single await
    below; static and live paths stay inline and never suspend.
    """
    live = _live_runtime
    if live is not None:
        _requestheaders_live(live, flow)
        return
    deferred = _requestheaders_pull(flow)
    if deferred is not None:
        await deferred


def _requestheaders_live(live: Any, flow: http.HTTPFlow) -> None:
    """Authorize one request against the admitted revision snapshot.

    Only HTTPS carries live admission; plain HTTP receives no injected
    credentials. Tracked H2 must first validate raw identity even if transparent
    rewriting changed the visible scheme. Every request on a decrypted connection
    must acquire request admission; a fenced connection (removed host, drained
    revision) is rejected and never falls back to the retired snapshot.
    """
    client = getattr(flow, "client_conn", None)
    if (
        getattr(client, "alpn", None) == b"h2"
        or (flow.request.http_version or "").upper() in ("HTTP/2", "HTTP/2.0")
    ):
        # Genuine cleartext H2 remains outside credential admission. Scheme
        # alone cannot establish that: tracked/decrypted H2 must validate its
        # captured raw identity even after another hook rewrites the scheme.
        if (getattr(client, "tls", None) is False
                and getattr(client, "alpn", None) is None
                and live.token_for(client) is None and live.h2_for(client) is None
                and (flow.request.scheme or "").lower() == "http"):
            return
        _requestheaders_live_h2(live, flow)
        return
    if (flow.request.scheme or "").lower() != "https":
        return
    # Per-request defense: insecure upstream verification must never be
    # effective in live mode. Deny instead of injecting into or tunneling a
    # bound request toward an unverified origin.
    if getattr(ctx.options, "ssl_insecure", False):
        _reject_request(flow, b"credential proxy unavailable\n", status_code=503)
        ctx.log.warn("credential proxy: request denied reason=ssl_insecure")
        return
    token = live.token_for(getattr(flow, "client_conn", None))
    admission = None if token is None else live.acquire_request(token)
    handle = None
    if admission is not None and admission.action == "allow":
        handle = admission.handle
        flow.metadata[FLOW_REQUEST_HANDLE_KEY] = handle
    if handle is None:
        reason = "no_connection_admission" if admission is None else admission.reason
        status_code = 403 if reason == "connection_fenced" else 503
        _reject_request(flow, b"credential proxy unavailable\n", status_code=status_code)
        if flow.response is not None:
            # Fenced transports stop accepting new requests: tell HTTP/1.1
            # keepalive clients this connection is finished.
            flow.response.headers["connection"] = "close"
        ctx.log.warn(f"credential proxy: request denied reason={reason}")
        return

    # HTTP/1 identity gate, applied to every decrypted request before any
    # binding selection: the validated authority must equal both the
    # connection SNI and the immutable admission token SNI, so a credential
    # can only reach the verified TLS peer. Cross-authority requests on
    # out-of-scope paths are denied just the same.
    authority_host = _live_h1_authority(flow)
    connection_sni = _connection_sni(flow)
    if (
        authority_host is None
        or connection_sni is None
        or authority_host != connection_sni
        or authority_host != token.sni
    ):
        _reject_request(
            flow,
            b"request authority does not match the intercepted destination\n",
            status_code=403,
        )
        ctx.log.warn("credential proxy: rejected invalid or cross-authority request")
        return

    try:
        vault = _live_snapshot_vault(admission.snapshot)
    except ActiveVaultLookupError:
        flow.metadata.pop(FLOW_REQUEST_HANDLE_KEY, None)
        live.finish_request(handle)
        _reject_request(flow, b"credential proxy unavailable\n", status_code=503)
        ctx.log.warn("credential proxy: admitted snapshot failed validation; request denied")
        return
    _observe_tls_shadow(flow, vault)
    if vault is None:
        return
    _apply_vault_binding(flow, vault, live=live)


def _live_snapshot_vault(snapshot: Any) -> ActiveVault | None:
    """Convert an admitted immutable snapshot into the binding view.

    Returns None for an authoritative snapshot without rendered bindings
    (no credential can match). Raises ActiveVaultLookupError for any payload
    that does not exactly reconstruct the validated envelope, which fails the
    request closed instead of forwarding it uncredentialed by accident.

    Only call after successful request admission and authority checks. The
    receiver has already verified the immutable payload's digest; memoizing
    its parsed view never caches the admission or rehashes the payload.
    """
    global _live_vault_cache
    identity = snapshot.revision
    cached = _live_vault_cache
    if cached is not None and cached[0] == identity:
        return cached[1]
    # A miss drops the owner's old view even if decoding or validation fails.
    _live_vault_cache = None
    try:
        payload = json.loads(snapshot.payload)
    except Exception:  # noqa: BLE001 - payload bytes may contain credentials
        raise ActiveVaultLookupError("admitted snapshot could not be decoded") from None
    if not isinstance(payload, dict):
        raise ActiveVaultLookupError("admitted snapshot must be an object")
    revision = snapshot.revision.vault_revision
    if type(revision) is not int or payload.get("vaultRevision") != revision:
        raise ActiveVaultLookupError("admitted snapshot revision disagreement")
    state = payload.get("state")
    bindings = payload.get("fullRenderedBindings")
    if state == "active-empty":
        if bindings:
            raise ActiveVaultLookupError("admitted snapshot state disagreement")
        _live_vault_cache = (identity, None)
        return None
    if state != "active" or not isinstance(bindings, list) or not bindings:
        raise ActiveVaultLookupError("admitted snapshot has no rendered bindings")
    redactions = payload.get("redactions", [])
    if not isinstance(redactions, list):
        raise ActiveVaultLookupError("admitted snapshot redactions are invalid")
    vault = _parse_active_vault(
        {"revision": revision, "bindings": bindings, "redactions": redactions}
    )
    _live_vault_cache = (identity, vault)
    return vault


def _reject_ambiguous_binding_path(
    flow: http.HTTPFlow, vault: ActiveVault
) -> bool:
    """Shared path gate for static and exchange injection: reject ambiguous
    or boundary-crossing encodings so a secret never reaches a scope the
    canonical path does not match. Returns True when rejected."""
    raw_path = flow.request.path or "/"
    if _path_is_ambiguous(raw_path, allow_encoded_slash=True):
        _reject_request(flow, b"request path contains ambiguous segments\n")
        ctx.log.warn(
            "credential proxy: rejected request with ambiguous path: "
            f"{flow.request.method} {_request_host(flow)}{_request_path(flow)}"
        )
        return True
    if _path_decoding_changes_binding(flow, vault):
        _reject_request(flow, b"request path contains ambiguous segments\n")
        ctx.log.warn(
            "credential proxy: rejected request whose percent-decoding crosses "
            "the credential binding boundary: "
            f"{flow.request.method} {_request_host(flow)}{_request_path(flow)}"
        )
        return True
    return False


def _apply_vault_binding(
    flow: http.HTTPFlow, vault: ActiveVault, live: Any | None = None
) -> Awaitable[None] | None:
    """Shared binding selection, ambiguity checks and credential injection.

    Returns an awaitable only for pull-mode exchange bindings (their resolve
    I/O must complete before the request continues)."""
    # Requests outside credential binding scope are ordinary egress traffic.
    # Leave them untouched, including paths whose encoding would be ambiguous
    # for credential injection, because no secret is at risk.
    binding = _select_binding(flow, vault)
    if not binding:
        return None

    if "exchange" in binding:
        return _apply_exchange_binding(flow, vault, binding, live)

    if _reject_ambiguous_binding_path(flow, vault):
        return None

    flow.metadata[FLOW_BINDING_KEY] = binding
    # Persist the redactions of the matched revision: body substitutions run
    # later in the request hook, and reloading the vault there could return a
    # different revision after a runtime mutation, leaving substituted
    # credentials unredactable in response headers.
    flow.metadata[FLOW_VAULT_REDACTIONS_KEY] = list(vault.redactions)

    substituted_surfaces = _apply_requestheaders_substitutions(flow, binding)
    if _flow_rejected(flow):
        return None

    injected_names: list[str] = []
    for header in binding.get("headers") or []:
        name = header.get("name")
        value = header.get("value")
        if not name or value is None:
            continue
        # mitmproxy Headers is case-insensitive; delete first to avoid duplicate
        # effective header names before setting the credentialed value.
        if name in flow.request.headers:
            del flow.request.headers[name]
        flow.request.headers[name] = value
        injected_names.append(name)

    if injected_names or substituted_surfaces:
        flow.metadata[FLOW_REDACTIONS_KEY] = list(flow.metadata[FLOW_VAULT_REDACTIONS_KEY])
        ctx.log.info(
            "credential proxy: applied binding="
            f"{binding.get('name')} revision={vault.revision} "
            f"host={_request_host(flow)} method={flow.request.method} "
            f"headers={','.join(injected_names)} "
            f"substitutions={','.join(sorted(set(substituted_surfaces)))}"
        )
    elif _has_substitutions_on(binding, {"path", "query", "header"}):
        ctx.log.info(
            "credential proxy: substitution miss binding="
            f"{binding.get('name')} revision={vault.revision} "
            f"host={_request_host(flow)} method={flow.request.method}"
        )
    return None


def _apply_exchange_binding(
    flow: http.HTTPFlow,
    vault: ActiveVault,
    binding: dict[str, Any],
    live: Any | None,
) -> Awaitable[None] | None:
    """Gate one exchange binding, then defer its resolve I/O.

    Live snapshots never carry exchange (the egress admission gate rejects
    them); the defensive branch stays fail closed."""
    if live is not None:
        _reject_request(flow, b"credential exchange unavailable\n", status_code=503)
        ctx.log.warn(
            "credential proxy: exchange binding unsupported binding="
            f"{binding.get('name')}"
        )
        return None
    if _reject_ambiguous_binding_path(flow, vault):
        return None
    sni = _connection_sni(flow)
    if sni is None:
        # Without a connection SNI the egress SNI gate can never pass.
        _reject_request(
            flow, b"credential resolution unavailable\n", status_code=407
        )
        ctx.log.warn(
            "credential proxy: exchange binding without connection sni was denied"
        )
        return None
    return _resolve_exchange_binding(flow, vault, binding, sni)


async def _resolve_exchange_binding(
    flow: http.HTTPFlow,
    vault: ActiveVault,
    binding: dict[str, Any],
    sni: str,
) -> None:
    """Resolve on the active socket and inject headers.

    I/O runs in a worker thread behind the semaphore so a slow resolver
    never blocks the loop; any failure fails closed (407/kill). Results
    live only in flow metadata."""
    name = binding.get("name")
    path = CREDENTIAL_RESOLVE_PATH
    client_ip = _flow_client_ip(flow)
    if _fast_sandbox_mode_enabled:
        if not client_ip:
            _reject_request(
                flow, b"credential resolution unavailable\n", status_code=407
            )
            ctx.log.warn(
                "credential proxy: exchange resolve denied reason=missing_client_ip"
            )
            return
        path = f"{CREDENTIAL_RESOLVE_PATH}?clientIp={quote(client_ip)}"
    socket_path = (
        os.environ.get(CREDENTIAL_PROXY_SOCKET_ENV, "").strip()
        or DEFAULT_CREDENTIAL_PROXY_SOCKET
    )
    payload = {
        "binding": name,
        "sni": sni,
        "request": {
            "scheme": (flow.request.scheme or "").lower(),
            "host": _request_host(flow),
            "port": _request_port(flow),
            "method": (flow.request.method or "").upper(),
            "path": flow.request.path or "/",
        },
    }
    budget = _resolve_budget_seconds()
    try:
        deadline = time.monotonic() + budget
        async with _resolve_limiter():
            # The deadline covers semaphore and executor queueing too, not
            # just the socket: a queued resolve fails within the budget
            # instead of stacking timeout batches behind a slow resolver.
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                raise CredentialResolveError("deadline")
            decision = await asyncio.wait_for(
                asyncio.to_thread(
                    _resolve_exchange_http,
                    socket_path,
                    remaining,
                    path,
                    payload,
                ),
                timeout=remaining,
            )
        _install_exchange_headers(flow, vault, binding, decision)
    except CredentialResolveError as error:
        _reject_request(
            flow, b"credential resolution unavailable\n", status_code=407
        )
        ctx.log.warn(
            f"credential proxy: exchange resolve failed binding={name} "
            f"reason={error}"
        )
        return
    except asyncio.TimeoutError:
        _reject_request(
            flow, b"credential resolution unavailable\n", status_code=407
        )
        ctx.log.warn(
            f"credential proxy: exchange resolve failed binding={name} "
            "reason=deadline"
        )
        return
    except Exception:  # noqa: BLE001 - unexpected failures fail closed too
        _reject_request(
            flow, b"credential resolution unavailable\n", status_code=407
        )
        ctx.log.warn(
            f"credential proxy: exchange resolve failed binding={name} "
            "reason=unexpected"
        )
        return


def _install_exchange_headers(
    flow: http.HTTPFlow,
    vault: ActiveVault,
    binding: dict[str, Any],
    decision: dict[str, Any],
) -> None:
    """Inject resolved headers and persist per-request redaction metadata.

    Variants of every injected value are re-derived (R9) and injected names
    always join the suppress set (D7), so redaction never depends on
    resolver output completeness."""
    injected_names: list[str] = []
    for header in decision["headers"]:
        name = header["name"]
        # Delete-then-set, as static injection: the resolved value must be
        # the only one.
        if name in flow.request.headers:
            del flow.request.headers[name]
        flow.request.headers[name] = header["value"]
        injected_names.append(name)
    flow.metadata[FLOW_BINDING_KEY] = binding
    redactions = list(vault.redactions)
    redactions.extend(decision["redactions"])
    for header in decision["headers"]:
        redactions.extend(
            _active_snapshot_substitution_redaction_variants(header["value"])
        )
    flow.metadata[FLOW_VAULT_REDACTIONS_KEY] = redactions
    flow.metadata[FLOW_REDACTIONS_KEY] = list(redactions)
    suppress = set(decision["suppressHeaders"])
    suppress.update(name.lower() for name in injected_names)
    flow.metadata[FLOW_VAULT_SUPPRESS_KEY] = sorted(suppress)
    ctx.log.info(
        "credential proxy: applied binding="
        f"{binding.get('name')} revision={decision['revision']} "
        f"host={_request_host(flow)} method={flow.request.method} "
        f"headers={','.join(injected_names)} exchange=1"
    )


def request(flow: http.HTTPFlow) -> None:
    """Credential proxy phase 2: body substitutions.

    Needs the full body, so it cannot run in ``requestheaders``. Streamed
    requests are skipped: the body was already forwarded upstream and is no
    longer available or modifiable.
    """
    binding = flow.metadata.get(FLOW_BINDING_KEY)
    if binding is None:
        return
    if getattr(flow.request, "stream", False):
        return

    applied = _apply_body_substitutions(flow, binding.get("substitutions") or [])
    if applied:
        if FLOW_REDACTIONS_KEY not in flow.metadata:
            flow.metadata[FLOW_REDACTIONS_KEY] = list(
                flow.metadata.get(FLOW_VAULT_REDACTIONS_KEY, [])
            )
        ctx.log.info(
            "credential proxy: applied body substitutions binding="
            f"{binding.get('name')} host={_request_host(flow)} "
            f"method={flow.request.method}"
        )
    elif FLOW_REDACTIONS_KEY not in flow.metadata and _has_substitutions_on(
        binding, {"body"}
    ):
        ctx.log.info(
            "credential proxy: substitution miss binding="
            f"{binding.get('name')} host={_request_host(flow)} "
            f"method={flow.request.method}"
        )


def responseheaders(flow: http.HTTPFlow) -> None:
    if flow.response is None:
        return
    _suppress_response_headers(flow)
    _redact_response_headers(flow)
    content_type = flow.response.headers.get("content-type", "").lower()
    transfer_encoding = flow.response.headers.get("transfer-encoding", "").lower()
    if "text/event-stream" in content_type or "chunked" in transfer_encoding:
        flow.response.stream = True


def response(flow: http.HTTPFlow) -> None:
    """Record application completion; H2 output and upgraded transports persist."""
    if (
        FLOW_REQUEST_HANDLE_KEY in flow.metadata
        and flow.response is not None
        and flow.response.status_code == 101
    ):
        # WebSocket and raw protocol upgrades outlive the HTTP response hook.
        # Keep the handle so rotation assigns a retirement deadline even if
        # the host stays bound. client_disconnected releases it with the token.
        return
    _finish_live_request(flow)


def error(flow: http.HTTPFlow) -> None:
    """Record failure; H2 retains its handle until transport obligations end."""
    _finish_live_request(flow)


def client_disconnected(client_conn: Any) -> None:
    """Release the transport's live admission on confirmed disconnect."""
    live = _live_runtime
    if live is not None:
        live.client_disconnected(client_conn)


def _suppress_response_headers(flow: http.HTTPFlow) -> None:
    """Delete by-name suppressed response headers; the set was validated at
    resolve time and every occurrence is removed."""
    suppress = flow.metadata.get(FLOW_VAULT_SUPPRESS_KEY)
    if not suppress or flow.response is None:
        return
    suppressed = {name.lower() for name in suppress}
    for name in {name.lower() for name, _ in flow.response.headers.items()}:
        if name in suppressed:
            del flow.response.headers[name]


def _redact_response_headers(flow: http.HTTPFlow) -> None:
    redactions = flow.metadata.get(FLOW_REDACTIONS_KEY, [])
    if not redactions or flow.response is None:
        return
    for name, value in list(flow.response.headers.items()):
        redacted = _redact_text(value, redactions)
        if redacted != value:
            flow.response.headers[name] = redacted


def _redact_text(text: str, values: list[str]) -> str:
    out = text
    for value in sorted({value for value in values if value}, key=len, reverse=True):
        out = out.replace(value, "[REDACTED]")
    return out