Skip to content

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

feat(egress): OSEP-0025 T3b — addon exchange resolve integration

高然4b826e9a31ae
diff --git a/components/egress/mitmscripts/system.py b/components/egress/mitmscripts/system.py
index 9fc771015..4a7fa20b4 100644
--- a/components/egress/mitmscripts/system.py
+++ b/components/egress/mitmscripts/system.py
@@ -28,6 +28,13 @@
# 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 an `exchange: {credential}`
+# marker in the snapshot: the async `requestheaders` hook resolves them
+# per request on the active socket `_resolve` endpoint (real I/O runs in
+# a worker thread behind a concurrency semaphore), injects the returned
+# headers, and fails closed — 407 for buffered requests, kill for
+# streamed ones — on any resolve failure. Static bindings keep running
+# fully inline inside the same hook and never suspend it.
# 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
@@ -60,6 +67,7 @@
# 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
@@ -79,9 +87,25 @@ if TYPE_CHECKING:
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"
+# The Go egress owns the resolver budget (seconds, 1..120, default 2 — mirror
+# of pkg/constants + ResolverTimeoutFromEnv); the addon adds a fixed margin so
+# the egress can deliver its own timeout classification before the socket
+# deadline fires. Never hardcode the raw timeout.
+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"
@@ -134,6 +158,9 @@ _ACTIVE_VAULT_BINDING_FIELDS = {
_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",
@@ -984,6 +1011,152 @@ def _validate_active_vault_etag(value: str | None) -> str:
return value
+class CredentialResolveError(Exception):
+ """A resolve RPC failure carrying a fixed, log-safe reason token.
+
+ Tokens: ``transport`` (socket/protocol error), ``invalid_response``
+ (non-contract 200 body), ``http_<status>`` (non-200 endpoint reply).
+ Resolve request/response content never reaches logs.
+ """
+
+
+def _env_int_range(name: str, default: int, bounds: tuple[int, int]) -> int:
+ # Mirrors Go EnvIntRange: trimmed decimal integer inside bounds, any
+ # other value keeps the default (no silent clamping of nonsense).
+ 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
+ )
+
+
+# Bounded concurrent resolves, aligned with the Go endpoint's semaphore. The
+# state is keyed by the running loop because tests and script reloads may
+# swap event loops while the module stays loaded.
+_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 on the active socket; runs in a worker thread.
+
+ Reuses the HTTP-over-unix-socket transport of `_fetch_active_vault`.
+ Failures are normalized to CredentialResolveError so callers have a
+ single fail-closed direction.
+ """
+ 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()
+ raw = response.read()
+ 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.
@@ -1708,20 +1881,9 @@ def _observe_tls_shadow(
ctx.log.warn("credential proxy: tls-shadow observer_error")
-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.
- """
- live = _live_runtime
- if live is not None:
- _requestheaders_live(live, flow)
- return
+def _requestheaders_pull(flow: http.HTTPFlow) -> Any | 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:
@@ -1732,11 +1894,35 @@ def requestheaders(flow: http.HTTPFlow) -> None:
b"credential proxy unavailable\n",
status_code=503,
)
- return
+ 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 to completion before the
+ request continues; exchange bindings defer their resolve I/O through the
+ single await below. Static bindings and the live path run fully inline
+ and never suspend the hook.
+ """
+ live = _live_runtime
+ if live is not None:
+ _requestheaders_live(live, flow)
return
- _apply_vault_binding(flow, vault)
+ deferred = _requestheaders_pull(flow)
+ if deferred is not None:
+ await deferred
def _requestheaders_live(live: Any, flow: http.HTTPFlow) -> None:
@@ -1873,24 +2059,22 @@ def _live_snapshot_vault(snapshot: Any) -> ActiveVault | None:
def _apply_vault_binding(
flow: http.HTTPFlow, vault: ActiveVault, live: Any | None = None
-) -> None:
- """Shared binding selection, ambiguity checks and credential injection."""
+) -> Any | None:
+ """Shared binding selection, ambiguity checks and credential injection.
+
+ Returns an awaitable when a pull-mode exchange binding defers its
+ resolve I/O to the caller (the request must not continue before it
+ completes); every other path returns None after handling the flow.
+ """
# 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
+ return None
- # Until the T3b resolve path exists, exchange bindings must fail closed
- # rather than forward uncredentialed.
if "exchange" in binding:
- _reject_request(flow, b"credential exchange unavailable\n", status_code=503)
- ctx.log.warn(
- "credential proxy: exchange binding unavailable binding="
- f"{binding.get('name')}"
- )
- return
+ return _apply_exchange_binding(flow, vault, binding, live)
# Reject ambiguous paths only for requests that would receive credentials:
# dot-segments or backslashes could redirect credentials to a scope the
@@ -1959,6 +2143,170 @@ def _apply_vault_binding(
)
+def _apply_exchange_binding(
+ flow: http.HTTPFlow,
+ vault: ActiveVault,
+ binding: dict[str, Any],
+ live: Any | None,
+) -> Any | None:
+ """Gate one exchange binding, then defer its resolve I/O to the caller.
+
+ Push-mode (live) snapshots never carry exchange bindings — the egress
+ admission gate rejects them — so the defensive branch stays fail closed
+ instead of resolving from the decision path.
+ """
+ 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
+ # Same path gates as static injection: an ambiguous or boundary-crossing
+ # encoding must never be handed a resolved credential.
+ 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 None
+ 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 None
+ sni = _connection_sni(flow)
+ if sni is None:
+ # The egress SNI gate needs the verified TLS destination; without a
+ # connection SNI no exchange binding can ever resolve.
+ _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 one exchange binding on the active socket and inject headers.
+
+ Real I/O runs in a worker thread behind the concurrency semaphore so a
+ slow resolver never blocks the event loop. Any failure fails closed:
+ 407 for buffered requests, kill for streamed ones. Results live only in
+ flow metadata — never a module-level cache.
+ """
+ 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 "/",
+ },
+ }
+ try:
+ async with _resolve_limiter():
+ decision = await asyncio.to_thread(
+ _resolve_exchange_http,
+ socket_path,
+ _resolve_budget_seconds(),
+ path,
+ payload,
+ )
+ _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 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.
+
+ The redaction set re-derives every rendered variant of each injected
+ value, so response redaction never depends on resolver output
+ completeness (R9), and injected names always join the by-name suppress
+ set (D7).
+ """
+ injected_names: list[str] = []
+ for header in decision["headers"]:
+ name = header["name"]
+ # Same delete-then-set as static injection: mitmproxy Headers is
+ # case-insensitive and 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.
@@ -1996,6 +2344,7 @@ def request(flow: http.HTTPFlow) -> None:
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()
@@ -2029,6 +2378,21 @@ def client_disconnected(client_conn: Any) -> None:
live.client_disconnected(client_conn)
+def _suppress_response_headers(flow: http.HTTPFlow) -> None:
+ """Delete by-name suppressed response headers (exchange bindings).
+
+ The suppress set was validated at resolve time; names are matched
+ case-insensitively 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:
diff --git a/components/egress/tests/fixtures/real_wire_worker.py b/components/egress/tests/fixtures/real_wire_worker.py
index afdee45ec..ca8eb2113 100644
--- a/components/egress/tests/fixtures/real_wire_worker.py
+++ b/components/egress/tests/fixtures/real_wire_worker.py
@@ -25,6 +25,7 @@ Usage: ``real_wire_worker.py {ech-parse|h1-parse}``
from __future__ import annotations
+import asyncio
import hashlib
import importlib.util
import json
@@ -91,6 +92,15 @@ class _ClientConn:
self.state = "open"
+def _drive_async_hook(hook):
+ """Run the async requestheaders hook synchronously, like mitmproxy."""
+
+ def run(*args, **kwargs):
+ return asyncio.run(hook(*args, **kwargs))
+
+ return run
+
+
def _load_system_module() -> object:
spec = importlib.util.spec_from_file_location(
"opensandbox_wire_system", MITMSCRIPTS / "system.py"
@@ -98,6 +108,7 @@ def _load_system_module() -> object:
assert spec is not None and spec.loader is not None
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
+ module.requestheaders = _drive_async_hook(module.requestheaders)
return module
diff --git a/components/egress/tests/test_credential_bound.py b/components/egress/tests/test_credential_bound.py
index 586f737b4..47813c03d 100644
--- a/components/egress/tests/test_credential_bound.py
+++ b/components/egress/tests/test_credential_bound.py
@@ -24,6 +24,7 @@ drain expiry, and fail-closed boundaries.
from __future__ import annotations
+import asyncio
import gc
import hashlib
import importlib.util
@@ -216,6 +217,15 @@ class _Flow:
self.live = False
+def _drive_async_hook(hook):
+ """Run the async requestheaders hook synchronously, like mitmproxy."""
+
+ def run(*args, **kwargs):
+ return asyncio.run(hook(*args, **kwargs))
+
+ return run
+
+
def _load_system_module() -> Any:
mitmproxy = types.ModuleType("mitmproxy")
mitmproxy.ctx = types.SimpleNamespace(
@@ -232,6 +242,7 @@ def _load_system_module() -> Any:
assert spec is not None and spec.loader is not None
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
+ module.requestheaders = _drive_async_hook(module.requestheaders)
return module
diff --git a/components/egress/tests/test_mitmscripts_system.py b/components/egress/tests/test_mitmscripts_system.py
index 23e2153b8..d87572503 100644
--- a/components/egress/tests/test_mitmscripts_system.py
+++ b/components/egress/tests/test_mitmscripts_system.py
@@ -14,6 +14,7 @@
from __future__ import annotations
+import asyncio
import concurrent.futures
import http.server
import importlib.util
@@ -122,6 +123,15 @@ class _Flow:
self.killable = False
+def _drive_async_hook(hook):
+ """Run the async requestheaders hook synchronously, like mitmproxy."""
+
+ def run(*args, **kwargs):
+ return asyncio.run(hook(*args, **kwargs))
+
+ return run
+
+
def _load_system_module() -> Any:
mitmproxy = types.ModuleType("mitmproxy")
mitmproxy.ctx = types.SimpleNamespace(
@@ -150,6 +160,7 @@ def _load_system_module() -> Any:
sys.modules, {"mitmproxy": mitmproxy, "mitmproxy.tls": mitmproxy_tls}
):
spec.loader.exec_module(module)
+ module.requestheaders = _drive_async_hook(module.requestheaders)
return module
@@ -1463,6 +1474,9 @@ class SystemAddonActiveVaultStrictParseTest(unittest.TestCase):
self.assertIsNone(flow.response)
def test_selected_exchange_binding_fails_closed_buffered_and_streamed(self) -> None:
+ # The T3a 503 placeholder was replaced by the T3b resolve branch;
+ # without a connection SNI the resolve can never be built, so the
+ # request still fails closed — 407 buffered, kill streamed.
for streamed in (False, True):
with self.subTest(streamed=streamed):
system = _load_system_module()
@@ -1495,7 +1509,7 @@ class SystemAddonActiveVaultStrictParseTest(unittest.TestCase):
self.assertIsNone(flow.response)
else:
self.assertFalse(flow.killed)
- self.assertEqual(503, flow.response.status_code)
+ self.assertEqual(407, flow.response.status_code)
@unittest.skipUnless(
diff --git a/components/egress/tests/test_system_h2.py b/components/egress/tests/test_system_h2.py
index 6365281f6..b3fee0e98 100644
--- a/components/egress/tests/test_system_h2.py
+++ b/components/egress/tests/test_system_h2.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import asyncio
import hashlib
import importlib.util
import json
@@ -26,6 +27,18 @@ spec = importlib.util.spec_from_file_location(
system = importlib.util.module_from_spec(spec)
spec.loader.exec_module(system)
+
+def _drive_async_hook(hook):
+ """Run the async requestheaders hook synchronously, like mitmproxy."""
+
+ def run(*args, **kwargs):
+ return asyncio.run(hook(*args, **kwargs))
+
+ return run
+
+
+system.requestheaders = _drive_async_hook(system.requestheaders)
+
HOST = "bound.example.com"
SECRET = "synthetic-h2-old-value"
diff --git a/components/egress/tests/test_system_resolve.py b/components/egress/tests/test_system_resolve.py
new file mode 100644
index 000000000..d172c2957
--- /dev/null
+++ b/components/egress/tests/test_system_resolve.py
@@ -0,0 +1,801 @@
+# 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.
+
+"""OSEP-0025 T3b: exchange binding resolve integration in the system addon.
+
+Covers the addon side of the `_resolve` contract: injection via
+delete-then-set, fail-closed matrix (407 buffered / kill streamed, never
+pass-through), per-request redaction + by-name suppression, static-path
+byte-for-byte behavior inside exchange vaults, the concurrency semaphore,
+event-loop responsiveness during slow resolves, and pull-mode H2.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import json
+import os
+import sys
+import threading
+import time
+import types
+import unittest
+from pathlib import Path
+from typing import Any
+from unittest import mock
+from urllib.parse import quote, quote_plus
+
+MITMSCRIPTS = Path(__file__).resolve().parents[1] / "mitmscripts"
+
+HOST = "code.example.com"
+BINDING = "internal-api"
+SECRET = 'tok"en secret'
+SECOND_SECRET = "sig-1"
+
+
+class _Log:
+ def __init__(self) -> None:
+ self.messages: list[str] = []
+
+ def warn(self, message: str) -> None:
+ self.messages.append(message)
+
+ def info(self, message: str) -> None:
+ self.messages.append(message)
+
+
+class _Headers:
+ def __init__(self, values: dict[str, str] | None = None) -> None:
+ self._values: dict[str, str] = dict(values or {})
+
+ def get(self, name: str, default: str = "") -> str:
+ for key, value in self._values.items():
+ if key.lower() == name.lower():
+ return value
+ return default
+
+ def items(self) -> list[tuple[str, str]]:
+ return list(self._values.items())
+
+ def __getitem__(self, name: str) -> str:
+ for key, value in self._values.items():
+ if key.lower() == name.lower():
+ return value
+ raise KeyError(name)
+
+ def __setitem__(self, name: str, value: str) -> None:
+ # mitmproxy Headers replaces every same-name field.
+ for key in list(self._values):
+ if key.lower() == name.lower():
+ del self._values[key]
+ self._values[name] = value
+
+ def __contains__(self, name: str) -> bool:
+ return any(key.lower() == name.lower() for key in self._values)
+
+ def __delitem__(self, name: str) -> None:
+ matched = [key for key in self._values if key.lower() == name.lower()]
+ if not matched:
+ raise KeyError(name)
+ for key in matched:
+ del self._values[key]
+
+
+class _Request:
+ def __init__(self) -> None:
+ self.pretty_host = HOST
+ self.host = HOST
+ self.port = 443
+ self.scheme = "https"
+ self.method = "GET"
+ self.path = "/api/v8/projects"
+ self.headers = _Headers()
+ self.raw_content: bytes | None = None
+ self.content = b""
+ self.stream = False
+ self.http_version = "HTTP/1.1"
+
+
+class _ClientConn:
+ def __init__(self, sni: str | None = HOST) -> None:
+ self.sni = sni
+ self.peername = ("10.1.2.3", 40000)
+
+
+class _Response:
+ def __init__(self) -> None:
+ self.headers = _Headers({"content-type": "application/json"})
+ self.stream = False
+ self.status_code = 200
+
+
+class _Flow:
+ def __init__(self, sni: str | None = HOST) -> None:
+ self.request = _Request()
+ self.response = None
+ self.metadata: dict[str, Any] = {}
+ self.client_conn = _ClientConn(sni)
+ self.error = None
+ self.live = True
+ self.killable = True
+ self.killed = False
+
+ def kill(self) -> None:
+ self.killed = True
+ self.error = "Killed"
+ self.live = False
+ self.killable = False
+
+
+def _load_system_module() -> Any:
+ mitmproxy = types.ModuleType("mitmproxy")
+ mitmproxy.ctx = types.SimpleNamespace(
+ log=_Log(), options=types.SimpleNamespace(ignore_hosts=[], ssl_insecure=False)
+ )
+
+ def _make_response(
+ status: int, body: bytes = b"", headers: dict | None = None
+ ) -> _Response:
+ response = _Response()
+ response.status_code = status
+ if headers:
+ response.headers = _Headers(headers)
+ return response
+
+ mitmproxy.http = types.SimpleNamespace(
+ HTTPFlow=object, Response=types.SimpleNamespace(make=_make_response)
+ )
+ mitmproxy_tls = types.ModuleType("mitmproxy.tls")
+ mitmproxy_tls.ClientHelloData = object
+ with mock.patch.dict(
+ sys.modules, {"mitmproxy": mitmproxy, "mitmproxy.tls": mitmproxy_tls}
+ ):
+ spec = importlib.util.spec_from_file_location(
+ "opensandbox_egress_system_resolve_test", MITMSCRIPTS / "system.py"
+ )
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def _exchange_binding(host: str = HOST) -> dict[str, Any]:
+ return {
+ "name": BINDING,
+ "match": {
+ "schemes": ["https"],
+ "hosts": [host],
+ "methods": ["GET"],
+ "paths": ["/api/v8/*"],
+ },
+ "headers": [],
+ "substitutions": [],
+ "exchange": {"credential": "spi-signer"},
+ }
+
+
+def _static_binding() -> dict[str, Any]:
+ return {
+ "name": "gitlab-api",
+ "match": {
+ "schemes": ["https"],
+ "hosts": [HOST],
+ "methods": ["GET"],
+ "paths": ["/api/v8/*"],
+ },
+ "headers": [{"name": "Private-Token", "value": "static-secret"}],
+ "substitutions": [],
+ }
+
+
+def _exchange_vault(system: Any, *, static: bool = False) -> Any:
+ bindings = [_exchange_binding()]
+ if static:
+ bindings = [_static_binding(), _exchange_binding("other.example.com")]
+ return system.ActiveVault(12, bindings, ["static-secret"] if static else [])
+
+
+def _parsed_decision(
+ *,
+ revision: int = 12,
+ binding: str = BINDING,
+ headers: list[tuple[str, str]] | None = None,
+ redactions: list[str] | None = None,
+ suppress: set[str] | None = None,
+) -> dict[str, Any]:
+ if headers is None:
+ headers = [("authorization", SECRET), ("x-signature", SECOND_SECRET)]
+ return {
+ "revision": revision,
+ "binding": binding,
+ "headers": [{"name": name, "value": value} for name, value in headers],
+ "redactions": redactions if redactions is not None else [SECRET, SECOND_SECRET],
+ "suppressHeaders": sorted(suppress)
+ if suppress is not None
+ else ["authorization", "x-signature"],
+ }
+
+
+class _ScriptedResponse:
+ def __init__(self, status: int, body: bytes = b"") -> None:
+ self.status = status
+ self._body = body
+
+ def read(self) -> bytes:
+ return self._body
+
+ def getheader(self, name: str) -> str | None:
+ return None
+
+
+class ExchangeResolveTest(unittest.TestCase):
+ def setUp(self) -> None:
+ self.system = _load_system_module()
+ self.log: _Log = self.system.ctx.log
+ env = mock.patch.dict(os.environ)
+ env.start()
+ self.addCleanup(env.stop)
+ for name in (
+ self.system.CREDENTIAL_RESOLVER_TIMEOUT_ENV,
+ self.system.CREDENTIAL_RESOLVER_MAX_CONCURRENCY_ENV,
+ self.system.CREDENTIAL_PROXY_SOCKET_ENV,
+ "OPENSANDBOX_EGRESS_PROFILE",
+ ):
+ os.environ.pop(name, None)
+
+ def _install_vault(self, *, static: bool = False, host: str = HOST) -> Any:
+ if static:
+ vault = _exchange_vault(self.system, static=True)
+ else:
+ vault = self.system.ActiveVault(12, [_exchange_binding(host)], [])
+ self.system._load_active_vault = lambda _client_ip=None: vault
+ return vault
+
+ def _install_transport(self, behavior: Any) -> list[tuple[Any, ...]]:
+ calls: list[tuple[Any, ...]] = []
+ lock = threading.Lock()
+
+ def transport(socket_path: str, timeout: float, path: str, payload: dict):
+ with lock:
+ calls.append((socket_path, timeout, path, payload))
+ return behavior(payload)
+
+ self.system._resolve_exchange_http = transport
+ return calls
+
+ def _decision_transport(self) -> list[tuple[Any, ...]]:
+ return self._install_transport(lambda payload: _parsed_decision())
+
+ # -- happy path -------------------------------------------------------
+
+ def test_happy_path_injects_resolved_headers(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ flow = _Flow()
+ flow.request.headers["Authorization"] = "client-side-token"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual(1, len(calls))
+ socket_path, timeout, path, payload = calls[0]
+ self.assertEqual(
+ self.system.DEFAULT_CREDENTIAL_PROXY_SOCKET, socket_path
+ )
+ self.assertEqual(2.25, timeout)
+ self.assertEqual(self.system.CREDENTIAL_RESOLVE_PATH, path)
+ self.assertEqual(
+ {
+ "binding": BINDING,
+ "sni": HOST,
+ "request": {
+ "scheme": "https",
+ "host": HOST,
+ "port": 443,
+ "method": "GET",
+ "path": "/api/v8/projects",
+ },
+ },
+ payload,
+ )
+ # Delete-then-set: the resolved value replaced the client's own header.
+ self.assertEqual(SECRET, flow.request.headers["authorization"])
+ self.assertEqual(SECOND_SECRET, flow.request.headers["x-signature"])
+ self.assertFalse(flow.killed)
+ self.assertIsNone(flow.response)
+ self.assertNotIn(self.system.FLOW_REJECTION_KEY, flow.metadata)
+ self.assertEqual(_exchange_binding(), flow.metadata[self.system.FLOW_BINDING_KEY])
+ self.assertEqual(
+ ["authorization", "x-signature"],
+ flow.metadata[self.system.FLOW_VAULT_SUPPRESS_KEY],
+ )
+ redactions = flow.metadata[self.system.FLOW_REDACTIONS_KEY]
+ self.assertIn(SECRET, redactions)
+ self.assertIn(quote(SECRET, safe=""), redactions)
+ self.assertIn(quote_plus(SECRET, safe=""), redactions)
+ self.assertIn(json.dumps(SECRET)[1:-1], redactions)
+ self.assertTrue(
+ any(
+ "exchange=1" in message and f"binding={BINDING}" in message
+ for message in self.log.messages
+ )
+ )
+ self.assertFalse(any(SECRET in message for message in self.log.messages))
+
+ def test_resolve_request_path_keeps_query(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ flow = _Flow()
+ flow.request.path = "/api/v8/projects?cursor=zzz"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual(
+ "/api/v8/projects?cursor=zzz", calls[0][3]["request"]["path"]
+ )
+
+ def test_fast_sandbox_mode_appends_client_ip(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ self.system._set_fast_sandbox_mode(True)
+ self.addCleanup(self.system._set_fast_sandbox_mode, False)
+ flow = _Flow()
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual(
+ f"{self.system.CREDENTIAL_RESOLVE_PATH}?clientIp=10.1.2.3", calls[0][2]
+ )
+
+ # -- fail-closed matrix -------------------------------------------------
+
+ def test_fail_closed_matrix_buffered(self) -> None:
+ self._install_vault()
+ cases = {
+ "transport-down": ConnectionRefusedError("no socket"),
+ "go-504-timeout": self.system.CredentialResolveError("http_504"),
+ "go-503-unavailable": self.system.CredentialResolveError("http_503"),
+ "go-409-invalidated": self.system.CredentialResolveError("http_409"),
+ "invalid-response": self.system.CredentialResolveError("invalid_response"),
+ "unexpected": RuntimeError("boom"),
+ }
+ for name, failure in cases.items():
+ with self.subTest(name=name):
+ calls = self._install_transport(lambda payload: (_ for _ in ()).throw(failure))
+ flow = _Flow()
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual(1, len(calls))
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertEqual(407, flow.response.status_code)
+ self.assertFalse(flow.killed)
+ # No pass-through: nothing was injected.
+ self.assertNotIn("authorization", flow.request.headers)
+ self.assertNotIn(self.system.FLOW_BINDING_KEY, flow.metadata)
+ self.assertTrue(
+ any(
+ "exchange resolve failed" in message
+ and f"binding={BINDING}" in message
+ for message in self.log.messages
+ )
+ )
+ self.assertFalse(any(SECRET in message for message in self.log.messages))
+
+ def test_fail_closed_matrix_streamed_kills(self) -> None:
+ self._install_vault()
+ for name, configure in (
+ ("body-stream-flag", lambda flow: setattr(flow.request, "stream", True)),
+ ("transfer-encoding", lambda flow: flow.request.headers.__setitem__(
+ "transfer-encoding", "chunked"
+ )),
+ ("h2-without-content-length", lambda flow: setattr(
+ flow.request, "http_version", "HTTP/2.0"
+ )),
+ ):
+ with self.subTest(name=name):
+ self._install_transport(
+ lambda payload: (_ for _ in ()).throw(
+ self.system.CredentialResolveError("http_504")
+ )
+ )
+ flow = _Flow()
+ configure(flow)
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertTrue(flow.killed)
+ self.assertIsNone(flow.response)
+ self.assertNotIn("authorization", flow.request.headers)
+
+ def test_failure_does_not_pollute_next_request(self) -> None:
+ self._install_vault()
+ outcomes: list[Any] = [
+ self.system.CredentialResolveError("transport"),
+ _parsed_decision(),
+ ]
+ calls = self._install_transport(
+ lambda payload: (_ for _ in ()).throw(outcomes.pop(0))
+ if isinstance(outcomes[0], Exception)
+ else outcomes.pop(0)
+ )
+ first = _Flow()
+ first.request.headers["Content-Length"] = "0"
+ second = _Flow()
+ second.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(first))
+ asyncio.run(self.system.requestheaders(second))
+
+ self.assertEqual(2, len(calls))
+ self.assertEqual(407, first.response.status_code)
+ self.assertIsNone(second.response)
+ self.assertEqual(SECRET, second.request.headers["authorization"])
+
+ def test_missing_sni_fails_closed_without_rpc(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ flow = _Flow(sni=None)
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual([], calls)
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertEqual(407, flow.response.status_code)
+
+ def test_ambiguous_paths_rejected_before_rpc(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ for name, path in (
+ ("dot-segments", "/api/v8/../v9/projects"),
+ ("encoded-boundary-crossing", "/api/v8/%2e%2e/v9/projects"),
+ ):
+ with self.subTest(name=name):
+ flow = _Flow()
+ flow.request.path = path
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual([], calls)
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertEqual(403, flow.response.status_code)
+
+ # -- redaction and suppression ------------------------------------------
+
+ def test_response_suppression_and_by_value_redaction(self) -> None:
+ self._install_vault()
+ # Redactions deliberately miss every rendered variant: the addon must
+ # re-derive them (R9) so echoes cannot leak the resolved value.
+ self._install_transport(
+ lambda payload: _parsed_decision(redactions=[SECRET, SECOND_SECRET])
+ )
+ flow = _Flow()
+ asyncio.run(self.system.requestheaders(flow))
+ flow.response = _Response()
+ flow.response.headers = _Headers(
+ {
+ "content-type": "application/json",
+ "Authorization": SECRET,
+ "x-signature": SECOND_SECRET,
+ "x-echo": f"wrapped {SECRET}",
+ "x-url-echo": quote(SECRET, safe=""),
+ "x-form-echo": quote_plus(SECRET, safe=""),
+ "x-json-echo": json.dumps(SECRET)[1:-1],
+ "x-clean": "no-secret-here",
+ }
+ )
+
+ self.system.responseheaders(flow)
+
+ headers = flow.response.headers
+ self.assertNotIn("authorization", headers)
+ self.assertNotIn("x-signature", headers)
+ self.assertEqual("wrapped [REDACTED]", headers["x-echo"])
+ self.assertEqual("[REDACTED]", headers["x-url-echo"])
+ self.assertEqual("[REDACTED]", headers["x-form-echo"])
+ self.assertEqual("[REDACTED]", headers["x-json-echo"])
+ self.assertEqual("no-secret-here", headers["x-clean"])
+ self.assertEqual("application/json", headers["content-type"])
+
+ def test_injected_names_suppress_even_when_resolver_omits_them(self) -> None:
+ self._install_vault()
+ self._install_transport(
+ lambda payload: _parsed_decision(
+ headers=[("authorization", SECRET)], suppress=set()
+ )
+ )
+ flow = _Flow()
+ asyncio.run(self.system.requestheaders(flow))
+ flow.response = _Response()
+ flow.response.headers = _Headers({"authorization": SECRET})
+
+ self.system.responseheaders(flow)
+
+ self.assertNotIn("authorization", flow.response.headers)
+ self.assertNotIn(SECRET, flow.response.headers.get("authorization", ""))
+
+ def test_static_binding_in_exchange_vault_is_untouched(self) -> None:
+ self._install_vault(static=True)
+ calls = self._decision_transport()
+ flow = _Flow()
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual([], calls)
+ self.assertEqual("static-secret", flow.request.headers["Private-Token"])
+ self.assertIsNone(flow.response)
+ self.assertNotIn(self.system.FLOW_VAULT_SUPPRESS_KEY, flow.metadata)
+ self.assertNotIn(self.system.FLOW_REJECTION_KEY, flow.metadata)
+
+ # -- concurrency and loop responsiveness ---------------------------------
+
+ def test_semaphore_bounds_concurrent_resolves(self) -> None:
+ os.environ[self.system.CREDENTIAL_RESOLVER_MAX_CONCURRENCY_ENV] = "2"
+ self._install_vault()
+ state = {"in_flight": 0, "max_in_flight": 0}
+ lock = threading.Lock()
+
+ def behavior(payload: dict) -> dict:
+ with lock:
+ state["in_flight"] += 1
+ state["max_in_flight"] = max(state["max_in_flight"], state["in_flight"])
+ time.sleep(0.12)
+ with lock:
+ state["in_flight"] -= 1
+ return _parsed_decision()
+
+ calls = self._install_transport(behavior)
+ flows = [_Flow() for _ in range(4)]
+
+ async def main() -> None:
+ await asyncio.gather(*(self.system.requestheaders(f) for f in flows))
+
+ asyncio.run(main())
+
+ self.assertEqual(4, len(calls))
+ self.assertLessEqual(state["max_in_flight"], 2)
+ for flow in flows:
+ self.assertEqual(SECRET, flow.request.headers["authorization"])
+
+ def test_slow_resolve_does_not_block_event_loop(self) -> None:
+ self._install_vault()
+
+ def behavior(payload: dict) -> dict:
+ time.sleep(0.3)
+ return _parsed_decision()
+
+ self._install_transport(behavior)
+ flow = _Flow()
+ ticks: list[int] = []
+
+ async def main() -> None:
+ task = asyncio.ensure_future(self.system.requestheaders(flow))
+ deadline = time.monotonic() + 0.15
+ while not task.done() and time.monotonic() < deadline:
+ await asyncio.sleep(0.02)
+ ticks.append(len(ticks))
+ self.assertFalse(task.done())
+ await asyncio.wait_for(task, timeout=2)
+
+ asyncio.run(main())
+
+ self.assertGreaterEqual(len(ticks), 3)
+ self.assertEqual(SECRET, flow.request.headers["authorization"])
+
+ # -- pull-mode H2 ---------------------------------------------------------
+
+ def test_h2_pull_mode_resolves_and_uses_connection_sni(self) -> None:
+ self._install_vault(host="authority.example.com")
+ calls = self._decision_transport()
+ flow = _Flow()
+ flow.request.http_version = "HTTP/2.0"
+ flow.request.pretty_host = "authority.example.com"
+ flow.request.host = "authority.example.com"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual("authority.example.com", calls[0][3]["request"]["host"])
+ self.assertEqual(HOST, calls[0][3]["sni"])
+ self.assertEqual(SECRET, flow.request.headers["authorization"])
+
+ def test_h2_failure_without_content_length_kills(self) -> None:
+ self._install_vault()
+ self._install_transport(
+ lambda payload: (_ for _ in ()).throw(
+ self.system.CredentialResolveError("http_409")
+ )
+ )
+ flow = _Flow()
+ flow.request.http_version = "HTTP/2.0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertTrue(flow.killed)
+ self.assertIsNone(flow.response)
+ self.assertNotIn("authorization", flow.request.headers)
+
+ def test_h2_failure_with_content_length_is_buffered_407(self) -> None:
+ self._install_vault()
+ self._install_transport(
+ lambda payload: (_ for _ in ()).throw(
+ self.system.CredentialResolveError("http_409")
+ )
+ )
+ flow = _Flow()
+ flow.request.http_version = "HTTP/2.0"
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertFalse(flow.killed)
+ self.assertEqual(407, flow.response.status_code)
+
+ # -- timeout budget derivation ---------------------------------------------
+
+ def test_timeout_budget_follows_env(self) -> None:
+ self._install_vault()
+ cases = {
+ "": 2.25,
+ "5": 5.25,
+ " 7 ": 7.25,
+ "+3": 3.25,
+ "0": 2.25,
+ "121": 2.25,
+ "abc": 2.25,
+ "2.5": 2.25,
+ }
+ for value, expected in cases.items():
+ with self.subTest(value=value):
+ os.environ[self.system.CREDENTIAL_RESOLVER_TIMEOUT_ENV] = value
+ calls = self._decision_transport()
+ flow = _Flow()
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertEqual(expected, calls[0][1])
+
+ # -- transport wire format ---------------------------------------------------
+
+ def test_transport_wire_format_and_error_statuses(self) -> None:
+ self._install_vault()
+ decisions: list[_ScriptedResponse] = [
+ _ScriptedResponse(200, json.dumps(_parsed_decision()).encode("utf-8")),
+ _ScriptedResponse(409, b"captured binding replaced"),
+ ]
+ requests: list[tuple[str, str, bytes | None, dict[str, str]]] = []
+
+ class FakeConnection:
+ def __init__(self, socket_path: str, timeout: float) -> None:
+ pass
+
+ def request(self, method, path, body=None, headers=None) -> None:
+ requests.append((method, path, body, dict(headers or {})))
+
+ def getresponse(self) -> _ScriptedResponse:
+ return decisions.pop(0)
+
+ def close(self) -> None:
+ pass
+
+ self.system.UnixSocketHTTPConnection = FakeConnection
+
+ flow = _Flow()
+ asyncio.run(self.system.requestheaders(flow))
+ method, path, body, headers = requests[0]
+ self.assertEqual("POST", method)
+ self.assertEqual(self.system.CREDENTIAL_RESOLVE_PATH, path)
+ self.assertEqual("application/json", headers["Content-Type"])
+ self.assertEqual(
+ {
+ "binding": BINDING,
+ "sni": HOST,
+ "request": {
+ "scheme": "https",
+ "host": HOST,
+ "port": 443,
+ "method": "GET",
+ "path": "/api/v8/projects",
+ },
+ },
+ json.loads(body.decode("utf-8")),
+ )
+ self.assertEqual(SECRET, flow.request.headers["authorization"])
+
+ second = _Flow()
+ second.request.headers["Content-Length"] = "0"
+ asyncio.run(self.system.requestheaders(second))
+ self.assertEqual(407, second.response.status_code)
+
+ def test_parse_resolve_response_rejects_malformed_bodies(self) -> None:
+ parse = self.system._parse_resolve_response
+ error = self.system.CredentialResolveError
+ valid = json.dumps(_parsed_decision()).encode("utf-8")
+ self.assertEqual(
+ {"authorization", "x-signature"}, parse(valid, BINDING)["suppressHeaders"]
+ )
+ broken: dict[str, Any] = {
+ "oversize": b"x" * (self.system.MAX_RESOLVE_RESPONSE_BYTES + 1),
+ "not-json": b"<html>",
+ "missing-field": json.dumps(
+ {k: v for k, v in _parsed_decision().items() if k != "redactions"}
+ ).encode("utf-8"),
+ "extra-field": json.dumps(
+ {**_parsed_decision(), "extra": 1}
+ ).encode("utf-8"),
+ "binding-mismatch": json.dumps(_parsed_decision(binding="other")).encode(
+ "utf-8"
+ ),
+ "bad-revision": json.dumps(_parsed_decision(revision=0)).encode("utf-8"),
+ "reserved-injected-name": json.dumps(
+ _parsed_decision(headers=[("content-length", "9")])
+ ).encode("utf-8"),
+ "empty-value": json.dumps(
+ _parsed_decision(headers=[("authorization", "")])
+ ).encode("utf-8"),
+ "reserved-suppress-name": json.dumps(
+ _parsed_decision(suppress={"transfer-encoding"})
+ ).encode("utf-8"),
+ "header-extra-field": json.dumps(
+ {
+ **_parsed_decision(),
+ "headers": [{"name": "authorization", "value": SECRET, "n": 1}],
+ }
+ ).encode("utf-8"),
+ "redaction-not-string": json.dumps(
+ _parsed_decision(redactions=[7])
+ ).encode("utf-8"),
+ }
+ for name, raw in broken.items():
+ with self.subTest(name=name):
+ with self.assertRaises(error):
+ parse(raw, BINDING)
+
+ # -- defensive branches ----------------------------------------------------
+
+ def test_live_mode_exchange_keeps_placeholder_fail_closed(self) -> None:
+ self._install_vault()
+ calls = self._decision_transport()
+ flow = _Flow()
+ flow.request.headers["Content-Length"] = "0"
+
+ deferred = self.system._apply_vault_binding(
+ flow, _exchange_vault(self.system), live=object()
+ )
+
+ self.assertIsNone(deferred)
+ self.assertEqual([], calls)
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertEqual(503, flow.response.status_code)
+
+ def test_static_lookup_failure_still_503(self) -> None:
+ def raise_lookup(_client_ip=None):
+ raise self.system.ActiveVaultLookupError("active vault lookup failed")
+
+ self.system._load_active_vault = raise_lookup
+ flow = _Flow()
+ flow.request.headers["Content-Length"] = "0"
+
+ asyncio.run(self.system.requestheaders(flow))
+
+ self.assertTrue(flow.metadata[self.system.FLOW_REJECTION_KEY])
+ self.assertEqual(503, flow.response.status_code)
+
+
+if __name__ == "__main__":
+ unittest.main()