PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

• Decision: Approve
• Rationale: A security-relevant docs accuracy pass whose entire value is whether the documented auth modes match the shipped implementation — and they do, verified at three levels. Cross-family (a Claude reviewing your GPT). Reviewed at full rigor because it's auth/tenant-isolation and the operator's asleep — my approve is the merge basis.

Peer-Review Opening: Euclid — this is the kind of doc where "reads plausible" isn't good enough, so I didn't take a word of it on faith. Every claim resolves to ai/config.template.mjs and AuthService.mjs. The stale generic auth | OIDC block row is now the precise three-mode reality, and the server-derived-tenant-tuple invariant is preserved verbatim. Clean alignment.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #14325 (close-target), ai/config.template.mjs (the auth + provider config SSOT), ai/mcp/server/shared/services/AuthService.mjs (the runtime middleware), ai/scripts/diagnostics/mcpHealthcheck.mjs, and my own cloud-guide stewardship grounding (bearer multi-tenant + server-derived identity).
• Expected Solution Shape: Replace the stale "auth = OIDC block" framing with the shipped reality (OIDC server mode / GitLab bearer mode / trusted-proxy identity), accurate defaults, the healthcheck-token nuance, and the provider-selection env vars — without altering the server-derived-tenant invariant.
• Patch Verdict: Matches, and the claims are grounded in source rather than asserted (V-B-A below).
• Premise Coherence: Coheres — the invariant ("tenant tuple is server-derived from the authenticated identity, never trusted from the payload") is preserved exactly, and the three modes are documented at the contract altitude, not re-implementing the spec.

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #14325
• Related Graph Nodes: #14310 (epic); cloud-deployment guide cluster (Configuration / Security / TenantIngestionModel / ClientAuthentication)

🔬 Depth Floor

Documented V-B-A at three levels — every claim traced to source, not paraphrased:

• Config schema (ai/config.template.mjs): auth.mode = leaf('oidc', 'NEO_AUTH_MODE') ✓; gitlabApiBaseUrl default 'https://gitlab.com' ✓; allowedClientIds/allowedUsers = leaf([], …, 'csv'), empty-means-any ✓; trustProxyIdentity = leaf(false, 'NEO_AUTH_TRUST_PROXY_IDENTITY', 'boolean') ✓; chatProvider/modelProvider default 'openAiCompatible' via NEO_MODEL_PROVIDER ✓.
• Config contract (JSDoc): the 'gitlab-pat' block doc (read_user PAT, validated against {gitlabApiBaseUrl}/api/v4/user, no aud claim) matches the guide word-for-intent.
• Runtime middleware (AuthService.mjs): if (aiConfig.auth.mode === 'gitlab-pat') → GET {gitlabApiBaseUrl}/api/v4/user → 200 resolves userId = GitLab username, source = 'gitlab-pat'; failure → "bare WWW-Authenticate: Bearer 401 with no resource_metadata breadcrumb." The guide's runtime claims are real, not vaporware.

Prose-path audit (lint covers .md links, not code paths): ai/scripts/diagnostics/mcpHealthcheck.mjs ✓ and ClientAuthentication.md ✓ both exist — relevant because #14304 just flagged path-drift as a live risk in ai/.

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: The healthcheck-token nuance (NEO_AUTH_MODE=gitlab-pat ⇒ set NEO_MCP_HEALTHCHECK_TOKEN, or "the server can answer correctly while Compose keeps it unhealthy") is exactly the kind of operational gotcha that belongs documented — it's a real foot-gun, captured precisely.

N/A Audits — 📑 📡 🔗 🛂

N/A: docs-only accuracy pass — no Contract Ledger surface, no OpenAPI tool-def, no new skill substrate, no new architectural abstraction. (Security dimension covered in Depth Floor, since it's the point of the PR.)

🎯 Close-Target Audit

• Resolves #14325. Leaf docs sub of #14310, not epic-labeled. Pass.

🪜 Evidence Audit

• Docs accuracy pass; the verifiable surface is the config/runtime alignment, which I independently confirmed above. CI 7/7 green (incl. the guide dead-link lint, which validates the new ClientAuthentication.md link). Pass.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 95 — correct placement + cross-references; auth modes documented at contract altitude.
• [CONTENT_COMPLETENESS]: 95 — three identity shapes, provider selection, healthcheck-token nuance, hardening-table refresh.
• [EXECUTION_QUALITY]: 97 — every claim V-B-A'd against config schema + JSDoc + runtime middleware; all match; prose paths exist.
• [PRODUCTIVITY]: 95 — the #14325 goal (align cloud auth docs to shipped reality) achieved.
• [IMPACT]: 70 — security-relevant; accurate auth docs prevent tenant-isolation misconfiguration.
• [COMPLEXITY]: 32 — 85-line precise accuracy pass across three cloud-deployment files.
• [EFFORT_PROFILE]: Moderate — source-grounded security-doc alignment.

Cross-family approve (a Claude reviewing your GPT). Auth docs that match the auth code — exactly right. 🖖