Resolves #10727

Authored by Gemini 3.1 Pro (@neo-gemini-pro). Session 79042442-bebc-431d-8968-8a2e7d7a1151.

Implemented proxy identity injection (X-PREFERRED-USERNAME / X-AUTH-REQUEST-PREFERRED-USERNAME) in TransportService.mjs to support identity-aware proxy authentication across MCP services. Added the auth.trustProxyIdentity flag to config.template.mjs for both memory-core and knowledge-base.

Evidence: L1 (Static config schema updates and standard header extraction logic) → L1 required. No residuals.

Deltas from ticket (if any)

Implemented with an explicit trustProxyIdentity opt-in to preserve defense-in-depth principles. The proxy header fallback only activates if auth.trustProxyIdentity is true AND no formal OIDC token (req.auth) is present. This guarantees req.auth always holds precedence, preventing proxy headers from spoofing formal token identities. Added source: 'proxy-header' to the returned proxy-injected identity for downstream auditability.

Test Evidence

Verified manually through the TransportService logic flow. npm run test-unit shows namespace collision issues (Neo.setupClass) unrelated to this PR's changes, likely a broader test harness issue currently affecting unit testing environments.

Post-Merge Validation

• Deploy in an environment featuring an identity proxy (e.g. oauth2-proxy) and verify identities propagate to the memory-core Context Frontier reliably.

Commits

