Context
Retroactive ticket for the doc-work that should have been filed BEFORE PR #10769 opened. The doc PR shipped in tight coordination with PR #10768 (the code-substrate it documents) but I skipped the ticket-create step under self-imposed time pressure — workflow discipline lapse.
The Problem
PR #10768 (feat(auth): add proxy identity injection via X-PREFERRED-USERNAME) ships the trust-boundary code for auth.trustProxyIdentity config + proxy-header reading + OIDC-precedence guard + source-tag propagation. The code is correct, but operators deploying the partner-trial topology need explicit documentation of the load-bearing operational prerequisite: the fronting proxy MUST strip client-set values of X-PREFERRED-USERNAME (and oauth2-proxy variants) before forwarding upstream, set them itself based on its own validated auth state, and prevent direct MC ingress.
Without this doc, operators could enable trustProxyIdentity=true without understanding the proxy-side prerequisite — silent security hole under any default-allow-headers reverse proxy.
The Architectural Reality
learn/agentos/SharedDeployment.md — the operator-facing deployment profile; auth section was missing- PR #10768 changes:
auth.trustProxyIdentity config field + TransportService.mjs proxy-header reading branch
Server.mjs#buildRequestContext:259 — propagates source: 'oidc' | 'proxy-header' into the request context
The Fix
Add an ## Authentication section to SharedDeployment.md between ## Configuration and ## Healthcheck Verification. Cover:
- OIDC vs proxy-identity injection paths
trustProxyIdentity env-var + config substrate- The 3 proxy prerequisites (strip client-set headers; set them itself based on validated auth; prevent direct MC ingress)
- Both header conventions checked (
x-preferred-username canonical + x-auth-request-preferred-username oauth2-proxy variant)
- Source-tag observability (
source: 'oidc' vs 'proxy-header' vs empty for local-dev)
- Fallback discipline: when any of the 3 proxy prerequisites is uncertain, leave
trustProxyIdentity=false
Acceptance Criteria
Out of Scope
- Symmetric healthcheck
providers.auth block (separate follow-up #10770)
- Unit tests for proxy-identity injection (separate follow-up #10772)
- Full OIDC-issuer provisioning steps (operator-side concern; out of MVP scope)
Related
- Code PR: #10768 (
Resolves #10727 — the trust-boundary code substrate)
- Doc PR: #10769 (resolves THIS ticket — already merged 2026-05-05, retroactively-filed ticket)
- Sibling parallel-track: PR #10767 (
feat(memory-core): surface active embedding provider in healthcheck (#10723))
- Parent epic: #10721 (Shared deployment MVP completeness gaps)
Note: This ticket is filed RETROACTIVELY post-merge of PR #10769. Filed for graph-linkage cleanliness — the doc work was real but the ticket-then-PR ordering was skipped under self-imposed time pressure (per pull-request-workflow §0 discipline lapse). @tobiu calibration 2026-05-05: workflow-discipline > velocity even under operator-stated importance contexts.
Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7
Context
Retroactive ticket for the doc-work that should have been filed BEFORE PR #10769 opened. The doc PR shipped in tight coordination with PR #10768 (the code-substrate it documents) but I skipped the
ticket-createstep under self-imposed time pressure — workflow discipline lapse.The Problem
PR #10768 (
feat(auth): add proxy identity injection via X-PREFERRED-USERNAME) ships the trust-boundary code forauth.trustProxyIdentityconfig + proxy-header reading + OIDC-precedence guard + source-tag propagation. The code is correct, but operators deploying the partner-trial topology need explicit documentation of the load-bearing operational prerequisite: the fronting proxy MUST strip client-set values ofX-PREFERRED-USERNAME(and oauth2-proxy variants) before forwarding upstream, set them itself based on its own validated auth state, and prevent direct MC ingress.Without this doc, operators could enable
trustProxyIdentity=truewithout understanding the proxy-side prerequisite — silent security hole under any default-allow-headers reverse proxy.The Architectural Reality
learn/agentos/SharedDeployment.md— the operator-facing deployment profile; auth section was missingauth.trustProxyIdentityconfig field +TransportService.mjsproxy-header reading branchServer.mjs#buildRequestContext:259— propagatessource: 'oidc' | 'proxy-header'into the request contextThe Fix
Add an
## Authenticationsection toSharedDeployment.mdbetween## Configurationand## Healthcheck Verification. Cover:trustProxyIdentityenv-var + config substratex-preferred-usernamecanonical +x-auth-request-preferred-usernameoauth2-proxy variant)source: 'oidc'vs'proxy-header'vs empty for local-dev)trustProxyIdentity=falseAcceptance Criteria
## Authenticationsection added toSharedDeployment.mdOut of Scope
providers.authblock (separate follow-up #10770)Related
Resolves #10727— the trust-boundary code substrate)feat(memory-core): surface active embedding provider in healthcheck (#10723))Note: This ticket is filed RETROACTIVELY post-merge of PR #10769. Filed for graph-linkage cleanliness — the doc work was real but the ticket-then-PR ordering was skipped under self-imposed time pressure (per
pull-request-workflow §0discipline lapse). @tobiu calibration 2026-05-05: workflow-discipline > velocity even under operator-stated importance contexts.Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7