Context
Surfaced during the writing of the Deployment Cookbook (#10800).
The Problem
The shared deployment topology requires routing external traffic to two distinct MCP servers (KB and MC). Without a reference reverse proxy config, operators must reinvent the routing wheel (pathname vs hostname routing).
The Architectural Reality
We support trustProxyIdentity which explicitly relies on headers like X-PREFERRED-USERNAME injected by an external proxy (e.g., oauth2-proxy or nginx).
The Fix
Provide a reference nginx.conf or Caddyfile demonstrating secure header stripping, injection, and routing to the distinct upstream MCP servers.
Acceptance Criteria
Out of Scope
Automated TLS provisioning recipes.
Contract Ledger (T3)
Per canonical specification in learn/agentos/contract-ledger.md. Authored 2026-05-06 via batch-Ledger-upgrade pass on cookbook follow-ups (#10801-#10805) — proposed by @neo-opus-4-7 (systemic gap A2A) and explicitly delegated to body-incorporation by @neo-gemini-3-1-pro per ticket-create-workflow §11 Authorship Respect delegation pattern.
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
Reference reverse-proxy configs: deploy/proxy/nginx.conf + deploy/proxy/Caddyfile (or sibling location). Documents: pathname-based routing (/kb/* → KB MCP server upstream; /mc/* → MC MCP server upstream); explicit header-stripping rules for X-PREFERRED-USERNAME and X-Auth-Request-Preferred-Username BEFORE upstream injection by trusted-proxy auth layer; SSE-compatible streaming config (proxy-buffer off; chunked-transfer enabled). |
#10803, parent #9999, surfacing PR #10806 cookbook Section 3 (Reverse Proxy Configuration) + threat model in SharedDeployment.md §Authentication (the 3 proxy prerequisites: strip client-set values; set them itself; prevent direct MC ingress). |
Reference Nginx config: location /kb/ { proxy_pass http://kb-upstream/; proxy_request_headers ...; proxy_pass_request_headers ...; } with explicit proxy_set_header X-PREFERRED-USERNAME "" to strip incoming spoofed values + proxy_set_header X-PREFERRED-USERNAME $oauth_preferred_username (variable populated by oauth2-proxy auth_request integration) for trusted injection. Symmetric for /mc/. SSE-friendly: proxy_http_version 1.1, proxy_buffering off, chunked_transfer_encoding on. Caddyfile equivalent uses reverse_proxy directives with similar header manipulation. Sample integration with oauth2-proxy for OIDC termination. |
TLS termination at proxy (annotated; out-of-scope for this ticket per Out of Scope clause but referenced as operator-required). Hostname-based routing alternative (e.g., kb.example.com + mc.example.com) noted as alternative pattern with multiple TLS certificate trade-off. Operators using non-oauth2-proxy IdPs (e.g., direct OIDC validation in nginx via auth_jwt) get a brief note pointing to upstream IdP-specific docs. |
Update learn/agentos/DeploymentCookbook.md Section 3 (Reverse Proxy Configuration) — replace "(Note: Canonical Nginx/Caddy configurations are tracked under #10803)" with link to shipped reference configs. Cross-link from SharedDeployment.md §Authentication threat model. |
L2 — operators following the reference Nginx config + a dockerized stack (cross-link #10801) can stand up a working proxy that passes the cookbook Section 8 smoke test. Header-spoof verification: configured proxy correctly strips client-set X-PREFERRED-USERNAME and replaces with auth-validated value; integration spec (#10805) optionally exercises this path. L3 dry-run remains operator-territory. |
Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7
Retrieval Hint: Deployment Cookbook gap surfacing
Context
Surfaced during the writing of the Deployment Cookbook (#10800).
The Problem
The shared deployment topology requires routing external traffic to two distinct MCP servers (KB and MC). Without a reference reverse proxy config, operators must reinvent the routing wheel (pathname vs hostname routing).
The Architectural Reality
We support
trustProxyIdentitywhich explicitly relies on headers likeX-PREFERRED-USERNAMEinjected by an external proxy (e.g., oauth2-proxy or nginx).The Fix
Provide a reference
nginx.conforCaddyfiledemonstrating secure header stripping, injection, and routing to the distinct upstream MCP servers.Acceptance Criteria
/kb/to KB,/mc/to MC) codified.Out of Scope
Automated TLS provisioning recipes.
Contract Ledger (T3)
Per canonical specification in
learn/agentos/contract-ledger.md. Authored 2026-05-06 via batch-Ledger-upgrade pass on cookbook follow-ups (#10801-#10805) — proposed by @neo-opus-4-7 (systemic gap A2A) and explicitly delegated to body-incorporation by @neo-gemini-3-1-pro perticket-create-workflow §11Authorship Respect delegation pattern.deploy/proxy/nginx.conf+deploy/proxy/Caddyfile(or sibling location). Documents: pathname-based routing (/kb/*→ KB MCP server upstream;/mc/*→ MC MCP server upstream); explicit header-stripping rules forX-PREFERRED-USERNAMEandX-Auth-Request-Preferred-UsernameBEFORE upstream injection by trusted-proxy auth layer; SSE-compatible streaming config (proxy-buffer off; chunked-transfer enabled).SharedDeployment.md§Authentication (the 3 proxy prerequisites: strip client-set values; set them itself; prevent direct MC ingress).location /kb/ { proxy_pass http://kb-upstream/; proxy_request_headers ...; proxy_pass_request_headers ...; }with explicitproxy_set_header X-PREFERRED-USERNAME ""to strip incoming spoofed values +proxy_set_header X-PREFERRED-USERNAME $oauth_preferred_username(variable populated byoauth2-proxyauth_requestintegration) for trusted injection. Symmetric for/mc/. SSE-friendly:proxy_http_version 1.1,proxy_buffering off,chunked_transfer_encoding on. Caddyfile equivalent usesreverse_proxydirectives with similar header manipulation. Sample integration withoauth2-proxyfor OIDC termination.kb.example.com+mc.example.com) noted as alternative pattern with multiple TLS certificate trade-off. Operators using non-oauth2-proxyIdPs (e.g., direct OIDC validation in nginx viaauth_jwt) get a brief note pointing to upstream IdP-specific docs.learn/agentos/DeploymentCookbook.mdSection 3 (Reverse Proxy Configuration) — replace "(Note: Canonical Nginx/Caddy configurations are tracked under #10803)" with link to shipped reference configs. Cross-link fromSharedDeployment.md§Authentication threat model.X-PREFERRED-USERNAMEand replaces with auth-validated value; integration spec (#10805) optionally exercises this path. L3 dry-run remains operator-territory.Origin Session ID: 88a6ed3a-b1b9-461a-aaf3-7c9984bd12e7 Retrieval Hint: Deployment Cookbook gap surfacing