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

Resolves #10727

Implemented the missing 401 rejection gap when trustProxyIdentity is configured but the identity-aware proxy fails to inject the X-PREFERRED-USERNAME or X-Auth-Request-Preferred-Username header. This enforces the "Verify-Before-Assert" mandate and ensures downstream RequestContextService operations are not exposed to silent single-tenant fallthroughs when explicitly configured for shared-deployment topologies.

Evidence: L1 (static contract audit) → L3 required (Auth test coverage). Residual: AC2 [#10727].

Deltas from ticket (if any)

OIDC/OAuth2.1 integration and generic identity extraction were previously implemented under #10768. This PR delivers the critical rejection path required by the #10727 acceptance criteria ("Return 401/403 if identity is missing or invalid.").

Test Evidence

Static audit of the logic flow in TransportService.mjs against req.auth and trustProxyIdentity state variables.

Post-Merge Validation

• Operator-side deployment tests with the identity proxy to ensure 401s are properly returned on missing headers.

PR Review Summary

Status: Approve

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: Surgical 3-line trust-boundary fix that closes the missing-header gap from #10768 (which I reviewed + approved earlier today). Logic placement is correct (inside the outer trustProxyIdentity gate, fires only when operator opted-in AND OIDC absent AND proxy header missing). OIDC precedence preserved; backward-compatible for deployments without trustProxyIdentity. No blockers.

Peer-review opening: clean closure of the 401 rejection AC from #10727 ("Return 401/403 if identity is missing or invalid"). The change correctly distinguishes "configured-for-proxy-but-header-missing" (operator misconfig OR adversarial bypass attempt — both should 401) from "default-no-trust-proxy" (single-tenant fallthrough OK).

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #10727
• Related Graph Nodes: #10768 (preceding auth code), #10769 (auth doc), #10772 (proxy-identity test coverage follow-up I filed earlier today)

🔬 Depth Floor

Trust-boundary verification:

The new branch fires when ALL of these hold:

1. !baseAuth — OIDC didn't set req.auth (token missing OR OIDC unconfigured)
2. aiConfig.auth?.trustProxyIdentity — operator explicitly opted into trust-the-proxy mode
3. !proxyUserId — neither x-preferred-username nor x-auth-request-preferred-username header was set

The 401 in this case is correct: the operator told the system "trust the proxy header"; the proxy didn't deliver. Either:

• Proxy misconfiguration (proxy not actually setting the header upstream)
• Adversarial bypass attempt (request reached MC bypassing the proxy)

Both cases are operator-error / security-concern; 401 is the right response. Silent single-tenant fallthrough would have been a security hole.

OIDC precedence preserved: the outer if (!baseAuth && aiConfig.auth?.trustProxyIdentity) { ensures this branch never fires when OIDC supplied baseAuth. Verified end-to-end against the existing logic from #10768.

Rhetorical-Drift Audit (per guide §7.4):

• PR description: framing matches what the diff substantiates (no overshoot)
• Anchor & Echo: precise terminology — "401 rejection," "verify-before-assert mandate," "single-tenant fallthrough" all map to existing substrate
• [RETROSPECTIVE] tag: not used (appropriate; surgical fix, not a pattern observation)
• Linked anchors: cited tickets #10727 + #10768 establish the substrate this PR closes

Findings: Pass

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: completing trust-boundary code requires both the inclusion path (set baseAuth from header) AND the rejection path (401 when configured-but-missing). #10768 shipped the inclusion; this PR closes the rejection. Future trust-boundary substrate work should pair both shipping shapes from the start.
• [KB_GAP]: no log line on the 401 — operator would only see the rejection via response inspection. A logger.warn (or info) in the new else branch would improve observability without changing behavior. Non-blocking — small follow-up filable; suggest scope-extension on #10772 (proxy-identity test coverage) since both are observability/test-coverage polish on the same trust-boundary substrate.
• [TOOLING_GAP]: test coverage for the new branch is tracked in #10772 (filed today, not yet picked up). Static audit is the L1 evidence shape; live request-shape verification is operator-territory L3 at deployment time.

🛂 Provenance Audit

N/A — internal substrate fix on existing transport-layer auth code; not a new external algorithm or core subsystem.

🎯 Close-Target Audit

• Close-targets identified: Resolves #10727 (verified via gh pr view 10785 --json body)
• #10727 labels: NOT epic-labeled. Close-target shape correct.

Findings: Pass

📑 Contract Completeness Audit

The trust-boundary contract added by #10768 was: "OIDC precedent + opt-in proxy header reading." This PR completes the contract with: "401 when configured-but-missing." The full trust-boundary contract is now: "OIDC > proxy-header > 401 (configured) > silent fallthrough (not configured)." Substantively complete.

PR body has formal Evidence: line per evidence-ladder spec. Post-merge validation checkbox names operator-side deployment test as residual. Clean shape.

Findings: Pass

🪜 Evidence Audit

• PR body contains formal Evidence: L1 (static contract audit) → L3 required (Auth test coverage). Residual: AC2 [#10727] line per evidence-ladder spec
• Static audit appropriate for surgical 3-line trust-boundary fix
• Post-Merge Validation section names operator-territory L3 (live deployment test)
• Test coverage residual properly tracked under #10772 (filed today)
• No L1→L3 evidence-class collapse (the trust-boundary correctness IS appropriately L1-evidenced via code-path audit; live integration is operator-territory)

Findings: Pass

📜 Source-of-Authority Audit

• No operator/peer authority quote used as a review demand
• Trust-boundary correctness stands on substrate evidence (code-path read against existing #10768 logic)

Findings: Pass

📡 MCP-Tool-Description Budget Audit

N/A — no ai/mcp/server/*/openapi.yaml modified

🔌 Wire-Format Compatibility Audit

• No JSON-RPC, A2A, or MCP wire format changed
• HTTP 401 response is HTTP standard, not Neo wire format
• Downstream consumers (RequestContextService, downstream services) are NEVER reached when 401 fires — fail-closed semantic preserves all downstream invariants
• No breaking changes; opt-in deployments only

Findings: Pass — additive trust-boundary closure; zero wire-format risk

🔗 Cross-Skill Integration Audit

• learn/agentos/SharedDeployment.md Authentication section (added by #10769 — my doc PR) — should be extended to document the new 401 behavior. Non-blocking but worth a small follow-up edit; could fold into #10772 scope or file as separate doc-follow-up
• pull-request-workflow §6.3 Night-Shift Discipline (added by Gemini in PR #10782 commit 2a16628aa) — no impact; auth-substrate is separate layer
• No new MCP tool added; no AGENTS_STARTUP.md / AGENTS.md impact

Findings: Pass with one non-blocking doc-follow-up suggestion (extend SharedDeployment.md Authentication section with the 401 behavior — operator-facing impact)

🧪 Test-Execution Audit

• No code-path test exists for the new branch (residual under #10772)
• PR body acknowledges static-audit-only with operator-territory L3 residual
• No regression risk for existing non-trustProxyIdentity deployments (verified via OIDC precedence preserved + outer-gate check)

Findings: Pass — substrate-correctness verified via static audit; live-test residual properly named under #10772

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 — correct trust-boundary closure; logic placement matches existing #10768 substrate; OIDC precedence preserved; opt-in semantics consistent with operator-territory discipline
• [CONTENT_COMPLETENESS]: 95 — completes the AC2 ("Return 401/403 if identity is missing or invalid") from #10727. -5 for missing logger.warn on the 401 branch (observability gap, non-blocking)
• [EXECUTION_QUALITY]: 95 — surgical 3-line addition; correct response shape; clean code. -5 for missing test coverage (tracked under #10772)
• [PRODUCTIVITY]: 100 — directly closes the AC2 gap from #10727 that #10768 left
• [IMPACT]: 90 — security-relevant trust-boundary completion; partner-trial-readiness substrate. -10 for non-default behavior (only fires for opt-in deployments)
• [COMPLEXITY]: 5 — 3-line addition; single conditional branch; no async logic
• [EFFORT_PROFILE]: Quick Win — high-leverage trust-boundary closure through minimal-surface change

Required Actions

None.

Suggested non-blocking follow-ups (post-merge)

1. Extend SharedDeployment.md Authentication section (added by #10769) to document the 401-on-missing-header behavior — operators reading the doc need to know about the new fail-closed semantic. 1-2 line addition; could fold into #10772 scope or file as separate doc-follow-up.
2. Add logger.warn on the 401 branch — observability for operators investigating "why is my request 401-ing?" Non-blocking; could fold into #10772 scope.
3. Test coverage for the new branch (3 cases: OIDC-active path unaffected, proxy-active path unaffected when header set, configured-but-missing produces 401) — already tracked under #10772 which I filed earlier today.

These are all non-blocking polish on the trust-boundary substrate; the merge can land independently. Eligible for human merge gate.

🤖 Reviewer: @neo-opus-ada (Claude Opus 4.7 in Claude Code)

Origin Session ID: 23b9cbcd-4938-4a46-b21a-0d48dd12e7e7