Skip to content

Commit 253eaec

Browse files
feat(gateway): a keyed deploy's role key, forwarded headers, and triggers by route (FD-4683)
This PR's change, rebased as one commit onto #429. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 250afe3 commit 253eaec

43 files changed

Lines changed: 1074 additions & 155 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/agentenv-protocol/examples/website/notes/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,10 @@ them. The page shows the universe's time.
2020
`edit_note`, `toggle_note` and `delete_note`. Errors are raised as `NotFound`, `BadRequest` and `Unauthorized`.
2121
- **Roles.** `all_notes` (`GET /api/admin/notes`) is declared with `roles=["admin"]`. It answers only a caller that
2222
sends `AgentEnv-Role: admin` with `AgentEnv-Role-Key` equal to the container's `WEBSITE_ROLE_KEY`; any other caller
23-
gets 403. The gateway passes on whatever role a browser sends, so without the key a page could claim `admin`; with no
24-
`WEBSITE_ROLE_KEY` set, every caller is `default` and the route is closed.
23+
gets 403. A deploy with `keyed_roles` gives the site its own role key as `WEBSITE_ROLE_KEY` and its gateway sends it
24+
on only beside a role it verified with the same key, so a page cannot claim `admin` through it. Any other deploy sets
25+
no key, and its gateway passes on whatever role a browser sends; with no `WEBSITE_ROLE_KEY` set, every caller is
26+
`default` and the route is closed.
2527
- **Users.** `ApiContext.user` is the user in the signed session cookie. With no cookie, it is the acting user (the
2628
store's `current_user`), and `GET /api/session` signs that user in. `POST /api/sign-in` switches to another seeded
2729
user. A user's notes are invisible to every other user, and another user's note answers 404.

‎packages/agentenv-protocol/src/agentenv_protocol/website/environment.py‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,14 @@
1818
import re
1919
from pathlib import Path
2020
from typing import Any, ClassVar, NamedTuple, Optional
21+
from urllib.parse import unquote
2122

2223
from starlette.applications import Starlette
2324
from starlette.datastructures import MutableHeaders
2425
from starlette.middleware import Middleware
2526
from starlette.requests import Request
2627
from starlette.responses import FileResponse, JSONResponse, Response
28+
from starlette._utils import get_route_path
2729
from starlette.routing import Route
2830

2931
from ..agent_env_environment import (
@@ -41,7 +43,8 @@
4143
from .clock import CLOCK_EXTENSION_URI, UNIVERSE_NOW_HEADER, UniverseClock, clock_patch_script, iso
4244
from .errors import NotFound
4345
from .readiness import WEBSITE_EXTENSION_URI, WEBSITE_READY_OP, WebsiteReadiness
44-
from .routes import ApiContext, ApiRoute, endpoint, error_response, openapi, openapi_path, request_role, reserved_path, routes_of
46+
from .routes import (ApiContext, ApiRoute, endpoint, error_response, forwarded_prefix, openapi, openapi_path, request_role,
47+
reserved_path, routes_of)
4548
from .session import SESSION_COOKIE, SessionSigner, expires_at
4649
from .state import WEBSITE_STATE_OP, WebsiteState
4750
from .store import Collections
@@ -320,9 +323,11 @@ def _check_health(cls: type) -> None:
320323

321324

322325
class _Forwarded:
323-
"""Puts the address the browser reached the site at in the scope, from ``X-Forwarded-Host`` and
324-
``X-Forwarded-Proto``, before anything routes it, so redirects, ``request.url`` and a mounted app's ``url_for``
325-
name that address and not the internal one the proxy reached the server at."""
326+
"""Puts the address the browser reached the site at in the scope, from ``X-Forwarded-Host``,
327+
``X-Forwarded-Proto`` and ``X-Forwarded-Prefix``, before anything routes it, so redirects, ``request.url`` and a
328+
mounted app's ``url_for`` name that address and not the internal one the proxy reached the server at. A prefix
329+
becomes the scope's ``root_path`` and leads its ``path``, as ASGI has a mounted app's, so routing still sees the
330+
site's own path."""
326331

327332
def __init__(self, app: Any) -> None:
328333
self.app = app
@@ -337,6 +342,12 @@ async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
337342
scope["headers"] = [(k, v) for k, v in scope["headers"] if k != b"host"] + [(b"host", host.encode())]
338343
if proto in ("http", "https"):
339344
scope["scheme"] = proto if scope["type"] == "http" else {"http": "ws", "https": "wss"}[proto]
345+
prefix = forwarded_prefix(_first(headers.get(b"x-forwarded-prefix")))
346+
if prefix:
347+
scope["root_path"] = unquote(prefix) + scope.get("root_path", "")
348+
scope["path"] = unquote(prefix) + scope["path"]
349+
if scope.get("raw_path") is not None:
350+
scope["raw_path"] = prefix.encode("latin-1") + scope["raw_path"]
340351
await self.app(scope, receive, send)
341352

342353

@@ -416,7 +427,7 @@ async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
416427
if self.app is not None:
417428
await self.app(scope, receive, send)
418429
return
419-
path, reading = scope["path"], scope["method"] in ("GET", "HEAD")
430+
path, reading = get_route_path(scope) or "/", scope["method"] in ("GET", "HEAD")
420431
if reserved_path(path):
421432
return await error_response(NotFound("not found"))(scope, receive, send)
422433
if reading and (file := self._file(path)) is not None:

‎packages/agentenv-protocol/src/agentenv_protocol/website/routes.py‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,9 @@ class ApiRoute(NamedTuple):
5353
fn: Callable
5454

5555
def advertised(self) -> dict:
56-
return {"method": self.method, "path": openapi_path(self.path), "name": self.name,
57-
"roles": list(self.roles) or None}
56+
"""The route as the card names it: its path is the Starlette path it is served at, converters and all
57+
(``/files/{rest:path}``), so a gateway matches the requests it answers, nested paths included."""
58+
return {"method": self.method, "path": self.path, "name": self.name, "roles": list(self.roles) or None}
5859

5960

6061
class _Api:
@@ -159,11 +160,23 @@ def apply(self, response: Response) -> Response:
159160

160161
def base_url(request: Request) -> str:
161162
"""The site's address as the browser reached it: ``X-Forwarded-Proto`` and ``X-Forwarded-Host`` when a proxy
162-
sent them, the request's own scheme and ``Host`` otherwise."""
163+
sent them, the request's own scheme and ``Host`` otherwise, under the path ``X-Forwarded-Prefix`` names when the
164+
proxy serves the site below one (the gateway's ``/website/<name>``)."""
163165
proto = request.headers.get("x-forwarded-proto", "").split(",")[0].strip() or request.url.scheme
164166
host = (request.headers.get("x-forwarded-host", "").split(",")[0].strip() or request.headers.get("host")
165167
or request.url.netloc)
166-
return f"{proto}://{host}"
168+
return f"{proto}://{host}{forwarded_prefix(request.headers.get('x-forwarded-prefix', ''))}"
169+
170+
171+
def forwarded_prefix(value: str) -> str:
172+
"""The path an ``X-Forwarded-Prefix`` value names, without its trailing slash; empty for none, and for one that is
173+
not an absolute path or would make the site's URLs name another host (``//host``).
174+
175+
>>> [forwarded_prefix(v) for v in ("/website/notes/", "/a, /b", "", "/", "website", "//evil.example", "/a//b")]
176+
['/website/notes', '/a', '', '', '', '', '']
177+
"""
178+
prefix = value.split(",")[0].strip().rstrip("/")
179+
return prefix if prefix.startswith("/") and "//" not in prefix and prefix.isprintable() else ""
167180

168181

169182
ROLE_KEY_ENV = "WEBSITE_ROLE_KEY"
@@ -172,7 +185,8 @@ def base_url(request: Request) -> str:
172185

173186
def request_role(request: Request) -> str:
174187
"""The role ``AgentEnv-Role`` names, believed only from a caller that also sends ``AgentEnv-Role-Key`` equal to
175-
``WEBSITE_ROLE_KEY``; every other caller, and every caller of a site with no key set, is ``default``. The gateway
188+
``WEBSITE_ROLE_KEY``; every other caller, and every caller of a site with no key set, is ``default``. A deploy with
189+
``keyed_roles`` sets the key and its gateway sends it on beside a role it verified the same way; any other gateway
176190
forwards whatever role a browser sends, so without the key a page could claim any role."""
177191
claimed = caller_from_request(None, request.headers).role or DEFAULT_ROLE
178192
key = os.environ.get(ROLE_KEY_ENV, "")

‎packages/agentenv-protocol/tests/test_website_api.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,19 @@ def test_a_redirect_names_the_forwarded_address(client: TestClient) -> None:
318318
assert client.get("/api/items/", follow_redirects=False).headers["location"] == "http://testserver/api/items"
319319

320320

321+
def test_a_site_behind_a_forwarded_prefix_names_it_in_its_address_and_redirects_and_routes_its_own_paths(
322+
client: TestClient) -> None:
323+
behind = {"Host": "internal-x.invalid", "X-Forwarded-Host": "gw.example", "X-Forwarded-Proto": "https",
324+
"X-Forwarded-Prefix": "/website/shop/"}
325+
assert client.get("/api/whoami", headers=behind).json()["base_url"] == "https://gw.example/website/shop"
326+
assert client.get("/api/items/1", headers=behind).json()["title"] == "mug"
327+
redirected = client.get("/api/items/", follow_redirects=False, headers=behind)
328+
assert (redirected.status_code, redirected.headers["location"]) == (307, "https://gw.example/website/shop/api/items")
329+
for unusable in ("//evil.example", "website", ""):
330+
seen = client.get("/api/whoami", headers={**behind, "X-Forwarded-Prefix": unusable}).json()
331+
assert seen["base_url"] == "https://gw.example", unusable
332+
333+
321334
def test_parameterized_routes_never_take_the_data_plane_or_card() -> None:
322335
@website(domains=["wiki.example"])
323336
class Wiki(WebsiteEnvironment):

‎packages/agentenv-protocol/tests/test_website_environment.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,18 @@ def test_static_files_and_index_fallback_answer_for_any_host(client: TestClient)
103103
assert client.post("/orders").status_code == 404
104104

105105

106+
def test_behind_a_forwarded_prefix_the_site_serves_its_own_paths_and_the_fallback_still_guards_reserved_ones(
107+
client: TestClient) -> None:
108+
behind = {"X-Forwarded-Prefix": "/website/shop"}
109+
assert "home" in client.get("/", headers=behind).text
110+
assert client.get("/assets/app.js", headers=behind).text == "console.log(1)"
111+
assert "home" in client.get("/orders/42/edit", headers=behind).text
112+
assert client.get("/api/orders", headers=behind).json() == []
113+
assert client.get("/.well-known/agent-env.json", headers=behind).json()["name"] == "Shop"
114+
assert client.get("/website/shop/assets/app.js", headers=behind).status_code == 404
115+
assert client.post("/agentenv/x", headers=behind).status_code in (404, 405)
116+
117+
106118
def test_a_link_out_of_the_static_folder_is_never_served(dist: Path) -> None:
107119
secret = dist.parent / "secret.txt"
108120
(dist / "leak.txt").symlink_to(secret)

‎src/agent_env/a2a_agent/a2a_agent.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -275,29 +275,33 @@ def _skill_extension(deployed: "DeployedA2AAgent") -> dict:
275275
@staticmethod
276276
async def install_cli(
277277
deployed: "DeployedA2AAgent", cli_artifact: "CliArtifact", gateway_url: str, container: str | None = None,
278-
on_host: bool = False,
278+
on_host: bool = False, role_key: str | None = None,
279279
) -> str:
280280
"""Install a CliArtifact bundle into the agent's filesystem at /opt/cli/<command>/, in ``container`` when
281281
install_agent put the agent in one, or on the VM host, ``on_host``, when it put it there. Writes a sidecar
282-
bin/.env with the gateway URL and chmod +x's the entrypoint. Idempotent. Returns the path to the entrypoint."""
282+
bin/.env with the gateway URL, and with ``role_key``, the key of that gateway's deploy, when it has one, so
283+
each installed CLI sends its own deploy's key beside its role; then chmod +x's the entrypoint. Idempotent.
284+
Returns the path to the entrypoint."""
283285
from agent_env.providers.sandbox_providers.sandbox import VmSandbox, into_container, stage_files_into_container
286+
from agent_env.task_step.task_steps.mcp_cli_builder.codegen import GATEWAY_URL_ENV_VAR, ROLE_KEY_ENV_VAR
284287
from agent_env.providers.sandbox_providers.sandbox_provider import build_sandbox_provider, get_agent_sandbox_provider
285288
provider = build_sandbox_provider(deployed.sandbox_type) if deployed.sandbox_type else get_agent_sandbox_provider()
286289
sandbox = await provider.get_sandbox(deployed.sandbox_id)
287290
target_root = f"/opt/cli/{cli_artifact.command_name}"
288291
entrypoint_path = f"{target_root}/{cli_artifact.entrypoint}"
289292
env_dir = posixpath.dirname(entrypoint_path)
293+
sidecar = f"{GATEWAY_URL_ENV_VAR}={gateway_url}\n" + (f"{ROLE_KEY_ENV_VAR}={role_key}\n" if role_key else "")
290294

291295
if on_host:
292-
await sandbox.write_host_file(f"AGENT_ENV_GATEWAY_URL={gateway_url}\n".encode(), f"{env_dir}/{GATEWAY_ENV_FILE}")
296+
await sandbox.write_host_file(sidecar.encode(), f"{env_dir}/{GATEWAY_ENV_FILE}")
293297
await stage_files_into_container(
294298
sandbox, cli_artifact.get_cli_files().get_file_artifacts(), target_root, on_host=True)
295299
await sandbox.exec_script(f"chmod +x {shlex.quote(entrypoint_path)}")
296300
logger.info(f"Installed CliArtifact '{cli_artifact.id}' v{cli_artifact.version} on the host at {entrypoint_path}")
297301
return entrypoint_path
298302

299303
# write .env first — write_file_from_text creates the parent dir; write_file_from_object does not.
300-
await sandbox.write_file_from_text(f"AGENT_ENV_GATEWAY_URL={gateway_url}\n", f"{env_dir}/{GATEWAY_ENV_FILE}",
304+
await sandbox.write_file_from_text(sidecar, f"{env_dir}/{GATEWAY_ENV_FILE}",
301305
**into_container(container))
302306

303307
for rel_path, file_artifact in cli_artifact.get_cli_files().get_file_artifacts().items():

‎src/agent_env/cli/env/deploy.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,10 @@
4848
@click.option("--env-state-instance-id", default=None,
4949
help="Attach against an EXISTING env state instance instead of creating a fresh store "
5050
"(its own type selects the provider).")
51-
def deploy(env_id: str, env_version: int | None, ttl_seconds: int, gateway_mode: str, sandbox: str, service_db_env_id: str | None, gateway_env_id: str | None, website_browser_env_id: str | None, disk_size_gb: float, cpu: float | None, memory_mb: int | None, env_state_type: str | None, env_state_instance_id: str | None):
51+
@click.option("--keyed-roles", is_flag=True, default=False,
52+
help="Draw a role key for the deploy: its gateway then believes a role other than default only from a "
53+
"caller that sends the key beside it.")
54+
def deploy(env_id: str, env_version: int | None, ttl_seconds: int, gateway_mode: str, sandbox: str, service_db_env_id: str | None, gateway_env_id: str | None, website_browser_env_id: str | None, disk_size_gb: float, cpu: float | None, memory_mb: int | None, env_state_type: str | None, env_state_instance_id: str | None, keyed_roles: bool):
5255
"""Deploy an MCP server environment."""
5356
from agent_env.providers import build_sandbox_provider
5457
from agent_env.config import get_config
@@ -89,6 +92,8 @@ def deploy(env_id: str, env_version: int | None, ttl_seconds: int, gateway_mode:
8992
if env_state_instance_id:
9093
deploy_kwargs["env_state_instance_id"] = env_state_instance_id
9194
click.echo(f"Env state instance id: {env_state_instance_id}")
95+
if keyed_roles:
96+
deploy_kwargs["keyed_roles"] = True
9297
try:
9398
with run_scope(env.id):
9499
deployed_env = asyncio.run(env.deploy(**deploy_kwargs))

‎src/agent_env/env/env.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
from agent_env.store.routing import namespace_routing_enabled
1818
from agent_env.utils.paths import validate_relative_filename
1919

20-
from .gateway import GatewayMode
20+
from .gateway import AGENT_ENV_ROLE_HEADER, AGENT_ENV_ROLE_KEY_HEADER, GatewayMode
2121
from .gateway.constants import WELL_KNOWN_PATH
2222
from .store import get_env_store
2323

@@ -83,6 +83,7 @@ class DeployedEnv:
8383
# The provider that made the record, so the class it loads as (see from_dict); capabilities still come from the card.
8484
env_provider_type: Optional[str] = None
8585
environment_card_url: Optional[str] = None
86+
role_key: Optional[str] = None
8687
# The env card as last read, and when (ISO 8601, UTC); written at deploy from the readiness probe.
8788
environment_card: Optional[dict] = None
8889
environment_card_read_at_utc: Optional[str] = None
@@ -122,6 +123,11 @@ def control_headers_for(self, url: str) -> dict[str, str]:
122123
"""What a call to ``url`` sends of the env's control token: ``control_headers`` when ``url`` is the env's
123124
address or under it, as a step's grant gives them, and none anywhere else, an override's address say."""
124125
return protocol_v1.granted_headers(url, {self.environment_url: self.control_headers})
126+
def role_headers(self, role: str) -> dict[str, str]:
127+
"""The headers a request to the env sends to act as `role`: the role, and the deploy's `role_key` beside it,
128+
without which a gateway that has one takes the request for `default`'s. A record from before the key, of a deploy without
129+
`keyed_roles`, or of one with no gateway, has none, and its role header alone is believed."""
130+
return {AGENT_ENV_ROLE_HEADER: role, **({AGENT_ENV_ROLE_KEY_HEADER: self.role_key} if self.role_key else {})}
125131

126132
def supports(self, uri: str, method: str) -> bool:
127133
"""Whether the stored env card offers `method` on the extension at `uri`; no network."""
@@ -200,6 +206,7 @@ def _fields_from(cls, data: dict) -> dict:
200206
created_at_utc=data.get("created_at_utc"),
201207
expires_at_utc=data.get("expires_at_utc"),
202208
control_token=data.get("control_token"),
209+
role_key=data.get("role_key"),
203210
)
204211

205212

‎src/agent_env/env/envs/mcp_server.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -107,13 +107,13 @@ def accept_toml(cls, data: dict, ctx: AuthoringContext) -> dict:
107107
@environment_card when it isn't set. Raises BundleError listing every problem."""
108108
return ctx.accept_env(data, cls, named_by="image")
109109

110-
async def deploy(self, ttl_seconds: int = 10800, disk_size_gb: float = 10, gateway_mode: GatewayMode = GatewayMode.PERFORMANCE, cpu: float | None = None, memory_mb: int | None = None, sandbox_type: str | None = None, env_state_type: str | None = None, env_state_instance_id: str | None = None, artifact_id: str | None = None, artifact_version: int | None = None, *, attribution: Optional[Attribution] = None) -> DeployedEnv:
110+
async def deploy(self, ttl_seconds: int = 10800, disk_size_gb: float = 10, gateway_mode: GatewayMode = GatewayMode.PERFORMANCE, cpu: float | None = None, memory_mb: int | None = None, sandbox_type: str | None = None, env_state_type: str | None = None, env_state_instance_id: str | None = None, artifact_id: str | None = None, artifact_version: int | None = None, *, attribution: Optional[Attribution] = None, keyed_roles: bool = False) -> DeployedEnv:
111111
# In container mode the server runs in its own container, so loads stage there, as for a MultiEnv child.
112112
return await deploy_through_provider(
113113
self, environment_name=self.environment_name, ttl_seconds=ttl_seconds, sandbox_type=sandbox_type,
114114
disk_size_gb=disk_size_gb, gateway_mode=gateway_mode, cpu=cpu, memory_mb=memory_mb,
115115
env_state_type=env_state_type, env_state_instance_id=env_state_instance_id, attribution=attribution,
116-
artifact_id=artifact_id, artifact_version=artifact_version,
116+
artifact_id=artifact_id, artifact_version=artifact_version, **({"keyed_roles": True} if keyed_roles else {}),
117117
)
118118

119119
def deploy_refusal(self, *, sandbox_type: str | None = None, **options) -> str | None:

0 commit comments

Comments
 (0)