[williamloo-scale]

Stacked on #429.

The gateway side of website/v1: roles that can't be spoofed, the address a site is reached at, and triggers matched by route.

• Role key, opt-in per deploy. A deploy with keyed_roles (deploy_env's keyed_roles: true, or env deploy --keyed-roles) draws a secret role key, gives it to the gateway (AGENTENV_ROLE_KEY) and to each website server (WEBSITE_ROLE_KEY), and records it on the deployed env (DeployedEnv.role_key, sent by role_headers(role)). Its gateway believes a role other than default, on REST and MCP, only beside AgentEnv-Role-Key equal to the key. It strips a client's key and sends its own upstream only beside a verified role, so SDK sites believe it. deploy_agent, the episode proxy, post-turn hook /step calls and the generated MCP CLI send the key. Any other deploy draws none, and its gateway believes the role header alone, as before. A step asking for keyed_roles of an env whose provider doesn't take them is refused at save.
• Forwarded headers. /svc and /website set X-Forwarded-Host, -Proto and -Prefix and drop the client's copies. The SDK takes the prefix as the root path, so base_url, request.url and redirects name the gateway's address.
• Triggers by route. A website trigger's when may name op, a route of the site's card, and then matches only requests that reach it. Registration refuses an op the card doesn't name. triggers/v1 declares website_op, so an older gateway is refused.

Before merging

• On a keyed_roles deploy, a caller that sends a non-default role without role_headers(role) is default; agentenvhub-sdk and the hub don't send the key yet, so their tasks shouldn't turn it on until they do. Unkeyed deploys, the default, are unaffected.
• An agent deployed with a role receives the key, so the key protects against pages and browsers, not a hostile agent.
• The key is stored in plaintext on the instance record, beside the control token.
• The CLI's default role cli is default on a keyed deploy.

Test

Unit suite: 12,712 passed (one GitHub-clone test from main, which hangs on the local machine on main too, deselected).

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, with the earlier non-blocking reserved-path finding still open.

Findings

1.  Reserved paths reach site handlers ▶

Fix with agent prompt

### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/website/environment.py:undefined-312
Adding the forwarded prefix to `scope["path"]` breaks `_unreserved`, which still checks that full path with `reserved_path`. For a site with `@api.post("/{rest:path}")`, a request to `/agentenv/unknown` with `X-Forwarded-Prefix: /website/shop` now runs the site's handler instead of returning 404. A write handler could change site data on a request that should be refused.

Check the site-relative path with `get_route_path(request.scope)` in `_unreserved`, as `_Fallback` now does.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds optional role keys, forwards the website’s public address, and lets website triggers match named routes.

• Keyed deployments require a matching key before the gateway accepts a non-default role.
• Website servers use the gateway’s public address in their URLs and redirects.
• Website triggers can match the named route that handled a request.

Diagram

sequenceDiagram
    participant Caller
    participant Gateway
    participant Website
    participant Triggers
    Caller->>Gateway: Request with role and optional key
    Gateway->>Gateway: Check role key when enabled
    Gateway->>Website: Verified role and forwarded address
    Website-->>Gateway: Response
    Gateway->>Triggers: Match method, upstream path, and named route
    Triggers-->>Gateway: Complete any response barrier
    Gateway-->>Caller: Response

Loading

_{Reviews (12) · Last reviewed commit: "feat(gateway): a keyed deploy's role key..." · Reviewed by Greptile}

[greptile-apps]

Reserved paths reach site handlers

Adding the forwarded prefix to scope["path"] breaks _unreserved, which still checks that full path with reserved_path. For a site with @api.post("/{rest:path}"), a request to /agentenv/unknown with X-Forwarded-Prefix: /website/shop now runs the site's handler instead of returning 404. A write handler could change site data on a request that should be refused.

Check the site-relative path with get_route_path(request.scope) in _unreserved, as _Fallback now does.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/website/environment.py
Line: 348

Comment:
**Reserved paths reach site handlers**

Adding the forwarded prefix to `scope["path"]` breaks `_unreserved`, which still checks that full path with `reserved_path`. For a site with `@api.post("/{rest:path}")`, a request to `/agentenv/unknown` with `X-Forwarded-Prefix: /website/shop` now runs the site's handler instead of returning 404. A write handler could change site data on a request that should be refused.

Check the site-relative path with `get_route_path(request.scope)` in `_unreserved`, as `_Fallback` now does.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.