docs(agentos): align cloud deployment auth docs (#14325) (#14376)

Author: neo-gpt

learn/agentos/cloud-deployment/Configuration.md

@@ -45,7 +45,18 @@ A deployment's `config.mjs` is gitignored and copied from `config.template.mjs`.
 | `transport` | `'stdio'` | `'stdio'` (local single-repo) or `'sse'` (StreamableHTTP — a cloud deployment serving remote tenants). |
 | `mcpHttpPort` | `3000` | The port the SSE transport listens on (only when `transport === 'sse'`). |
 | `publicUrl` | `null` | Canonical public URL — required behind a reverse proxy for OAuth 2.1 / OIDC audience claims + SSE callback advertising. |
-| `auth` | OIDC block | OAuth 2.1 / OIDC config (`host`, `port`, `realm`, `issuerUrl`, `clientId`, `clientSecret`, `trustProxyIdentity`) — used only when `transport === 'sse'`. |
+| `auth.mode` | `'oidc'` | Server-side bearer strategy for HTTP/SSE: `'oidc'` uses OIDC introspection + audience enforcement; `'gitlab-pat'` validates a GitLab OAuth token or PAT against `/api/v4/user` and returns a bare bearer challenge on failure. |
+| `auth.issuerUrl` / `auth.host` / `auth.realm` | `null` / `null` / `'master'` | OIDC authority inputs for the default server mode. `issuerUrl` is preferred when the provider publishes discovery metadata directly. |
+| `auth.clientId` / `auth.clientSecret` | `null` / `''` | OIDC introspection client credentials for deployments that require them. |
+| `auth.trustProxyIdentity` | `false` | Accept identity from a trusted reverse-proxy header after the ingress strips spoofable client-supplied headers. |
+| `auth.gitlabApiBaseUrl` | `'https://gitlab.com'` | GitLab API root used only by `auth.mode === 'gitlab-pat'`; set to a self-managed GitLab host when needed. |
+| `auth.allowedClientIds` / `auth.allowedUsers` | `[]` / `[]` | Optional hardening gates for GitLab bearer mode. Empty means any token that resolves to a valid GitLab user is accepted. |
+
+Compose healthchecks use `ai/scripts/diagnostics/mcpHealthcheck.mjs` against the
+same `/mcp` route as external callers. When a deployment sets
+`NEO_AUTH_MODE=gitlab-pat`, also set `NEO_MCP_HEALTHCHECK_TOKEN` (or
+`NEO_MCP_HEALTHCHECK_TOKEN_ENV`) to a GitLab bearer with `read_user`; otherwise
+the server can answer correctly while Compose keeps it unhealthy.
 
 Each key is also bindable via an environment variable (`NEO_KB_DEFAULT_TENANT_ID`, `NEO_TRANSPORT`, `MCP_HTTP_PORT`, …) — see `config.template.mjs`'s `envBindings` map for the full set.
 
@@ -57,12 +68,14 @@ Each key is also bindable via an environment variable (`NEO_KB_DEFAULT_TENANT_ID
 |---|---|---|
 | `NEO_KB_MCP_URL` | Yes unless `--url` is passed | Remote KB MCP endpoint URL, for example `https://agent-os.example.com/kb/mcp`. |
 | `NEO_KB_MCP_TRANSPORT` | No | MCP client transport; defaults to `streamable-http`, accepts `sse` for older endpoint wiring. |
-| `NEO_KB_INGEST_TOKEN` | Yes for production | Bearer token for the repo-push automation identity. |
+| `NEO_KB_INGEST_TOKEN` | Yes for production | Bearer token for the repo-push automation identity. In OIDC mode it is an access token whose audience matches the KB public URL; in GitLab bearer mode it is a GitLab OAuth access token or PAT accepted by `/api/v4/user`. |
 | `NEO_KB_TOKEN_ENV` | No | Name of the environment variable that holds the bearer token when the deployment does not use `NEO_KB_INGEST_TOKEN`. |
 | `NEO_KB_TENANT_ID` | No | Envelope default for tenant id; authenticated server context remains authoritative. |
 | `NEO_KB_REPO_SLUG` | No | Envelope default for repo slug; use a deterministic, secret-free value such as `neomjs/create-app`. |
 
-The token is a KB MCP authorization credential, not a Git credential. Store it in the tenant hook/CI secret store and rotate it using the deployment's normal OIDC or workload-identity policy.
+The token is a KB MCP authorization credential, not a Git credential. Store it
+in the tenant hook/CI secret store and rotate it using the deployment's normal
+OIDC, GitLab OAuth, or PAT-rotation policy.
 
 ## Per-tenant config storage — `KnowledgeBaseTenantConfig` (#11637)
 
@@ -105,7 +118,26 @@ The default-resolved tier means a single-repo deployment needs no tenant config
 
 ## Model-provider runtime + orchestrator-readiness
 
-Beyond KB ingestion, a cloud deployment tunes the model-provider request behaviour and the orchestrator's provider-readiness probe through five env vars. All carry resident-friendly defaults — a zero-config deployment keeps local models warm across REM/Sandman cycles and probes patiently on cold start.
+Beyond KB ingestion, a cloud deployment chooses where model calls run. External
+provider endpoints remain the default operational posture; the optional
+`local-model` compose profile is a self-hosted OpenAI-compatible provider that
+operators opt into explicitly.
+
+### Provider selection
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `NEO_MODEL_PROVIDER` | `openAiCompatible` | Chat / summary / dream provider selector for Memory Core and the Orchestrator. Set `gemini` for the cloud API route. |
+| `NEO_EMBEDDING_PROVIDER` | `openAiCompatible` | Embedding provider selector for Knowledge Base and Memory Core. Set `gemini` for cloud embeddings. |
+| `NEO_OPENAI_COMPATIBLE_HOST` | deployment-specific | Base URL for a local or hosted OpenAI-compatible endpoint, for example `http://local-model:11434` when the compose profile is enabled. |
+| `NEO_OPENAI_COMPATIBLE_MODEL` | deployment-specific | Chat model id already resident or pullable on the selected OpenAI-compatible provider. |
+| `NEO_OPENAI_COMPATIBLE_EMBEDDING_MODEL` | deployment-specific | Embedding model id for the same provider; local deployments must keep chat + embedding roles available together. |
+| `NEO_OPENAI_COMPATIBLE_API_KEY` | optional | Bearer token for OpenAI-compatible providers that require one; normally empty for the internal `local-model` service. |
+
+The request behaviour and orchestrator-readiness probe below carry
+resident-friendly defaults — when a local provider profile is selected, Neo keeps
+the configured chat and embedding roles warm across REM/Sandman cycles and
+probes patiently on cold start.
 
 ### Provider request `keep_alive`
 

learn/agentos/cloud-deployment/Security.md

@@ -52,7 +52,37 @@ This asymmetry drives retention policy (see Phase 4 #11628): KB backup is cost-o
 
 ## Auth flow and tenant context
 
-The authenticated-ingestion-context resolution maps a tenant's push to its `tenantId` / `originAgentIdentity` before the ingestion service reaches Chroma. The invariant that holds regardless of the transport: **the tenant tuple is server-derived from the authenticated identity, never trusted from the payload.** Endpoint-exact auth wiring depends on the deployment's proxy/OIDC mode; see [Deployment Cookbook](../DeploymentCookbook.md) for the MCP deployment boundary and [Hook Wiring](./HookWiring.md) for ingestion facades.
+The authenticated-ingestion-context resolution maps a tenant's push to its
+`tenantId` / `originAgentIdentity` before the ingestion service reaches Chroma.
+The invariant that holds regardless of the transport: **the tenant tuple is
+server-derived from the authenticated identity, never trusted from the
+payload.**
+
+The shipped HTTP/SSE deployment has three identity shapes:
+
+- **OIDC server mode** (`NEO_AUTH_MODE=oidc`, the default) validates
+  `Authorization: Bearer <token>` through the configured issuer, enforces the
+  MCP server's `NEO_PUBLIC_URL` as the token audience, and derives identity from
+  `preferred_username` / `sub`.
+- **GitLab bearer mode** (`NEO_AUTH_MODE=gitlab-pat`) accepts a GitLab OAuth
+  access token or Personal Access Token as the bearer, validates it against
+  GitLab's `/api/v4/user`, and derives identity from the returned username. This
+  mode intentionally has no OIDC audience claim or protected-resource metadata;
+  failed requests return a bare `WWW-Authenticate: Bearer` challenge.
+- **Trusted proxy identity** (`NEO_AUTH_TRUST_PROXY_IDENTITY=true`) lets an
+  authenticated reverse proxy inject `X-Preferred-Username` /
+  `X-Auth-Request-Preferred-Username`. The reference Caddy ingress strips any
+  client-supplied copies before an optional auth layer injects trusted values.
+
+In `gitlab-pat` mode, the container healthchecks hit the same authenticated
+`/mcp` route as external callers. Set `NEO_MCP_HEALTHCHECK_TOKEN` to a bearer
+that validates under the selected mode, or the MCP server can be healthy but
+Compose will still mark the service unhealthy.
+
+Endpoint-exact auth wiring depends on the deployment's chosen mode; see
+[Client Authentication](./ClientAuthentication.md),
+[Deployment Cookbook](../DeploymentCookbook.md), and [Hook Wiring](./HookWiring.md)
+for the operator and ingestion facades.
 
 ## Post-MVP hardening review (#11736)
 
@@ -64,7 +94,7 @@ tree and which remain deferred to tracked residual work.
 
 | Hardening area | Current documented baseline | Disposition |
 |---|---|---|
-| Reverse proxy identity boundary | `ai/deploy/Caddyfile` strips spoofable identity headers before optional auth injection, and [Deployment Cookbook](../DeploymentCookbook.md) Section 4 names the same invariant. | Actioned for the reference ingress. Production deployments must enable an OIDC/proxy-auth layer or direct OIDC before serving mutually-untrusting tenants. |
+| Reverse proxy identity boundary | `ai/deploy/Caddyfile` strips spoofable identity headers before optional auth injection, and [Deployment Cookbook](../DeploymentCookbook.md) Section 4 names the same invariant. | Actioned for the reference ingress. Production deployments must enable OIDC server mode, GitLab bearer mode, or trusted proxy identity before serving mutually-untrusting tenants. |
 | Repo-push automation token | [Tenant Ingestion Model](./TenantIngestionModel.md) and [Hook Wiring](./HookWiring.md) define `NEO_KB_INGEST_TOKEN` as a tenant-scoped MCP authorization credential, never a Git credential and never part of `repoSlug`, logs, manifests, or graph-visible config. | Actioned for the push-based MVP path. Server-side Git credential transport remains deferred to [#11731](https://github.com/neomjs/neo/issues/11731). |
 | Secret storage | The guide tree consistently routes tokens through tenant hook/CI secret stores and deployment auth/provider config, not committed files. | Actioned at runbook level. Platform-specific secret-manager/KMS wiring belongs to downstream deployment-pipeline work ([#11733](https://github.com/neomjs/neo/issues/11733)) once a concrete platform is selected. |
 | Network policy | The reference compose profile keeps KB and MC internal behind Caddy (`expose`, public path routing through `/kb/*` and `/mc/*`). | Actioned for compose. Kubernetes network policies, managed ingress rules, and service-mesh variants are deferred platform work, tracked under [#11733](https://github.com/neomjs/neo/issues/11733) if adopted. |

learn/agentos/cloud-deployment/TenantIngestionModel.md

@@ -84,15 +84,28 @@ If a future server-side clone path becomes necessary, [#11731](https://github.co
 
 ## Repo-Push Automation Identity
 
-For day-0 tenant push, create a machine/service account in the deployment's OIDC provider and scope it to the tenant repository source it represents. The tenant hook or CI job stores the resulting access token in its secret store and exposes it as `NEO_KB_INGEST_TOKEN`.
+For day-0 tenant push, create an automation identity accepted by the deployment's
+MCP auth mode and scope it to the tenant repository source it represents. The
+tenant hook or CI job stores the resulting bearer in its secret store and
+exposes it as `NEO_KB_INGEST_TOKEN`.
 
-The deployment's OAuth audience/resource must match the KB MCP public resource. Behind the reference ingress, the client URL is typically:
+For OIDC server mode, the deployment's OAuth audience/resource must match the
+KB MCP public resource. Behind the reference ingress, the KB MCP URL is
+typically:
 
 ```text
 https://agent-os.example.com/kb/mcp
 ```
 
-The token's resource should match the canonical KB public URL configured by `NEO_PUBLIC_URL` / the auth provider. The exact token acquisition flow is operator-owned — client credentials, workload identity, or CI OIDC exchange are all valid — but the resulting token must be short-lived or rotated, tenant-scoped, and stored outside the repository.
+In the default OIDC server mode, the token's resource should match the canonical
+KB public URL configured by `NEO_PUBLIC_URL` / the auth provider. In
+`NEO_AUTH_MODE=gitlab-pat`, the bearer is a GitLab OAuth access token or
+Personal Access Token with `read_user`; the server validates it against
+GitLab's `/api/v4/user` and derives the tenant identity from the returned
+username. The exact token acquisition flow is operator-owned — client
+credentials, workload identity, GitLab OAuth, or a rotated PAT are all valid —
+but the resulting bearer must be tenant-scoped, stored outside the repository,
+and rotated according to the deployment's auth policy.
 
 The server remains authoritative for tenant identity. `NEO_KB_TENANT_ID` is a client default for envelope construction; authenticated context still stamps or rejects tenant metadata according to deployment policy.
 
@@ -151,7 +164,7 @@ Incremental pushes should include deletion intent. Prefer this default shape:
 2. Build the source-family inventory.
 3. Choose dispatch for each family: raw server parse, registered server parser, client-side `parsed-chunk-v1`, unsupported, or excluded.
 4. Run initial import with `ai:ingest-tenant` when volume exceeds the MCP gate.
-5. Create the repo-push automation identity, configure token audience/resource, and store the token as `NEO_KB_INGEST_TOKEN` in the tenant hook or CI secret store.
+5. Create the repo-push automation identity, configure the OIDC audience or GitLab bearer policy, and store the token as `NEO_KB_INGEST_TOKEN` in the tenant hook or CI secret store.
 6. Wire incremental `pre-push` or CI pushes through `ai:kb-push-client` to the remote MCP endpoint.
 7. Include tombstones and revision boundaries; include manifests at reconciliation points.
 8. Fail the hook or CI job on structured ingestion errors instead of silently dropping files.