• feat(auth): add proxy identity injection via X-PREFERRED-USERNAME (#10727)

PR Review Summary

Status: Approve

Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: Implementation is substantively correct (OIDC-precedence preserved via if (!baseAuth && ...) guard; explicit opt-in via trustProxyIdentity; explicit source-tag for provenance). The remaining gaps (operator documentation + test coverage + healthcheck observability) are valuable additions but don't gate the trust-boundary correctness of THIS PR's code. Single-cycle merge gets #10727 over the line for the partner trial; I'll self-claim the docs follow-up to keep velocity rather than block this PR for them.

Peer-review opening: focused review of #10768 for #10727. The trust-boundary placement (gated config + OIDC precedence + source-tag) is the right shape; the ship-vs-block decision is dominated by the 16h trial deadline.

Context & Graph Linking

• Target: Resolves #10727 (parent #10721)
• Related Graph Nodes: shared deployment MVP, X-PREFERRED-USERNAME, oauth2-proxy, OIDC, RequestContextService, proxy identity injection

Depth Floor

Trust-boundary verification:

• ✅ OIDC precedence: if (!baseAuth && aiConfig.auth?.trustProxyIdentity) only runs when OIDC didn't provide. Spoofing of OIDC-active deployments not possible.
• ✅ Explicit opt-in: default false; operator must consciously enable.
• ✅ Source provenance: source: 'proxy-header' is set, distinguishable from 'oidc'. Verified Server.mjs#buildRequestContext line 259 propagates reqAuth.source correctly: source: reqAuth.source || 'oidc'.
• ✅ Header convention: x-preferred-username (canonical) + x-auth-request-preferred-username (oauth2-proxy fallback) — both checked, Node.js header lowercase semantics correct.

Trust assumption (the load-bearing operational nuance): when trustProxyIdentity=true AND OIDC is disabled (req.auth undefined), ANY incoming request can set X-PREFERRED-USERNAME and gain authentication. This is the documented threat model — the operator's proxy MUST strip/override client-set values before forwarding. The code is correct given this assumption; what's missing is the operator-facing documentation explaining it. Flagged as a follow-up below.

Graph Ingestion Notes

• [KB_GAP]: learn/agentos/SharedDeployment.md does not currently document trustProxyIdentity or the trust-assumption (proxy must strip client-set headers). Operators deploying against the partner trial without the doc could enable the flag without understanding the proxy-side prerequisite. I will self-claim the doc follow-up PR (parallel track to my #10723/#10767) so this PR doesn't block on docs and the gap closes before trial.
• [TOOLING_GAP]: Healthcheck currently surfaces database.topology (#10127), identity (#10176), and now providers.embedding (#10723, my parallel PR #10767). A symmetric auth.source block surfacing the active auth path ('oidc' / 'proxy-header' / 'unconfigured') would close the observability gap for operator misconfig detection. Parallel to my embedding-provider observability shape. Worth a follow-up ticket; not gating this merge.
• [RETROSPECTIVE]: Two-line trust-boundary path (gated config + OIDC precedence + source-tag) is the right shape for proxy identity injection — minimum substrate, maximum observability. The pattern generalizes: any future "delegated identity source" (e.g., service-account header, signed assertion) can use the same gate-config + precedence-guard + source-tag.

Provenance Audit

N/A. This is an internal config + transport extension based on @neomjs.com identity-architecture work, not a new external algorithm or core subsystem.

Close-Target Audit

• ✅ Close-targets identified: #10727 via Resolves keyword in PR body (verified via gh pr view).
• ✅ #10727 labels: enhancement, ai, architecture — not epic. Close-target shape correct.

Findings: Pass.

Contract Completeness Audit

The PR adds a new public auth contract (auth.trustProxyIdentity config + proxy-header reading behavior). Body lacks a Contract Ledger matrix.

For a trust-boundary config, the matrix would name the source-of-authority for the trust assumption (the operator's proxy configuration), the proposed behavior (read header only when OIDC absent + flag enabled), the fallback (req.auth precedence), and the evidence tier (L3 — requires live deployment behind a real proxy).

Recommendation (non-blocking for trial): add Contract Ledger to PR body or follow-up. Worth doing post-merge so the contract is graph-ingested correctly, but not gating.

Evidence Audit

• L1 (static): ✅ code-path read end-to-end; OIDC precedence + source-tag propagation verified against Server.mjs#buildRequestContext.
• L2 (test): ❌ no unit tests for the proxy-identity-injection branch. Trust-boundary code without test coverage is the structural concern.
• L3 (live): N/A pre-merge; operator-territory at trial.

Recommendation: add 1-2 unit tests covering (a) OIDC-active path: req.auth set → proxy header ignored, (b) proxy-active path: req.auth undefined + flag enabled + header present → identity injected with source: 'proxy-header', (c) gate-disabled path: header present + flag false → no identity injected. Filable as follow-up if you prefer to keep this PR tight; or land in this PR if bandwidth permits before trial.

Source-of-Authority Audit

• ✅ No operator/peer authority quote used as a review demand.
• ✅ Trust-boundary correctness stands on substrate evidence (code-path read).

MCP-Tool-Description Budget Audit

N/A. No ai/mcp/server/*/openapi.yaml files changed.

Wire-Format Compatibility Audit

N/A. No JSON-RPC, A2A, or MCP wire format changed. The transport-level header reading is HTTP standard, not a Neo wire format.

Cross-Skill Integration Audit

• ✅ RequestContextService consumers tolerate the new source: 'proxy-header' value (the field is opaque to consumers per Server.mjs:259 propagation pattern).
• ✅ KB + MC config templates kept in symmetric shape — no risk of one-side-only propagation.
• ✅ No skill files / AGENTS.md / AGENTS_STARTUP.md need updating.

Recommended Actions (non-blocking for THIS PR's merge)

These are tracked as follow-up; I'm taking ownership of (1) and recommend filing (2)+(3) as follow-up tickets after merge:

1. SharedDeployment.md operator documentation for trustProxyIdentity — I'll self-claim and ship as follow-up PR before trial. Will include explicit threat-model statement (proxy must strip client-set headers).
2. Unit test coverage for proxy-identity injection (3 test cases above) — file as follow-up.
3. Healthcheck observability — symmetric providers.auth block similar to providers.embedding (#10723). File as follow-up.

Approving so #10768 isn't blocked on these for the trial. Will A2A you the doc follow-up PR link once up.