Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
from .types import (
CONTROL_TOKEN_ENV,
CONTROL_TOKEN_HEADER,
CONTROL_TOKEN_SHA256_ENV,
DATA_OBJECTS_EXTENSION_URI,
INTAKE_EXTENSION_URI,
MCP_PATH,
Expand Down Expand Up @@ -167,6 +168,7 @@
"RPC_PATH",
"CONTROL_TOKEN_ENV",
"CONTROL_TOKEN_HEADER",
"CONTROL_TOKEN_SHA256_ENV",
"WELL_KNOWN_PATH",
"METHOD_RESET",
"METHOD_ADD",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
import decimal
import enum
import functools
import hashlib
import hmac
import inspect
import json
Expand All @@ -29,7 +30,7 @@
from .tool_access import extensions as tool_access_extensions
from .tool_context import EMPTY, ToolContext, bound, context_from_http, context_from_mcp
from .transfers import WriteNamespaceGrant
from .types import CONTROL_TOKEN_ENV, DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, SKILL_EXTENSION_URI, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body
from .types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV, DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, SKILL_EXTENSION_URI, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -1598,8 +1599,14 @@ def _error_response(error: AgentEnvError) -> Response:


def control_check() -> Callable[[Any], bool]:
"""Whether a call's headers carry the env's control token as their bearer, with ``CONTROL_TOKEN_ENV`` set; without
it, any do."""
"""Whether a call's headers carry the env's control token as their bearer: one whose sha256 is
``CONTROL_TOKEN_SHA256_ENV`` when that is set, else ``CONTROL_TOKEN_ENV``; with neither set, any do."""
if digest := os.environ.get(CONTROL_TOKEN_SHA256_ENV, "").strip().lower():
def verified(headers: Any) -> bool:
scheme, _, token = headers.get("authorization", "").partition(" ")
sent = hashlib.sha256(token.encode()).hexdigest() if scheme == "Bearer" and token else ""
return hmac.compare_digest(sent, digest)
return verified
token = os.environ.get(CONTROL_TOKEN_ENV)
if not token:
return lambda headers: True
Expand All @@ -1609,9 +1616,9 @@ def control_check() -> Callable[[Any], bool]:

def control_guard() -> Callable[[Callable], Callable]:
"""What wraps a framework-only route, everything an env serves but its MCP endpoint and its card: with
``CONTROL_TOKEN_ENV`` set, a call that doesn't carry that token as its bearer is refused before the route runs;
without it, nothing."""
if not os.environ.get(CONTROL_TOKEN_ENV):
``CONTROL_TOKEN_SHA256_ENV`` or ``CONTROL_TOKEN_ENV`` set, a call that doesn't carry the token as its bearer is
refused before the route runs (``control_check``); without either, nothing."""
if not (os.environ.get(CONTROL_TOKEN_SHA256_ENV) or os.environ.get(CONTROL_TOKEN_ENV)):
return lambda handler: handler
allowed = control_check()

Expand Down
7 changes: 4 additions & 3 deletions packages/agentenv-protocol/src/agentenv_protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,10 @@ def request_headers(url: str, headers: dict[str, str] | None = None) -> dict[str

def granted_headers(url: str, grants: dict[str | None, dict[str, str]]) -> dict[str, str]:
"""What ``grants``, env addresses and the headers that carry their control tokens, give a call to ``url``: those of
the address it is or is under, and none anywhere else."""
return next((sent for base, sent in grants.items()
if base and (url == base.rstrip("/") or url.startswith(f"{base.rstrip('/')}/"))), {})
the longest address it is or is under, as a child's route under its gateway's, and none anywhere else."""
under = [(len(base.rstrip("/")), sent) for base, sent in grants.items()
if base and (url == base.rstrip("/") or url.startswith(f"{base.rstrip('/')}/"))]
return max(under, key=lambda found: found[0])[1] if under else {}


async def _rpc(base_url: str, method: str, params: dict, timeout: int, verify: bool,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
COMPUTER_EXEC = "urn:agentenv:computer-exec/v1"
COMPUTER_RECORDING = "urn:agentenv:computer-recording/v1"

#: What computer/v1's ``control_token`` says of a driver that takes its control token's sha256.
CONTROL_TOKEN_SHA256 = "sha256"
MAX_EXEC_TIMEOUT_S = 3600
KEYBOARD_RANGES = {"tap_hold_ms": (0, 1000), "type_delay_ms": (0, 1000), "max_hold_ms": (0, 600_000)}

Expand Down Expand Up @@ -86,15 +88,17 @@ def extension_params(driver: ComputerDriverEnvironment, uri: str) -> dict:


def computer_features(driver: ComputerDriverEnvironment) -> dict:
"""computer/v1's params: what the seven tools take, how input is delivered, the platform and the default data
paths."""
"""computer/v1's params: what the seven tools take, how input is delivered, the platform, the default data paths,
and that the driver takes its control token's sha256 (``CONTROL_TOKEN_SHA256_ENV``), so agent-env boots it with
that and not the token."""
return {
"buttons": list(driver.buttons), "max_click_count": driver.max_click_count,
"keys": driver.keys if driver.keys == "all" else list(driver.keys), "max_text_length": driver.max_text_length,
"max_wait_ms": driver.max_wait_ms, "max_drag_points": driver.max_drag_points,
"max_duration_ms": driver.max_duration_ms, "max_key_repeat": driver.max_key_repeat,
"max_scroll_amount": driver.max_scroll_amount, "delivery": "foreground", "platform": driver.platform.as_dict(),
"supports": list(driver.supports), "default_data_paths": list(DEFAULT_DATA_PATHS), "screen": driver.screen_kind,
"control_token": CONTROL_TOKEN_SHA256,
}


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
``python -m agentenv_protocol.computer.serve_app <file>:<Class>``, run in the app's folder, serves the class's card and
``computer-app/v1`` where only the computer reaches it (``served``): on Linux and macOS the Unix socket
``.agentenv/server.sock`` there, on Windows a loopback port it writes there with a token. It takes no control token
(``CONTROL_TOKEN_ENV``): the driver checks it in front of the app. Before it serves, it keeps a copy of
(``CONTROL_TOKEN_ENV``, ``CONTROL_TOKEN_SHA256_ENV``): the driver checks it in front of the app. Before it serves, it keeps a copy of
the app's data paths as installed, which a reset puts back; once it serves, it adds the app's launcher and launches a
boot app (``AppRuntime.start``). A server that can't start, or whose start fails once it serves, writes why to
``.agentenv/server.failure``, which its computer's driver reports, and exits. It runs on real time, so its own
Expand All @@ -20,7 +20,7 @@
import uvicorn

from .. import transfers
from ..types import CONTROL_TOKEN_ENV
from ..types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_SHA256_ENV
from ._load import load_class
from .app import FAILURE, ComputerAppEnvironment
from .served import LOOPBACK, SOCKET, bind, guarded
Expand All @@ -45,6 +45,7 @@ def _serve(argv: list[str]) -> None:
raise SystemExit(USAGE)
file, _, name = argv[0].partition(":")
os.environ.pop(CONTROL_TOKEN_ENV, None)
os.environ.pop(CONTROL_TOKEN_SHA256_ENV, None)
app = load_class(Path(file), name, ComputerAppEnvironment)()
runtime = app._computer_app_runtime()
app._computer_app_data_plane().keep_initial()
Expand Down
3 changes: 3 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ def error_body(code: str, message: str, **fields: Any) -> dict:
#: The variable that hands an env the token its framework-only routes take as their bearer, everything it serves but
#: its MCP endpoint and its card; agent-env sets it when it deploys the env, and without it those routes are open.
CONTROL_TOKEN_ENV = "AGENTENV_CONTROL_TOKEN"
#: The variable that hands an env only the hex sha256 of that token, which those routes then take in its place: a
#: process that can read the env's environment learns nothing it could send. Set, it is checked and the token isn't.
CONTROL_TOKEN_SHA256_ENV = "AGENTENV_CONTROL_TOKEN_SHA256"
#: The header a control token travels in where it must not collide with a front door's own ``Authorization``.
CONTROL_TOKEN_HEADER = "AgentEnv-Control-Token"

Expand Down
1 change: 1 addition & 0 deletions packages/agentenv-protocol/tests/test_computer_driver.py
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,7 @@ async def test_the_card_declares_the_contract_the_driver_implements():
assert computer["buttons"] == ["left", "right", "middle"] and computer["max_click_count"] == 3
assert computer["keys"] == "all" and computer["platform"] == LINUX.as_dict() and computer["delivery"] == "foreground"
assert computer["default_data_paths"] == ["Desktop", "Documents", "Downloads"] and computer["screen"] == "desktop"
assert computer["control_token"] == "sha256" # agent-env boots it with the token's digest, not the token
assert "methods" not in computer and extensions["urn:agentenv:skill/v1"]["params"]["methods"]["get"]["method"] == "GET"
assert extensions["urn:agentenv:computer-pointer/v1"]["params"]["buttons"] == ["left", "right", "middle"]
assert set(extensions["urn:agentenv:computer-keyboard/v1"]["params"]["methods"]) == {"get", "set"}
Expand Down
35 changes: 35 additions & 0 deletions packages/agentenv-protocol/tests/test_control_token.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from __future__ import annotations

import contextlib
import hashlib

import anyio
import httpx
Expand All @@ -18,6 +19,7 @@

from agentenv_protocol import ( # noqa: E402
CONTROL_TOKEN_ENV,
CONTROL_TOKEN_SHA256_ENV,
RPC_PATH,
WELL_KNOWN_PATH,
AgentEnvEnvironment,
Expand Down Expand Up @@ -96,9 +98,42 @@ async def test_with_a_token_every_framework_only_route_refuses_a_call_without_it
assert card.status_code == 200 and tools == ["read"]


@pytest.mark.asyncio
@pytest.mark.parametrize("plain", [None, "a-different-token"], ids=["alone", "beside-a-token"])
async def test_given_only_the_tokens_sha256_every_framework_only_route_takes_the_token_itself(monkeypatch, plain):
"""An env handed the token's sha256 holds nothing a caller could send: the digest itself is refused, the token
answers, and a plain token beside the digest is ignored."""
digest = hashlib.sha256(b"s3cret").hexdigest()
monkeypatch.setenv(CONTROL_TOKEN_SHA256_ENV, digest)
if plain is None:
monkeypatch.delenv(CONTROL_TOKEN_ENV, raising=False)
else:
monkeypatch.setenv(CONTROL_TOKEN_ENV, plain)

with anyio.fail_after(30):
async with _served() as (rest, _):
without = await _calls(rest, {})
the_digest = await _calls(rest, client.control_headers(digest))
not_bearer = await _calls(rest, {"Authorization": "s3cret"})
beside = await _calls(rest, client.control_headers(plain)) if plain else [401, 401, 401]
right = await _calls(rest, client.control_headers("s3cret"))

assert without == the_digest == not_bearer == beside == [401, 401, 401]
assert right == [200, 200, 200]


def test_a_grant_for_a_route_under_an_address_wins_over_the_address():
gateway = "http://gw:18765"
with client.authorized({gateway: client.control_headers("env"), f"{gateway}/svc/desk": client.control_headers("desk")}):
sent = [client.request_headers(url) for url in (f"{gateway}/svc/desk/agentenv", f"{gateway}/svc/desk",
f"{gateway}/svc/desk-2/agentenv", f"{gateway}/state")]
assert sent == [{"Authorization": "Bearer desk"}] * 2 + [{"Authorization": "Bearer env"}] * 2


@pytest.mark.asyncio
async def test_without_a_token_every_route_is_open(monkeypatch):
monkeypatch.delenv(CONTROL_TOKEN_ENV, raising=False)
monkeypatch.delenv(CONTROL_TOKEN_SHA256_ENV, raising=False)

with anyio.fail_after(30):
async with _served() as (rest, _):
Expand Down
28 changes: 22 additions & 6 deletions src/agent_env/env/env.py
Original file line number Diff line number Diff line change
Expand Up @@ -118,10 +118,16 @@ def control_headers(self) -> dict[str, str]:
"""What a call to the env's framework-only routes sends: its control token, when it has one."""
return protocol_v1.control_headers(self.control_token)

@property
def control_grants(self) -> dict[Optional[str], dict[str, str]]:
"""The addresses under the env's that take a control token, each with the headers that carry it
(``protocol_v1.authorized``): the env's own address, with ``control_headers``."""
return {self.environment_url: self.control_headers}

def control_headers_for(self, url: str) -> dict[str, str]:
"""What a call to ``url`` sends of the env's control token: ``control_headers`` when ``url`` is the env's
address or under it, as a step's grant gives them, and none anywhere else, an override's address say."""
return protocol_v1.granted_headers(url, {self.environment_url: self.control_headers})
"""What a call to ``url`` sends of a control token: the headers of the longest of ``control_grants`` that
``url`` is or is under, as a step's grant gives them, and none anywhere else, an override's address say."""
return protocol_v1.granted_headers(url, self.control_grants)

def supports(self, uri: str, method: str) -> bool:
"""Whether the stored env card offers `method` on the extension at `uri`; no network."""
Expand Down Expand Up @@ -166,10 +172,11 @@ async def invoke(self, uri: str, method: str, params: Optional[dict] = None, *,
environment_name = child.name
else:
card = self.environment_card if environment_name is None else self.get_child_env_card(environment_name)
if card is None or not self.environment_url or protocol_v1.find_extension_method(card, uri, method) is None:
if card is None or not self.environment_url or (op := protocol_v1.find_extension_method(card, uri, method)) is None:
raise EnvCapabilityUnsupported(uri, method, self.env_id, self.instance_id, environment_name)
return await protocol_v1.invoke_extension(self.environment_url, card, uri, params, timeout, method=method,
headers=self.control_headers)
return await protocol_v1.invoke_extension(
self.environment_url, card, uri, params, timeout, method=method,
headers=self.control_headers_for(f"{self.environment_url.rstrip('/')}{op.get('endpoint') or ''}"))

async def readiness(self, timeout: float = READY_TIMEOUT_S) -> WebsiteReadiness:
"""Whether the env is ready, as the protocol determines a website env's health (``env_readiness``): every site
Expand Down Expand Up @@ -243,6 +250,15 @@ class DeployedGatewayEnv(DeployedSandboxEnv):
# by its environment name.
child_envs: dict[str, dict] = field(default_factory=dict)

@property
def control_grants(self) -> dict[Optional[str], dict[str, str]]:
"""The gateway's address with its control token, and under it each child's /svc route with the child's own,
which reaches the child through any gateway, one that would put a child's in place of its own or not."""
return {**super().control_grants,
**{f"{self.environment_url.rstrip('/')}/svc/{name}": protocol_v1.control_headers(token)
for name, record in self.child_envs.items()
if self.environment_url and (token := (record or {}).get("control_token"))}}

@classmethod
def _fields_from(cls, data: dict) -> dict:
return {
Expand Down
16 changes: 8 additions & 8 deletions src/agent_env/env/envs/_multi_computers.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ def routes_later(entry: Optional[dict]) -> bool:

def _clock_read_token(record: DeployedEnv) -> str | None:
"""The read token a computer's clock watch carries when its card says it's a clock follower (``clock/v1``'s
``sync_time``): for now its control token, which a token of its own can replace without the gateway knowing."""
``sync_time``): its own control token, which the gateway takes from it only at the watch."""
return record.control_token if computer_clock.follows(record) else None


Expand Down Expand Up @@ -190,10 +190,10 @@ def _recorded_browser(self, records: Mapping[str, dict]) -> Optional[ComputerEnv

def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_seconds: int,
attribution: Optional[Attribution], websites: Mapping[str, str], live_hosts: Iterable[str] = ()
) -> Callable[[Optional[str], Optional[str]], Awaitable[list[ExternalChild]]]:
) -> Callable[[Optional[str]], Awaitable[list[ExternalChild]]]:
"""The gateway's ``children``: every computer deployed as its child_envs entry says, its tools served under its
name and ``_``, its framework-only routes taking ``control_token``, the gateway's, which the gateway passes on to
them, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the
name and ``_``, its framework-only routes taking a token of its own, which the gateway sends it in place of the
gateway's own on its /svc routes, so nothing in a computer holds the gateway's, and its network allowing ``reach``, the gateway's address when the gateway has one yet, and the
``live_hosts`` of the multi env's live websites; then each as the gateway fronts it. A computer routing the multi env's ``websites`` (their environment names by env id)
boots with its boot apps held, for ``finish`` to route them once the gateway is up. A gateway deploy tried again
deploys them again, after closing the earlier try's."""
Expand All @@ -205,23 +205,23 @@ def deployer(self, child_envs: Optional[dict], *, sandbox_type: str | None, ttl_
routing = entry["env_params"]["site_routing"]
self._routes[name] = None if routing is True else [websites[env_id] for env_id in routing]

async def deploy(reach: Optional[str], control_token: Optional[str]) -> list[ExternalChild]:
async def deploy(reach: Optional[str]) -> list[ExternalChild]:
nonlocal tries
if tries:
await self.close()
tries += 1
results = await asyncio.gather(*(env.deploy(
ttl_seconds=ttl_seconds, attribution=attribution, tool_prefix=f"{env.environment_name}_",
reach=reach or "", sites_later=env.environment_name in self._routes, control_token=control_token,
reach=reach or "", sites_later=env.environment_name in self._routes,
**({"live_hosts": live} if live else {}),
**deploy_options((child_envs or {}).get(env.environment_name), sandbox_type))
for env in self.every), return_exceptions=True)
if failed := [result for result in results if isinstance(result, BaseException)]:
for error in failed[1:]:
logger.warning(f"multi env '{self._owner}': another computer failed to deploy too: {error!r}")
raise failed[0]
return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record))
for env, record in zip(self.every, results)]
return [ExternalChild(env.environment_name, record.mcp_url, record.environment_url, _clock_read_token(record),
record.control_token) for env, record in zip(self.every, results)]
return deploy

async def finish(self, deployed: DeployedEnv) -> None:
Expand Down
Loading
Loading